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

package/dist/plugins/fonts.d.ts

@@ -1,85 +1,46 @@
 /**
- * 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.ts';
+import type { BuildManifest } from '../server/build-manifest.ts';
+export { FontPipeline } from '../fonts/pipeline.ts';
+export { generateFontId, extractFontConfig, detectDynamicFontCall, parseGoogleFontImports, parseGoogleFontFamilies, parseLocalFontImportName, } from '../fonts/transform.ts';
+/**
+ * What the post-build phase asks of the font plugin (plugins/post-build.ts).
+ * Called after every environment has been built, so the font entries are
+ * complete — no environment's `generateBundle` has to run after the build
+ * manifest exists.
+ */
+export interface FontsBuildStep {
+    /** Write this build's font entries into the build manifest. */
+    contributeManifest(manifest: BuildManifest): void;
+    /**
+     * Directories of the client bundle this build filled with content-hashed
+     * font binaries — `[FONT_OUTPUT_DIR]` when any were emitted, else none.
+     */
+    immutableDirs(): string[];
+}
 /**
  * Create the timber-fonts Vite plugin.
  */
-export declare function timberFonts(ctx: PluginContext): Plugin;
+export declare function timberFonts(ctx: PluginContext): Plugin & {
+    api: FontsBuildStep;
+};
 //# sourceMappingURL=fonts.d.ts.map

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;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AA2BjE,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;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,kBAAkB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAClD;;;OAGG;IACH,aAAa,IAAI,MAAM,EAAE,CAAC;CAC3B;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,GAAG;IAAE,GAAG,EAAE,cAAc,CAAA;CAAE,CAgQhF"}

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,14 +1,26 @@
 /**
- * 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.
@@ -19,9 +31,10 @@ 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;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;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAKnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAM1D;;;;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/post-build.d.ts

@@ -0,0 +1,110 @@
+/**
+ * timber-post-build — the post-build phase, as one ordered handler.
+ *
+ * Everything timber does after Vite has built the three environments runs
+ * here, in this order, each step handed what the previous one returned:
+ *
+ *   1. finalize the build manifest — font entries, the RSC assets manifest
+ *      merged in once, JavaScript stripped once when client JS is disabled
+ *   2. prebuilt capture   (cache.component prerender payloads, design/44)
+ *   3. static generation  (output: 'static', design/11)
+ *   4. the build report
+ *   5. assemble `BuildArtifacts` and call the adapter's `buildOutput`
+ *
+ * One `buildApp` hook with `order: 'post'` — so Vite runs the RSC plugin's
+ * buildApp, which orchestrates every environment build and writes the
+ * assets manifests, first. The order above is this function's, not the
+ * plugin array's, and no step reads another's result off the shared
+ * context: sibling plugins contribute through the typed steps they expose
+ * (`FontsBuildStep`, `PrebuiltBuildStep`, `BuildReportStep`), which
+ * `timber()` hands to this plugin directly.
+ *
+ * Design docs: 18-build-system.md §"Post-Build Phase", 11-platform.md
+ * §"Build Artifacts", 49-explicit-subsystem-boundaries.md §B
+ */
+import type { Plugin, Rollup } from 'vite';
+import { type PluginContext } from '../plugin-context.ts';
+import type { BuildArtifacts, DirectoryArtifact } from '../adapters/types.ts';
+import type { BuildManifest } from '../server/build-manifest.ts';
+import type { FontsBuildStep } from './fonts.ts';
+import type { PrebuiltBuildStep } from './prebuilt.ts';
+import type { BuildReportStep } from './build-report.ts';
+import { type StaticSite } from './static-build.ts';
+/** The Vite environments whose output adapters consume. */
+declare const ARTIFACT_ENVIRONMENTS: readonly ['client', 'rsc', 'ssr'];
+type ArtifactEnvironment = (typeof ARTIFACT_ENVIRONMENTS)[number];
+/** Each environment's output directory, as its own `writeBundle` recorded it. */
+export type EnvironmentOutputs = Partial<Record<ArtifactEnvironment, DirectoryArtifact>>;
+/** The steps sibling plugins own. */
+export interface PostBuildSteps {
+    fonts: FontsBuildStep;
+    prebuilt: PrebuiltBuildStep;
+    report: BuildReportStep;
+}
+export declare function timberPostBuild(ctx: PluginContext, steps: PostBuildSteps): Plugin;
+/**
+ * The client bundle's assets directory, in the artifacts' form (no leading
+ * or trailing slash) — or `''` when its files are not all content-hashed.
+ *
+ * `assetsDir` names where Vite writes; it is the naming patterns that decide
+ * whether a file name carries a hash. Vite's defaults do
+ * (`<assetsDir>/[name]-[hash].js`), but an app can set
+ * `assetFileNames: 'static/[name][extname]'`, and marking that directory
+ * immutable would pin a changed image under an unchanged URL for a year. A
+ * pattern given as a function cannot be inspected, so it counts as unhashed:
+ * those files fall back to the revalidating per-file rule.
+ *
+ * @internal Exported for testing.
+ */
+export declare function hashedAssetsDir(assetsDir: string, output: Pick<Rollup.NormalizedOutputOptions, 'entryFileNames' | 'chunkFileNames' | 'assetFileNames'>): string;
+/**
+ * Keep only the directories whose every file the client bundle emitted.
+ *
+ * A producer knows it hashes what *it* writes, not what else lands beside it:
+ * Vite copies `public/` into the client output verbatim, so `public/assets/logo.png`
+ * sits in `assets/` under a stable name, and `public/_rsc/…` would sit among
+ * the hashed payloads. A directory holding any file the bundle did not emit
+ * is not content-hashed as a whole, and marking it immutable would pin that
+ * file for a year — so it is dropped, and its files take the per-file rule.
+ *
+ * @internal Exported for testing.
+ */
+export declare function onlyEmittedDirs(clientDir: string, dirs: readonly string[], emitted: ReadonlySet<string>): Promise<string[]>;
+/**
+ * Step 1: bring the build manifest to its final shape, once.
+ *
+ * `timber-build-manifest` creates it from the client bundle; this adds what
+ * only exists once every environment is built — the font entries and the
+ * per-route CSS and modulepreloads in the RSC plugin's assets manifest —
+ * and then, when client JavaScript is disabled, removes every JavaScript
+ * reference, from the manifest and from the assets manifests on disk. The
+ * manifest's `js` / `modulepreload` are cleared after the merge has written
+ * into them, so nothing the merge adds survives.
+ *
+ * Returns null only when no client bundle produced a manifest.
+ *
+ * @internal Exported for testing.
+ */
+export declare function finalizeBuildManifest(ctx: PluginContext, fonts: FontsBuildStep, rsc: DirectoryArtifact, ssr: DirectoryArtifact): Promise<BuildManifest | null>;
+/**
+ * Assemble the adapter's view of the build from what each step returned.
+ *
+ * Not a validator: every field is copied from the phase that produced it.
+ * The throws are the states the union cannot represent — a Vite environment
+ * that wrote no bundle, a static build with no site. Each means an earlier
+ * phase failed without failing the build, and a deploy missing its SSR
+ * bundle fails on the first request rather than here.
+ *
+ * @internal Exported for testing.
+ */
+export declare function assembleBuildArtifacts(input: {
+    output: 'server' | 'static';
+    outputDir: string;
+    environments: EnvironmentOutputs;
+    immutableDirs: readonly string[];
+    prebuilt?: DirectoryArtifact;
+    site?: StaticSite;
+    manifestInit?: string;
+}): BuildArtifacts;
+export {};
+//# sourceMappingURL=post-build.d.ts.map

package/dist/plugins/post-build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-build.d.ts","sourceRoot":"","sources":["../../src/plugins/post-build.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAG3C,OAAO,EAAiC,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACzF,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAuB,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGzE,2DAA2D;AAC3D,QAAA,MAAM,qBAAqB,YAAI,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAU,CAAC;AAChE,KAAK,mBAAmB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAMlE,iFAAiF;AACjF,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,iBAAiB,CAAC,CAAC,CAAC;AAEzF,qCAAqC;AACrC,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,cAAc,CAAC;IACtB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,MAAM,EAAE,eAAe,CAAC;CACzB;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAiCjF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,IAAI,CACV,MAAM,CAAC,uBAAuB,EAC9B,gBAAgB,GAAG,gBAAgB,GAAG,gBAAgB,CACvD,GACA,MAAM,CAKR;AAUD;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,GAC3B,OAAO,CAAC,MAAM,EAAE,CAAC,CAanB;AA+DD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,aAAa,EAClB,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,iBAAiB,EACtB,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAiB/B;AA4BD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,kBAAkB,CAAC;IACjC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,cAAc,CAyBjB"}

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

@@ -0,0 +1,67 @@
+/**
+ * Post-build prebuilt capture — Node-side orchestration (TIM-1119).
+ *
+ * Runs as the capture step of the post-build phase (plugins/post-build.ts),
+ * after Vite's 5-step build sequence and the manifest finalization step. 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 { DirectoryArtifact } from '../adapters/types.ts';
+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;
+/** What a capture pass produced. */
+export interface PrebuiltCaptureResult {
+    summary: CaptureSummary;
+    /** The payload directory — present only when the pass wrote a payload. */
+    artifact?: DirectoryArtifact;
+}
+/**
+ * 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
+ * capture step, 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, rscDir: string): Promise<PrebuiltCaptureResult>;
+//# 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,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,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;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,MAAM,GAAG,sBAAsB,CAwCxF;AAED,oCAAoC;AACpC,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,cAAc,CAAC;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtE;AASD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,qBAAqB,CAAC,CAyEhC"}

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,98 @@
+/**
+ * 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';
+import type { PrebuiltCaptureResult } from './prebuilt-capture.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[];
+/**
+ * What the post-build phase asks of the prebuilt plugin (plugins/post-build.ts).
+ */
+export interface PrebuiltBuildStep {
+    /**
+     * Run the capture pass against the built RSC bundle in `rscDir`. Always
+     * removes the previous build's `prebuilt/` first — even when this build
+     * captures nothing, a stale manifest must never ship. Returns null when
+     * there was nothing to capture: no prerender call site is reachable from a
+     * route, or `output: 'static'` already renders everything at build time.
+     */
+    capture(rscDir: string): Promise<PrebuiltCaptureResult | null>;
+}
+export declare function timberPrebuilt(ctx: PluginContext): Plugin & {
+    api: PrebuiltBuildStep;
+};
+//# 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;AAU1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AA2GnE;;;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;AA6HD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;CAChE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,GAAG;IAAE,GAAG,EAAE,iBAAiB,CAAA;CAAE,CAmStF"}