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

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.ts';
+/**
+ * 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.ts';
+import type { PositionedNode, ProgramNode } from './callsite-ast.ts';
+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.ts';
 /**
  * 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,sBAAsB,CAAC;AAE1D;;;;;;;;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/client-dep-entries.d.ts

@@ -0,0 +1,44 @@
+/**
+ * client-dep-entries — seed the client dep optimizer's startup scan with
+ * the app's `'use client'` modules.
+ *
+ * Vite's dev optimizer discovers bare imports by crawling from its
+ * entries before the first request. With no `optimizeDeps.entries`, the
+ * client environment crawls its build input — timber's browser entry —
+ * and nothing more: every `'use client'` module is reached only through
+ * the RSC payload at runtime, never through a static import the crawl
+ * can follow. A package imported only from client components is then
+ * found on the first browser request, re-optimized mid-load, and the
+ * page full-reloads ("optimized dependencies changed. reloading"). That
+ * reload can leave react and react-dom from two optimizer runs in the
+ * browser (duplicate React → "Invalid hook call").
+ *
+ * Listing the `'use client'` files as entries lets the startup crawl see
+ * those imports. Setting `entries` replaces the build-input default, so
+ * the browser entry is listed too. Files that gain the directive after
+ * startup still fall back to Vite's late discovery.
+ *
+ * Design docs: 21-dev-server.md §"Client Dependency Pre-Bundling".
+ */
+/**
+ * Every project source file under `root` whose directive prologue holds
+ * `'use client'`. Uses the same walker as `timber graph` (node_modules,
+ * root-level dot dirs and build outputs skipped) and the same AST
+ * directive check the RSC plugin applies. Files under `excludeDir` (the
+ * build output) are skipped.
+ */
+export declare function findUseClientFiles(root: string, excludeDir?: string): Promise<string[]>;
+/**
+ * Escape a path for use as an `optimizeDeps.entries` pattern. Vite globs
+ * entries, and route directories are full of glob syntax: `(group)`,
+ * `[slug]`, `[[...catchAll]]`, `@slot`. Slashes are normalized first, so
+ * the only backslashes left are literal (POSIX) ones, which are escaped
+ * too.
+ */
+export declare function escapeGlobPath(path: string): string;
+/**
+ * The client environment's `optimizeDeps.entries`: timber's browser
+ * entry plus every `'use client'` file in the project.
+ */
+export declare function clientOptimizeDepsEntries(root: string, browserEntryFile: string, buildDir: string): Promise<string[]>;
+//# sourceMappingURL=client-dep-entries.d.ts.map

package/dist/plugins/client-dep-entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-dep-entries.d.ts","sourceRoot":"","sources":["../../src/plugins/client-dep-entries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAOH;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAkB7F;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,MAAM,EACZ,gBAAgB,EAAE,MAAM,EACxB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,EAAE,CAAC,CAGnB"}

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.ts';
+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.ts';
 /**
  * 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,EAAgB,MAAM,MAAM,CAAC;AAGjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAyC1D;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAwGxD"}

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

@@ -0,0 +1,123 @@
+/**
+ * Dev-server discovery records — `.timber/dev/<pid>-<port>-<token>.json`.
+ *
+ * On startup each dev server writes `{ port, pid, host, protocol }` to its own record
+ * file under the app's `.timber/dev/` so the `timber graph` CLI and the
+ * VS Code extension can discover a running dev server for the
+ * live-graph fast path.
+ *
+ * One record file per server, one writer per file. This is what makes
+ * multi-server roots (Vite auto-increments the port across processes;
+ * programmatic embeddings run several servers in one process) safe
+ * without any coordination: there is no shared file to displace, no
+ * ownership to arbitrate, and no shutdown-order dependency — each
+ * server removes exactly its own record.
+ *
+ * Consumers must list the directory and trust a record only if its pid
+ * is alive AND a probe request to the endpoint succeeds; anything else
+ * is treated as absent (silent fallback), never an error. Stale records
+ * (crashed servers) are therefore the normal case — startup sweeps
+ * dead-pid records best-effort, and consumers validate the rest away.
+ *
+ * The directory layout and file format are implementation details, not
+ * a public contract.
+ *
+ * Design doc: 47-module-environment-tooling.md §5, 21-dev-server.md.
+ */
+import type { Server } from 'node:net';
+/** Relative path of the discovery directory within the project root. */
+export declare const DEV_DISCOVERY_DIR: string;
+export interface DevRecord {
+    port: number;
+    pid: number;
+    /**
+     * The bound address, as reported by the socket. Consumers probing the
+     * endpoint need it for servers bound to non-default interfaces;
+     * wildcard addresses (`0.0.0.0`, `::`) should be probed via loopback.
+     */
+    host: string;
+    /**
+     * Probe scheme. `server.https` dev servers (including HTTP/2) answer
+     * only TLS — an http:// probe of one would fail and wrongly trigger
+     * the cold-crawl fallback.
+     */
+    protocol: 'http' | 'https';
+    /**
+     * Vite `base` path. When non-root (e.g. `/my-app/`), the WebSocket
+     * upgrade path is `base + hmrPath`.
+     */
+    base?: string;
+    /**
+     * HMR WebSocket path (from `server.ws.path` or deprecated
+     * `server.hmr.path`). Absent when no path is configured (default `/`).
+     */
+    hmrPath?: string;
+    /**
+     * Custom WebSocket host override (from `server.ws.host` or deprecated
+     * `server.hmr.host`). When set, the WS connection targets this host
+     * instead of the HTTP server's bound address.
+     */
+    hmrHost?: string;
+    /**
+     * Custom WebSocket port override (from `server.ws.clientPort` ??
+     * `server.ws.port`, or deprecated `server.hmr.clientPort` ??
+     * `server.hmr.port`). When set, the WS connection targets this port
+     * instead of the HTTP server's bound port.
+     */
+    hmrPort?: number;
+    /**
+     * Custom WebSocket protocol override (from `server.ws.protocol` or
+     * deprecated `server.hmr.protocol`). When set (e.g. `'wss'`), the
+     * upgrade request uses the corresponding HTTP scheme.
+     */
+    hmrProtocol?: string;
+    /**
+     * Vite 8 WebSocket token (from `config.webSocketToken`). Required for
+     * browser WS upgrades; the extension passes it as `?token=` on the
+     * WebSocket URL.
+     */
+    webSocketToken?: string;
+    /**
+     * Absolute path to the Vite config file this server was started with.
+     * When multiple dev servers share a project root but use different
+     * configs, the fast path must only accept the record matching the
+     * config the CLI resolved (TIM-1393).
+     */
+    configFile?: string;
+}
+/** Best-effort "is this pid alive" — signal 0 probes without killing. */
+export declare function isPidAlive(pid: number): boolean;
+/**
+ * Register discovery-record lifecycle handlers on the dev server's HTTP
+ * server. Writes `.timber/dev/<pid>-<port>-<token>.json` once the server is
+ * listening (the bound port is only known then) and removes exactly
+ * that record on clean shutdown.
+ *
+ * All filesystem work is best-effort: a failure to write or remove a
+ * record must never break the dev server. `httpServer` is null in
+ * middleware mode — no port exists, so there is nothing to advertise.
+ * Typed as `net.Server` — the common base of Vite's `http.Server` and
+ * `Http2SecureServer` variants, which carries the events and `address()`.
+ */
+export declare function registerDevDiscovery(httpServer: Server | null, root: string, config?: {
+    configFile?: string | false;
+    base?: string;
+    server?: {
+        hmr?: {
+            path?: string;
+            host?: string;
+            port?: number;
+            clientPort?: number;
+            protocol?: string;
+        } | boolean;
+        ws?: {
+            path?: string;
+            host?: string;
+            port?: number;
+            clientPort?: number;
+            protocol?: string;
+        } | false;
+    };
+    webSocketToken?: string;
+}): void;
+//# sourceMappingURL=dev-discovery.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dev-discovery.d.ts","sourceRoot":"","sources":["../../src/plugins/dev-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAMvC,wEAAwE;AACxE,eAAO,MAAM,iBAAiB,QAAyB,CAAC;AAExD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAQ/C;AA+BD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE;IACP,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE;QACP,GAAG,CAAC,EACA;YAAE,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,UAAU,CAAC,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;SAAE,GACvF,OAAO,CAAC;QACZ,EAAE,CAAC,EACC;YAAE,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,UAAU,CAAC,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;SAAE,GACvF,KAAK,CAAC;KACX,CAAC;IACF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GACA,IAAI,CAsDN"}

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

@@ -12,11 +12,34 @@
  * 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.ts';
+/**
+ * Exit code used to signal the CLI supervisor that the dev server needs
+ * a full process restart (e.g. timber.config.ts changed). The supervisor
+ * in cli.ts respawns the worker on this code. 75 = EX_TEMPFAIL (sysexits).
+ * See TIM-1444.
+ */
+export declare const RESTART_EXIT_CODE = 75;
 /**
  * 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;AA8B1D;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAC;AA2BpC;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA0J1D;AAyND;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAuC9D"}

package/dist/plugins/entries.d.ts

@@ -11,14 +11,30 @@
  * 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.ts';
 /**
- * Detect the user's instrumentation.ts file at the project root.
+ * The real file behind virtual:timber-browser-entry. The client dep
+ * optimizer scans it explicitly once timber sets optimizeDeps.entries
+ * (see plugins/client-dep-entries.ts).
+ */
+export declare const BROWSER_ENTRY_FILE: string;
+/**
+ * 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 +45,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;AAsC1D;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAA2C,CAAC;AAmI3E;;;;;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"}