@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/dist/server/prebuilt/manifest-tag-index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Manifest tag index — maps tags to seed cache keys for tombstone writes.
+ *
+ * When `revalidateTag(tag)` fires, the framework must write tombstones for
+ * every build-seed entry carrying that tag. The manifest records tags per
+ * entry; this module inverts the index at startup so the lookup is O(1) per
+ * tag instead of a full manifest scan per invalidation.
+ *
+ * The index is built lazily on first access and cached for the process
+ * lifetime — the manifest is immutable within a deploy.
+ *
+ * See design/45-cache-lifetimes.md §ISR mechanics.
+ */
+import type { PrebuiltManifest } from './payload-source.ts';
+export interface SeedKeyInfo {
+    componentId: string;
+    cacheKey: string;
+}
+/**
+ * Build the inverted tag → seed key index from the manifest.
+ *
+ * Returns a Map where each tag maps to the set of (componentId, cacheKey)
+ * pairs whose manifest entries carry that tag. Only entries with non-empty
+ * `tags` arrays participate.
+ */
+export declare function buildTagIndex(manifest: PrebuiltManifest): Map<string, SeedKeyInfo[]>;
+//# sourceMappingURL=manifest-tag-index.d.ts.map

package/dist/server/prebuilt/manifest-tag-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-tag-index.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/manifest-tag-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,gBAAgB,GAAG,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,CAiBpF"}

package/dist/server/prebuilt/overlay.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Component cache overlay — runtime CacheHandler layer for ISR.
+ *
+ * Sits in front of the immutable build artifact (`.flight` files) and
+ * stores replacement payloads and tombstones via the configured
+ * CacheHandler. Overlay entries are per-deploy namespaced:
+ *   `timber:c:{deploymentId}:{componentId}:{hash}`
+ *
+ * The CacheHandler contract is untouched — tombstones and the tag index
+ * live above the interface as value conventions. Redis, KV, and custom
+ * handlers work unmodified.
+ *
+ * See design/45-cache-lifetimes.md §ISR mechanics.
+ */
+import { type SeedKeyInfo } from './manifest-tag-index.ts';
+import type { PrebuiltManifest } from './payload-source.ts';
+/**
+ * A cached component flight payload stored in the overlay.
+ * The `_t` discriminant distinguishes this from a tombstone.
+ */
+export interface ComponentOverlayRecord {
+    _t: 'co';
+    /** Base64-encoded flight payload bytes. */
+    p: string;
+    /** Logical freshness deadline (Date.now() + ttl * 1000). */
+    fu: number;
+    /** Whether a build-artifact seed exists for this key. */
+    s: boolean;
+}
+/**
+ * A tombstone marking a build seed as invalidated.
+ * Written by revalidateTag for seeds carrying the invalidated tag.
+ */
+export interface ComponentTombstoneRecord {
+    _t: 'ct';
+}
+export declare function isOverlayRecord(v: unknown): v is ComponentOverlayRecord;
+export declare function isTombstone(v: unknown): v is ComponentTombstoneRecord;
+export declare function overlayKey(componentId: string, cacheKey: string): string;
+export interface OverlayLookupResult {
+    kind: 'fresh' | 'stale' | 'tombstone';
+    /** The overlay value (null for tombstones). */
+    record: ComponentOverlayRecord | null;
+    /** Raw flight payload bytes (decoded from base64). Null for tombstones. */
+    payload: Uint8Array | null;
+}
+/**
+ * Look up an overlay entry in the cache handler.
+ * Returns null on a clean miss (no overlay entry at all).
+ */
+export declare function lookupOverlay(componentId: string, cacheKey: string): Promise<OverlayLookupResult | null>;
+/**
+ * Resolve the effective TTL for a component's runtime lifetime.
+ * Tag-only entries (no explicit ttl) get the ceiling TTL (design/45
+ * §Tag-only entries carry a ceiling TTL).
+ */
+export declare function effectiveTtl(ttl: number | undefined): number;
+/**
+ * Store a component flight payload in the overlay.
+ */
+export declare function storeOverlayEntry(componentId: string, cacheKey: string, payloadBytes: Uint8Array, opts: {
+    ttl?: number;
+    tags: string[];
+    hasSeed: boolean;
+}): Promise<void>;
+/**
+ * Initialize the tag index from the prebuilt manifest. Called once when the
+ * manifest is loaded. Without a manifest (no prebuilt components), this is
+ * never called and revalidateTag skips the tombstone path entirely.
+ */
+export declare function initTagIndex(manifest: PrebuiltManifest): void;
+/**
+ * Get the tag index, if initialized.
+ * @internal — exported for testing.
+ */
+export declare function getTagIndex(): Map<string, SeedKeyInfo[]> | null;
+/**
+ * Reset the tag index (for tests).
+ * @internal
+ */
+export declare function resetTagIndex(): void;
+/**
+ * Write tombstones for all seed entries carrying the given tag.
+ * Called from cache.invalidate (cache-api.ts) AFTER the handler's own
+ * invalidation clears overlay entries.
+ *
+ * The tombstone prevents the immutable seed from being served after
+ * invalidation — without it, a handler.invalidate that clears the overlay
+ * would expose the (now-stale) build artifact on the next request.
+ *
+ * Ensures the manifest is loaded first so cold-process actions that
+ * invalidate before any page render still write tombstones.
+ */
+export declare function writeTombstonesForTag(tag: string): Promise<void>;
+/**
+ * Reset the diagnostic flag (for tests).
+ * @internal
+ */
+export declare function resetIsrDiagnostic(): void;
+//# sourceMappingURL=overlay.d.ts.map

package/dist/server/prebuilt/overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAW5D;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,IAAI,CAAC;IACT,2CAA2C;IAC3C,CAAC,EAAE,MAAM,CAAC;IACV,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAC;IACX,yDAAyD;IACzD,CAAC,EAAE,OAAO,CAAC;CACZ;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,IAAI,CAAC;CACV;AAID,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,sBAAsB,CAEvE;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,wBAAwB,CAErE;AAID,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGxE;AAID,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,WAAW,CAAC;IACtC,+CAA+C;IAC/C,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACtC,2EAA2E;IAC3E,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAoBrC;AAID;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAE5D;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,UAAU,EACxB,IAAI,EAAE;IACJ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB,GACA,OAAO,CAAC,IAAI,CAAC,CAcf;AAMD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAG7D;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,GAAG,IAAI,CAE/D;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBtE;AA8BD;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/server/prebuilt/payload-source.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Prebuilt payload source — the adapter seam through which the runtime
+ * reads build-time flight artifacts (`.timber/dist/prebuilt/`).
+ *
+ * The runtime never touches the filesystem directly: adapters register a
+ * source at startup (Node: fs reads; Cloudflare: the assets binding —
+ * design/44-render-at-build-time.md §Adapter Integration). Artifacts are
+ * produced by the post-build capture pass (TIM-1119, prebuilt-builder.ts);
+ * adapter registration of the source is TIM-1122. Until a source is
+ * registered (adapter not wired yet, dev mode, no artifacts built), every
+ * lookup misses and cache.component wrappers render live — the designed
+ * dynamic-fallback behavior.
+ *
+ * Phase 3 (design/45 runtime tier) inserts the CacheHandler overlay lookup
+ * in front of `lookupPrebuiltPayload` — overlay first, then artifact. The
+ * single-lookup-function shape here is that seam.
+ */
+import type { CoercedParams } from '../../shared/param-value.ts';
+export interface PrebuiltManifestEntry {
+    /** Segment params this entry was captured under. */
+    params: CoercedParams;
+    /** Payload path relative to the prebuilt/ directory. */
+    file: string;
+    /** Payload size in bytes (build report / diagnostics). */
+    bytes?: number;
+    /** Runtime invalidation tags (design/45 ISR tier). */
+    tags?: string[];
+    /** Epoch ms when this entry was captured (seed freshness for ISR). */
+    buildTimestamp?: number;
+}
+export interface PrebuiltManifest {
+    [componentId: string]: {
+        entries: Record<string, PrebuiltManifestEntry>;
+        /** When true, the component does not read segment params — the cache key uses `{}`. */
+        paramIndependent?: boolean;
+    };
+}
+export interface PrebuiltPayloadSource {
+    /** Load prebuilt/manifest.json. Null when no artifacts exist. */
+    loadManifest(): Promise<PrebuiltManifest | null>;
+    /** Read a `.flight` payload by manifest file path. Null when missing. */
+    readPayload(file: string): Promise<Uint8Array | null>;
+}
+/**
+ * Register the payload source. Called once at server startup by the
+ * adapter/entry wiring (TIM-1122); tests inject fakes. Passing null
+ * unregisters (and drops the memoized manifest).
+ */
+export declare function setPrebuiltPayloadSource(next: PrebuiltPayloadSource | null): void;
+/**
+ * Whether a source is registered — the gate for both marker emission and
+ * splice-transform installation. False means zero prebuilt overhead.
+ */
+export declare function hasPrebuiltPayloadSource(): boolean;
+/**
+ * Ensure the manifest is loaded (and the tag index initialized). No-op
+ * when no source is registered. Used by the tombstone path to avoid
+ * skipping tombstones on cold processes where the first request is an
+ * action rather than a page render.
+ */
+export declare function ensureManifestLoaded(): Promise<void>;
+/**
+ * Look up a manifest entry (metadata only, no payload read).
+ * Used by the overlay to check seed existence and freshness.
+ */
+export declare function isParamIndependent(componentId: string): Promise<boolean>;
+export declare function getManifestEntry(componentId: string, cacheKey: string): Promise<PrebuiltManifestEntry | null>;
+/**
+ * Look up a cached payload: manifest entry → payload bytes.
+ * Null on any miss or read failure — callers fall back to live render.
+ *
+ * The manifest is loaded once and memoized (design/44 §manifest.json:
+ * loaded at startup, held in memory; payloads read on demand). A failed
+ * manifest load is memoized as null rather than retried per-request — a
+ * broken artifact should degrade to dynamic rendering, not add a failing
+ * read to every request.
+ */
+export declare function lookupPrebuiltPayload(componentId: string, cacheKey: string): Promise<Uint8Array | null>;
+//# sourceMappingURL=payload-source.d.ts.map

package/dist/server/prebuilt/payload-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload-source.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/payload-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE,MAAM,WAAW,qBAAqB;IACpC,oDAAoD;IACpD,MAAM,EAAE,aAAa,CAAC;IACtB,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,CAAC,WAAW,EAAE,MAAM,GAAG;QACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;QAC/C,uFAAuF;QACvF,gBAAgB,CAAC,EAAE,OAAO,CAAC;KAC5B,CAAC;CACH;AAED,MAAM,WAAW,qBAAqB;IACpC,iEAAiE;IACjE,YAAY,IAAI,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IACjD,yEAAyE;IACzE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;CACvD;AAsED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,qBAAqB,GAAG,IAAI,GAAG,IAAI,CAIjF;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAI1D;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAK9E;AAED,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAKvC;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAmB5B"}

package/dist/server/prebuilt/slots.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Slot-component helpers for cache.component (TIM-1173).
+ *
+ * A `slots: ['children', ...]` declaration caches the component's output
+ * as a shell with a stable <SlotOutlet slot={name} /> client-reference
+ * hole per declared slot prop; live slot content composes in per instance
+ * at request time via SlotsProvider/SlotContext. This generalizes the
+ * TIM-1181 layout mechanism to explicitly declared, named slots on any
+ * cached component. Layouts use the same mechanism with a `children` slot.
+ *
+ * Both the production wrapper (cache path) and the dev wrapper (no cache,
+ * same tree shape for dev/prod parity) build their render from these
+ * helpers. See design/45-cache-lifetimes.md §Slot Components.
+ */
+import type { PrebuiltComponentOptions } from '../prebuilt-runtime.ts';
+/**
+ * Framework-internal slot name for layout children. Uses a prefix that
+ * cannot collide with user-declared slot names (which are React prop
+ * names). Layout children flow through SlotsProvider/SlotOutlet with
+ * this key instead of the bare "children" key, so a cached component
+ * with `slots: ['children']` inside a layout never shadows the layout's
+ * own children delivery.
+ *
+ * Defined here (a server module) rather than in `client/slot-context.ts`
+ * (`'use client'`) because RSC's client-reference proxying would replace
+ * the string value with a proxy object in the server environment. The
+ * client-side SlotOutlet receives this value via props, so it doesn't
+ * need the constant. See TIM-1191.
+ */
+export declare const LAYOUT_CHILDREN_SLOT = "\0timber:children";
+/**
+ * Is this value the framework-injected layout children slot outlet
+ * (`<SlotOutlet slot={LAYOUT_CHILDREN_SLOT} />`)? Layout components
+ * receive this as their `children` prop — a stable client reference
+ * whose cache key is stripped so layout `cache.component` hits work
+ * (design/45 §Layout Propagation).
+ *
+ * Uses a framework-reserved slot name (LAYOUT_CHILDREN_SLOT) that
+ * cannot collide with user-declared slot names, preventing context
+ * shadowing when a cached component with its own SlotsProvider is
+ * nested inside a layout. See TIM-1191.
+ *
+ * Total: the probes run against a user-controlled value, and a Proxy
+ * trap can throw — that must classify as "not the outlet" (the
+ * canonicalizer then rejects the value as unkeyable → live render), not
+ * abort the request (codex P2 on PR #890).
+ */
+export declare function isChildrenSlotOutletElement(value: unknown): boolean;
+/**
+ * `props` without the framework-injected children outlet — the key props
+ * of a render. The outlet is the same client reference on every request,
+ * so it never varies the cache key; user-provided children stay (and
+ * leave the props unkeyable). See design/45 §Layout Propagation, TIM-1181.
+ */
+export declare function withoutChildrenOutlet(props: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Outcome of validating a `slots` declaration at registration time.
+ *
+ * - `none` — not declared (or an empty array): plain non-slot component.
+ * - `disabled` — declared but unusable (malformed shape, or missing the
+ *   required runtime lifetime): warned once here (module load); the
+ *   component falls back WHOLESALE to non-slot semantics — the caller
+ *   strips `slots` from the options and every other option (including
+ *   `prerender`) keeps its normal meaning. Safe by construction:
+ *   element-valued props are unkeyable on the non-slot path, so renders
+ *   with slot content go live. Slower, never wrong.
+ * - `active` — usable slot names.
+ */
+export type SlotResolution = {
+    kind: 'none' | 'disabled';
+} | {
+    kind: 'active';
+    slots: string[];
+};
+/**
+ * Validate the `slots` option. Both the production and dev wrappers gate
+ * on this — slot substitution is active in dev exactly when it would be
+ * active in production, so the tree shape a component sees never
+ * diverges between the two.
+ */
+export declare function resolveSlotNames(id: string, options: PrebuiltComponentOptions): SlotResolution;
+export interface SlotRender {
+    /** Props the shell renders with: data props + a SlotOutlet per slot. */
+    shellProps: Record<string, unknown>;
+    /** Non-slot props — the only props that participate in the cache key. */
+    dataProps: Record<string, unknown>;
+    /** Live slot content, keyed by slot name, for the SlotsProvider. */
+    slotValues: Record<string, unknown>;
+}
+/**
+ * Split the live props into the cacheable shell render (data props plus a
+ * deterministic SlotOutlet placeholder per declared slot — identical
+ * whether or not the caller passed the slot) and the per-instance live
+ * slot values.
+ *
+ * Null when the props object itself is unkeyable at the top level
+ * (accessors, hidden properties, exotic prototype — see splitSlotProps):
+ * the caller must render live with the original props.
+ */
+export declare function prepareSlotRender(props: Record<string, unknown>, slots: readonly string[]): SlotRender | null;
+/**
+ * Wrap a rendered shell (revived payload or live element) in a
+ * per-instance SlotsProvider feeding the live values to its outlets.
+ */
+export declare function wrapInSlotsProvider(shell: unknown, slotValues: Record<string, unknown>): React.ReactElement;
+//# sourceMappingURL=slots.d.ts.map

package/dist/server/prebuilt/slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slots.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/slots.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAEvE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AAExD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CASnE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAI7F;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG;IAAE,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAqBjG;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,wBAAwB,GAAG,cAAc,CAyB9F;AAED,MAAM,WAAW,UAAU;IACzB,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,UAAU,GAAG,IAAI,CAiBnB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,KAAK,CAAC,YAAY,CAMpB"}

package/dist/server/prebuilt/synthetic-store.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Synthetic ALS store for build-time capture (design/44 §Param Injection).
+ *
+ * Each param combo renders inside a `RequestContextStore` that provides
+ * segment params and NOTHING else. Every per-request API is a hard error,
+ * never a silent empty value — a component that branches on a header
+ * (locale, experiment, auth state) must fail the build, not bake the
+ * "header absent" branch into the cache for every future request:
+ *
+ * - `segmentParams.get()` works — reads from this store
+ * - `cookies()` / `headers()` / `searchParams` throw `BuildTimeContextError`
+ *
+ * The enforcement lives in the store's own fields (recording accessors)
+ * rather than in request-context.ts / cookie-context.ts, so the request
+ * path pays nothing and those modules stay untouched. The per-request
+ * fields — `headers`, `parsedCookies`, `searchParams` — are getters that
+ * record a violation and throw, so the CALL itself (`getHeaders()`,
+ * `getCookieJar()`, `getSearchParams()`) is the build error, not some
+ * later member read; merely obtaining and passing the object around is
+ * already outside the build-time contract (codex P2 round 5 on PR #836).
+ * `mutableContext` gets the same treatment because cookie MUTATORS reach
+ * it (via cookie-context's assertMutable, its only reader) before any
+ * other store field (codex P2 round 4).
+ *
+ * Every violation is recorded in a side channel BEFORE the throw — a
+ * component that catches the error (`try { headers() } catch { fallback }`)
+ * still fails its entry; accepting that render would silently bake the
+ * request-dependent fallback branch into the payload (codex P1 on PR #836).
+ * The capture pass checks the side channel after every render.
+ *
+ * This is safe precisely because capture renders the bare component
+ * element — no pipeline, no SSR bridge, no action machinery — so the only
+ * code that can reach these fields during a capture is the component
+ * itself (via the public accessors).
+ */
+import type { RequestContextStore } from '../als-registry.ts';
+import type { CoercedParams } from '../../shared/param-value.ts';
+/**
+ * Thrown when a prerendered component touches per-request context at
+ * build time. The capture pass treats this as a HARD build error —
+ * it indicates a design mistake, not transient bad data (design/44
+ * §Build-Phase Error Handling).
+ */
+export declare class BuildTimeContextError extends Error {
+    /** The per-request API that was called (e.g. "cookies()"). */
+    readonly api: string;
+    constructor(componentId: string, api: string);
+}
+/** A synthetic store plus the side channel its accessors report into. */
+export interface BuildTimeStoreHandle {
+    store: RequestContextStore;
+    /**
+     * Every per-request API access during the render, recorded even when
+     * the accompanying throw was caught by user code. Non-empty after the
+     * render ⇒ the entry must fail as a hard build error.
+     */
+    violations: BuildTimeContextError[];
+    /** Whether the component read `segmentParams` during the render. */
+    segmentParamsRead: boolean;
+}
+/**
+ * Create the synthetic per-combo store. `segmentParams` must already be
+ * coerced through the route's codecs — cache-key parity with request time
+ * depends on hashing the exact record `coerceSegmentParams` produces.
+ */
+export declare function createBuildTimeStore(componentId: string, segmentParams: CoercedParams): BuildTimeStoreHandle;
+//# sourceMappingURL=synthetic-store.d.ts.map

package/dist/server/prebuilt/synthetic-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthetic-store.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/synthetic-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,YAAY,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAU3C;CACF;AAED,yEAAyE;AACzE,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,mBAAmB,CAAC;IAC3B;;;;OAIG;IACH,UAAU,EAAE,qBAAqB,EAAE,CAAC;IACpC,oEAAoE;IACpE,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,aAAa,GAC3B,oBAAoB,CAyCtB"}

package/dist/server/prebuilt-builder.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Prebuilt payload capture — the post-build half of cache.component
+ * (TIM-1119, design/44-render-at-build-time.md §Build Phase).
+ *
+ * Runs AFTER Vite's 5-step build sequence, INSIDE the built RSC bundle:
+ * the component registry, the ALS instances, and the flight renderer are
+ * module instances in the bundle's graph, so the capture pass must share
+ * that graph — `server/rsc-entry/index.ts` re-exports this module's
+ * entry point as `__timber_capturePrebuilt`, and the timber-prebuilt
+ * plugin imports the built `rsc/index.js` and calls it.
+ *
+ * Per candidate route (a page with prebuilt components attributed by the
+ * build-time module-graph walk):
+ *
+ *   1. Load the page module (+ layout-chain modules that declare prebuilt
+ *      components) — module evaluation registers `__prebuilt` components.
+ *   2. Enumerate param combos: `generateStaticSegmentParams()` for dynamic
+ *      routes, the single empty combo for static routes.
+ *   3. Per combo, reconstruct the URL and run the REAL request-time pair —
+ *      `matchRoute` + `coerceSegmentParams` — so codec-coerced params hash
+ *      byte-identically to a live request. `computeComponentCacheKey` is
+ *      the single shared implementation (design/44 §Cache Key).
+ *   4. Render each registered component in isolation under a synthetic ALS
+ *      store (segment params only; cookies/headers/searchParams are hard
+ *      errors — synthetic-store.ts), fully drain the flight stream, and
+ *      smoke-revive the captured bytes once before accepting them.
+ *   5. Hand each payload to the caller's sink. Persistence (atomic file
+ *      writes, manifest.json) is the PLUGIN's job on the Node side —
+ *      keeping node:fs out of the server bundle, which must also run on
+ *      Cloudflare Workers.
+ *
+ * No payload source is registered while this runs, so wrappers rendered
+ * inside a captured subtree always miss and render live — inner output is
+ * baked flat into the outer entry, which is exactly the nesting clamp of
+ * design/45 §Nesting Semantics. The capture pass detects and reports the
+ * clamp (and fails cyclic entries) via capture-state.ts.
+ *
+ * Error policy (design/44 §Build-Phase Error Handling):
+ *   - `BuildTimeContextError` (cookies/headers/searchParams at build time)
+ *     → HARD error; the caller must fail the build.
+ *   - Anything else (bad data, deny(), cycles, timeouts, revival failures)
+ *     → skip that entry, warn, keep building.
+ */
+import type { CoercedParams } from '../shared/param-value.ts';
+import type { ManifestRoot } from './route-matcher.ts';
+/** One captured flight payload, ready for the caller's persistence sink. */
+export interface CapturedEntry {
+    componentId: string;
+    /** `computeComponentCacheKey(callSiteProps, coercedParams)` — names the .flight file. */
+    cacheKey: string;
+    /** The param combo — manifest metadata, not the hash input. */
+    params: CoercedParams;
+    /** Call-site props used for this entry (empty object for zero-prop usages). */
+    props?: Record<string, unknown>;
+    bytes: Uint8Array;
+    /** Resolved tags from callsite options — static or function-form, evaluated at capture time. */
+    tags?: string[];
+    /** Component does not read segment params — cache key uses `{}`. */
+    paramIndependent?: boolean;
+}
+/** A per-entry problem — either a skip (build continues) or a hard error. */
+export interface CaptureIssue {
+    componentId: string;
+    routeUrlPath: string;
+    params: CoercedParams;
+    message: string;
+}
+export interface CaptureSummary {
+    /** Entries captured, smoke-revived, and accepted by the sink. */
+    captured: number;
+    /** Skipped entries — reported, build continues (design/44 policy). */
+    skipped: CaptureIssue[];
+    /** Dynamic-context violations — the caller MUST fail the build. */
+    hardErrors: CaptureIssue[];
+    /** Nesting-clamp warnings emitted (design/45 §Nesting Semantics). */
+    nestingWarnings: number;
+}
+export interface CaptureOptions {
+    /**
+     * Route file path (page or layout, absolute) → prebuilt component IDs
+     * transitively reachable from it. Computed by the timber-prebuilt
+     * plugin's RSC module-graph walk at generateBundle time.
+     */
+    fileComponentMap: Record<string, string[]>;
+    /**
+     * Component ID → array of distinct static call-site prop objects captured
+     * from JSX usage sites (design/44 §Props Derivation). Each entry renders
+     * one payload per (props, params) combination. Components with no captured
+     * props (zero-prop usages) render with `{}` — the pre-TIM-1142 behavior.
+     */
+    callSiteProps?: Record<string, Record<string, unknown>[]>;
+    /**
+     * Persistence sink, called once per accepted payload. Throws propagate
+     * and abort the capture — a failed artifact write is an infrastructure
+     * failure, not a per-entry data problem.
+     */
+    onEntry: (entry: CapturedEntry) => Promise<void>;
+    /**
+     * Component ID → built chunk file name (or URL) for declaring modules
+     * behind dynamic imports. The capture pass imports these to trigger
+     * cache.component() registration before rendering.
+     */
+    lazyChunks?: Record<string, string>;
+    /** @internal Override chunk loader for testing. */
+    _loadChunk?: (chunkFile: string) => Promise<void>;
+    /**
+     * Per-entry ceiling on render + drain. A component that hangs (stalled
+     * fetch, unbounded recursion the cycle guard can't see) fails its entry
+     * instead of hanging the whole build — the A2 stream-read rule from
+     * design/13-security.md applied to the build process.
+     */
+    renderTimeoutMs?: number;
+    /** Progress/warning logger. Defaults to console.warn. */
+    log?: (message: string) => void;
+}
+/**
+ * Capture flight payloads for every attributed, registered, prerender-tier
+ * component across the route manifest. See module docblock for the flow.
+ */
+export declare function capturePrebuiltPayloads(manifest: ManifestRoot, options: CaptureOptions): Promise<CaptureSummary>;
+//# sourceMappingURL=prebuilt-builder.d.ts.map

package/dist/server/prebuilt-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prebuilt-builder.d.ts","sourceRoot":"","sources":["../../src/server/prebuilt-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAe9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAQvD,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,MAAM,EAAE,aAAa,CAAC;IACtB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,KAAK,EAAE,UAAU,CAAC;IAClB,gGAAgG;IAChG,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,mEAAmE;IACnE,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,qEAAqE;IACrE,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3C;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IAC1D;;;;OAIG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,mDAAmD;IACnD,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AA6CD;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,cAAc,CAAC,CAkUzB"}

package/dist/server/prebuilt-runtime.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Prebuilt component runtime — registration target for the timber-prebuilt
+ * transform (plugins/prebuilt.ts) and the request-time half of
+ * cache.component (TIM-1140).
+ *
+ * `cache.component(fn, opts)` call sites are rewritten at build time to
+ * `__prebuilt(stableId, fn, opts)` (production) or `__prebuiltDev(name, fn)`
+ * (dev). Both are exported via #server-internal — they are framework
+ * plumbing, never called by user code directly.
+ *
+ * Cache hits are served by FLIGHT REVIVAL: the cached `.flight` payload is
+ * decoded back into React elements inside the RSC environment with
+ * `createFromReadableStream` (the flight client running in the flight
+ * server — plugin-rsc wires the server-decode manifest so client
+ * references revive as re-serializable reference proxies). The revived
+ * element is returned from the wrapper and the outer render re-serializes
+ * it like any other subtree. This is the same mechanism as Next.js
+ * `"use cache"` (next/src/server/use-cache/use-cache-wrapper.ts).
+ *
+ * What a hit skips: all user work — data fetching, MDX compilation, the
+ * component function itself never runs. What it re-pays: React
+ * re-serializes the already-resolved tree (cost proportional to payload
+ * size, not to data latency). The alternative — splicing raw payload bytes
+ * into the outer stream — avoids re-serialization but requires byte-level
+ * coupling to the flight wire format (row framing, ID rebasing, marker
+ * detection); it was implemented and reviewed on PR #835 and deliberately
+ * replaced by revival. See design/44-render-at-build-time.md
+ * §Request-Time Injection.
+ *
+ * Misses render the original component live via the wrapper's own closure,
+ * inside the React pass — segment params from ALS, deny()/redirect()
+ * signals, Suspense, and error boundaries behave exactly as an unwrapped
+ * component. `fallbackOnMissingSegmentParams: false` throws instead.
+ */
+/**
+ * Set the timeout for component re-render captures. Called at boot from
+ * the RSC entry with renderTimeoutMs from timber.config.ts.
+ */
+export declare function setComponentRefreshTimeout(timeoutMs: number): void;
+/**
+ * Options captured from the `cache.component(fn, opts)` call site.
+ *
+ * `prerender`/`ttl`/`tags` (design/45) are carried through untouched — the
+ * build phase (TIM-1119) and runtime overlay (design/45 phase 3) consume
+ * them.
+ */
+export interface PrebuiltComponentOptions {
+    /** Populate the cache at build time via generateStaticSegmentParams. */
+    prerender?: boolean;
+    /** Runtime freshness window, seconds (design/45 runtime tier). */
+    ttl?: number;
+    /** Runtime invalidation tags (design/45 runtime tier). */
+    tags?: string[] | ((props: Record<string, unknown>) => string[]);
+    /** Serve stale while a background re-render refreshes (design/45 §SWR). */
+    staleWhileRevalidate?: boolean;
+    /**
+     * Slot props (TIM-1173): prop names whose values are live React
+     * elements composed into the cached shell at request time instead of
+     * participating in the cache. Each declared slot renders as a stable
+     * SlotOutlet client reference at capture time; the live value flows in
+     * through SlotContext per instance. Slot props are excluded from the
+     * cache key — only the remaining data props (+ segment params) hash.
+     * Runtime tier only: `prerender` is ignored (with a warning) because
+     * the build cannot enumerate children variants.
+     */
+    slots?: string[];
+    /**
+     * On a cache miss, render the component live (default: true). When false,
+     * a miss throws instead — for sites that must never render unknown params
+     * dynamically. See design/44 §fallbackOnMissingSegmentParams.
+     */
+    fallbackOnMissingSegmentParams?: boolean;
+}
+/** An async server component: props in, renderable out. */
+type ServerComponent = (props: any) => unknown;
+export interface PrebuiltRegistration {
+    id: string;
+    component: ServerComponent;
+    options: PrebuiltComponentOptions;
+}
+interface RscFunctions {
+    createFromReadableStream: (stream: ReadableStream<Uint8Array>) => Promise<unknown>;
+    renderToReadableStream: (element: unknown, options?: {
+        onError?: (error: unknown) => string;
+    }) => ReadableStream<Uint8Array>;
+}
+/**
+ * Wire the RSC flight client/server functions. Called once at server
+ * startup from the RSC entry module.
+ */
+export declare function setRscFunctions(fns: RscFunctions): void;
+/**
+ * Production wrapper injected by the timber-prebuilt transform. Registers
+ * the component under its stable ID and returns a wrapper component that
+ * either revives the cached payload (hit) or renders the original
+ * component live (miss).
+ */
+export declare function __prebuilt<C extends ServerComponent>(id: string, component: C, options?: PrebuiltComponentOptions): C;
+/** Look up a registration by stable component ID. */
+export declare function getPrebuiltRegistration(id: string): PrebuiltRegistration | undefined;
+/** All registrations, for the post-build capture pass (TIM-1119). */
+export declare function getPrebuiltRegistry(): ReadonlyMap<string, PrebuiltRegistration>;
+/**
+ * Dev-mode wrapper injected by the timber-prebuilt transform: a no-op that
+ * renders the component dynamically on every request, logging once per
+ * component on first render so the production behavior difference is visible.
+ * See design/44 §Dev Mode.
+ */
+export declare function __prebuiltDev<C extends ServerComponent>(name: string, component: C, options?: PrebuiltComponentOptions): C;
+export {};
+//# sourceMappingURL=prebuilt-runtime.d.ts.map

package/dist/server/prebuilt-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prebuilt-runtime.d.ts","sourceRoot":"","sources":["../../src/server/prebuilt-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAsDH;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAGlE;AAYD;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB;IACvC,wEAAwE;IACxE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC;IACjE,2EAA2E;IAC3E,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;;OAIG;IACH,8BAA8B,CAAC,EAAE,OAAO,CAAC;CAC1C;AAED,2DAA2D;AAE3D,KAAK,eAAe,GAAG,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC;AAY/C,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,eAAe,CAAC;IAC3B,OAAO,EAAE,wBAAwB,CAAC;CACnC;AA0GD,UAAU,YAAY;IACpB,wBAAwB,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACnF,sBAAsB,EAAE,CACtB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAA;KAAE,KAC/C,cAAc,CAAC,UAAU,CAAC,CAAC;CACjC;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAEvD;AA4YD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,eAAe,EAClD,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,CAAC,EACZ,OAAO,GAAE,wBAA6B,GACrC,CAAC,CAoEH;AAED,qDAAqD;AACrD,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAEpF;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,IAAI,WAAW,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAE/E;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,eAAe,EACrD,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,CAAC,EACZ,OAAO,GAAE,wBAA6B,GACrC,CAAC,CAmCH"}