@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/dist/plugins/entries.d.ts

@@ -11,7 +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.ts';
+/**
+ * Detect a user convention file at both root and src/.
+ *
+ * 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.
  *
@@ -22,6 +39,20 @@ import type { PluginContext } from '#/index.js';
  * 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;AA0HhD;;;;;;;;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;AAsK1D;;;;;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,75 +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 the CSS output for all extracted fonts.
- *
- * Includes @font-face rules, 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.ts';
+export { FontPipeline } from '../fonts/pipeline.ts';
+export { generateFontId, extractFontConfig, detectDynamicFontCall, parseGoogleFontImports, parseGoogleFontFamilies, parseLocalFontImportName, } from '../fonts/transform.ts';
 /**
  * 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,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAkBxE;;;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;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAiBjE;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,CAoOtD"}
+{"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,CAqPtD"}

package/dist/plugins/graph-endpoint.d.ts

@@ -0,0 +1,112 @@
+/**
+ * graph-endpoint — `GET /__timber/graph` on the dev server.
+ *
+ * The fast path of design/47: when a dev server runs, the env module
+ * graphs are already resident and classification is a lookup. Serves
+ * the `timber graph` CLI (delegation lands with the fast-path ticket)
+ * and the VS Code extension, which additionally needs push updates on
+ * HMR — something a CLI cannot provide.
+ *
+ * Dev-only by construction: registered from the timber-dev-server
+ * plugin, which is `apply: 'serve'`; production builds contain none of
+ * this. Same JSON contract as the CLI, produced by the same
+ * classification module (analyze/live-graph.ts → classify/chains/
+ * poison-scan) — never a second implementation.
+ *
+ * Endpoint hygiene (§10): requests are validated against DNS rebinding
+ * consistent with Vite's own dev-endpoint protections — the Host
+ * header must be a localhost form or an allowed host (Vite's
+ * `server.allowedHosts` semantics, including leading-dot suffix
+ * entries), and a present Origin header must pass the same check. A
+ * CLI probe sends no Origin and passes; a browser on an attacker's
+ * page either fails the Host check (rebinding: Host is the attacker's
+ * domain) or the Origin check (direct cross-origin fetch).
+ *
+ * Push channel: `timber:graph-update` custom HMR events, one per
+ * project-source watcher event. The channel just emits — debounce is
+ * the consumer's concern (design/47 §"Dev-server endpoint").
+ *
+ * Design docs: 47-module-environment-tooling.md §10, 21-dev-server.md.
+ */
+import type { ViteDevServer } from 'vite';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { PluginContext } from '../plugin-context.ts';
+export declare const GRAPH_ENDPOINT_PATH = "/__timber/graph";
+/** HMR custom event name for graph-affecting file changes. */
+export declare const GRAPH_UPDATE_EVENT = "timber:graph-update";
+/**
+ * Host-header allowlist check, ported branch-for-branch from Vite's
+ * host-validation middleware (`isHostAllowedWithoutCache`) so this
+ * endpoint's reachability matches the rest of the dev server:
+ *
+ * - `allowedHosts: true` allows everything
+ * - a MISSING Host header is allowed (Vite parity — HTTP/1.0 probes)
+ * - any IP-literal host is allowed (`vite --host` LAN access sends
+ *   `Host: 192.168.x.x:port`; rejecting it would 403 this endpoint
+ *   while every other dev route works)
+ * - `localhost` and `*.localhost` are always allowed
+ * - allowedHosts entries: exact match, or `.suffix` subdomain entries
+ */
+export declare function isAllowedGraphHost(hostHeader: string | undefined, allowedHosts: true | string[] | undefined): boolean;
+/** Origin check: absent is fine (CLI probe); present must pass the host allowlist. */
+export declare function isAllowedGraphOrigin(originHeader: string | undefined, allowedHosts: true | string[] | undefined): boolean;
+/**
+ * Create the Connect middleware handling GET /__timber/graph.
+ *
+ * Query surface: `?file=<path>` (absolute or project-root-relative) or
+ * `?all=1`. Anything else is a 400 — fail loudly, like the CLI.
+ */
+export declare function createGraphEndpointMiddleware(server: ViteDevServer, ctx: PluginContext): (req: IncomingMessage, res: ServerResponse, next: () => void) => Promise<void>;
+/** What one hotUpdate invocation tells the emitter. */
+export interface GraphHotUpdate {
+    file: string;
+    /** Vite's own hotUpdate vocabulary. */
+    type: 'create' | 'update' | 'delete';
+    /** Environment the hook ran for (rsc/ssr/client). */
+    environment: string;
+}
+/** The push channel's two notification points for one edit. */
+export interface GraphUpdateChannel {
+    /** Feed from the plugin's hotUpdate hook (post graph invalidation). */
+    onHotUpdate(update: GraphHotUpdate): void;
+    /**
+     * Feed from the plugin's transform hook (module id, may carry a
+     * query suffix). Emits phase "transformed" for files with a pending
+     * invalidation, once their import edges are actually rebuilt.
+     */
+    onTransform(id: string, environment: string): void;
+}
+/**
+ * Accessor the channel uses to decide when a re-transforming module's
+ * graph data is current: Vite stores the node's `transformResult` only
+ * at the END of the transform request — after `vite:import-analysis`
+ * has rebuilt the importer edges — so a non-null result is the
+ * edges-are-current signal.
+ */
+export type IsNodeTransformed = (file: string, environment: string) => boolean;
+/**
+ * Build the push channel: `timber:graph-update` custom HMR events per
+ * project-source change. Consumers (the VS Code extension) re-query
+ * and debounce on their side; the channel just emits. Non-source noise
+ * (build output, dotdirs) is filtered by the same extension set the
+ * scanners use.
+ *
+ * Two phases per edit, because one is not enough (codex review, PR
+ * #1057): the `invalidated` event fires from the plugin's `hotUpdate`
+ * hook — after Vite clears the module's transform result, but its
+ * importer EDGES are only rebuilt when the module is next transformed.
+ * The `transformed` event fires for exactly the files with a pending
+ * invalidation, and only once the node's `transformResult` is set
+ * again — the plugin transform hook itself runs BEFORE Vite's trailing
+ * `vite:import-analysis` (which rebuilds the edges), so the hook only
+ * marks the file "settling" and a short bounded timer confirms
+ * completion via `isTransformed` before emitting. (A module nothing
+ * re-requests never re-transforms — its `transformed` event waits for
+ * the next render, which is also when the graph has new information.)
+ */
+export declare function makeGraphUpdateChannel(ctx: Pick<PluginContext, 'root' | 'config'>, send: (payload: {
+    type: 'custom';
+    event: string;
+    data: unknown;
+}) => void, isTransformed?: IsNodeTransformed, canonicalize?: (file: string) => string): GraphUpdateChannel;
+//# sourceMappingURL=graph-endpoint.d.ts.map

package/dist/plugins/graph-endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-endpoint.d.ts","sourceRoot":"","sources":["../../src/plugins/graph-endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAE1C,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAIjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD,8DAA8D;AAC9D,eAAO,MAAM,kBAAkB,wBAAwB,CAAC;AAExD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,YAAY,EAAE,IAAI,GAAG,MAAM,EAAE,GAAG,SAAS,GACxC,OAAO,CAwBT;AAqBD,sFAAsF;AACtF,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,YAAY,EAAE,IAAI,GAAG,MAAM,EAAE,GAAG,SAAS,GACxC,OAAO,CA2BT;AAsBD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,aAAa,SAElE,eAAe,OAAO,cAAc,QAAQ,MAAM,IAAI,KAAG,OAAO,CAAC,IAAI,CAAC,CAkM1F;AAED,uDAAuD;AACvD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACrC,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAC1C;;;;OAIG;IACH,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CACpD;AAED;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,QAAQ,CAAC,EAC3C,IAAI,EAAE,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,KAAK,IAAI,EACzE,aAAa,CAAC,EAAE,iBAAiB,EAMjC,YAAY,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAuB,GACtD,kBAAkB,CA2GpB"}

package/dist/plugins/mdx.d.ts

@@ -1,21 +1,40 @@
 /**
- * timber-mdx — Vite sub-plugin for MDX page rendering.
+ * timber-mdx — Vite sub-plugin for MDX and Markdown rendering.
  *
- * Wires @mdx-js/rollup into the Vite pipeline when MDX is activated.
+ * Wires vite-plugin-satteri into the Vite pipeline when MDX is activated.
  * MDX is activated when pageExtensions includes 'mdx' or 'md', or
  * when a content/ directory exists at the project root.
  *
+ * Satteri is a Rust-based Markdown/MDX compiler with a native Vite plugin:
+ * - `.mdx` files compile to React components (ES modules with real import
+ *   statements, so @vitejs/plugin-rsc client-boundary detection works).
+ * - `.md` files compile to modules exporting a rendered HTML string.
+ * - Frontmatter (YAML/TOML) parses natively and is emitted as a
+ *   `frontmatter` named export — no remark plugins needed.
+ * - GFM (tables, footnotes, strikethrough, task lists) is on by default.
+ *
+ * Extensibility is satteri's visitor-based plugin API (defineMdastPlugin /
+ * defineHastPlugin), not unified — the AST lives on the Rust side, so
+ * remark/rehype plugins cannot run. See design/20-content-collections.md.
+ *
  * 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.ts';
+/**
+ * Check if mdx-components.tsx (or .ts, .jsx, .js) exists at the project root
+ * or in src/. Root takes precedence, matching Next.js behavior.
+ * Returns the absolute path if found, otherwise undefined.
+ */
+export declare function findMdxComponents(root: string): string | undefined;
 /**
  * Create the timber-mdx Vite plugin.
  *
  * Uses the transform and resolveId hooks to delegate MDX compilation
- * to @mdx-js/rollup. The inner plugin is loaded lazily on first activation.
+ * to vite-plugin-satteri. The inner plugin is loaded lazily on first
+ * activation.
  *
- * Hooks: buildStart (loads @mdx-js/rollup), resolveId, load, transform
+ * Hooks: buildStart (loads vite-plugin-satteri), resolveId, load, transform
  */
 export declare function timberMdx(ctx: PluginContext): Plugin;
 //# sourceMappingURL=mdx.d.ts.map

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;AAmDhD;;;;;;;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;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAKnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAK1D;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAelE;AAqED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA4HpD"}

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.ts';
+import type { CaptureSummary, CapturedEntry } from '../server/prebuilt-builder.ts';
+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"}

package/dist/plugins/prebuilt-options-analysis.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Static analysis of `cache.component(fn, options)` option literals for
+ * the timber-prebuilt transform: can this call site's options put the
+ * component in the prerender tier?
+ *
+ * Runtime-tier call sites must do NO build work — recording them would
+ * make the post-build hook import the built RSC entry (running production
+ * startup) and load route modules for routes that have nothing to
+ * prerender (codex P2 on PR #836). The analysis is conservative in one
+ * direction only: over-inclusion costs a wasted entry load (the capture
+ * pass re-checks the real options at runtime and skips), under-inclusion
+ * would silently skip prerendering.
+ */
+import type { CallExpressionNode, PositionedNode } from './callsite-ast.ts';
+/** Unwrap TS expression wrappers (`as`, `satisfies`, `!`, parens). */
+export declare function unwrapExpression(node: PositionedNode): PositionedNode;
+/**
+ * Can this call site's options put the component in the prerender tier?
+ * The answer is static only when the options argument is an object
+ * literal:
+ *
+ *   - literal with `prerender: true`            → yes
+ *   - literal with `prerender: false`/absent    → no  (spread-free)
+ *   - literal with statically ACTIVE `slots` + certain runtime lifetime
+ *     → no — registration strips `prerender` for active slot components
+ *       (TIM-1173), so attributing the callsite would make the post-build
+ *       hook import the RSC entry and enumerate route params for entries
+ *       the capture pass then skips (codex P2 on PR #890)
+ *   - anything else (identifier, spread, non-literal values)
+ *     → conservatively yes — the capture pass re-checks at runtime
+ *
+ * Properties walk in source order with last-write-wins, mirroring
+ * object-literal evaluation: `{ prerender: false, ...opts }` may end up
+ * prerenderable (the spread can override), while `{ ...opts,
+ * prerender: false }` is statically false (codex P2 on PR #836).
+ * Computed keys are treated like spreads — they may evaluate to any of
+ * the tracked names.
+ */
+export declare function mayPrerender(call: CallExpressionNode): boolean;
+//# sourceMappingURL=prebuilt-options-analysis.d.ts.map

package/dist/plugins/prebuilt-options-analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prebuilt-options-analysis.d.ts","sourceRoot":"","sources":["../../src/plugins/prebuilt-options-analysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAS5E,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,CAMrE;AAsED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAoD9D"}

package/dist/plugins/prebuilt.d.ts

@@ -0,0 +1,82 @@
+/**
+ * timber-prebuilt — Vite plugin that detects `cache.component(...)` call
+ * sites and rewrites them to `__prebuilt(stableId, component, options)`.
+ *
+ * `timber.cache.component(Component, { prerender: true })` is a build-time
+ * transform, not a runtime function (design/44-render-at-build-time.md
+ * §Registration, surface API renamed by design/45-cache-lifetimes.md). The
+ * rewrite registers the component in the server-side prebuilt registry under
+ * a stable ID that keys its cached flight payloads.
+ *
+ * Detected callsite forms (mirrors timber-cache-transform, TIM-1054):
+ *   - named imports, including aliases:
+ *       `import { cache } from '@timber-js/app/cache'` + `cache.component(fn, opts)`
+ *   - namespace imports:
+ *       `import * as timber` + `timber.cache.component(fn, opts)`
+ * Computed access (`cache['component']`) is deliberately not matched — the
+ * untransformed call reaches the runtime `cache.component` fallback
+ * (cache/cache-api.ts), which warns once and renders dynamically.
+ *
+ * Matching is an ALLOWLIST of module-scope positions: the direct initializer
+ * of a top-level variable declarator (including exported ones) and a
+ * top-level `export default cache.component(...)`, with TS expression
+ * wrappers (`as`, `satisfies`, `!`) unwrapped. Nothing else is walked — no
+ * function/class/loop bodies, no params, no call arguments. Two reasons:
+ * (1) `__prebuilt` must register exactly once at module load time; the
+ * post-build capture pass walks the registry after loading modules, so a
+ * call inside a function registers too late to ever be prebuilt, and a call
+ * in a loop would re-register per iteration. (2) Name-based callee matching
+ * is only shadow-proof in these positions — nested scopes can rebind `cache`
+ * (`function render(cache) {...}`, `for (const cache of caches) ...`), and
+ * rewriting those would corrupt user code; a top-level declarator initializer
+ * cannot see a shadow of an import binding (redeclaration error). Calls in
+ * other positions fall back to the runtime path like other untraceable forms.
+ *
+ * The rewrite per mode:
+ *   production:  cache.component(fn, opts)  →  __prebuilt("<id>", fn, opts)
+ *   dev:         cache.component(fn, opts)  →  __prebuiltDev("<name>", fn, opts)
+ *
+ * with `import { __prebuilt } from '#server-internal'` prepended. In dev the
+ * wrapper is a no-op that logs once per component and renders dynamically —
+ * no caching, no markers (design/44 §Dev Mode).
+ *
+ * Component identity: `<name>_<hash16>`, e.g. `blogbody_a1b2c3d4e5f6a7b8`.
+ * The name prefix is the declaring variable's name (lowercased, for legible
+ * manifest keys and log lines); the hash is the same content-derived callsite
+ * scheme as the data cache transform (callsite-ast.ts) — deterministic across
+ * builds for unchanged calls, immune to inserting/reordering other calls, and
+ * fresh when the component or its options change. Component cache entries are
+ * per-deploy (design/45 §Per-deploy namespacing) so cross-deploy ID reuse is
+ * not a poisoning vector, but content-derived IDs keep prebuilt artifacts
+ * addressable across incremental edits for free.
+ *
+ * The transform is skipped in the client environment: server components never
+ * execute there, and `#server-internal` resolves to an empty stub in the
+ * client bundle (plugins/shims.ts).
+ *
+ * See TIM-1118, design/44-render-at-build-time.md, design/45-cache-lifetimes.md.
+ */
+import type { Plugin } from 'vite';
+import type { PluginContext } from '../plugin-context.ts';
+/**
+ * Generate the stable component ID for a cache.component() call site:
+ * `<sanitized-name>_<content-hash16>`. Exported for testing.
+ */
+export declare function generatePrebuiltId(relativeModulePath: string, statementText: string, callSpanText: string, occurrence: number, displayName: string): string;
+/** Rollup getModuleInfo shape (subset — static + dynamic imports). */
+export interface PrebuiltModuleInfo {
+    importedIds: string[];
+    dynamicallyImportedIds?: string[];
+}
+/**
+ * Collect the prebuilt component IDs transitively reachable from a route
+ * file, following static AND dynamic imports. Same pattern as the
+ * client-reference walk in build-manifest.ts; dynamic imports are included
+ * because a dynamically-imported module still registers its components
+ * when it eventually loads — attribution over-approximating registration
+ * is handled at capture time (an attributed-but-unregistered component is
+ * reported and skipped).
+ */
+export declare function collectReachablePrebuiltComponents(entryModuleId: string, moduleComponents: Map<string, string[]>, getModuleInfo: (id: string) => PrebuiltModuleInfo | null): string[];
+export declare function timberPrebuilt(ctx: PluginContext): Plugin;
+//# sourceMappingURL=prebuilt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prebuilt.d.ts","sourceRoot":"","sources":["../../src/plugins/prebuilt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAoH1D;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,kBAAkB,EAAE,MAAM,EAC1B,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,MAAM,CAUR;AAID,sEAAsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,wBAAgB,kCAAkC,CAChD,aAAa,EAAE,MAAM,EACrB,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EACvC,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,kBAAkB,GAAG,IAAI,GACvD,MAAM,EAAE,CAgBV;AA8HD,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAkSzD"}

package/dist/plugins/prerender-sugar.d.ts

@@ -0,0 +1,39 @@
+/**
+ * timber-prerender-sugar — Vite plugin that desugars `export const prerender`
+ * on page and layout files into `cache.component(...)` wrappers.
+ *
+ * Design doc: design/45-cache-lifetimes.md §"Route-Level Static" and
+ * §"Layout Propagation".
+ *
+ * `export const prerender = true` on a page is pure sugar: it desugars to
+ * wrapping the page's default export in `timber.cache.component(Component,
+ * { prerender: true })`. Layout propagation cascades a layout's
+ * `export const prerender` to descendant pages via most-specific-wins:
+ * walk the segment tree from leaf to root, first explicit value wins.
+ *
+ * Layout declarations are propagation policy only. Layouts receive the real
+ * descendant React element as `children` to preserve the server-layout
+ * containment boundary, so their props are not cache-keyable and the layout
+ * itself must not be registered for capture.
+ *
+ * This transform runs BEFORE timber-prebuilt so the generated
+ * `cache.component(...)` call is picked up by the callsite rewrite.
+ */
+import type { Plugin } from 'vite';
+import type { PluginContext } from '../plugin-context.ts';
+import type { SegmentNode } from '../routing/types.ts';
+import { type PrerenderExportValue } from '../routing/export-detect.ts';
+/**
+ * Walk the segment tree and resolve the effective prerender value for
+ * every page. Returns a map from page file path to resolved value.
+ *
+ * **Pages:** walk from leaf toward root; first explicit `export const prerender`
+ * wins (page > nearest layout > ... > root layout). If none, dynamic.
+ *
+ * **Layouts:** declarations propagate to descendant pages but layouts are not
+ * included in the result. Their real React-element `children` preserve secure
+ * containment and deliberately make child-independent layout caching invalid.
+ */
+export declare function resolvePagePrerender(root: SegmentNode): Map<string, PrerenderExportValue>;
+export declare function timberPrerenderSugar(ctx: PluginContext): Plugin;
+//# sourceMappingURL=prerender-sugar.d.ts.map

package/dist/plugins/prerender-sugar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prerender-sugar.d.ts","sourceRoot":"","sources":["../../src/plugins/prerender-sugar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAa,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAsB,KAAK,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAY5F;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CA2BzF;AAuFD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA4J/D"}