@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

package/dist/server/version-skew.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Version Skew Detection — graceful recovery when stale clients hit new deployments.
+ *
+ * When a new version of the app is deployed, clients with open tabs still have
+ * the old JavaScript bundle. Without version skew handling, these stale clients
+ * will experience:
+ *
+ * 1. Server action calls that crash (action IDs are content-hashed)
+ * 2. Chunk load failures (old filenames gone from CDN)
+ * 3. RSC payload mismatches (component references differ between builds)
+ *
+ * This module implements deployment ID comparison:
+ * - A per-build deployment ID is generated at build time (see build-manifest.ts)
+ * - The client sends it via `X-Timber-Deployment-Id` header on every RSC/action request
+ * - The server compares it against the current build's ID
+ * - On mismatch: signal the client to reload (not crash)
+ *
+ * The deployment ID is always-on in production. Dev mode skips the check
+ * (HMR handles code updates without full reloads).
+ *
+ * See design/25-production-deployments.md, TIM-446
+ */
+/** Header sent by the client with every RSC/action request. */
+export declare const DEPLOYMENT_ID_HEADER = "X-Timber-Deployment-Id";
+/** Response header that signals the client to do a full page reload. */
+export declare const RELOAD_HEADER = "X-Timber-Reload";
+/**
+ * Set the current deployment ID. Called once at server startup from the
+ * manifest init module. In dev mode this is never called (deployment ID
+ * checks are skipped).
+ */
+export declare function setDeploymentId(id: string): void;
+/**
+ * Get the current deployment ID. Returns null in dev mode.
+ */
+export declare function getDeploymentId(): string | null;
+/** Result of a version skew check. */
+export interface SkewCheckResult {
+    /** Whether the client's deployment ID matches the server's. */
+    ok: boolean;
+    /** The client's deployment ID (null if header not sent — e.g., initial page load). */
+    clientId: string | null;
+}
+/**
+ * Check if a request's deployment ID matches the current build.
+ *
+ * Returns `{ ok: true }` when:
+ * - Dev mode (no deployment ID set — HMR handles updates)
+ * - No deployment ID header (initial page load, non-RSC request)
+ * - Deployment IDs match
+ *
+ * Returns `{ ok: false }` when:
+ * - Client sends a deployment ID that differs from the current build
+ */
+export declare function checkVersionSkew(req: Request): SkewCheckResult;
+/**
+ * Apply version skew reload headers to a response.
+ * Sets X-Timber-Reload: 1 to signal the client to do a full page reload.
+ */
+export declare function applyReloadHeaders(headers: Headers): void;
+//# sourceMappingURL=version-skew.d.ts.map

package/dist/server/version-skew.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-skew.d.ts","sourceRoot":"","sources":["../../src/server/version-skew.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,+DAA+D;AAC/D,eAAO,MAAM,oBAAoB,2BAA2B,CAAC;AAE7D,wEAAwE;AACxE,eAAO,MAAM,aAAa,oBAAoB,CAAC;AAU/C;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAEhD;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAE/C;AAID,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,EAAE,EAAE,OAAO,CAAC;IACZ,sFAAsF;IACtF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,CAmB9D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAEzD"}

package/dist/server/workers-cache-bridge.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Per-request Workers Cache purge bridge — ALS bridge for Cloudflare adapter.
+ *
+ * The generated _worker.js wraps each request with `runWithWorkersCachePurge`,
+ * binding `ctx.cache` from the Cloudflare ExecutionContext. The
+ * `WorkersCachePurge` CDN purge handler reads from this ALS to call
+ * `ctx.cache.purge({ tags })` without needing an API token.
+ *
+ * Design doc: design/06-caching.md, design/25-production-deployments.md
+ */
+import type { WorkersCachePurgeCtx } from './als-registry.ts';
+/**
+ * Run a function with Workers Cache purge context available.
+ *
+ * Called by the generated Cloudflare _worker.js entry to bind
+ * `ctx.cache` for the request duration.
+ */
+export declare function runWithWorkersCachePurge<T>(ctx: WorkersCachePurgeCtx, fn: () => T): T;
+/**
+ * Get the current request's Workers Cache context, if available.
+ *
+ * Returns undefined outside a Cloudflare Workers request context
+ * or on platforms without Workers Cache support.
+ */
+export declare function getWorkersCachePurgeCtx(): WorkersCachePurgeCtx | undefined;
+//# sourceMappingURL=workers-cache-bridge.d.ts.map

package/dist/server/workers-cache-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workers-cache-bridge.d.ts","sourceRoot":"","sources":["../../src/server/workers-cache-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9D;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,GAAG,EAAE,oBAAoB,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAErF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,oBAAoB,GAAG,SAAS,CAE1E"}

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

@@ -0,0 +1,42 @@
+/**
+ * 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.
+ */
+import type { CoercedParams } from './param-value.ts';
+/** @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: () => CoercedParams) => void;
+/** @internal Read by `segment-params/define.ts` inside `.get()`. */
+export declare const getSegmentParamsFromAls: () => CoercedParams;
+//# 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;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAgCtD,wEAAwE;AACxE,eAAO,MAAM,qBAAqB,iCA7Bd,IA6BqC,CAAC;AAC1D,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,uBAAuB,CAAC;AAE3D,wEAAwE;AACxE,eAAO,MAAM,sBAAsB,+BAlCf,IAkCuC,CAAC;AAC5D,oEAAoE;AACpE,eAAO,MAAM,uBAAuB,qBAAwB,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/href-validation.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared href/URL validation for all navigation sinks.
+ *
+ * Used by <Link>, useRouter().push/replace, and redirectExternal().
+ * Single source of truth for dangerous-scheme detection — prevents
+ * control-character smuggling that bypasses naive regex checks.
+ *
+ * See design/13-security.md §"Link scheme injection" (test #9)
+ * and design/07-routing.md §"<Link> Scheme Validation".
+ */
+/**
+ * Validate an href for navigation sinks (<Link>, useRouter, etc.).
+ *
+ * Rejects dangerous schemes (javascript:, data:, vbscript:) even when
+ * control characters are embedded to bypass naive regex checks.
+ * Also rejects protocol-relative URLs (//evil.com).
+ *
+ * Throws on rejection. Safe hrefs pass through silently.
+ */
+export declare function validateNavigationHref(href: string): void;
+/**
+ * Check if an href is internal (same-origin navigation) or external.
+ *
+ * Strips control characters before checking so that "java\tscript:" is
+ * correctly identified as having a scheme (and thus not internal).
+ */
+export declare function isInternalHref(href: string): boolean;
+/**
+ * Assert that a redirect target is a relative path — rejects absolute and
+ * protocol-relative URLs. Used by both the server `redirect()` primitive and
+ * the client next/navigation shim so they enforce identical semantics.
+ *
+ * Normalizes for validation only: strips C0 controls, trims, then replaces
+ * backslashes with forward slashes. Browsers normalize \ → / during URL
+ * resolution, so "/\evil.com" becomes "//evil.com" (protocol-relative open
+ * redirect). See design/13-security.md tests #8, #8a–#8c.
+ */
+export declare function assertRelativeRedirectPath(path: string): void;
+/**
+ * Validate and canonicalize an external redirect URL.
+ *
+ * Requires http: or https: scheme and checks origin against an allow-list.
+ * Returns the parsed canonical URL string (from URL.href) to prevent
+ * raw user input from reaching the Location header.
+ *
+ * @throws On invalid URL, dangerous scheme, or origin not in allow-list.
+ */
+export declare function validateExternalRedirectUrl(url: string, allowList: string[]): string;
+//# sourceMappingURL=href-validation.d.ts.map

package/dist/shared/href-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"href-validation.d.ts","sourceRoot":"","sources":["../../src/shared/href-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAuBH;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAqBzD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUpD;AAKD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAiB7D;AAID;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAiCpF"}

package/dist/shared/merge-search-params.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared utility for merging preserved search params into a target URL.
+ *
+ * Used by both <Link> (client) and redirect() (server). Extracted to a shared
+ * module to avoid importing client code ('use client') from server modules.
+ */
+/**
+ * Merge preserved search params from the current URL into a target href.
+ *
+ * When `preserve` is `true`, all current search params are merged.
+ * When `preserve` is a `string[]`, only the named params are merged.
+ *
+ * The target href's own search params take precedence — preserved params
+ * are only added if the target doesn't already define them.
+ *
+ * @param targetHref - The resolved target href (may already contain query string)
+ * @param currentSearch - The current URL's search string (e.g. "?private=access&page=2")
+ * @param preserve - `true` to preserve all, or `string[]` to preserve specific params
+ * @returns The target href with preserved search params merged in
+ */
+export declare function mergePreservedSearchParams(targetHref: string, currentSearch: string, preserve: true | string[]): string;
+//# sourceMappingURL=merge-search-params.d.ts.map

package/dist/shared/merge-search-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-search-params.d.ts","sourceRoot":"","sources":["../../src/shared/merge-search-params.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,IAAI,GAAG,MAAM,EAAE,GACxB,MAAM,CA6BR"}

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

@@ -0,0 +1,104 @@
+/**
+ * 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".
+ */
+/**
+ * A single segment param value after codec coercion and normalization.
+ *
+ * Before coercion, every param is `string | string[]` (the raw URL part).
+ * After `app/schema.ts` codecs run, a param can be any value in the
+ * `normalizeParamValue` domain below. This type replaces the previous
+ * `string | string[]` declaration, which was a lie whenever a codec
+ * produced a non-string value (TIM-1347).
+ *
+ * The typed accessor `getSegmentParams(SEGMENT_PATH)` resolves through
+ * the schema and returns the exact type the codec declares. This type
+ * covers the untyped/no-argument form and internal plumbing.
+ */
+export type CoercedParamValue = string | number | boolean | bigint | null | undefined | Date | Map<CoercedParamValue, CoercedParamValue> | Set<CoercedParamValue> | CoercedParamValue[] | {
+    [key: string]: CoercedParamValue;
+};
+/**
+ * A record of coerced segment params, keyed by param name.
+ *
+ * This is the post-coercion type for `segmentParams` throughout the
+ * framework. Before coercion (route matcher output, `rawSegmentParams`),
+ * the type is `Record<string, string | string[]>`.
+ */
+export type CoercedParams = Record<string, CoercedParamValue>;
+/**
+ * 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): CoercedParamValue;
+/**
+ * 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;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN,MAAM,GACN,OAAO,GACP,MAAM,GACN,IAAI,GACJ,SAAS,GACT,IAAI,GACJ,GAAG,CAAC,iBAAiB,EAAE,iBAAiB,CAAC,GACzC,GAAG,CAAC,iBAAiB,CAAC,GACtB,iBAAiB,EAAE,GACnB;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAAA;CAAE,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAqB9D;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,SAAK,GAAG,iBAAiB,CAEhF;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,109 @@
+/**
+ * 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 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,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,MAAM,EAAE,aAAa,CAAC;IACtB,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/redirect-type.d.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 declare const RedirectType: {
+    readonly push: 'push';
+    readonly replace: 'replace';
+};
+export type RedirectTypeValue = (typeof RedirectType)[keyof typeof RedirectType];
+//# sourceMappingURL=redirect-type.d.ts.map

package/dist/shared/redirect-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redirect-type.d.ts","sourceRoot":"","sources":["../../src/shared/redirect-type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY;aACvB,IAAI,EAAE,MAAM;aACZ,OAAO,EAAE,SAAS;CACV,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC"}