@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.180

package/dist/plugins/cache.d.ts

@@ -0,0 +1,64 @@
+/**
+ * timber-cache-transform — Vite plugin that injects stable callsite IDs
+ * into `cache.data()` calls imported from `@timber-js/app/cache`.
+ *
+ * Detected callsite forms (TIM-1054):
+ *   - named imports, including aliases: `import { cache as c }` + `c.data(fn, opts)`
+ *   - namespace imports: `import * as ns` + `ns.cache.data(fn, opts)`
+ * Forms a per-module transform cannot trace — local variable aliases
+ * (`const c = cache`), user re-export wrapper modules, computed access
+ * (`cache['data']`) — fall back to the runtime fnId derived from
+ * fnv1a(fn.toString()) (see cache/timber-cache.ts), which is deterministic
+ * across instances and cold starts of the same build. Without either
+ * mechanism, an ordinal counter would collide across instances with a shared
+ * CacheHandler (Redis/KV) — cache key poisoning, serving one route's cached
+ * data to another.
+ *
+ * The plugin transforms:
+ *   cache.data(fn, opts)          →  cache.data(fn, opts, "stable-id")
+ *   ns.cache.data(fn, opts)       →  ns.cache.data(fn, opts, "stable-id")
+ *
+ * where stable-id =
+ *   fnv1a(relPath + ":cache:" + fnv1a(stmtText) + ":" + fnv1a(callSpanText) + ":" + occurrence)
+ *
+ * stmtText is the source text of the enclosing *top-level statement* and
+ * callSpanText is the source text of the cache(...) call expression itself.
+ *
+ * The ID is derived from the *content* of the call, not its ordinal position
+ * in the file. A position-based index (the original TIM-997 scheme) was stable
+ * within one build but shifted across builds: inserting, deleting, or
+ * reordering a cache() call changed the index of every call below it, so with
+ * a persistent shared CacheHandler (Redis/KV) a new function could inherit
+ * another function's old ID and serve its persisted data — cross-deploy cache
+ * poisoning (TIM-1053). Content hashing makes IDs immune to reordering and
+ * unrelated edits, while a changed call gets a fresh ID — which is exactly
+ * when invalidation is wanted.
+ *
+ * The enclosing-statement text is included so that byte-identical cache.data()
+ * calls in different scopes — e.g. two factory helpers that each `return
+ * cache.data(fn, { ttl: 60 })` — get distinct, insertion-stable IDs: their
+ * enclosing declarations differ by name/body even when the call spans are
+ * identical. Without it, a source-order occurrence counter alone would shift
+ * when an identical span is inserted above, reassigning IDs across deploys.
+ * Calls that are byte-identical INCLUDING their enclosing top-level statement
+ * are disambiguated by a source-order occurrence index. That residue is safe:
+ * identical top-level declarations are a redeclaration error, so fully
+ * identical (statement, call) pairs can only be expression statements
+ * referencing the same bindings — the same function, where an ID swap is
+ * harmless.
+ *
+ * AST helpers and the ID derivation are shared with timber-prebuilt
+ * (plugins/prebuilt.ts) via plugins/callsite-ast.ts.
+ *
+ * See TIM-997, TIM-1053, design/06-caching.md §"Cache Key Security".
+ */
+import type { Plugin } from 'vite';
+import type { PluginContext } from '../plugin-context.js';
+/**
+ * Generate a stable callsite ID for a cache() call. See callsite-ast.ts for
+ * the derivation properties.
+ */
+declare function generateStableId(relativeModulePath: string, statementText: string, callSpanText: string, occurrence: number): string;
+export declare function timberCacheTransform(ctx: PluginContext): Plugin;
+export { generateStableId };
+//# sourceMappingURL=cache.d.ts.map

package/dist/plugins/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/plugins/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AA2E1D;;;GAGG;AACH,iBAAS,gBAAgB,CACvB,kBAAkB,EAAE,MAAM,EAC1B,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,MAAM,CAQR;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAuF/D;AAGD,OAAO,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/plugins/callsite-ast.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Shared AST helpers for callsite-ID transforms.
+ *
+ * Both timber-cache-transform (plugins/cache.ts) and timber-prebuilt
+ * (plugins/prebuilt.ts) detect calls on bindings imported from the cache
+ * module and stamp them with content-derived stable IDs. The node shapes,
+ * import-binding resolution, recursive call walk, and ID derivation are
+ * identical — only the callee shape and rewrite differ per plugin.
+ *
+ * See TIM-997, TIM-1053, design/06-caching.md §"Cache Key Security".
+ */
+/** Module specifiers whose bindings the transforms track. */
+export declare const CACHE_MODULE_SOURCES: Set<string>;
+export interface PositionedNode {
+    type: string;
+    start: number;
+    end: number;
+    [key: string]: unknown;
+}
+export interface IdentifierNode extends PositionedNode {
+    type: 'Identifier';
+    name: string;
+}
+export interface ImportDeclarationNode extends PositionedNode {
+    type: 'ImportDeclaration';
+    source: {
+        value: string;
+    };
+    specifiers: Array<PositionedNode & {
+        type: string;
+        local: IdentifierNode;
+        imported?: IdentifierNode;
+    }>;
+}
+export interface CallExpressionNode extends PositionedNode {
+    type: 'CallExpression';
+    callee: PositionedNode;
+    arguments: PositionedNode[];
+}
+export interface MemberExpressionNode extends PositionedNode {
+    type: 'MemberExpression';
+    object: PositionedNode;
+    property: PositionedNode;
+    computed: boolean;
+}
+export interface ProgramNode extends PositionedNode {
+    type: 'Program';
+    body: PositionedNode[];
+}
+export interface ImportBindings {
+    /** Local names bound to the named import (`import { cache as c }`). */
+    named: Set<string>;
+    /** Local names of namespace imports (`import * as ns`) of a tracked module. */
+    namespaces: Set<string>;
+}
+/**
+ * Find the local binding name(s) for `importedName` imported from one of
+ * `sources` — both named imports (including aliases) and namespace imports
+ * (TIM-1054).
+ */
+export declare function findImportBindings(program: ProgramNode, sources: ReadonlySet<string>, importedName: string): ImportBindings;
+export interface ShadowRange {
+    start: number;
+    end: number;
+    /** Which tracked binding names are shadowed in this range. */
+    names: ReadonlySet<string>;
+}
+/**
+ * Collect byte ranges where any name in `tracked` is shadowed by a
+ * function/arrow parameter, catch clause binding, or lexical declaration
+ * (`const`/`let`/`var`, `function`, `class`, for-loop binding). Calls
+ * inside these ranges must NOT be rewritten — the name resolves to the
+ * local binding, not the import (TIM-1141).
+ *
+ * Each range records WHICH names are shadowed so the consumer can skip
+ * only calls to the shadowed name, not unrelated imports (codex review
+ * on PR #876).
+ *
+ * When a scope shadows some-but-not-all tracked names, the walker
+ * continues descending to find inner scopes that shadow remaining names
+ * (codex review round 2 on PR #876).
+ */
+export declare function collectShadowRanges(node: PositionedNode, tracked: ReadonlySet<string>, ranges: ShadowRange[]): void;
+/**
+ * Recursively walk AST nodes collecting call expressions accepted by
+ * `matches`. Calls are typically at module scope, but calls inside
+ * functions/blocks are handled for completeness.
+ *
+ * Consumers that match by binding NAME should pair this with
+ * `collectShadowRanges` to filter out calls in scopes where the tracked
+ * name is shadowed (TIM-1141). The prebuilt transform avoids the class
+ * entirely by allowlisting top-level declarator positions
+ * (plugins/prebuilt.ts).
+ */
+export declare function findCallSites(node: PositionedNode, matches: (call: CallExpressionNode) => boolean, results: CallExpressionNode[]): void;
+/**
+ * Generate a stable callsite ID from a module path, a kind discriminator
+ * ('cache' | 'component'), the source text of the enclosing top-level
+ * statement, the source text of the call expression, and an occurrence index
+ * among fully byte-identical (statement, call) pairs in the same file.
+ *
+ * The ID is deterministic and:
+ * - Stable across cold starts AND across builds/deploys for unchanged calls —
+ *   inserting, deleting, or reordering other calls does not affect it
+ * - Unique across different modules (relPath component)
+ * - Unique across distinct calls within a module (statement + span hashes),
+ *   with fully identical duplicates disambiguated by source-order occurrence
+ * - Fresh when the wrapped fn, opts, or enclosing statement change, which
+ *   intentionally invalidates the old persisted entries
+ *
+ * The enclosing-statement text is included so that byte-identical calls in
+ * different scopes — e.g. two factory helpers with identical call spans —
+ * get distinct, insertion-stable IDs. See plugins/cache.ts header for the
+ * full derivation rationale (TIM-1053).
+ */
+export declare function generateStableCallsiteId(relativeModulePath: string, kind: string, statementText: string, callSpanText: string, occurrence: number): string;
+//# sourceMappingURL=callsite-ast.d.ts.map

package/dist/plugins/callsite-ast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callsite-ast.d.ts","sourceRoot":"","sources":["../../src/plugins/callsite-ast.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,6DAA6D;AAC7D,eAAO,MAAM,oBAAoB,aAAoD,CAAC;AAEtF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,cAAe,SAAQ,cAAc;IACpD,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC3D,IAAI,EAAE,mBAAmB,CAAC;IAC1B,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1B,UAAU,EAAE,KAAK,CACf,cAAc,GAAG;QACf,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,cAAc,CAAC;QACtB,QAAQ,CAAC,EAAE,cAAc,CAAC;KAC3B,CACF,CAAC;CACH;AAED,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACxD,IAAI,EAAE,gBAAgB,CAAC;IACvB,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,EAAE,cAAc,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IAC1D,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,EAAE,cAAc,CAAC;IACvB,QAAQ,EAAE,cAAc,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,WAAY,SAAQ,cAAc;IACjD,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,cAAc,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnB,+EAA+E;IAC/E,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,EAC5B,YAAY,EAAE,MAAM,GACnB,cAAc,CAoBhB;AAqID,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC5B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,EAC5B,MAAM,EAAE,WAAW,EAAE,GACpB,IAAI,CAkJN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,CAAC,IAAI,EAAE,kBAAkB,KAAK,OAAO,EAC9C,OAAO,EAAE,kBAAkB,EAAE,GAC5B,IAAI,CAsBN;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CACtC,kBAAkB,EAAE,MAAM,EAC1B,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,MAAM,CAIR"}

package/dist/plugins/callsite-jsx.d.ts

@@ -0,0 +1,35 @@
+/**
+ * JSX call-site props extraction for prebuilt components (TIM-1142).
+ *
+ * At build time, the timber-prebuilt transform captures the exact props
+ * from each JSX usage site of a cache.component binding so the post-build
+ * capture pass can prerender entries for each distinct prop set. Only
+ * statically analyzable props (JSON-safe literals, arrays, and plain
+ * objects) are captured; dynamic/computed props bail — those call sites
+ * fall back to live rendering per design/44 §Props Derivation.
+ *
+ * See design/44-render-at-build-time.md §Props Derivation at Build Time.
+ */
+import type { PluginContext } from '../plugin-context.js';
+import type { PositionedNode, ProgramNode } from './callsite-ast.js';
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Extract static props from a JSX element's attributes. Returns null if
+ * any attribute is dynamic (spread, computed expression, JSX element, etc.)
+ * — the component must fall back to dynamic rendering for that call site.
+ */
+export declare function extractStaticJsxProps(attributes: PositionedNode[]): Record<string, JsonValue> | null;
+/**
+ * Walk an AST tree and collect JSX usages of the given binding names,
+ * returning the static props for each usage. Returns a map of
+ * bindingName → array of static prop objects (or null for dynamic props).
+ */
+export declare function collectJsxUsages(program: ProgramNode, bindingNames: Set<string>): Map<string, Array<Record<string, JsonValue> | null>>;
+/**
+ * Add a distinct props object to the call-site-props map for a component,
+ * deduplicating by deep JSON value (recursively sorted keys).
+ */
+export declare function recordCallSiteProps(ctx: PluginContext, componentId: string, props: Record<string, JsonValue>): void;
+//# sourceMappingURL=callsite-jsx.d.ts.map

package/dist/plugins/callsite-jsx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callsite-jsx.d.ts","sourceRoot":"","sources":["../../src/plugins/callsite-jsx.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAkB,cAAc,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAsBrF,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AA2EjC;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,cAAc,EAAE,GAC3B,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,IAAI,CA+BlC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,WAAW,EACpB,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,GACxB,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,IAAI,CAAC,CAAC,CA0CtD;AAkBD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,aAAa,EAClB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAC/B,IAAI,CASN"}

package/dist/plugins/chunks.d.ts

@@ -13,9 +13,15 @@
  *   - Per-route chunks (page/layout components, only when route-specific)
  *   - rolldown-runtime (Rolldown's own output, unavoidable)
  *
+ * Additionally, this plugin builds a facade ancestry map during the RSC
+ * build so that `clientChunkGroup` can reclassify `shared:` client
+ * references that are only consumed by a single route boundary.
+ * See TIM-1107, design/27-chunking-strategy.md.
+ *
  * Design docs: 27-chunking-strategy.md
  */
 import type { Plugin } from 'vite';
+import type { PluginContext } from '../plugin-context';
 /**
  * Check if a module is part of the timber framework runtime.
  *
@@ -29,9 +35,10 @@ export declare function isTimberRuntime(id: string): boolean;
 /**
  * Create the timber-chunks Vite plugin.
  *
- * Currently a no-op — Rolldown's default splitting produces the desired
- * output (one main bundle + per-route chunks). The plugin is retained as
- * a hook point for future chunking adjustments.
+ * Rolldown's default splitting produces the desired output (one main
+ * bundle + per-route chunks). This plugin's main job is building the
+ * facade ancestry map during the RSC build so `clientChunkGroup` can
+ * reclassify shared client references to their correct route boundary.
  *
  * NOTE: Ideally we'd use Rolldown's `format: 'app'` (module registry format)
  * which guarantees single-copy module semantics like webpack/Turbopack.
@@ -41,5 +48,5 @@ export declare function isTimberRuntime(id: string): boolean;
  *
  * Design docs: 27-chunking-strategy.md
  */
-export declare function timberChunks(): Plugin;
+export declare function timberChunks(ctx: PluginContext): Plugin;
 //# sourceMappingURL=chunks.d.ts.map

package/dist/plugins/chunks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunks.d.ts","sourceRoot":"","sources":["../../src/plugins/chunks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAOnD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAIrC"}
+{"version":3,"file":"chunks.d.ts","sourceRoot":"","sources":["../../src/plugins/chunks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAU,MAAM,MAAM,CAAC;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAOnD;AA4DD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAQvD"}

package/dist/plugins/client-chunks.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Client chunk grouping strategy for @vitejs/plugin-rsc.
+ *
+ * Groups client reference modules by the **consuming route's** layout boundary
+ * (derived from `meta.serverChunk`), not by the module's own file location.
+ * This ensures components in shared directories (e.g. `components/`) land in
+ * the chunk of the route that uses them, not in a single catch-all chunk.
+ *
+ * For `shared:` modules (client references in non-facade RSC chunks), the
+ * function consults a facade ancestry map built during the RSC build. If all
+ * consuming facades belong to the same route boundary, the module is
+ * reclassified to that boundary instead of falling through to `client-shared`.
+ *
+ * See design/27-chunking-strategy.md, TIM-440, TIM-499, TIM-1104, TIM-1107.
+ */
+/**
+ * Derive a chunk group name for a client reference module.
+ *
+ * Always derives the group from the **consuming route** (`serverChunk`'s
+ * facade path), not from the module's own file location. This prevents
+ * components in shared directories (e.g. `app/components/`, `src/lib/`)
+ * from collapsing into a single chunk when they're only used by one route.
+ *
+ * For `shared:` modules (non-facade RSC chunks), consults the facade
+ * ancestry map to reclassify modules that are only consumed by a single
+ * route boundary. This prevents large dependencies from polluting
+ * `client-shared` when they're route-scoped (TIM-1107).
+ *
+ * Examples:
+ *   - `facade:app/dashboard/settings/page.tsx` → `"client-dashboard"`
+ *   - `facade:app/(group-a)/group-page-a/page.tsx` → `"client-group-page-a"`
+ *   - `facade:app/layout.tsx` (root layout) → `"client-shared"`
+ *   - `shared:...` (shared across chunks) → reclassified or `"client-shared"`
+ */
+export declare function clientChunkGroup(meta: {
+    id: string;
+    normalizedId: string;
+    serverChunk: string;
+}, appDir: string, root: string, sharedModuleFacades?: Map<string, string[]>): string;
+//# sourceMappingURL=client-chunks.d.ts.map

package/dist/plugins/client-chunks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-chunks.d.ts","sourceRoot":"","sources":["../../src/plugins/client-chunks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAiHH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,EAC/D,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,mBAAmB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GAC1C,MAAM,CAiCR"}

package/dist/plugins/cloudflare-wasm.d.ts

@@ -0,0 +1,21 @@
+/**
+ * timber-cloudflare-wasm — Handle WASM modules for Cloudflare Workers builds.
+ *
+ * Cloudflare Workers can natively import `.wasm` files as compiled
+ * WebAssembly.Module. But Rolldown can't load `.wasm` files at build time.
+ *
+ * This plugin bridges the gap:
+ * 1. Adds the `workerd` resolve condition so libraries like @takumi-rs/wasm
+ *    resolve to their Cloudflare-native entry (bare `.wasm` import)
+ * 2. Externalizes `.wasm` imports so Rolldown skips them
+ * 3. Copies the WASM files to the build output so wrangler can find them
+ *
+ * Only active for Cloudflare adapter production builds — every hook bails
+ * unless `isCloudflareBuild` was set in configResolved. In dev and non-CF
+ * builds, `.wasm` imports are left to Vite's own handling (?init / ?url or
+ * a clear build error), never silently externalized.
+ */
+import type { Plugin } from 'vite';
+import type { PluginContext } from '../plugin-context.js';
+export declare function timberCloudflareWasm(ctx: PluginContext): Plugin[];
+//# sourceMappingURL=cloudflare-wasm.d.ts.map

package/dist/plugins/cloudflare-wasm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-wasm.d.ts","sourceRoot":"","sources":["../../src/plugins/cloudflare-wasm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAkB,MAAM,MAAM,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAO1D,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,EAAE,CA+GjE"}

package/dist/plugins/content.d.ts

@@ -8,7 +8,7 @@
  * Design doc: 20-content-collections.md §"Content Collections"
  */
 import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../plugin-context.js';
 /**
  * Create the timber-content Vite plugin.
  *

package/dist/plugins/content.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../src/plugins/content.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAGnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAoBhD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAgGxD"}
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../src/plugins/content.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAGnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAoB1D;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAgGxD"}

package/dist/plugins/dev-server.d.ts

@@ -12,11 +12,27 @@
  * Design docs: 18-build-system.md §"Dev Server", 02-rendering-pipeline.md
  */
 import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
+import type { IncomingMessage } from 'node:http';
+import type { PluginContext } from '../plugin-context.js';
 /**
  * Create the timber-dev-server Vite plugin.
  *
  * Hook: configureServer (returns post-hook to register after Vite's middleware)
  */
 export declare function timberDevServer(ctx: PluginContext): Plugin;
+/**
+ * Convert a Node IncomingMessage to a Web Request.
+ *
+ * Constructs the full URL from the Host header and request URL,
+ * and forwards the method, headers, and body.
+ *
+ * The scheme comes from the socket's TLS state — with `server.https` the
+ * browser sends `Origin: https://host`, and a hardcoded `http://` would
+ * fail CSRF origin comparison on every POST. X-Forwarded-Proto is NOT
+ * consulted: dev connections are direct, so the header would be
+ * attacker-controlled. (TIM-1067, B32)
+ *
+ * Exported for tests.
+ */
+export declare function toWebRequest(nodeReq: IncomingMessage): Request;
 //# sourceMappingURL=dev-server.d.ts.map

package/dist/plugins/dev-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev-server.d.ts","sourceRoot":"","sources":["../../src/plugins/dev-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiC,MAAM,MAAM,CAAC;AAGlE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAkChD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAmD1D"}
+{"version":3,"file":"dev-server.d.ts","sourceRoot":"","sources":["../../src/plugins/dev-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiC,MAAM,MAAM,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,WAAW,CAAC;AAKjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AA8C1D;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA6D1D;AA8PD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAuC9D"}

package/dist/plugins/entries.d.ts

@@ -11,14 +11,24 @@
  * Design docs: 18-build-system.md §"Entry Generation", §"Virtual Modules"
  */
 import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../plugin-context.js';
 /**
- * Detect the user's instrumentation.ts file at the project root.
+ * Detect a user convention file at both root and src/.
  *
- * Checks for instrumentation.ts, .js, and .mjs — matching the same
- * extensions as timber.config.ts detection.
+ * Root takes precedence over src/, extension priority: .ts > .js > .mjs.
+ * Used for instrumentation.ts, timber.cache.ts, and similar file conventions.
  */
+export declare function detectConventionFile(root: string, basename: string): string | null;
 export declare function detectInstrumentationFile(root: string): string | null;
+/**
+ * Detect the user's timber.cache file.
+ *
+ * This file holds runtime cache instances (cacheHandler, cdnPurge)
+ * that cannot be JSON-serialized. Separating them from timber.config.ts
+ * prevents the RSC build from pulling build-time deps (adapters, MDX,
+ * rollup) into the runtime bundle. See TIM-1211.
+ */
+export declare function detectCacheFile(root: string): string | null;
 /**
  * Generate the virtual:timber-instrumentation module source.
  *
@@ -29,6 +39,20 @@ export declare function detectInstrumentationFile(root: string): string | null;
  * See design/17-logging.md §"instrumentation.ts — The Entry Point"
  */
 export declare function generateInstrumentationModule(instrumentationPath: string | null): string;
+/**
+ * Generate the virtual:timber-cache-handler module source.
+ *
+ * When the user's timber.cache.ts exists, generates a module that
+ * dynamically imports it and extracts cacheHandler and cdnPurge.
+ * These are class instances (e.g. RedisCacheHandler) that cannot be
+ * JSON-serialized into virtual:timber-config, so they must be loaded
+ * at runtime via dynamic import.
+ *
+ * timber.cache.ts exports: default cacheHandler, named cdnPurge.
+ *
+ * See TIM-1211, TIM-599.
+ */
+export declare function generateCacheHandlerModule(cachePath: string | null): string;
 /**
  * Create the timber-entries Vite plugin.
  *

package/dist/plugins/entries.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entries.d.ts","sourceRoot":"","sources":["../../src/plugins/entries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAInC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA6GhD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUrE;AAED;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAAC,mBAAmB,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAwBxF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAwExD"}
+{"version":3,"file":"entries.d.ts","sourceRoot":"","sources":["../../src/plugins/entries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAInC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AA+J1D;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUlF;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAErE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAAC,mBAAmB,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAqBxF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CA+B3E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAiFxD"}

package/dist/plugins/fonts.d.ts

@@ -1,83 +1,26 @@
 /**
- * timber-fonts — Vite sub-plugin for build-time font processing.
+ * timber-fonts — Vite sub-plugin shell for build-time font processing.
  *
- * Handles:
- * - Virtual module resolution for `@timber/fonts/google` and `@timber/fonts/local`
- * - Static analysis of font function calls during `transform`
- * - @font-face CSS generation and scoped class output
- * - Size-adjusted fallback font generation
+ * This file is intentionally thin: it wires the Vite plugin hooks to the
+ * pipeline + per-concern modules under `../fonts/`. All real logic lives
+ * in:
  *
- * Does NOT handle (separate tasks):
- * - Google Fonts downloading/caching (timber-nk5)
- * - Build manifest / Early Hints integration (timber-qnx)
+ * - `../fonts/pipeline.ts`        — `FontPipeline` (state, mutators)
+ * - `../fonts/transform.ts`       — transform-hook logic, parsing helpers
+ * - `../fonts/dev-middleware.ts`  — dev font binary server
+ * - `../fonts/virtual-modules.ts` — virtual module ID constants + source
+ *
+ * The public exports below are the stable API that the test suite and
+ * other parts of the framework import. Anything new should be added to
+ * one of the per-concern modules and re-exported here only if external
+ * consumers need it.
  *
  * Design doc: 24-fonts.md
  */
 import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
-import type { ExtractedFont, GoogleFontConfig } from '#/fonts/types.js';
-/**
- * Registry of fonts extracted during transform.
- * Keyed by a unique font ID derived from family + config.
- */
-export type FontRegistry = Map<string, ExtractedFont>;
-/**
- * Extract static font config from a font function call in source code.
- *
- * Parses patterns like:
- *   const inter = Inter({ subsets: ['latin'], weight: '400', display: 'swap', variable: '--font-sans' })
- *
- * Returns null if the call cannot be statically analyzed.
- *
- * Uses acorn AST parsing for robust handling of comments, trailing commas,
- * and multi-line configs.
- */
-export declare function extractFontConfig(callSource: string): GoogleFontConfig | null;
-/**
- * Detect if a source file contains dynamic/computed font function calls
- * that cannot be statically analyzed.
- *
- * Returns the offending expression if found, null if all calls are static.
- *
- * Uses acorn AST parsing for accurate detection.
- */
-export declare function detectDynamicFontCall(source: string, importedNames: string[]): string | null;
-/**
- * Parse import specifiers from a source file that imports from
- * `@timber/fonts/google` or `next/font/google`.
- *
- * Returns the list of imported font names (e.g. ['Inter', 'JetBrains_Mono']).
- */
-export declare function parseGoogleFontImports(source: string): string[];
-/**
- * Parse the original (remote) font family names from imports.
- *
- * Returns a map of local name → family name.
- * e.g. { Inter: 'Inter', JetBrains_Mono: 'JetBrains Mono' }
- */
-export declare function parseGoogleFontFamilies(source: string): Map<string, string>;
-/**
- * Generate CSS for a single extracted font.
- *
- * Includes @font-face rules (for local fonts), fallback @font-face,
- * and the scoped class rule.
- */
-export declare function generateFontCss(font: ExtractedFont): string;
-/**
- * Generate the CSS output for all extracted fonts.
- *
- * Includes @font-face rules for local fonts, fallback @font-face rules,
- * and scoped classes.
- */
-export declare function generateAllFontCss(registry: FontRegistry): string;
-/**
- * Parse the local name used for the default import of `@timber/fonts/local`.
- *
- * Handles:
- *   import localFont from '@timber/fonts/local'
- *   import myLoader from '@timber/fonts/local'
- */
-export declare function parseLocalFontImportName(source: string): string | null;
+import type { PluginContext } from '../plugin-context.js';
+export { FontPipeline } from '../fonts/pipeline.js';
+export { generateFontId, extractFontConfig, detectDynamicFontCall, parseGoogleFontImports, parseGoogleFontFamilies, parseLocalFontImportName, } from '../fonts/transform.js';
 /**
  * Create the timber-fonts Vite plugin.
  */

package/dist/plugins/fonts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fonts.d.ts","sourceRoot":"","sources":["../../src/plugins/fonts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAGlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAmCxE;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AA4CtD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAE7E;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAE5F;AAUD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAkB/D;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAqB3E;AAwED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAmB3D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAMjE;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKtE;AAqED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAwVtD"}
+{"version":3,"file":"fonts.d.ts","sourceRoot":"","sources":["../../src/plugins/fonts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAiC,MAAM,MAAM,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AA2B1D,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAE/B;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA2OtD"}

package/dist/plugins/mdx.d.ts

@@ -8,7 +8,7 @@
  * Design doc: 20-content-collections.md §"The timber-mdx Plugin"
  */
 import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../plugin-context.js';
 /**
  * Check if mdx-components.tsx (or .ts, .jsx, .js) exists at the project root
  * or in src/. Root takes precedence, matching Next.js behavior.

package/dist/plugins/mdx.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mdx.d.ts","sourceRoot":"","sources":["../../src/plugins/mdx.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAGnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIhD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAelE;AA+BD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA0GpD"}
+{"version":3,"file":"mdx.d.ts","sourceRoot":"","sources":["../../src/plugins/mdx.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAKnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAelE;AAiED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA2GpD"}

package/dist/plugins/prebuilt-capture.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Post-build prebuilt capture — Node-side orchestration (TIM-1119).
+ *
+ * Runs from timber-prebuilt's `buildApp` post hook, after Vite's 5-step
+ * build sequence. Imports the BUILT `rsc/index.js` (the bundle carries
+ * the react-server condition resolved at build time, so a plain dynamic
+ * import works) and calls its `__timber_capturePrebuilt` export — the
+ * capture itself must run inside the bundle's module graph, where the
+ * component registry and flight renderer live. See
+ * server/prebuilt-builder.ts and design/44-render-at-build-time.md
+ * §Build Phase.
+ *
+ * This side owns PERSISTENCE: each captured payload is written to
+ * `.timber/dist/prebuilt/<componentId>/<cacheKey>.flight` atomically
+ * (temp file + rename — a crashed build never leaves a torn artifact
+ * under its final name), and `manifest.json` is written last, only after
+ * every payload it references is fully on disk. Keeping node:fs on the
+ * plugin side keeps it out of the server bundle, which must also run on
+ * Cloudflare Workers.
+ *
+ * NOTE: importing the built entry runs the app's production startup —
+ * instrumentation.ts register() and the configured cache handler load
+ * inside the build process. That is by design (prebuilt components may
+ * call timber.cache), and it only happens when the app actually declares
+ * prebuilt components.
+ */
+import type { PluginContext } from '../plugin-context.js';
+import type { CaptureSummary, CapturedEntry } from '../server/prebuilt-builder.js';
+export interface PrebuiltArtifactWriter {
+    write(entry: CapturedEntry): Promise<void>;
+    /** Write manifest.json (if any entries exist). Returns the entry count. */
+    finalize(): Promise<number>;
+}
+/**
+ * Create the writer for `.timber/dist/prebuilt/`. Storage layout per
+ * design/44 §Storage: one directory per component ID, one `.flight` file
+ * per cache key, one manifest.json mapping componentId + key → file +
+ * metadata.
+ */
+export declare function createPrebuiltArtifactWriter(prebuiltDir: string): PrebuiltArtifactWriter;
+/**
+ * Remove any `prebuilt/` output left by a previous build in this
+ * directory (watch mode, `emptyOutDir: false`). A stale manifest would
+ * make adapters ship payloads from an OLD build — reviving them serves
+ * outdated content with that build's chunk references instead of the
+ * intended miss → live render. Runs unconditionally at the start of the
+ * post-build hook, BEFORE the capture decision: a build whose app no
+ * longer declares any prebuilt components must also shed the artifacts
+ * (codex P2 on PR #836).
+ */
+export declare function cleanPrebuiltDir(buildDir: string): Promise<void>;
+/**
+ * Load the built RSC entry and run the capture pass. Throws (failing the
+ * build) on infrastructure errors — missing/unloadable entry — and on
+ * dynamic-context hard errors (cookies()/headers() in a prerendered
+ * component). Per-entry data errors skip-and-report per design/44
+ * §Build-Phase Error Handling.
+ */
+export declare function runPrebuiltCapture(ctx: PluginContext): Promise<CaptureSummary>;
+//# sourceMappingURL=prebuilt-capture.d.ts.map

package/dist/plugins/prebuilt-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prebuilt-capture.d.ts","sourceRoot":"","sources":["../../src/plugins/prebuilt-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAOH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAkB,cAAc,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAanG,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,2EAA2E;IAC3E,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7B;AASD;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,MAAM,GAAG,sBAAsB,CAwCxF;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtE;AASD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAiFpF"}