What this package is

Every application with more than one screen answers the same questions: what places exist, which place are we on, how do places link to each other, and what does each place show. Foldkit's Router already answers the URL half with bidirectional parsers. foldkit-site answers the structural half: a tree of stable route nodes over those parsers, with one annotated place for the metadata (titles, sections, history intent) that applications otherwise recompute in four parallel tables. Site and Foldkit's Router draws the line between the two and shows how the Site works, and Site, Remote and SSR together builds a routed application with its data rendered on the server.

When it owns the problem#

foldkit-site owns where the application is, and nothing else:

Site        "What location are we at, and what is around it?"
Surface     "What may this location observe, and which Messages may it cause?"
Remote      "What server facts do those observations require?"

It owns no Model, runs no Effects, dispatches no Messages, and fetches nothing. A node lowers to an ordinary Foldkit Router (which it is built from), an ordinary Surface.when (through Site.sources), and — in a later cut — an ordinary Bundle placement. If a feature would need the Site to become another store, async runtime, or cache, it does not belong here.

The mental model#

Foldkit Router (per node)     URL <-> typed route value
        +
Site tree                       route value -> chain, metadata, Surfaces
        +
Surface / Remote / SSR          the existing consumers of those answers

A node is a stable first-class value: mounting it in a tree never mutates it, so the same node builds targets, hrefs, and inspection wherever it is mounted. A target is one typed destination — node, route value, and URL from one declaration — so a link can never point where the parser would not go.

Install#

pnpm add foldkit-site

Peers: effect, foldkit. foldkit-surface is a dependency (for Site.sources), and foldkit-ssr for the Meta a node's head returns.