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

package/src/shared/payload-root.ts

@@ -0,0 +1,152 @@
+/**
+ * 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 { CoercedParams } from './param-value.ts';
+import type { SlotParamsRecord } from './slot-params.ts';
+
+/** The params published beside a tree. */
+export interface PublishedParams {
+  /** The main route's coerced params. */
+  params: CoercedParams;
+  /** 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 const NO_PUBLISHED_PARAMS: PublishedParams = { params: {}, slotParams: null };
+
+/** True when `value` carries published params — a root, or a read of one. */
+function hasPublishedParams(value: unknown): value is PublishedParams {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'params' in value &&
+    typeof (value as PublishedParams).params === 'object' &&
+    (value as PublishedParams).params !== null
+  );
+}
+
+/**
+ * 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 function readPublishedParams(source: unknown): PublishedParams {
+  if (!hasPublishedParams(source)) return NO_PUBLISHED_PARAMS;
+  return { params: source.params, slotParams: source.slotParams ?? null };
+}
+
+/**
+ * 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 function readPayloadTree(root: unknown): unknown {
+  if (typeof root === 'object' && root !== null && 'tree' in root && hasPublishedParams(root)) {
+    return (root as RscPayloadRoot).tree;
+  }
+  return root;
+}
+
+/** 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 function splitPayloadRoot(root: unknown): SplitPayload {
+  if (
+    typeof root !== 'object' ||
+    root === null ||
+    typeof (root as PromiseLike<unknown>).then !== 'function'
+  ) {
+    return { tree: readPayloadTree(root), params: readPublishedParams(root) };
+  }
+  const settled = root as PromiseLike<unknown>;
+  const tree = Promise.resolve(settled).then(readPayloadTree);
+  // The rejection still reaches React through its own read of `tree`; this
+  // only marks it handled for the case where nothing renders it (a partial
+  // navigation whose segment update finds no matching outlet).
+  tree.catch(() => {});
+  const params = Promise.resolve(settled).then(readPublishedParams, () => NO_PUBLISHED_PARAMS);
+  return { tree, params };
+}

package/src/shared/redirect-type.ts

@@ -0,0 +1,17 @@
+/**
+ * Next.js redirect type discriminator.
+ *
+ * Provided for API compatibility with libraries that import `RedirectType`
+ * from `next/navigation`. In timber, `redirect()` always uses `replace`
+ * semantics (no history entry for the redirect itself).
+ *
+ * Lives in shared/ (isomorphic) so both the server primitives and the
+ * client-only next/navigation shim export the same definition without the
+ * client shim pulling in server code.
+ */
+export const RedirectType = {
+  push: 'push',
+  replace: 'replace',
+} as const;
+
+export type RedirectTypeValue = (typeof RedirectType)[keyof typeof RedirectType];

package/src/shared/rsc-cache-key.ts

@@ -0,0 +1,269 @@
+/**
+ * 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".
+ */
+
+/**
+ * Digest length in hex characters. 128 bits: the origin guard compares a
+ * caller-supplied key against a recomputed one, so the relevant bound is a
+ * birthday attack (an attacker who can influence a victim's `X-Timber-URL`
+ * gets to search both sides), not second preimage. 64 bits would fall to
+ * ~2^32 work; 128 puts it at 2^64.
+ */
+const KEY_HEX_LENGTH = 32;
+
+/**
+ * Marks a value as a framework-issued key, and versions the derivation.
+ *
+ * Without it, an application value that happened to be 32 lowercase hex — an
+ * MD5, a token — is indistinguishable from a forged claim: both are "the
+ * right shape, the wrong digest", and no information in the value separates
+ * them. So the exemption cannot key on shape alone.
+ *
+ * The prefix resolves that because it is anchored to the address the
+ * victim's own client uses. A payload lives at `?_rsc=1.<digest>`, so
+ * anything aimed at that cache entry must carry the prefix and therefore
+ * gets validated; anything without it cannot be addressing a payload URL at
+ * all, and is exempt as application data. An attacker cannot both hit the
+ * victim's cache key and dodge the check.
+ *
+ * The version component also gives the derivation a migration path: the
+ * client and the origin must agree byte for byte, so a future change to the
+ * canonical form can be rolled out by bumping this instead of a flag day.
+ */
+const KEY_PREFIX = '1.';
+
+/**
+ * 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 const RSC_KEY_HEADERS = [
+  'Accept',
+  'X-Timber-State-Tree',
+  'X-Timber-URL',
+  'X-Timber-Deployment-Id',
+] as const;
+
+/**
+ * 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 function isRscCacheKeyShape(value: string): boolean {
+  if (!value.startsWith(KEY_PREFIX)) return false;
+  const digest = value.slice(KEY_PREFIX.length);
+  return digest.length === KEY_HEX_LENGTH && /^[0-9a-f]+$/.test(digest);
+}
+
+/**
+ * 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 const RSC_KEY_PARAM = '_rsc';
+
+// ─── Keeping the key out of application state ────────────────────────────
+
+/**
+ * Decode one raw `name` or `value` the way `URLSearchParams` does:
+ * `application/x-www-form-urlencoded`, so `+` is a space.
+ *
+ * Malformed percent-escapes throw in `decodeURIComponent`. `URLSearchParams`
+ * leaves those bytes as-is rather than throwing, and so do we — a pair we
+ * cannot decode is by definition not the framework's, so it is kept.
+ */
+function formDecode(raw: string): string {
+  try {
+    return decodeURIComponent(raw.replace(/\+/g, ' '));
+  } catch {
+    return raw;
+  }
+}
+
+/**
+ * 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 function stripRscCacheKey(search: string): string {
+  const query = search.startsWith('?') ? search.slice(1) : search;
+  if (query === '') return '';
+  const kept = query.split('&').filter((pair) => {
+    const eq = pair.indexOf('=');
+    if (formDecode(eq === -1 ? pair : pair.slice(0, eq)) !== RSC_KEY_PARAM) return true;
+    return !isRscCacheKeyShape(eq === -1 ? '' : formDecode(pair.slice(eq + 1)));
+  });
+  const result = kept.join('&');
+  return result === '' ? '' : `?${result}`;
+}
+
+/** 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 function appVisibleSearch(url: URL): AppVisibleSearch {
+  const search = stripRscCacheKey(url.search);
+  return { params: new URLSearchParams(search), search };
+}
+
+/**
+ * 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 async function rscCacheKey(lookup: HeaderLookup): Promise<string | null> {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) return null;
+  let canonical = '';
+  for (const name of RSC_KEY_HEADERS) {
+    const value = lookup(name);
+    if (value == null) continue;
+    // Lowercased in the canonical form so the two implementations cannot
+    // disagree over the casing of the constant they share.
+    canonical += `${name.toLowerCase()}:${value.length}:${value}`;
+  }
+  const digest = await subtle.digest('SHA-256', new TextEncoder().encode(canonical));
+  let hex = '';
+  for (const byte of new Uint8Array(digest, 0, KEY_HEX_LENGTH / 2)) {
+    hex += byte.toString(16).padStart(2, '0');
+  }
+  return KEY_PREFIX + hex;
+}
+
+/**
+ * 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 function randomRscCacheKey(): string {
+  const bytes = new Uint8Array(KEY_HEX_LENGTH / 2);
+  globalThis.crypto.getRandomValues(bytes);
+  return KEY_PREFIX + [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/** Build a case-insensitive lookup over a plain header record. */
+export function recordLookup(headers: Record<string, string>): HeaderLookup {
+  const lowered: Record<string, string> = {};
+  for (const name of Object.keys(headers)) {
+    lowered[name.toLowerCase()] = headers[name];
+  }
+  return (name) => lowered[name.toLowerCase()];
+}

package/src/shared/rsc-error-envelope.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 const TIMBER_ERROR_HEADER = 'X-Timber-Error';

package/src/shared/rsc-manifest.ts

@@ -0,0 +1,29 @@
+/**
+ * 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>;

package/src/shared/rsc-media-type.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 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 function isRscRequest(req: Request): boolean {
+  return (req.headers.get('Accept') ?? '').includes(RSC_CONTENT_TYPE);
+}
+
+/**
+ * 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 function isRscContentType(contentType: string | null): boolean {
+  if (!contentType) return false;
+  return contentType.split(';')[0].trim().toLowerCase() === RSC_CONTENT_TYPE;
+}

package/src/shared/rsc-payload-path.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 function rscPayloadPath(routePath: string): string {
+  const prefix = routePath === '/' ? '' : routePath;
+  return `/_rsc${prefix}/index.rsc`;
+}

package/src/shared/segment-info.ts

@@ -0,0 +1,67 @@
+/**
+ * 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[];
+}