foldkit-site 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,614 @@
1
+ import { Effect, Option, Schema } from "effect";
2
+ import { AnyMessage, Bundle, Helper, Link, Placed, PlacementConfig, ResourceEntries, SeedFor } from "foldkit-bundle";
3
+ import { Router } from "foldkit/route";
4
+ import * as Update from "foldkit/update";
5
+ import { Url } from "foldkit/url";
6
+ import { ActiveSurface, ModelPlace, Surface, SurfaceSource, Wiring } from "foldkit-surface";
7
+ import { Html, HtmlBuilder } from "foldkit/html";
8
+ import { KeyBinding, KeySequence } from "foldkit/subscription";
9
+ import { Meta } from "foldkit-ssr/client";
10
+ //#region src/index.d.ts
11
+ /** Whether moving to a target adds a history step (`push`) or replaces the current one. */
12
+ export type HistoryIntent = 'push' | 'replace';
13
+ /**
14
+ * A route-case constructor: the Schema for `Surface.when`, called to build
15
+ * route values for targets. The `any` is deliberate and quarantined here:
16
+ * every constructor of a `defineRouteUnion` case is callable with its fields,
17
+ * and `Site.target` types the params from the route value instead.
18
+ */
19
+ export interface RouteCase<Route extends {
20
+ readonly _tag: string;
21
+ }> extends Schema.Schema<Route> {
22
+ (params: any): Route;
23
+ }
24
+ /**
25
+ * A Surface a node activates, with the route's params made into its own: the
26
+ * `Surface.when` a node lowers to, once the application says where its route
27
+ * lives. The surface's own types are checked where the node is declared
28
+ * (`Site.route` infers them); by the time sources resolve, only the owner
29
+ * check can still fail, and it does, loudly.
30
+ */
31
+ export interface BoundSurface {
32
+ readonly surface: Surface<any, any, any, any>;
33
+ readonly params: (route: any) => any;
34
+ }
35
+ /**
36
+ * A layout around everything under a node: it receives the composed child
37
+ * explicitly — no Outlet, no context, no hidden route state. Ancestors with
38
+ * layouts wrap the leaf's view root-first; ancestors without one pass
39
+ * through. The `any` positions are deliberate and quarantined, as with
40
+ * `BoundSurface`: annotate the function where it is declared and it checks
41
+ * there.
42
+ */
43
+ export interface NodeLayout {
44
+ readonly render: (child: Html, model: any, h: any) => Html;
45
+ }
46
+ /**
47
+ * What a node draws for its own route: only the deepest node of the active
48
+ * chain draws (its ancestors contribute layouts, never their views — a
49
+ * person page shows no people list). Same `any` quarantine as `NodeLayout`.
50
+ */
51
+ export interface NodeView {
52
+ readonly render: (model: any, h: any) => Html;
53
+ }
54
+ /**
55
+ * What a node says of itself in the document's head, from its route value and
56
+ * the Model (a post's excerpt is in the Model, not the route). The node keeps
57
+ * it with the Model as `any`, quarantined as `NodeLayout`'s is: name the Model
58
+ * where it is declared (`.meta<Model>(...)`) and it checks there.
59
+ */
60
+ export type NodeMeta<Route, Model = any> = (page: {
61
+ readonly route: Route;
62
+ readonly model: Model;
63
+ }) => Meta;
64
+ /**
65
+ * The route's place in the Model, read and written. A field holding a tagged
66
+ * union is a *union of* `FieldRef`s, one per case, which no single
67
+ * `ModelRef<Root, Route>` accepts — so this is structural:
68
+ *
69
+ * ```ts
70
+ * route: {
71
+ * dependency: App.model.route.dependency,
72
+ * get: (model) => model.route,
73
+ * set: (model, route) => modifyFields(model, { route: () => route }),
74
+ * },
75
+ * ```
76
+ */
77
+ export interface RouteField<Root, Route> {
78
+ readonly dependency: readonly string[];
79
+ readonly get: (root: Root) => Route;
80
+ readonly set: (root: Root, route: Route) => Root;
81
+ }
82
+ /**
83
+ * One routed page: its node, its Bundle placement, and how a route arrival
84
+ * reaches the child. The placement drives both folds from one declaration —
85
+ * `placed.update` for Messages, `placed.view` for drawing — and `inform`
86
+ * tells the child when its route arrives, through its own Message. The
87
+ * placement's full type rides along, so assemblies keep inferring services.
88
+ */
89
+ export interface SitePage<Parent, ParentMessage, R, P> {
90
+ readonly node: SiteNode<any>;
91
+ readonly placed: P;
92
+ /**
93
+ * The child told of a route arrival: `None` for another node's route, for
94
+ * a page with nothing to say, or when the child says nothing is needed.
95
+ */
96
+ readonly inform: (model: Parent, route: {
97
+ readonly _tag: string;
98
+ }) => Option.Option<Update.Return<Parent, ParentMessage, R>>;
99
+ }
100
+ /**
101
+ * One deployed location: its Router (which owns URL semantics), its route
102
+ * case, and its metadata. A stable first-class value: mounting it in a tree
103
+ * never mutates it, so the same node serves targets, hrefs, and inspection
104
+ * wherever it is mounted.
105
+ */
106
+ export interface SiteNode<Route extends {
107
+ readonly _tag: string;
108
+ }> {
109
+ readonly tag: string;
110
+ readonly router: Router<Route>;
111
+ readonly case: RouteCase<Route>;
112
+ /** The page's title for this route, once the route value is known. */
113
+ readonly title?: ((route: Route) => string) | undefined;
114
+ /** The navigation section this route belongs to, for menus and breadcrumbs. */
115
+ readonly section?: string | undefined;
116
+ /**
117
+ * Where the section's nav item points: this node's params for its landing
118
+ * address (a people list with no search, say). Nodes a section never lands
119
+ * on — a person, a file — leave it absent; `Site.landing` reads the first
120
+ * node of a section that declares one.
121
+ */
122
+ readonly landing?: Omit<Route, '_tag'> | undefined;
123
+ /**
124
+ * The keys that go to this node's `landing`, as Foldkit's key bindings name
125
+ * them: one press (`'/'`, `'Mod+K'`) or a sequence (`['G', 'H']`).
126
+ * `Site.shortcuts` makes the bindings.
127
+ */
128
+ readonly shortcut?: KeySequence | undefined;
129
+ /**
130
+ * Which history step a move within this node is: a string, or a function
131
+ * for nodes where some param changes are entries of their own (another
132
+ * person) and others are views of one entry (another search). A move to
133
+ * another node — or from an unknown location — is always a step.
134
+ */
135
+ readonly history?: HistoryIntent | ((prev: Route, next: Route) => HistoryIntent) | undefined;
136
+ /** The Surface this route activates, if the node declares one. */
137
+ readonly bound?: BoundSurface | undefined;
138
+ /** A layout wrapping everything under this node, if it declares one. */
139
+ readonly layout?: NodeLayout | undefined;
140
+ /** What this node draws for its own route, if it draws anything. */
141
+ readonly view?: NodeView | undefined;
142
+ /** What this node says of itself in the head; nodes below override it per field. */
143
+ readonly meta?: NodeMeta<Route> | undefined;
144
+ /**
145
+ * Whether search engines index this node and, unless they say otherwise,
146
+ * the nodes below it. Undeclared up the whole chain, a node is indexed.
147
+ */
148
+ readonly indexed?: boolean | undefined;
149
+ }
150
+ /** Carries the routes a mount or tree holds, in its type only: nothing sets it. */
151
+ declare const routes: unique symbol;
152
+ /** A node mounted with its children: structure, not state. `Route` is every route it holds. */
153
+ export interface SiteMount<Route extends {
154
+ readonly _tag: string;
155
+ } = any> {
156
+ readonly node: SiteNode<any>;
157
+ readonly children: ReadonlyArray<SiteMount>;
158
+ readonly [routes]?: (route: Route) => void;
159
+ }
160
+ /** The routes a bare node or a mount holds. */
161
+ export type RoutesOf<Mounted> = Mounted extends SiteNode<infer Route> ? Route : Mounted extends SiteMount<infer Route> ? Route : never;
162
+ /**
163
+ * A node under construction, from `Site.node`: each method annotates and
164
+ * returns the builder, so nodes compose in steps and annotation bundles are
165
+ * ordinary values. Methods — not pipeable fragments — because each stage of
166
+ * a pipe is a separate generic call and could not infer the route. Read
167
+ * `.node` at any stage for the frozen node so far.
168
+ */
169
+ export interface NodeBuilder<Route extends {
170
+ readonly _tag: string;
171
+ }> {
172
+ /** The node so far: frozen, usable for targets and hrefs at any stage. */
173
+ readonly node: SiteNode<Route>;
174
+ /**
175
+ * One named bundle through the builder, Effect-style: the bundle stays
176
+ * generic over the builder it meets, so it instantiates to this node's
177
+ * route with no annotation. Chain for more than one.
178
+ *
179
+ * ```ts
180
+ * const inSection = <R extends { readonly _tag: string }>(b: NodeBuilder<R>) =>
181
+ * b.section('People').shortcut(['G', 'P'])
182
+ *
183
+ * const Person = Site.node(personRouter, AppRoute.Person).pipe(inSection).node
184
+ * ```
185
+ *
186
+ * Free `pipe(builder, bundle)` from `effect` composes the same way; this
187
+ * method is the same spelling without the import.
188
+ */
189
+ pipe<A>(fn: (builder: NodeBuilder<Route>) => A): A;
190
+ /** The page's title for this route, once the route value is known. */
191
+ title(title: (route: Route) => string): NodeBuilder<Route>;
192
+ /** The navigation section this route belongs to. */
193
+ section(section: string): NodeBuilder<Route>;
194
+ /** Where the section's nav item points, as this node's params. */
195
+ landing(landing: Omit<Route, '_tag'>): NodeBuilder<Route>;
196
+ /** The keys that go to this node's landing. */
197
+ shortcut(shortcut: KeySequence): NodeBuilder<Route>;
198
+ /** Which history step a move within this node is. */
199
+ history(history: HistoryIntent | ((prev: Route, next: Route) => HistoryIntent)): NodeBuilder<Route>;
200
+ /** A layout wrapping everything under this node. */
201
+ layout(layout: NodeLayout): NodeBuilder<Route>;
202
+ /** What this node draws for its own route. */
203
+ view(view: NodeView): NodeBuilder<Route>;
204
+ /** What this node says of itself in the head, from its route and the Model. */
205
+ meta<Model = any>(meta: NodeMeta<Route, Model>): NodeBuilder<Route>;
206
+ /** Whether search engines index this node and the nodes below it. */
207
+ indexed(indexed: boolean): NodeBuilder<Route>;
208
+ /** The Surface this route activates. */
209
+ surface<SRoot, SModel, SMessage, SParams>(config: {
210
+ readonly surface: Surface<SRoot, SModel, SMessage, SParams>;
211
+ readonly params: (route: Route) => SParams;
212
+ }): NodeBuilder<Route>;
213
+ }
214
+ /**
215
+ * The deployed topology: roots with everything mounted under them, frozen.
216
+ * `Route` is the union of every node's route, so the tree parses an address
217
+ * to it (`Site.parse`) and builds one back (`Site.hrefOf`).
218
+ */
219
+ export interface SiteTree<Route extends {
220
+ readonly _tag: string;
221
+ } = any> {
222
+ readonly roots: ReadonlyArray<SiteMount>;
223
+ readonly [routes]?: (route: Route) => void;
224
+ }
225
+ /** One address a node's `Site.paths` lists: the route's params, and when its content last changed. */
226
+ export interface SitePath<Route extends {
227
+ readonly _tag: string;
228
+ }> {
229
+ readonly params: Omit<Route, '_tag'>;
230
+ /** When what the page shows last changed, as ISO 8601 text, for a sitemap. */
231
+ readonly modified?: string | undefined;
232
+ }
233
+ /** A node's addresses, listed by an Effect the build runs: from `Site.paths`. */
234
+ export interface SitePaths<E, R> {
235
+ readonly node: SiteNode<any>;
236
+ readonly list: Effect.Effect<ReadonlyArray<SitePath<any>>, E, R>;
237
+ }
238
+ /** How a listing of `SitePaths` can fail: each one's error, and none for no paths. */
239
+ export type PathsError<Paths> = Paths extends SitePaths<infer E, any> ? E : never;
240
+ /** What a listing of `SitePaths` needs: each one's services, and none for no paths. */
241
+ export type PathsServices<Paths> = Paths extends SitePaths<any, infer R> ? R : never;
242
+ /** One address of the whole site, from `Site.targets`: a target, and when it last changed. */
243
+ export interface SiteListed<Route extends {
244
+ readonly _tag: string;
245
+ }> extends SiteTarget<Route> {
246
+ readonly modified?: string | undefined;
247
+ }
248
+ /**
249
+ * One typed destination: the node, the route value, and the URL, all from one
250
+ * declaration. Links, prefetch, and route analysis share this instead of each
251
+ * rebuilding it.
252
+ */
253
+ export interface SiteTarget<Route extends {
254
+ readonly _tag: string;
255
+ }> {
256
+ readonly node: SiteNode<Route>;
257
+ readonly route: Route;
258
+ readonly url: string;
259
+ }
260
+ export declare const Site: {
261
+ /**
262
+ * One deployed location from its Foldkit Router and its route case:
263
+ *
264
+ * ```ts
265
+ * const Person = Site.route(personRouter, AppRoute.Person, {
266
+ * title: ({ personId }) => `Person ${personId} | Routing`,
267
+ * section: 'People',
268
+ * })
269
+ * ```
270
+ *
271
+ * The router stays the whole URL story (parse and build); the case names
272
+ * the tag and builds route values. Metadata is annotated once here, and
273
+ * navigation, titles, and history derive from it. To share annotations
274
+ * across nodes, or to build incrementally, use the `Site.node` builder
275
+ * instead — these options are sugar over it.
276
+ */
277
+ route: <Route extends {
278
+ readonly _tag: string;
279
+ }, SRoot, SModel, SMessage, SParams>(router: Router<Route>, routeCase: RouteCase<Route>, options?: {
280
+ readonly title?: ((route: Route) => string) | undefined;
281
+ readonly section?: string | undefined;
282
+ readonly landing?: Omit<Route, "_tag"> | undefined;
283
+ readonly shortcut?: KeySequence | undefined;
284
+ readonly history?: HistoryIntent | ((prev: Route, next: Route) => HistoryIntent) | undefined;
285
+ readonly layout?: NodeLayout | undefined;
286
+ readonly view?: NodeView | undefined;
287
+ readonly meta?: NodeMeta<Route> | undefined;
288
+ readonly indexed?: boolean | undefined;
289
+ readonly surface?: {
290
+ readonly surface: Surface<SRoot, SModel, SMessage, SParams>;
291
+ readonly params: (route: Route) => SParams;
292
+ } | undefined;
293
+ }) => SiteNode<Route>;
294
+ /**
295
+ * One deployed location as an incremental builder, for nodes annotated in
296
+ * steps or annotations shared across nodes:
297
+ *
298
+ * ```ts
299
+ * const Person = Site.node(personRouter, AppRoute.Person)
300
+ * .title(({ personId }) => `Person ${personId} | Routing`)
301
+ * .section('People')
302
+ * .node
303
+ * ```
304
+ *
305
+ * Methods — not pipeable fragments — because a pipeable fragment cannot
306
+ * infer the route: each stage is a separate generic call, so its type
307
+ * parameter falls back to the constraint and a typed callback no longer
308
+ * matches. A method already knows its node's route, so inline lambdas
309
+ * infer with no annotation. Read `.node` at any stage: every step freezes,
310
+ * so intermediates are usable nodes too (targets, hrefs), never drafts.
311
+ * `Site.route`'s options are sugar over this builder — one implementation.
312
+ */
313
+ node: <Route extends {
314
+ readonly _tag: string;
315
+ }>(router: Router<Route>, routeCase: RouteCase<Route>) => NodeBuilder<Route>;
316
+ /**
317
+ * A node with its children. Returns a mount; the node itself is untouched,
318
+ * so it stays usable bare for targets and hrefs. Children may be bare
319
+ * nodes (childless) or mounts.
320
+ */
321
+ mount: <Route extends {
322
+ readonly _tag: string;
323
+ }, const Children extends ReadonlyArray<SiteNode<any> | SiteMount> = []>(node: SiteNode<Route>, children?: Children) => SiteMount<Route | RoutesOf<Children[number]>>;
324
+ /**
325
+ * The deployed topology from its roots: bare nodes or mounts, frozen.
326
+ * Refuses two nodes sharing a tag and one node mounted twice, since both
327
+ * would make chain inspection ambiguous.
328
+ */
329
+ make: <const Roots extends ReadonlyArray<SiteNode<any> | SiteMount>>(...roots: Roots) => SiteTree<RoutesOf<Roots[number]>>;
330
+ /**
331
+ * One typed destination: the route value and the URL from the node's own
332
+ * declaration, so a link can never point where the parser would not go.
333
+ */
334
+ target: <Route extends {
335
+ readonly _tag: string;
336
+ }>(node: SiteNode<Route>, params: Omit<Route, "_tag">) => SiteTarget<Route>;
337
+ /** The URL of a target, or of a node with params directly. */
338
+ href: {
339
+ <Route extends {
340
+ readonly _tag: string;
341
+ }>(target: SiteTarget<Route>): string;
342
+ <Route extends {
343
+ readonly _tag: string;
344
+ }>(node: SiteNode<Route>, params: Omit<Route, "_tag">): string;
345
+ };
346
+ /**
347
+ * The tree's parser: an address to the route of the first node, in tree
348
+ * order (depth-first, parents first), whose router takes all of it, or the
349
+ * fallback. A router that takes any segment (`/:slug`) belongs after the
350
+ * nodes whose literal it would take too. With `Site.hrefOf`, the tree is
351
+ * the one declaration of both directions.
352
+ */
353
+ parse: <Route extends {
354
+ readonly _tag: string;
355
+ }, Fallback>(site: SiteTree<Route>, fallback: {
356
+ readonly make: (data: {
357
+ readonly path: string;
358
+ }) => Fallback;
359
+ }) => ((url: Url) => Route | Fallback);
360
+ /**
361
+ * The route the tree reads at an address, as `Site.parse` does, or nothing
362
+ * when no node takes it: an address the tree does not hold is another
363
+ * document's, which a link reaches with a full load.
364
+ */
365
+ routeAt: <Route extends {
366
+ readonly _tag: string;
367
+ }>(site: SiteTree<Route>, url: Url) => Option.Option<Route>;
368
+ /**
369
+ * The address of a route the tree holds, built by its node's router, so it
370
+ * parses back to the same route (`Site.parse`).
371
+ */
372
+ hrefOf: <Route extends {
373
+ readonly _tag: string;
374
+ }>(site: SiteTree<Route>, route: Route) => string;
375
+ /**
376
+ * A node's addresses, from data: every published post is one. `list` is an
377
+ * Effect the build runs, such as a Remote query read through
378
+ * `Data.satisfy`, so it lists what a visitor may see.
379
+ *
380
+ * ```ts
381
+ * const posts = Site.paths(PostNode, listPosts.pipe(
382
+ * Effect.map(rows => rows.map(row => ({ params: { slug: row.slug }, modified: row.at }))),
383
+ * ))
384
+ * ```
385
+ */
386
+ paths: <Route extends {
387
+ readonly _tag: string;
388
+ }, E, R>(node: SiteNode<Route>, list: Effect.Effect<ReadonlyArray<SitePath<Route>>, E, R>) => SitePaths<E, R>;
389
+ /**
390
+ * Every address of the site, in tree order: one for each node whose route
391
+ * has no params, and what `paths` lists for each node whose route has
392
+ * them. What a build renders, a sitemap lists (with `Site.indexedOf`), and
393
+ * a prefetch warms. A node with params and no `paths` is refused, as are
394
+ * `paths` for a node the tree does not hold or twice for one node, so no
395
+ * page is left out unsaid; `Site.paths(node, Effect.succeed([]))` lists none.
396
+ */
397
+ targets: <const Paths extends ReadonlyArray<SitePaths<any, any>>>(site: SiteTree, paths: Paths) => Effect.Effect<ReadonlyArray<SiteListed<any>>, PathsError<Paths[number]>, PathsServices<Paths[number]>>;
398
+ /** Every node in the tree, depth-first, parents before children. */
399
+ nodesOf: (site: SiteTree) => ReadonlyArray<SiteNode<any>>;
400
+ /** The node a route value is on, or nothing for a tag the tree does not hold. */
401
+ nodeOf: (site: SiteTree, route: {
402
+ readonly _tag: string;
403
+ }) => SiteNode<any> | undefined;
404
+ /** The chain a route value is on, root first; none for an unknown tag. */
405
+ chainOf: (site: SiteTree, route: {
406
+ readonly _tag: string;
407
+ }) => ReadonlyArray<SiteNode<any>>;
408
+ /** The node above this one in the tree, or nothing at a root. */
409
+ parentOf: (site: SiteTree, node: SiteNode<any>) => SiteNode<any> | undefined;
410
+ /** Every node above this one, root first. */
411
+ ancestorsOf: (site: SiteTree, node: SiteNode<any>) => ReadonlyArray<SiteNode<any>>;
412
+ /** How deep the node sits: a root is 0, its children 1. */
413
+ depthOf: (site: SiteTree, node: SiteNode<any>) => number;
414
+ /** The title the tree annotates for a route value, or nothing. */
415
+ titleOf: (site: SiteTree, route: {
416
+ readonly _tag: string;
417
+ }) => string | undefined;
418
+ /**
419
+ * Whether search engines index a route: the nearest declaration up its
420
+ * chain, so a `noindex` studio covers every node below it. A route the tree
421
+ * does not hold is indexed, as a page with no declaration is.
422
+ */
423
+ indexedOf: (site: SiteTree, route: {
424
+ readonly _tag: string;
425
+ }) => boolean;
426
+ /**
427
+ * What a route says of itself in the head, for an SSR plan's `meta`:
428
+ *
429
+ * ```ts
430
+ * SSR.plan(App, { id: 'site', state, meta: model => Site.metaOf(AppSite, model.route, model) })
431
+ * ```
432
+ *
433
+ * Each node of the chain's `meta`, root first, with a deeper node's field
434
+ * replacing its ancestor's and a field it leaves out keeping the ancestor's.
435
+ * The preview title falls back to the route's `title`. An unindexed route
436
+ * (`Site.indexedOf`) is `noindex` whatever its `meta` says.
437
+ */
438
+ metaOf: <Root>(site: SiteTree, route: {
439
+ readonly _tag: string;
440
+ }, model: Root) => Meta;
441
+ /** The navigation section the tree annotates for a route value, or nothing. */
442
+ sectionOf: (site: SiteTree, route: {
443
+ readonly _tag: string;
444
+ }) => string | undefined;
445
+ /**
446
+ * Where a section's nav item points: the first node of the section with a
447
+ * landing, as a target. Nothing when no node of the section declares one —
448
+ * every section shown needs a landing, so navigation asserts it.
449
+ */
450
+ landing: (site: SiteTree, section: string) => SiteTarget<any> | undefined;
451
+ /**
452
+ * The tree's shortcuts as key bindings, each sending the Message
453
+ * `toMessage` makes of its node's landing:
454
+ *
455
+ * ```ts
456
+ * Subscription.keyBindings({
457
+ * bindings: Site.shortcuts(AppSite, target => Message.PressedShortcut({ url: target.url })),
458
+ * })
459
+ * ```
460
+ *
461
+ * A shortcut on a node with no `landing` goes nowhere, and one used twice
462
+ * goes to two places; both are refused.
463
+ */
464
+ shortcuts: <Message>(site: SiteTree, toMessage: (target: SiteTarget<any>) => Message) => ReadonlyArray<KeyBinding<Message>>;
465
+ /**
466
+ * Which history step a move is: to another node, a step; within a node, its
467
+ * declaration (a string, or a function for nodes where some param changes
468
+ * are entries of their own); with no previous target — the current location
469
+ * is unknown to the site — a step too, so Back can still return to it.
470
+ */
471
+ historyOf: (prev: SiteTarget<any> | undefined, next: SiteTarget<any>) => HistoryIntent;
472
+ /**
473
+ * What the route draws: the deepest node's view, wrapped by every
474
+ * ancestor's layout root-first. Ancestors contribute layouts only — never
475
+ * their views. Pure function composition over ordinary Foldkit rendering;
476
+ * unknown tags and viewless leaves fail loudly, since rendering one would
477
+ * guess.
478
+ */
479
+ view: <Root, Message>(site: SiteTree, route: {
480
+ readonly _tag: string;
481
+ }, model: Root, h: HtmlBuilder<Message>) => Html;
482
+ /**
483
+ * What the tree's surfaced nodes activate, keyed by tag, for `Data.wiring`,
484
+ * `Data.subscriptions`, `Data.satisfy`, or an SSR plan's `surfaces`: each
485
+ * node's `Surface.when` over the application's route place. A surface from
486
+ * another application is refused here, not at its reads.
487
+ */
488
+ sources: <Root>(site: SiteTree, owner: object, place: ModelPlace<Root>) => Record<string, ActiveSurface<Root> & SurfaceSource<Root>>;
489
+ /**
490
+ * The route-level Sources for one destination: the same entries as
491
+ * `Site.sources`, but only the target's chain. Prefetch, SSR, and DevTools
492
+ * read what a route will activate without building its Model first; the
493
+ * preparation itself stays caller-composed (`Data.satisfy` over these, with
494
+ * the route set to the target's). A tag the tree does not hold resolves to
495
+ * no Sources, the way an inactive Surface resolves to nothing.
496
+ *
497
+ * ```ts
498
+ * const active = Site.sourcesFor(AppSite, App.owner, App.model.route, target.route)
499
+ * const prepared = yield* Data.satisfy({ ...model, route: target.route }, active)
500
+ * ```
501
+ *
502
+ * There is deliberately no `SitePlan` object: the chain is already
503
+ * `Site.chainOf`, and the head is `Site.metaOf`.
504
+ */
505
+ sourcesFor: <Root>(site: SiteTree, owner: object, place: ModelPlace<Root>, route: {
506
+ readonly _tag: string;
507
+ }) => Record<string, ActiveSurface<Root> & SurfaceSource<Root>>;
508
+ /**
509
+ * The application's link-click and URL-change lifecycle as one wiring, so
510
+ * `update` stops hand-writing those two branches. A click on a link the
511
+ * tree holds navigates (pushing or replacing per `Site.historyOf`); on any
512
+ * other, on this origin or not, it loads, since another document serves
513
+ * it (`Site.routeAt`); a URL change sets the route field — or touches
514
+ * nothing when the address parses to the route already shown, so an echo
515
+ * of our own write never re-renders or clears pending state. The
516
+ * application's own update answers nothing for either message; `reduces`
517
+ * names them for its guard, the way `Remote.reduces` does.
518
+ *
519
+ * ```ts
520
+ * const Routing = Site.routing<Model, Message, AppRoute>({
521
+ * site: AppSite,
522
+ * owner: App.owner,
523
+ * route: {
524
+ * dependency: App.model.route.dependency,
525
+ * get: (model) => model.route,
526
+ * set: (model, route) => modifyFields(model, { route: () => route }),
527
+ * },
528
+ * parse: urlToAppRoute,
529
+ * tags: { clicked: 'ClickedLink', changed: 'ChangedUrl' },
530
+ * completed: Message.CompletedNavigation,
531
+ * })
532
+ * const assembly = Bundle.assemble([Routing, ...pages])
533
+ * const update = assembly.update((model, message) =>
534
+ * Routing.reduces(message) ? { model } : updateOwn(model, message),
535
+ * )
536
+ * ```
537
+ *
538
+ * One routing per application: it claims the click tag and shares the
539
+ * change tag with URL mirrors, which read their slices first. With `pages`,
540
+ * a route change sets the field and then informs each page whose route
541
+ * arrived, through the page's own `changed` Message.
542
+ */
543
+ routing: <Root, Message extends {
544
+ readonly _tag: string;
545
+ }, Route extends {
546
+ readonly _tag: string;
547
+ }, R = never>(config: {
548
+ readonly site: SiteTree;
549
+ /**
550
+ * The application's identity token, for the Module contract. Raw Foldkit
551
+ * applications have none; omit it and the contract claims no owner.
552
+ */
553
+ readonly owner?: object | undefined;
554
+ /** The route field, read and written (a `RouteField`, struct). */
555
+ readonly route: RouteField<Root, Route>;
556
+ /** The application's URL parser, with its NotFound fallback. */
557
+ readonly parse: (url: Url) => Route;
558
+ /** The application's own link-click and URL-change tags. */
559
+ readonly tags: {
560
+ readonly clicked: string;
561
+ readonly changed: string;
562
+ };
563
+ /** One completion for the navigation commands to dispatch. */
564
+ readonly completed: Schema.Schema<Message> & (() => Message);
565
+ /**
566
+ * Routed pages, informed when their route arrives. With service-needing
567
+ * pages, name the services fourth:
568
+ * `Site.routing<Model, Message, AppRoute, RemoteClient>`.
569
+ */
570
+ readonly pages?: ReadonlyArray<SitePage<Root, Message, R, any>> | undefined;
571
+ /**
572
+ * What the application does once a new route is set and its pages are
573
+ * told: moving focus to what it drew, say. An echo of the shown address
574
+ * arrives nowhere, so it runs nothing.
575
+ */
576
+ readonly arrived?: ((model: Root, route: Route) => Update.Return<Root, Message, R>) | undefined;
577
+ }) => Wiring<Root, Message, R> & {
578
+ /** Whether the routing owns a message: its click or its URL change. */
579
+ readonly reduces: (message: Message) => boolean;
580
+ };
581
+ /**
582
+ * One routed page stated once: its link (where its Model lives and how its
583
+ * Messages wrap), what starts it, and what its route arrival tells it. The
584
+ * link carries the field and the wrapper together; `placed.update` folds
585
+ * the child's Messages and `placed.view` draws it, and `Site.routing`
586
+ * informs it through `changed` when its route arrives.
587
+ *
588
+ * ```ts
589
+ * const PeoplePage = Site.placement(People, PeopleBundle, {
590
+ * link: Link.field<Model>()('peoplePage', Link.wrapper(Message.GotPeopleMessage)),
591
+ * args: parent => ({
592
+ * searchText: parent.route._tag === 'People' ? parent.route.searchText : Option.none(),
593
+ * }),
594
+ * changed: route => People.Message.ChangedRoute({ route }),
595
+ * })
596
+ * const assembly = Bundle.assemble([PeoplePage.placed, Routing])
597
+ * ```
598
+ *
599
+ * `changed` receives the node's own case value and returns the child's
600
+ * Message, or nothing when the arrival needs no answer. Without it the
601
+ * page is never informed. Bundles with OutMessages, and children that are
602
+ * not Bundles, stay on `Bundle.at` and `Link.child` directly.
603
+ */
604
+ placement: <Route extends {
605
+ readonly _tag: string;
606
+ }, Parent, LinkMessage extends AnyMessage, ChildModel, ChildMessage extends AnyMessage, Field extends string, Name extends string, Args, BundleR = never, BundleS = never, ViewInputs = void, Resources extends ResourceEntries<ChildModel, ChildMessage> = never, Helpers extends Readonly<Record<string, Helper<ChildModel, ChildMessage, never, BundleR>>> = never, ObserverR = never>(node: SiteNode<Route>, bundle: Bundle.Bundle<Name, Args, ChildModel, ChildMessage, never, BundleR, BundleS, ViewInputs, Resources, Helpers>, config: {
607
+ readonly link: Link<Parent, LinkMessage, ChildModel, ChildMessage, Field>;
608
+ readonly changed?: (route: Route) => ChildMessage | undefined;
609
+ } & PlacementConfig<Args, Parent, LinkMessage, ChildMessage, never, never, ObserverR, SeedFor<Parent, Field>>) => SitePage<Parent, LinkMessage, BundleR | ObserverR, Placed<Name, Parent, LinkMessage, ChildModel, ChildMessage, BundleR | ObserverR, BundleS, ViewInputs, Resources, Helpers, Field, LinkMessage extends {
610
+ readonly _tag: infer Tag extends string;
611
+ } ? Tag : string>>;
612
+ };
613
+ //#endregion
614
+ //# sourceMappingURL=index.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":"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"}