@timber-js/app 0.2.0-alpha.158 → 0.2.0-alpha.159

package/dist/server/prebuilt/cache-key.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Component cache-key hashing for prebuilt (cache.component) entries.
+ *
+ * Key: `sha256(canonicalJson({ props, params })).slice(0, 16)` — see
+ * design/44-render-at-build-time.md §Cache Key. Both the request-time
+ * lookup (prebuilt-runtime.ts) and the post-build capture pass (TIM-1119)
+ * MUST use this exact function, or build artifacts become unaddressable.
+ *
+ * THE IDENTITY CONTRACT (design/44 §Cache Key): cache identity is **JSON
+ * value semantics** — two inputs are the same entry iff they are the same
+ * JSON value. This is an ALLOWLIST, not a denylist: a value participates
+ * in caching iff it is plain JSON data — null, boolean, finite number,
+ * string, dense array, or a plain `Object.prototype` object with only
+ * enumerable string-keyed data properties — plus `undefined` and `-0`,
+ * which hash as distinct sentinels because flight preserves them. Every
+ * value outside that domain (functions, symbols, bigints, accessors,
+ * hidden or symbol-keyed properties, non-`Object.prototype` prototypes
+ * including null, aliased references, sparse arrays, cycles, non-finite
+ * numbers) is UNKEYABLE by definition: `computeComponentCacheKey` returns
+ * null and the caller renders live — slower, never wrong.
+ *
+ * The line between rejected and declared-out-of-domain: values are
+ * REJECTED when the JSON projection itself would be ambiguous or lossy
+ * (hidden/symbol/non-enumerable properties, accessors, exotic
+ * prototypes). Observable state that leaves the projection intact — key
+ * order, reference identity, descriptor metadata (writable/configurable,
+ * frozen/sealed/extensible), proxy behavior — is DECLARED outside
+ * cache.component's supported input domain rather than rejected:
+ * key-order insensitivity is required for determinism, and rejecting
+ * frozen objects would unkey ubiquitous legitimate inputs
+ * (Object.freeze'd config props) to defend against components that
+ * render differently based on property attributes.
+ *
+ * Two hard rules for this walk itself: it must be TOTAL (never throw
+ * anything but UnkeyableValueError) and SIDE-EFFECT-FREE (descriptor
+ * reads only; never invoke user code such as getters).
+ *
+ * Object keys sort recursively so `{a, b}` and `{b, a}` hash identically
+ * (design/13-security.md checklist #14 — cache key determinism; key order
+ * is deliberately NOT part of identity).
+ */
+/**
+ * Canonicalize a single value, or null if it is unkeyable. The ONE
+ * definition of "faithfully comparable" — every prebuilt code path that
+ * needs value equality (cache keys, slot-param divergence) goes through
+ * this, so the unkeyable rules (accessors, hidden props, aliases,
+ * bigints, …) live in exactly one place.
+ */
+export declare function tryCanonicalize(value: unknown): string | null;
+/**
+ * Compute the cache-entry hash for a component render:
+ * `sha256({props, params}).slice(0, 16)` over canonical JSON.
+ *
+ * Returns null when props (or params) contain unkeyable values — the
+ * caller must fall back to dynamic rendering.
+ */
+export declare function computeComponentCacheKey(props: Record<string, unknown>, params: Record<string, string | string[]>): string | null;
+//# sourceMappingURL=cache-key.d.ts.map

package/dist/server/prebuilt/cache-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-key.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/cache-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAwGH;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAM7D;AAsBD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GACxC,MAAM,GAAG,IAAI,CAkCf"}

package/dist/server/prebuilt/capture-state.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Build-time capture state — the channel between the post-build capture
+ * pass (server/prebuilt-builder.ts) and the `__prebuilt` wrapper
+ * (server/prebuilt-runtime.ts).
+ *
+ * During capture, a wrapped component's subtree may render OTHER wrapped
+ * components. With no payload source registered (the capture pass runs
+ * before artifacts exist), those inner wrappers render live and their
+ * output is baked flat into the outer entry — the nesting clamp of
+ * design/45-cache-lifetimes.md §Nesting Semantics (TIM-1136). The capture
+ * pass is the designated detection point for that clamp, so the wrapper
+ * reports every render that happens while a capture is active:
+ *
+ * - **Cycle**: the inner wrapper IS the component being captured (directly
+ *   or transitively — the transitive case still renders the outer's own
+ *   wrapper, so the identity check catches both). Left alone this recurses
+ *   until the render times out; instead the wrapper throws
+ *   `PrebuiltCaptureCycleError`, failing that entry with an error naming
+ *   the cycle while the build continues (doc 44 skip-and-report policy).
+ * - **Nesting**: any other wrapper render is recorded as an (outer, inner)
+ *   pair. The builder warns after the entry completes when the inner
+ *   declares a refresh channel the outer cannot honor (doc 45 clamp rule).
+ *
+ * Captures run strictly sequentially (one entry at a time), so a single
+ * module-level slot is sufficient — there is never a second active capture
+ * to confuse renders between. At request time `active` is null and
+ * `noteWrapperRender` is a single null-check.
+ */
+import type { PrebuiltComponentOptions } from '../prebuilt-runtime.js';
+/** A wrapped component that rendered inside an active capture. */
+export interface NestedWrapperRender {
+    innerId: string;
+    options: PrebuiltComponentOptions;
+}
+/** Thrown by the wrapper when a capture renders its own component. */
+export declare class PrebuiltCaptureCycleError extends Error {
+    constructor(componentId: string);
+}
+/**
+ * Mark a capture as active. The builder calls this immediately before
+ * rendering an entry and MUST pair it with `endCapture()` in a finally.
+ */
+export declare function beginCapture(outerId: string): void;
+/**
+ * End the active capture and return the wrapped components that rendered
+ * inside it (first options object wins per inner ID).
+ */
+export declare function endCapture(): NestedWrapperRender[];
+/** Whether a build-time capture is currently rendering. */
+export declare function isCaptureActive(): boolean;
+/**
+ * Called by the `__prebuilt` wrapper on every render. No-op unless a
+ * capture is active. Throws `PrebuiltCaptureCycleError` when the wrapper
+ * belongs to the component currently being captured.
+ */
+export declare function noteWrapperRender(innerId: string, options: PrebuiltComponentOptions): void;
+//# sourceMappingURL=capture-state.d.ts.map

package/dist/server/prebuilt/capture-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-state.d.ts","sourceRoot":"","sources":["../../../src/server/prebuilt/capture-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAEvE,kEAAkE;AAClE,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,wBAAwB,CAAC;CACnC;AAED,sEAAsE;AACtE,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,WAAW,EAAE,MAAM;CAQhC;AAID;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAElD;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,mBAAmB,EAAE,CAKlD;AAED,2DAA2D;AAC3D,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,wBAAwB,GAAG,IAAI,CAQ1F"}

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.js';
+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.js';
+import type { PrebuiltManifest } from './payload-source.js';
+/**
+ * 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,75 @@
+/**
+ * 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.
+ */
+export interface PrebuiltManifestEntry {
+    /** Segment params this entry was captured under. */
+    params: Record<string, string | string[]>;
+    /** 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>;
+    };
+}
+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 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;AAIH,MAAM,WAAW,qBAAqB;IACpC,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,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;KAChD,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,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/synthetic-store.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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.js';
+/**
+ * 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[];
+}
+/**
+ * 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: Record<string, string | string[]>): 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;AAE9D;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;gBAET,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;CAW7C;AAED,yEAAyE;AACzE,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,mBAAmB,CAAC;IAC3B;;;;OAIG;IACH,UAAU,EAAE,qBAAqB,EAAE,CAAC;CACrC;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAC/C,oBAAoB,CA2BtB"}

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

@@ -0,0 +1,110 @@
+/**
+ * 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 { ManifestRoot } from './route-matcher.js';
+/** 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 raw param combo (JSON-safe) — manifest metadata, not the hash input. */
+    params: Record<string, string | string[]>;
+    /** 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[];
+}
+/** A per-entry problem — either a skip (build continues) or a hard error. */
+export interface CaptureIssue {
+    componentId: string;
+    routeUrlPath: string;
+    params: Record<string, string | string[]>;
+    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>;
+    /**
+     * 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;AAsBH,OAAO,KAAK,EAAgB,YAAY,EAAuB,MAAM,oBAAoB,CAAC;AAO1F,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,+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;CACjB;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,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;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAmSD;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,cAAc,CAAC,CAgNzB"}

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

@@ -0,0 +1,101 @@
+/**
+ * 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;
+    /**
+     * 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;
+export declare const keyDisciplineWarned: Set<string>;
+/**
+ * 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;AAiCH;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAGlE;AAID;;;;;;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;;;;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;AA8ED,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;AAmCD,eAAO,MAAM,mBAAmB,aAAoB,CAAC;AAoXrD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,eAAe,EAClD,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,CAAC,EACZ,OAAO,GAAE,wBAA6B,GACrC,CAAC,CAyCH;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,QAAQ,CAAC,EAAE,wBAAwB,GAClC,CAAC,CAYH"}