@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/dist/shared/rsc-cache-key.d.ts

@@ -0,0 +1,163 @@
+/**
+ * The `_rsc` payload cache key — derived identically on both sides.
+ *
+ * The client puts this in the payload URL so the document and its Flight
+ * payload occupy different cache keys (TIM-1268). The server recomputes it
+ * from the received headers so a request cannot claim one client's key while
+ * sending another client's headers — see `server/rsc-cache-key-guard.ts`.
+ * Both sides must agree exactly, which is why the derivation lives here and
+ * not in either one.
+ *
+ * Isomorphic: no server or client imports. The browser bundle audit
+ * (`tests/client-bundle-audit.test.ts`) enforces the client half of that.
+ *
+ * See design/19-client-navigation.md §"The `_rsc` cache key".
+ */
+/**
+ * The request headers that vary an RSC payload response, in canonical
+ * casing — this list is also emitted verbatim as the response's `Vary`
+ * tokens (`server/pipeline.ts`), since "what varies the response" is one
+ * question with one answer, not two lists that happen to agree.
+ *
+ * This list is the contract, and it is enforced rather than trusted:
+ * `tests/rsc-cache-key.test.ts` asserts that the header names
+ * `buildRscHeaders()` can emit are exactly this set. A header added to the
+ * request without being added here fails that test, because a varying input
+ * outside the key is precisely the cache-poisoning hazard the key exists to
+ * close.
+ *
+ * **No credentials, session identifiers, or user-supplied content may be
+ * added.** Every value here is hashed into a URL, and URLs are logged by
+ * proxies, CDNs, and origin access logs. `fnv1aHash` is a cache-key hash,
+ * not a KDF — a low-entropy secret would be recoverable by brute force.
+ * Authentication travels on cookies, which never enter the key.
+ */
+export declare const RSC_KEY_HEADERS: readonly ['Accept', 'X-Timber-State-Tree', 'X-Timber-URL', 'X-Timber-Deployment-Id'];
+/**
+ * Whether a value could be a key this module produced.
+ *
+ * `_rsc` is not a reserved parameter name — an application may already use
+ * it for its own search state, including for a value that happens to look
+ * like a digest. Anything without the `KEY_PREFIX` is therefore application
+ * data, not a claim on a payload cache key, and the origin guard leaves it
+ * alone rather than penalizing the response.
+ *
+ * Derived from `KEY_PREFIX` and `KEY_HEX_LENGTH` rather than spelled again,
+ * so the shape cannot drift from the digest that has to satisfy it.
+ *
+ * Ignoring a malformed value costs no protection: clients only ever send
+ * well-formed keys, so a URL bearing a malformed one is an address no
+ * legitimate request will ever ask for, and nothing can be poisoned at an
+ * address nobody reads.
+ */
+export declare function isRscCacheKeyShape(value: string): boolean;
+/**
+ * The query parameter carrying the payload cache key.
+ *
+ * Spelled here rather than at each of the four places that read or write it
+ * — the client that appends it, the origin guard that validates it, and the
+ * strip below — because it is a wire contract between two independent
+ * implementations, exactly like the digest itself.
+ */
+export declare const RSC_KEY_PARAM = "_rsc";
+/**
+ * Remove framework-issued `_rsc` values from a raw query string.
+ *
+ * Only values matching `isRscCacheKeyShape` are removed. `_rsc` is not a
+ * reserved name (see that function), so `/search?_rsc=foo` is application
+ * state and survives — the same exemption the origin guard applies, derived
+ * from the same predicate so the two cannot disagree about what "ours"
+ * means.
+ *
+ * Operates on the raw string rather than round-tripping through
+ * `URLSearchParams`, so every surviving pair keeps its original bytes.
+ * Re-serializing would rewrite `?b` as `?b=` and `?a=%7E` as `?a=~` on RSC
+ * navigations only, which is the same class of inconsistency this function
+ * exists to remove.
+ *
+ * Matching decodes the name, because `?%5Frsc=<key>` is a `_rsc` parameter
+ * as far as `URLSearchParams` is concerned — the same reasoning as the
+ * guard's fast path.
+ *
+ * @param search - `url.search`, with or without the leading `?`.
+ * @returns The query string including a leading `?`, or `''` if empty.
+ */
+export declare function stripRscCacheKey(search: string): string;
+/** A request's search state as application code should see it. */
+export interface AppVisibleSearch {
+    /** Parsed params, with the framework's cache key removed. */
+    params: URLSearchParams;
+    /** The matching raw query string — `''` or `?…`. */
+    search: string;
+}
+/**
+ * The search state application code sees, for any request URL.
+ *
+ * The `_rsc` key rides on the payload URL of every RSC navigation and on no
+ * other request, so reading search params straight off `req.url` makes the
+ * same page observe different search state depending on whether it was
+ * reached by a full load or a client navigation — and lets the cache key
+ * leak into whatever the page builds from it: a canonical URL, a pagination
+ * link, an analytics payload (TIM-1272).
+ *
+ * Every application-facing derivation of search state goes through here.
+ * `params` and `search` are returned together, from one strip, because they
+ * are two views of one answer and were previously two expressions that had
+ * to agree.
+ *
+ * The raw request URL is deliberately untouched: `server/rsc-cache-key-guard.ts`
+ * still reads the parameter from `req.url` to bind the key to the request.
+ */
+export declare function appVisibleSearch(url: URL): AppVisibleSearch;
+/**
+ * Reads a header value by name. Must be case-insensitive — `Headers.get()`
+ * already is, and `recordLookup` below makes a plain record so.
+ */
+export type HeaderLookup = (name: string) => string | null | undefined;
+/**
+ * Compute the `_rsc` cache key for a request.
+ *
+ * Absent headers are omitted rather than sent as empty, so "header missing"
+ * and "header present but empty" produce different keys.
+ *
+ * Values are length-prefixed rather than delimiter-separated. Any delimiter
+ * can be forged by a value that contains it: with a `\0` separator, an
+ * `accept` of `a\nx-timber-url\0b` serializes identically to an `accept` of
+ * `a` alongside an `x-timber-url` of `b`, which would let one header claim
+ * another's key. HTTP forbids control characters in header values and both
+ * `fetch()` and the server runtime reject them, so this is defense in depth
+ * — but a length prefix is unambiguous for *any* content, which is a
+ * property worth having in a function whose whole job is to be agreed on by
+ * two independent implementations.
+ *
+ * SHA-256, truncated to 128 bits. A fast non-cryptographic hash is the
+ * obvious choice for a cache key and is the wrong one here: the origin
+ * *compares* this value against a recomputed one, which makes it a check.
+ * FNV-1a — used for timber's other cache keys — is a multiply-xor over a
+ * fixed field, so an attacker controlling a few bytes of any input (their
+ * own `X-Timber-URL`, say) can solve for a chosen digest rather than search
+ * for one, and forge a key belonging to somebody else.
+ *
+ * Returns `null` when no digest is available — `crypto.subtle` is absent in
+ * non-secure browsing contexts (plain `http://` on a LAN address). Callers
+ * must treat that as "no key", never as "key matches": the client omits the
+ * parameter and the server refuses to share-cache. That returns those
+ * clients to the pre-TIM-1268 posture, where `Vary` alone separates HTML
+ * from Flight — acceptable, because a non-secure origin has no shared-CDN
+ * caching story to protect in the first place.
+ */
+export declare function rscCacheKey(lookup: HeaderLookup): Promise<string | null>;
+/**
+ * An unverifiable stand-in key, for the one case where the digest cannot be
+ * computed: `crypto.subtle` is absent in non-secure browsing contexts.
+ * `crypto.getRandomValues` is not gated that way, so it is available exactly
+ * where the digest is not.
+ *
+ * Carries `KEY_PREFIX` like any other key, so the origin reads it as a claim
+ * it cannot verify — and refuses to share-cache the response — rather than
+ * exempting it as application data. Lives here so the prefix has one home.
+ */
+export declare function randomRscCacheKey(): string;
+/** Build a case-insensitive lookup over a plain header record. */
+export declare function recordLookup(headers: Record<string, string>): HeaderLookup;
+//# sourceMappingURL=rsc-cache-key.d.ts.map

package/dist/shared/rsc-cache-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsc-cache-key.d.ts","sourceRoot":"","sources":["../../src/shared/rsc-cache-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAgCH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,eAAe,YAC1B,QAAQ,EACR,qBAAqB,EACrB,cAAc,EACd,wBAAwB,CAChB,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAIzD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,SAAS,CAAC;AAoBpC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAUvD;AAED,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,MAAM,EAAE,eAAe,CAAC;IACxB,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,gBAAgB,CAG3D;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiB9E;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAI1C;AAED,kEAAkE;AAClE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,YAAY,CAM1E"}

package/dist/shared/rsc-error-envelope.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The hard-navigate error envelope shared by the server and the client router.
+ *
+ * A client-navigation (RSC) request cannot carry an error *page* — the response
+ * body must be Flight data or the decoder crashes. Instead the server answers
+ * with this envelope: an `X-Timber-Error: 1` header and a minimal JSON body.
+ * The client treats it as "give up on SPA navigation and hard-navigate", and
+ * the resulting document request renders the real error page as HTML.
+ *
+ * The header name lives here so the four server producers and the single
+ * client consumer cannot drift apart. See design/10-error-handling.md
+ * §"Error Page Rendering for Client Navigation".
+ */
+/** Header the client checks to decide whether to hard-navigate. */
+export declare const TIMBER_ERROR_HEADER = "X-Timber-Error";
+//# sourceMappingURL=rsc-error-envelope.d.ts.map

package/dist/shared/rsc-error-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsc-error-envelope.d.ts","sourceRoot":"","sources":["../../src/shared/rsc-error-envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,mBAAmB,CAAC"}

package/dist/shared/rsc-manifest.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The RSC manifest — the shape the static build writes and the client reads.
+ *
+ * In `output: 'static'` there is no server at navigation time and a generated
+ * `.rsc` file carries no response headers, so anything a navigation would
+ * normally learn from headers has to be inlined here at build time.
+ *
+ * Route params used to be such a thing (TIM-1255, TIM-1285). They are not any
+ * more: they ride inside the payload, on its root row, so the
+ * `.rsc` file carries them the same way it carries the tree, and the static
+ * path stopped needing a special case (TIM-1294). What is left is the content
+ * hash, which genuinely cannot live inside the file it names.
+ *
+ * Declared once rather than in each half. The producer
+ * (`plugins/static-build.ts`) and the consumer (`client/rsc-fetch.ts`) each
+ * had their own copy, and the copies drifted the moment a field was added to
+ * one — a static SPA navigation then committed `null` for the field the
+ * producer was faithfully writing.
+ *
+ * Isomorphic: no server, client, or build-time imports.
+ */
+export interface RscManifestEntry {
+    /** The content-hashed URL the payload actually lives at, in route space. */
+    url: string;
+}
+/** Keyed by the unhashed `/_rsc/*.rsc` path. */
+export type RscManifest = Record<string, RscManifestEntry>;
+//# sourceMappingURL=rsc-manifest.d.ts.map

package/dist/shared/rsc-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsc-manifest.d.ts","sourceRoot":"","sources":["../../src/shared/rsc-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC;CACb;AAED,gDAAgD;AAChD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC"}

package/dist/shared/rsc-media-type.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The RSC Flight media type, and the request predicate over it.
+ *
+ * One module owns the string because two independently-written spellings of
+ * "is this an RSC request?" must agree, and the consequence of them
+ * disagreeing is cache poisoning rather than a visible bug. The Cloudflare
+ * adapter's `isRsc` decides what may enter the edge cache; the origin's
+ * pipeline decides which headers may vary the response. TIM-1269 made the
+ * adapter's `VARY_HONORED` allowlist exempt `Accept` *because* `isRsc`
+ * excludes Flight responses from the cache, and exempt the `X-Timber-*`
+ * headers *because* the origin reads them only behind its own RSC check. If
+ * one predicate is ever tightened (a real media-type parse, a
+ * parameter-aware match) and the other is not, the adapter can classify a
+ * request as a document while the origin treats it as RSC, and store a
+ * Flight payload under the document's key — the class
+ * `design/48-payload-addressing.md` exists to prevent.
+ *
+ * `tests/rsc-media-type-single-source.test.ts` fails if the literal reappears
+ * in executable source outside this file.
+ *
+ * Isomorphic: zero imports, so `adapters/cloudflare.ts` — which Node's native
+ * ESM loader evaluates before Vite's resolver exists — can load it and
+ * interpolate the value into the generated worker. Same precedent as
+ * `shared/rsc-cache-key.ts`.
+ *
+ * See design/19-client-navigation.md, design/25-production-deployments.md
+ * §"`Vary` and the Workers Cache API".
+ */
+/** Media type of a React Flight payload. */
+export declare const RSC_CONTENT_TYPE = "text/x-component";
+/**
+ * Is this request asking for an RSC payload rather than a full document?
+ *
+ * Substring containment, deliberately: `Accept` is a list, and a client may
+ * send `text/x-component;charset=utf-8` or list it alongside other types.
+ * Tightening this to a real media-type parse is a behaviour change that has
+ * to move the adapter's generated `isRsc` in the same commit — see above.
+ */
+export declare function isRscRequest(req: Request): boolean;
+/**
+ * Does this Content-Type header value designate an RSC Flight payload?
+ *
+ * Case-insensitive exact media-type match per RFC 9110 §8.3.1 — media types
+ * are case-insensitive. Parameters (`;charset=utf-8`) are stripped before
+ * comparison.
+ *
+ * Contrast with `isRscRequest`, which uses substring containment because
+ * `Accept` is a list of types. A `Content-Type` header names exactly one
+ * type, so substring would over-match (e.g. `text/x-component-v2`).
+ */
+export declare function isRscContentType(contentType: string | null): boolean;
+//# sourceMappingURL=rsc-media-type.d.ts.map

package/dist/shared/rsc-media-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsc-media-type.d.ts","sourceRoot":"","sources":["../../src/shared/rsc-media-type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,4CAA4C;AAC5C,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAEnD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAElD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAGpE"}

package/dist/shared/rsc-payload-path.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Where a route's Flight payload lives in `output: 'static'`.
+ *
+ * The static build writes these files and the client fetches them, so the two
+ * halves must agree byte for byte. They used to state the naming rule
+ * separately — `plugins/static-build.ts` for the write and
+ * `client/rsc-fetch.ts` for the read — which is a duplicate representation with
+ * nothing checking it. One function now, called by both.
+ *
+ * ## The shape
+ *
+ * The payload path mirrors the HTML path: every route gets a directory and the
+ * artifact is the `index` inside it.
+ *
+ *   /           → /_rsc/index.rsc          (cf. index.html)
+ *   /about      → /_rsc/about/index.rsc    (cf. about/index.html)
+ *   /blog/hello → /_rsc/blog/hello/index.rsc
+ *
+ * That shape is **injective**, which the previous one (`/about` →
+ * `/_rsc/about.rsc`, root → `/_rsc/index.rsc`) was not: a site with both `/`
+ * and `/index` produced two payloads at `_rsc/index.rsc`, and the second write
+ * won silently — a client navigation to one route was served the other route's
+ * payload, same content type and same shape, undetectable downstream
+ * (TIM-1266).
+ *
+ * Injectivity holds because two distinct non-root routes give distinct
+ * directories, and the root's `/_rsc/index.rsc` has no directory component for
+ * a non-root route to occupy — reaching it would need an empty route path,
+ * which is not a route.
+ *
+ * Isomorphic: no server, client, or build-time imports.
+ */
+/**
+ * The route-space path of a route's static Flight payload.
+ *
+ * @param routePath A route-space pathname: leading slash, no deployment base,
+ *   no query or fragment, no trailing slash (except the root `/`). Callers
+ *   normalize; this function does not, because the two callers normalize from
+ *   different sources (a browser URL, a build-time route entry).
+ */
+export declare function rscPayloadPath(routePath: string): string;
+//# sourceMappingURL=rsc-payload-path.d.ts.map

package/dist/shared/rsc-payload-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsc-payload-path.d.ts","sourceRoot":"","sources":["../../src/shared/rsc-payload-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAGxD"}

package/dist/shared/segment-info.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The segment metadata wire contract between server and client.
+ *
+ * One declaration, imported by both ends. The producer
+ * (`server/rsc-entry/helpers.ts` → `X-Timber-Segments` and the
+ * `self.__timber_segments` bootstrap script) and the consumers
+ * (`client/segment-cache.ts`, the history stack, the prefetch cache) used to
+ * declare this shape separately, which is how a field gets added to one side
+ * only.
+ *
+ * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+ * See design/07-routing.md §"Intercepting Routes"
+ */
+/**
+ * Metadata for one rendered segment or slot, sent via `X-Timber-Segments`.
+ */
+export interface SegmentInfo {
+    /** The segment's URL path (e.g. `/`, `/feed`), or the slot key for slots. */
+    path: string;
+    /** Outlet key — includes route group name when applicable (e.g. `/(marketing)`). */
+    segmentId?: string;
+    /**
+     * The segment's directory path in `app/`, groups included and slots elided
+     * (e.g. `app/(browse)/feed` → `/(browse)/feed`). Absent on slot entries.
+     *
+     * This is the identity interception scoping compares against, and it is the
+     * reason it travels: `path`/`segmentId` are URL-addressed and collapse
+     * `(browse)/feed` and `(landing)/feed` to the same key, while a scope has to
+     * tell those two directories apart. See `computeSegmentTreePaths`.
+     */
+    treePath?: string;
+    isRequestDependent: boolean;
+    /** True for parallel route slot entries, keyed by slot path (e.g. `/@sidebar`). */
+    slot?: boolean;
+    /** Parent segment path for slot entries — attaches the slot to its SegmentNode. */
+    parentSegment?: string;
+    /** True when the slot's access.ts denied on this render. Denied slots are excluded from the state tree. */
+    denied?: boolean;
+    /** True when the slot was skipped (cached content reused). Payloads with skipped slots are not replayable. */
+    skipped?: boolean;
+    /**
+     * Content key for slot entries — encodes owner parts, slot name, matched
+     * entry file, and slot params. The client stores and advertises this key;
+     * the server computes the destination key and checks membership.
+     * Replaces URL-based departing/destination diffing (TIM-1370).
+     */
+    contentKey?: string;
+}
+/**
+ * The client's `X-Timber-State-Tree` request header.
+ *
+ * `segments` and `slots` are a caching optimization — they tell the server what
+ * the client can reuse. `treePaths` is not: it describes the *shape* of the
+ * tree currently on screen, so the server can answer "does the rendered route
+ * pass through the segment that owns this intercepting slot?" without
+ * re-deriving it from the address bar, which stops being the source route the
+ * moment a modal is open (TIM-1282).
+ *
+ * None of the three is a security input. Every `access.ts` runs regardless.
+ */
+export interface StateTree {
+    segments: string[];
+    slots?: string[];
+    treePaths?: string[];
+}
+//# sourceMappingURL=segment-info.d.ts.map

package/dist/shared/segment-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"segment-info.d.ts","sourceRoot":"","sources":["../../src/shared/segment-info.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,mFAAmF;IACnF,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,mFAAmF;IACnF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2GAA2G;IAC3G,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8GAA8G;IAC9G,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB"}

package/dist/shared/slot-params.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Per-slot segment params — the one definition both halves of the API read.
+ *
+ * A parallel slot matches the URL through its *own* sub-tree, so it can derive
+ * a param the main route never had, or derive the same name with a different
+ * type (`[...year]` → `string[]` where the main route's `[year]` gave
+ * `string`). The server answers `getSegmentParams(slotPath)` from a per-slot
+ * map; the client answers `useSegmentParams(slotPath)` from the same map,
+ * published on the RSC payload (TIM-1285).
+ *
+ * The merge lives here rather than in either half because the two must agree
+ * about what "the slot's params" are — a divergence is invisible until
+ * somebody reads a param of the wrong type, which is exactly the class of bug
+ * this module closes.
+ *
+ * Isomorphic: no server or client imports.
+ *
+ * See design/41-global-params.md §"Params in a parallel slot".
+ */
+import type { CoercedParams } from './param-value.ts';
+/** Slot tree path → that slot's own coerced params. */
+export type SlotParamsRecord = Record<string, CoercedParams>;
+/**
+ * The params a slot sees: the main route's as a base, the slot's own on top.
+ *
+ * Params from segments *above* the slot are not re-derived by the slot's own
+ * chain, so they have to come from the main route; params the slot does
+ * re-derive may have a different type than the main route gave them, so the
+ * slot's win.
+ *
+ * Null-prototype, like every other param record the framework hands out
+ * (`coerceSegmentParams` installs one unconditionally). A spread literal would
+ * inherit `Object.prototype`, so a lookup for a param the route does not
+ * define would resolve to an inherited member — `params.constructor` returning
+ * a function instead of `undefined` — in the one param record that was built
+ * by merging. See design/13-security.md #36c.
+ */
+export declare function mergeSlotParams(mainParams: CoercedParams, slotParams: CoercedParams): CoercedParams;
+/**
+ * Resolve the params for a segment path against a published slot map.
+ *
+ * Returns the merge when `segmentPath` names a slot that published params,
+ * and the main route's record otherwise — an ordinary (non-slot) segment
+ * path, an unknown path, or a request with no slots at all. Mirrors the
+ * server's `getSegmentParams(segmentPath)` branch exactly.
+ *
+ * `Object.hasOwn` rather than `in` or a truthiness test: the map arrives from
+ * JSON, so a segment path of `constructor` or `toString` would otherwise
+ * resolve to an inherited member of `Object.prototype`.
+ */
+export declare function resolveSegmentParams(mainParams: CoercedParams, slotParams: SlotParamsRecord | null | undefined, segmentPath: string | undefined): CoercedParams;
+//# sourceMappingURL=slot-params.d.ts.map

package/dist/shared/slot-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slot-params.d.ts","sourceRoot":"","sources":["../../src/shared/slot-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,uDAAuD;AACvD,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAE7D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,aAAa,EACzB,UAAU,EAAE,aAAa,GACxB,aAAa,CAEf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,aAAa,EACzB,UAAU,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EAC/C,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,aAAa,CAGf"}

package/dist/shared/static-platform-files.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Platform files the static build is allowed to overwrite in the output.
+ *
+ * The build merges two trees into the deployed directory — the client bundle
+ * (which carries everything the user put in `public/`) and the pre-rendered
+ * site. That merge otherwise refuses overlaps, because a silent overwrite
+ * leaves one of two artifacts deployed with nothing recording which
+ * (TIM-1266).
+ *
+ * These names are the exception, and only because the pre-rendered copy is
+ * *derived from* the one it replaces rather than competing with it:
+ * `plugins/static-build.ts` reads `public/_redirects` and writes the
+ * generated rules plus the user's, so the winner is a superset of the loser.
+ *
+ * That holds only for a file the current pass produced, which is why
+ * `cleanConditionalArtifacts` deletes a previous build's `_redirects` before
+ * generation: written only when a pass finds redirects, it would otherwise
+ * survive into a pass that produced nothing and claim an exemption it no
+ * longer earns.
+ *
+ * `_headers` is NOT here. It is not written into the pre-rendered tree at
+ * all — adapters generate it directly into the output, folding in the
+ * user's copy as they go (TIM-1326).
+ *
+ * Declared once so the code that performs the merge and the code that
+ * produces the merged file cannot disagree about which names are exempt.
+ *
+ * Isomorphic: no server, client, or build-time imports.
+ */
+/** Platform redirect rules (Cloudflare Pages, Netlify). See TIM-1245/TIM-1249. */
+export declare const REDIRECTS_FILE = "_redirects";
+/** Platform header rules (Cloudflare Pages, Netlify). See TIM-1241/TIM-1326. */
+export declare const HEADERS_FILE = "_headers";
+/**
+ * Where a user authors platform files. Stated once because two modules read
+ * from here — `plugins/static-build.ts` for `_redirects`, adapters for
+ * `_headers` — and they must look in the same place.
+ *
+ * Both read the **project source**, never the build output. The generated
+ * file lands under the same name in the output directory, so a reader aimed
+ * there would fold the previous build's generated rules back in and compound
+ * them on every rebuild.
+ */
+export declare const USER_PLATFORM_DIR = "public";
+/** Output-relative paths whose pre-rendered copy subsumes the `public/` one. */
+export declare const USER_MERGED_PLATFORM_FILES: readonly string[];
+/**
+ * Output paths the framework writes itself, which no route may claim.
+ *
+ * These are written outside the per-entry writer — `_redirects` after
+ * generation, `_headers` by the adapter after the copy — so the collision
+ * tracker never sees them and a route rendering to one of these paths is
+ * overwritten with nothing recording it.
+ *
+ * Reserved rather than tracked, because there is no version of "serve a route
+ * at `/_headers`" that works: Cloudflare Pages and Netlify read these two
+ * files themselves and never serve them, so the route is unservable however
+ * the conflict is resolved.
+ *
+ * That justification is per-file, not per-mechanism. `.nojekyll` is written
+ * the same way and is deliberately NOT here: only the `github-pages` target
+ * writes it, and everywhere else `/.nojekyll` is an ordinary servable path,
+ * so reserving it globally would refuse a valid Cloudflare site. Its write
+ * site skips the write when a file is already there instead — GitHub Pages
+ * only cares that the file exists.
+ *
+ * Same reasoning as the synthetic 404 entry using an internal urlPath so a
+ * real `/404` route cannot collide with `404.html`.
+ */
+export declare const RESERVED_OUTPUT_PATHS: readonly string[];
+//# sourceMappingURL=static-platform-files.d.ts.map

package/dist/shared/static-platform-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-platform-files.d.ts","sourceRoot":"","sources":["../../src/shared/static-platform-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,kFAAkF;AAClF,eAAO,MAAM,cAAc,eAAe,CAAC;AAE3C,gFAAgF;AAChF,eAAO,MAAM,YAAY,aAAa,CAAC;AAEvC;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,WAAW,CAAC;AAE1C,gFAAgF;AAChF,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAAqB,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAAmC,CAAC"}

package/dist/shared/status-reason-phrase.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Reason phrases for the framework default status page.
+ *
+ * Shared between the server-rendered default page (`server/default-status-page.ts`,
+ * the HTML terminal of the deny chain) and its client-rendered counterpart
+ * (`client/deny-last-resort.tsx`, the terminal a streamed deny reaches when no
+ * status file sits at or above the component that denied). One table, so the
+ * two surfaces cannot drift — a reader who sees "403 Forbidden" on a document
+ * load must see the same words after a client navigation.
+ *
+ * Nothing here is caller-supplied text: the phrase is looked up from a clamped
+ * integer, never interpolated from a request. See design/13-security.md
+ * principle 4 ("Errors don't leak").
+ */
+/**
+ * Coerce a status into something safe to put in markup.
+ *
+ * `DenySignal.status` is typed `number` but nothing validates it at
+ * construction, and JS callers can hand us anything. Rather than escaping a
+ * value that should never have been a string, collapse non-integers to 500 —
+ * the page is decoration for a status already on the wire.
+ */
+export declare function displayStatus(status: number): number;
+/** Human-readable phrase for a status code. Never caller-supplied text. */
+export declare function statusReasonPhrase(status: number): string;
+//# sourceMappingURL=status-reason-phrase.d.ts.map

package/dist/shared/status-reason-phrase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-reason-phrase.d.ts","sourceRoot":"","sources":["../../src/shared/status-reason-phrase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA8BH;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAIzD"}

package/dist/shims/font-google.d.ts

@@ -16,7 +16,7 @@
  *
  * Design doc: 24-fonts.md, "Next.js Font Compatibility"
  */
-import type { GoogleFontConfig, FontResult } from '#/fonts/types.js';
+import type { GoogleFontConfig, FontResult } from '../fonts/types.ts';
 export type { GoogleFontConfig, FontResult };
 /**
  * Generic font loader — accepts any font name, returns a stub FontResult.

package/dist/shims/font-google.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"font-google.d.ts","sourceRoot":"","sources":["../../src/shims/font-google.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAErE,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,CAAC;AAkB7C;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,gBAAgB,GAAG,UAAU,CAEjF;AAID,eAAO,MAAM,KAAK,GAAI,SAAS,gBAAgB,KAAG,UAA0C,CAAC;AAC7F,eAAO,MAAM,MAAM,GAAI,SAAS,gBAAgB,KAAG,UAA0C,CAAC;AAC9F,eAAO,MAAM,SAAS,GAAI,SAAS,gBAAgB,KAAG,UAA0C,CAAC;AACjG,eAAO,MAAM,IAAI,GAAI,SAAS,gBAAgB,KAAG,UAA0C,CAAC;AAC5F,eAAO,MAAM,UAAU,GAAI,SAAS,gBAAgB,KAAG,UAA0C,CAAC;AAClG,eAAO,MAAM,OAAO,GAAI,SAAS,gBAAgB,KAAG,UAA0C,CAAC;AAC/F,eAAO,MAAM,KAAK,GAAI,SAAS,gBAAgB,KAAG,UAA0C,CAAC;AAC7F,eAAO,MAAM,UAAU,GAAI,SAAS,gBAAgB,KAAG,UAA0C,CAAC;AAClG,eAAO,MAAM,cAAc,GAAI,SAAS,gBAAgB,KAAG,UAC7B,CAAC;AAC/B,eAAO,MAAM,eAAe,GAAI,SAAS,gBAAgB,KAAG,UAC9B,CAAC;AAC/B,eAAO,MAAM,gBAAgB,GAAI,SAAS,gBAAgB,KAAG,UAC/B,CAAC;AAC/B,eAAO,MAAM,YAAY,GAAI,SAAS,gBAAgB,KAAG,UAA0C,CAAC"}
+{"version":3,"file":"font-google.d.ts","sourceRoot":"","sources":["../../src/shims/font-google.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEtE,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,CAAC;AAkB7C;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,gBAAgB,GAAG,UAAU,CAEjF;AAID,eAAO,MAAM,KAAK,YAAa,gBAAgB,KAAG,UAA0C,CAAC;AAC7F,eAAO,MAAM,MAAM,YAAa,gBAAgB,KAAG,UAA0C,CAAC;AAC9F,eAAO,MAAM,SAAS,YAAa,gBAAgB,KAAG,UAA0C,CAAC;AACjG,eAAO,MAAM,IAAI,YAAa,gBAAgB,KAAG,UAA0C,CAAC;AAC5F,eAAO,MAAM,UAAU,YAAa,gBAAgB,KAAG,UAA0C,CAAC;AAClG,eAAO,MAAM,OAAO,YAAa,gBAAgB,KAAG,UAA0C,CAAC;AAC/F,eAAO,MAAM,KAAK,YAAa,gBAAgB,KAAG,UAA0C,CAAC;AAC7F,eAAO,MAAM,UAAU,YAAa,gBAAgB,KAAG,UAA0C,CAAC;AAClG,eAAO,MAAM,cAAc,YAAa,gBAAgB,KAAG,UAC7B,CAAC;AAC/B,eAAO,MAAM,eAAe,YAAa,gBAAgB,KAAG,UAC9B,CAAC;AAC/B,eAAO,MAAM,gBAAgB,YAAa,gBAAgB,KAAG,UAC/B,CAAC;AAC/B,eAAO,MAAM,YAAY,YAAa,gBAAgB,KAAG,UAA0C,CAAC"}

package/dist/shims/font-google.js

@@ -0,0 +1,42 @@
+//#region src/shims/font-google.ts
+/**
+* Create a stub FontResult with empty values.
+*
+* The timber-fonts plugin replaces these calls at build time with real
+* class names and font stacks. This stub ensures code that imports
+* font functions outside of the build pipeline (tests, type-checking)
+* gets a valid FontResult shape without runtime errors.
+*/
+function createStubFontResult(config) {
+	return {
+		className: "",
+		style: { fontFamily: "" },
+		variable: config?.variable
+	};
+}
+/**
+* Generic font loader — accepts any font name, returns a stub FontResult.
+*
+* Named exports like `Inter`, `Roboto`, etc. are generated dynamically
+* by the virtual module at build time. This function provides a catch-all
+* for non-Vite contexts.
+*/
+function createFont(_family, config) {
+	return createStubFontResult(config);
+}
+var Inter = (config) => createStubFontResult(config);
+var Roboto = (config) => createStubFontResult(config);
+var Open_Sans = (config) => createStubFontResult(config);
+var Lato = (config) => createStubFontResult(config);
+var Montserrat = (config) => createStubFontResult(config);
+var Poppins = (config) => createStubFontResult(config);
+var Geist = (config) => createStubFontResult(config);
+var Geist_Mono = (config) => createStubFontResult(config);
+var JetBrains_Mono = (config) => createStubFontResult(config);
+var Source_Code_Pro = (config) => createStubFontResult(config);
+var Playfair_Display = (config) => createStubFontResult(config);
+var Merriweather = (config) => createStubFontResult(config);
+//#endregion
+export { Geist, Geist_Mono, Inter, JetBrains_Mono, Lato, Merriweather, Montserrat, Open_Sans, Playfair_Display, Poppins, Roboto, Source_Code_Pro, createFont };
+
+//# sourceMappingURL=font-google.js.map

package/dist/shims/font-google.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"font-google.js","names":[],"sources":["../../src/shims/font-google.ts"],"sourcesContent":["/**\n * Fallback shim for `next/font/google` → `@timber/fonts/google`.\n *\n * At build time, the timber-fonts plugin's transform hook replaces font\n * function calls with static FontResult objects containing real class names\n * and font stacks. This file serves two purposes:\n *\n * 1. **TypeScript resolution** — provides types for IDEs and `tsc` outside\n *    of Vite's module graph (where the virtual module handles it).\n * 2. **Runtime fallback** — returns empty className/fontFamily values when\n *    the plugin hasn't processed a call (e.g. in tests or non-Vite environments).\n *\n * The shim resolution path (`next/font/google` → `\\0@timber/fonts/google`)\n * is unchanged — this file is NOT on that resolution path. It exists as a\n * physical module for direct imports and type re-exports.\n *\n * Design doc: 24-fonts.md, \"Next.js Font Compatibility\"\n */\n\nimport type { GoogleFontConfig, FontResult } from '../fonts/types.ts';\n\nexport type { GoogleFontConfig, FontResult };\n\n/**\n * Create a stub FontResult with empty values.\n *\n * The timber-fonts plugin replaces these calls at build time with real\n * class names and font stacks. This stub ensures code that imports\n * font functions outside of the build pipeline (tests, type-checking)\n * gets a valid FontResult shape without runtime errors.\n */\nfunction createStubFontResult(config?: GoogleFontConfig): FontResult {\n  return {\n    className: '',\n    style: { fontFamily: '' },\n    variable: config?.variable,\n  };\n}\n\n/**\n * Generic font loader — accepts any font name, returns a stub FontResult.\n *\n * Named exports like `Inter`, `Roboto`, etc. are generated dynamically\n * by the virtual module at build time. This function provides a catch-all\n * for non-Vite contexts.\n */\nexport function createFont(_family: string, config?: GoogleFontConfig): FontResult {\n  return createStubFontResult(config);\n}\n\n// Common Google Font exports for TypeScript autocomplete.\n// These are stubs — the virtual module and transform hook provide real values.\nexport const Inter = (config?: GoogleFontConfig): FontResult => createStubFontResult(config);\nexport const Roboto = (config?: GoogleFontConfig): FontResult => createStubFontResult(config);\nexport const Open_Sans = (config?: GoogleFontConfig): FontResult => createStubFontResult(config);\nexport const Lato = (config?: GoogleFontConfig): FontResult => createStubFontResult(config);\nexport const Montserrat = (config?: GoogleFontConfig): FontResult => createStubFontResult(config);\nexport const Poppins = (config?: GoogleFontConfig): FontResult => createStubFontResult(config);\nexport const Geist = (config?: GoogleFontConfig): FontResult => createStubFontResult(config);\nexport const Geist_Mono = (config?: GoogleFontConfig): FontResult => createStubFontResult(config);\nexport const JetBrains_Mono = (config?: GoogleFontConfig): FontResult =>\n  createStubFontResult(config);\nexport const Source_Code_Pro = (config?: GoogleFontConfig): FontResult =>\n  createStubFontResult(config);\nexport const Playfair_Display = (config?: GoogleFontConfig): FontResult =>\n  createStubFontResult(config);\nexport const Merriweather = (config?: GoogleFontConfig): FontResult => createStubFontResult(config);\n"],"mappings":";;;;;;;;;AA+BA,SAAS,qBAAqB,QAAuC;CACnE,OAAO;EACL,WAAW;EACX,OAAO,EAAE,YAAY,GAAG;EACxB,UAAU,QAAQ;CACpB;AACF;;;;;;;;AASA,SAAgB,WAAW,SAAiB,QAAuC;CACjF,OAAO,qBAAqB,MAAM;AACpC;AAIA,IAAa,SAAS,WAA0C,qBAAqB,MAAM;AAC3F,IAAa,UAAU,WAA0C,qBAAqB,MAAM;AAC5F,IAAa,aAAa,WAA0C,qBAAqB,MAAM;AAC/F,IAAa,QAAQ,WAA0C,qBAAqB,MAAM;AAC1F,IAAa,cAAc,WAA0C,qBAAqB,MAAM;AAChG,IAAa,WAAW,WAA0C,qBAAqB,MAAM;AAC7F,IAAa,SAAS,WAA0C,qBAAqB,MAAM;AAC3F,IAAa,cAAc,WAA0C,qBAAqB,MAAM;AAChG,IAAa,kBAAkB,WAC7B,qBAAqB,MAAM;AAC7B,IAAa,mBAAmB,WAC9B,qBAAqB,MAAM;AAC7B,IAAa,oBAAoB,WAC/B,qBAAqB,MAAM;AAC7B,IAAa,gBAAgB,WAA0C,qBAAqB,MAAM"}