@timber-js/app 0.2.0-alpha.184 → 0.2.0-alpha.186

package/dist/server/status-code-resolver.d.ts

@@ -19,9 +19,8 @@
  *
  * **Component chain (4xx):**
  *   Pass 1 — status files (leaf → root): {status}.tsx → 4xx.tsx
- *   Pass 2 — legacy compat (leaf → root): not-found.tsx / forbidden.tsx / unauthorized.tsx
- *   Pass 3 — error.tsx (leaf → root)
- *   Pass 4 — framework default (returns null)
+ *   Pass 2 — error.tsx (leaf → root)
+ *   Pass 3 — framework default (returns null)
  *
  * **JSON chain (4xx and 5xx):**
  *   Pass 1 — json status files (leaf → root): {status}.json → {category}.json
@@ -33,7 +32,7 @@
  */
 import type { SegmentNode } from '../routing/types.js';
 /** How the status-code file was matched. */
-export type StatusFileKind = 'exact' | 'category' | 'legacy' | 'error';
+export type StatusFileKind = 'exact' | 'category' | 'error';
 /** Response format family for status-code resolution. */
 export type StatusFileFormat = 'component' | 'json';
 /** Result of resolving a status-code file for a segment chain. */
@@ -58,12 +57,6 @@ export interface SlotDeniedResolution<TFile> {
     /** How the file was matched. */
     kind: SlotDeniedKind;
 }
-/**
- * Maps legacy file convention names to their corresponding HTTP status codes.
- * Only used in the 4xx component fallback chain. Exported so the in-tree
- * deny chain (deny-boundary.ts) uses the same mapping — see TIM-1081.
- */
-export declare const LEGACY_FILE_TO_STATUS: Record<string, number>;
 /**
  * Resolve the status-code file to render for a given HTTP status code.
  *

package/dist/server/status-code-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status-code-resolver.d.ts","sourceRoot":"","sources":["../../src/server/status-code-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIvD,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GACtB,OAAO,GACP,UAAU,GACV,QAAQ,GACR,OAAO,CAAC;AAEZ,yDAAyD;AACzD,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,MAAM,CAAC;AAEpD,kEAAkE;AAClE,MAAM,WAAW,oBAAoB,CAAC,KAAK;IACzC,8BAA8B;IAC9B,IAAI,EAAE,KAAK,CAAC;IACZ,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,IAAI,EAAE,cAAc,CAAC;IACrB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,0CAA0C;AAC1C,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,CAAC;AAElD,8CAA8C;AAC9C,MAAM,WAAW,oBAAoB,CAAC,KAAK;IACzC,0DAA0D;IAC1D,IAAI,EAAE,KAAK,CAAC;IACZ,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,IAAI,EAAE,cAAc,CAAC;CACtB;AAID;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAIxD,CAAC;AAkDF;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EACrC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,aAAa,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAC3C,MAAM,GAAE,gBAA8B,GACrC,oBAAoB,CAAC,KAAK,CAAC,GAAG,IAAI,CAKpC;AA0FD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EACrC,QAAQ,EAAE,WAAW,CAAC,KAAK,CAAC,GAC3B,oBAAoB,CAAC,KAAK,CAAC,GAAG,IAAI,CAYpC"}
+{"version":3,"file":"status-code-resolver.d.ts","sourceRoot":"","sources":["../../src/server/status-code-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIvD,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GACtB,OAAO,GACP,UAAU,GACV,OAAO,CAAC;AAEZ,yDAAyD;AACzD,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,MAAM,CAAC;AAEpD,kEAAkE;AAClE,MAAM,WAAW,oBAAoB,CAAC,KAAK;IACzC,8BAA8B;IAC9B,IAAI,EAAE,KAAK,CAAC;IACZ,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,IAAI,EAAE,cAAc,CAAC;IACrB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,0CAA0C;AAC1C,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,CAAC;AAElD,8CAA8C;AAC9C,MAAM,WAAW,oBAAoB,CAAC,KAAK;IACzC,0DAA0D;IAC1D,IAAI,EAAE,KAAK,CAAC;IACZ,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,IAAI,EAAE,cAAc,CAAC;CACtB;AA4BD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EACrC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,aAAa,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAC3C,MAAM,GAAE,gBAA8B,GACrC,oBAAoB,CAAC,KAAK,CAAC,GAAG,IAAI,CAKpC;AAoFD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EACrC,QAAQ,EAAE,WAAW,CAAC,KAAK,CAAC,GAC3B,oBAAoB,CAAC,KAAK,CAAC,GAAG,IAAI,CAYpC"}

package/dist/shared/als-slots.d.ts

@@ -0,0 +1,41 @@
+/**
+ * ALS getter slots for the isomorphic `define*` modules.
+ *
+ * `searchParams.get()` and `segmentParams.get()` read per-request state out of
+ * `server/als-registry.ts`, but the modules that expose them are *isomorphic*:
+ * `search-params/define.ts` and `segment-params/define.ts` are imported by
+ * `'use client'` components for their hooks, so neither may import
+ * `node:async_hooks` — not even transitively, because the dep optimizer
+ * pre-bundles them before per-environment resolution runs. So the server
+ * registers its getter into a slot at module-init time and the define modules
+ * read the slot.
+ *
+ * The slots live here, in a module with **no imports at all**, rather than in
+ * the define modules themselves. That is the whole point: `request-context.ts`
+ * has to reach the setter, and when the setter lived in
+ * `search-params/define.ts` every server entry that touched
+ * `@timber-js/app/server` pulled that module — and therefore its `'use client'`
+ * import of `client/use-query-states.ts`, and therefore `nuqs` — into the
+ * server graph. `nuqs` named-imports `createContext`/`useContext` from React,
+ * which React's `react-server` export withholds, so `@timber-js/app`,
+ * `@timber-js/app/server`, `@timber-js/app/cookies` and `@timber-js/app/cache`
+ * all failed to instantiate under the `react-server` condition (TIM-1298).
+ * A leaf module breaks the edge without a registration ceremony on either side.
+ *
+ * Registration must be eager, not a call-time `await import()`: the async
+ * microtask a dynamic import introduces loses AsyncLocalStorage context inside
+ * React's RSC Flight renderer, which broke `getSearchParams()` in parallel slot
+ * pages (TIM-523).
+ *
+ * See design/23-search-params.md §"defineSearchParams — The Factory" and
+ * design/41-global-params.md.
+ */
+/** @internal Called from `server/request-context.ts` at module init. */
+export declare const _setGetSearchParamsFn: (fn: () => URLSearchParams) => void;
+/** @internal Read by `search-params/define.ts` inside `.get()`. */
+export declare const getSearchParamsFromAls: () => URLSearchParams;
+/** @internal Called from `server/request-context.ts` at module init. */
+export declare const _setGetSegmentParamsFn: (fn: () => Record<string, string | string[]>) => void;
+/** @internal Read by `segment-params/define.ts` inside `.get()`. */
+export declare const getSegmentParamsFromAls: () => Record<string, string | string[]>;
+//# sourceMappingURL=als-slots.d.ts.map

package/dist/shared/als-slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"als-slots.d.ts","sourceRoot":"","sources":["../../src/shared/als-slots.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAgCH,wEAAwE;AACxE,eAAO,MAAM,qBAAqB,iCA7Bd,IA6BqC,CAAC;AAC1D,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,uBAAuB,CAAC;AAE3D,wEAAwE;AACxE,eAAO,MAAM,sBAAsB,mDAlCf,IAkCuC,CAAC;AAC5D,oEAAoE;AACpE,eAAO,MAAM,uBAAuB,yCAAwB,CAAC"}

package/dist/shared/base-path.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Deployment base path — Vite's resolved `base`, as it applies to the URLs
+ * timber addresses at runtime.
+ *
+ * A static build deployed under a sub-path (`base: '/repo/'`, the GitHub
+ * Pages project-site layout) serves every generated file below that prefix:
+ * the document for `/about` lives at `/repo/about/index.html`, its flight
+ * payload at `/repo/_rsc/about/index.rsc`. The client works in *route space* — the
+ * paths the app declares — so both a strip (browser URL → route path) and a
+ * prefix (route-space path → URL) are needed, and this module owns both.
+ *
+ * Pure functions, no state: the caller supplies the base. `client/rsc-fetch.ts`
+ * holds the client's copy, set at bootstrap from `virtual:timber-config`.
+ *
+ * See design/11-platform.md §"Deploying under a non-root base" (TIM-1261).
+ */
+/**
+ * True when `base` is document-relative (`'./'`, `'foo/'`) — it makes asset
+ * URLs resolve against whatever document loaded them, which says nothing
+ * about where the deployment sits, so no prefix can be computed from it.
+ */
+export declare function isRelativeBase(base: string | undefined): boolean;
+/**
+ * Normalize Vite's `base` into a path prefix. Always returns a value with a
+ * leading and trailing slash.
+ *
+ * Two forms carry no usable deployment prefix and normalize to `/`:
+ *
+ * - **An absolute-URL base** points *assets* at a CDN. The HTML documents and
+ *   `.rsc` payloads are still served from the deployment origin, so their
+ *   URLs stay root-relative. This is correct, not a degradation.
+ * - **A relative base** — see `isRelativeBase`. The static build warns,
+ *   because SPA navigation then only works at the domain root.
+ */
+export declare function normalizeBasePath(base: string | undefined): string;
+/**
+ * Strip the base prefix from a browser pathname, returning the route-space
+ * path. With base `/repo/`: `/repo/about` → `/about`, `/repo/` and `/repo`
+ * → `/`.
+ *
+ * A pathname outside the base is returned unchanged. It cannot be served by
+ * this deployment at all, so there is no better answer than letting the
+ * resulting fetch 404 and the router hard-navigate — visibly wrong beats
+ * silently rewritten.
+ *
+ * @param base A normalized base (see `normalizeBasePath`).
+ */
+export declare function stripBasePath(base: string, pathname: string): string;
+/**
+ * Prefix a route-space, root-relative path with the base.
+ * `/_rsc/about/index.rsc` → `/repo/_rsc/about/index.rsc`.
+ *
+ * @param base A normalized base (see `normalizeBasePath`).
+ */
+export declare function withBasePath(base: string, path: string): string;
+//# sourceMappingURL=base-path.d.ts.map

package/dist/shared/base-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-path.d.ts","sourceRoot":"","sources":["../../src/shared/base-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAGhE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAIlE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMpE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG/D"}

package/dist/shared/param-value.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The canonical form of a segment param value.
+ *
+ * `getSegmentParams()` on the server and `useSegmentParams()` on the client
+ * must return the same value — same prototype, same own properties. This
+ * module is how that is guaranteed, and the mechanism matters:
+ *
+ * **Both sides are images of one normalizer.** A codec's output is deep-cloned
+ * into a closed canonical domain at coercion time, and *that clone* is what the
+ * server returns and what goes on the wire. Server and client agree by
+ * construction, because neither holds the codec's original.
+ *
+ * That replaces predicting what React Flight would do to an arbitrary value.
+ * Prediction is what the previous design attempted and it cannot be finished:
+ * the question "will Flight's decode output be observably identical to this
+ * input?" ranges over every way a JS object can carry state that is not in its
+ * serialization — own keys, enumerability, symbols, holes, accessors,
+ * subclassing, exotic objects — and a `Proxy` defeats it outright, since a
+ * lying `getPrototypeOf` trap makes any static check unsound. Twelve review
+ * findings on PR #992 were each one more case of that set, and the set does
+ * not close.
+ *
+ * Normalizing closes it. The only remaining question is whether Flight
+ * round-trips the normalizer's *output range* — a finite domain we defined,
+ * covered by `tests/e2e/segment-params.test.ts` against the real serializer.
+ *
+ * ## The domain
+ *
+ * - `undefined`, `null`, `string`, `number`, `boolean`, `bigint`
+ * - null-prototype objects, own enumerable string keys only
+ * - dense arrays
+ * - `Date`, `Map`, `Set` — rebuilt, never the codec's instance
+ *
+ * ...and it is a **tree**: no value appears twice, and nothing is cyclic.
+ * That is not a simplification, it is the last prediction being removed.
+ * Flight encodes a `Date` by value at each occurrence but tracks plain objects
+ * for reference dedup, so preserving aliasing would carry it across for some
+ * types and drop it for others — and knowing which is exactly the kind of
+ * guess this design exists to stop making (codex, PR #992). A tree has no
+ * sharing to preserve or lose, so what Flight does about it is unobservable.
+ *
+ * Anything else throws, naming the param and what it was. Note what is *not*
+ * a rejection: a `Date` subclass normalizes to a `Date`, a decorated array to
+ * a plain one, a sparse array to a dense one, a getter to the value it
+ * returned. Those used to be twelve separate checks. They are not divergences
+ * any more, because the normalization happens once and both sides see its
+ * result — so they need no checks at all.
+ *
+ * Own properties that Flight would drop (non-enumerable, symbol-keyed) are
+ * dropped here instead, symmetrically. Prototype pollution is handled by the
+ * same pass: `__proto__` is never copied, and every object is
+ * `Object.create(null)` (design/13-security.md #36b/#36c, TIM-873).
+ *
+ * ## The prototype flip
+ *
+ * Flight refuses to serialize a null-prototype object, so the canonical form
+ * cannot go on the wire as-is. `toPlainRecord` and `toNullProtoRecord` flip
+ * the prototype on the way out and back. They are exact inverses and both
+ * total, because they only ever see canonical values — there is nothing to
+ * validate and no shape to special-case.
+ *
+ * See design/41-global-params.md §"Transport".
+ */
+/**
+ * Deep-clone a codec's output into the canonical form, or throw.
+ *
+ * `seen` accumulates every object the walk has entered, and a second encounter
+ * is rejected. That is one rule for two things — a shared reference and a cycle
+ * are both "this object again" — and it is what keeps the result a tree.
+ */
+export declare function normalizeParamValue(value: unknown, path?: string): unknown;
+/**
+ * Canonical form → wire form. React Flight rejects a null prototype
+ * ("Classes or null prototypes are not supported"), so objects cross as plain
+ * ones and are restored on arrival.
+ */
+export declare function toPlainRecord<T>(value: T): T;
+/** Wire form → canonical form. The exact inverse of `toPlainRecord`. */
+export declare function toNullProtoRecord<T>(value: T): T;
+//# sourceMappingURL=param-value.d.ts.map

package/dist/shared/param-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"param-value.d.ts","sourceRoot":"","sources":["../../src/shared/param-value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAqBH;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,SAAK,GAAG,OAAO,CAEtE;AAmGD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAE5C;AAED,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAEhD"}

package/dist/shared/payload-root.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The shape of an RSC payload's root row.
+ *
+ * Every tree the server sends the browser is serialized as
+ * `{ tree, params, slotParams }` — the route's element tree, plus the coerced
+ * params it rendered with, as *siblings* rather than as a wrapper around the
+ * tree. See design/41-global-params.md §"Transport".
+ *
+ * Two reasons it is a sibling field rather than a provider inside the payload
+ * (TIM-1297, which is TIM-1294's mechanism corrected):
+ *
+ * 1. **A provider inside the payload cannot serve a partial navigation.** The
+ *    client keeps the previous tree and splices the new payload in at the
+ *    first updated `SegmentOutlet`, so the payload's own provider lands
+ *    *below* the retained region — and the retained region's root is the
+ *    *departing* route's provider, which therefore wins for every reader in a
+ *    skipped layout. Wrapping something above it does not help: context
+ *    resolves to the nearest provider, and the departing one is nearer.
+ *    Params belong to the *navigation*, so the provider has to be owned by the
+ *    client, above the merge point, and there must be exactly one.
+ *
+ * 2. **Element props are not readable at the instant the root resolves.**
+ *    Flight outlines a React element's props and fills the record in after the
+ *    root row resolves, so a reader that unblocks on the root sees `{}` — and
+ *    since the object is filled *in place*, its identity never changes and any
+ *    memo keyed on it caches the empty snapshot permanently. A plain model
+ *    field has no such window: the root chunk stays blocked until everything
+ *    it references has resolved.
+ *
+ * This module is the single declaration of that shape. The server builds roots
+ * through `server/publish-params.ts` and the client reads them through the
+ * helpers here — producer and consumer do not each describe the payload.
+ */
+import type { SlotParamsRecord } from './slot-params.js';
+/** The params published beside a tree. */
+export interface PublishedParams {
+    /** The main route's coerced params. */
+    params: Record<string, string | string[]>;
+    /** Per-slot params, or null when the route rendered no slots with params. */
+    slotParams: SlotParamsRecord | null;
+}
+/**
+ * Params ready to publish: settled, or a promise the root provider suspends on.
+ *
+ * Both forms exist on purpose. The hydration path cannot await — `hydrateRoot`
+ * has to be called before the inline Flight stream has necessarily produced
+ * the root row — so it hands over the promise and suspends exactly where React
+ * was already going to suspend on the tree. Every other path settles it inside
+ * the navigation transition first, which is what keeps a decode failure inside
+ * the app's own error boundaries instead of above them (TIM-1297).
+ */
+export type ParamsSource = PublishedParams | Promise<PublishedParams>;
+/** The root row of an RSC payload. */
+export interface RscPayloadRoot extends PublishedParams {
+    /** The route's element tree. */
+    tree: unknown;
+}
+/**
+ * What a reader gets when the value it was handed is not a payload root.
+ *
+ * In the browser this is unreachable for a real response: all four producers
+ * of a route payload go through `withPublishedParams`, and a client talking to
+ * a different build is answered with 204 at Stage 1c
+ * (`server/pipeline-phases.ts`) before any payload exists. It is reachable in
+ * the router's test/fallback path, where `decodeRsc` is absent and the
+ * "payload" is the raw response text.
+ */
+export declare const NO_PUBLISHED_PARAMS: PublishedParams;
+/**
+ * Read the params published beside a tree.
+ *
+ * Accepts a payload root *or* a `PublishedParams` already split off one, so
+ * the client can pre-resolve on the navigation path and still hand the same
+ * value to the same provider. Never throws.
+ */
+export declare function readPublishedParams(source: unknown): PublishedParams;
+/**
+ * Read the renderable tree out of a payload root.
+ *
+ * Returns the value unchanged when it is not a root — the router's fallback
+ * path stores raw response text under the same name, and a test asserting on
+ * that text should see the text.
+ */
+export declare function readPayloadTree(root: unknown): unknown;
+/** A decoded payload, split into the two things the client does with it. */
+export interface SplitPayload {
+    /** The renderable tree — an element, or a thenable React suspends on. */
+    tree: unknown;
+    /**
+     * The params published beside it. Settled when the root already is, so the
+     * hydration path can render without an extra await.
+     *
+     * **Never rejects.** A decode failure has to surface where React renders
+     * `tree`, so the error boundary *around the tree* catches it. Rejecting here
+     * too would take down the provider above every boundary in the app, turning
+     * a contained failure into a blank page (TIM-1297).
+     */
+    params: ParamsSource;
+}
+/**
+ * Split a decoded payload root into its tree and its params.
+ *
+ * Accepts a settled root or a thenable of one, and preserves which it was: a
+ * settled root splits synchronously, so no code path gains a suspend point it
+ * did not already have.
+ */
+export declare function splitPayloadRoot(root: unknown): SplitPayload;
+//# sourceMappingURL=payload-root.d.ts.map

package/dist/shared/payload-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload-root.d.ts","sourceRoot":"","sources":["../../src/shared/payload-root.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,6EAA6E;IAC7E,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;AAEtE,sCAAsC;AACtC,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD,gCAAgC;IAChC,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAE,eAAkD,CAAC;AAarF;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,eAAe,CAGpE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAKtD;AAED,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,IAAI,EAAE,OAAO,CAAC;IACd;;;;;;;;OAQG;IACH,MAAM,EAAE,YAAY,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,YAAY,CAgB5D"}

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,25 @@
+/**
+ * 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";
+/**
+ * Build the hard-navigate envelope for a status code.
+ *
+ * `responseHeaders` carries anything middleware already set (cookies, cache
+ * directives); the content type and error header are overwritten because the
+ * body is always this envelope. The body deliberately carries no message —
+ * only the status already on the wire (design/13-security.md principle 4).
+ */
+export declare function rscErrorEnvelope(status: number, responseHeaders?: Headers): Response;
+//# 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;AAEpD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,OAAO,GAAG,QAAQ,CAKpF"}

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-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"}