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

package/dist/params/codec-registry.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Client-side registry for schema segment param codecs.
+ *
+ * The Link component uses codec `serialize` functions to convert typed
+ * segment param values back to URL-safe strings. Without this registry,
+ * Link falls back to `String(value)` — which works for simple types
+ * but breaks for custom codecs (e.g., Date → '2026-04-10').
+ *
+ * Populated at startup by the browser entry importing `virtual:timber-schema`.
+ * Also usable on the server (isomorphic).
+ *
+ * Design doc: design/41-global-params.md §"Link Component"
+ */
+import type { Codec } from '../codec.ts';
+/**
+ * Register the resolved schema codecs for use by Link's URL interpolation.
+ * Called once at startup from the browser entry or RSC entry.
+ * @internal
+ */
+export declare function setLinkCodecs(codecs: Record<string, Codec<unknown>> | null): void;
+/**
+ * Look up a codec by bracket key (e.g. '[id]', '[...slug]').
+ * Returns undefined if no schema is registered or the key has no codec.
+ */
+export declare function getLinkCodec(bracketKey: string): Codec<unknown> | undefined;
+//# sourceMappingURL=codec-registry.d.ts.map

package/dist/params/codec-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec-registry.d.ts","sourceRoot":"","sources":["../../src/params/codec-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAIzC;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,CAEjF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,SAAS,CAE3E"}

package/dist/params/define-schema.d.ts

@@ -0,0 +1,81 @@
+/**
+ * defineSchema — global segment param schema definition.
+ *
+ * Identity function at runtime; the type information is what matters.
+ * The Vite plugin reads the schema at build time for codegen, and
+ * the pipeline reads it at runtime for coercion.
+ *
+ * Design doc: design/41-global-params.md
+ */
+import type { Codec, CatchAllCodec, OptionalCatchAllCodec } from '../codec.ts';
+import type { StandardSchemaV1 } from '../schema-bridge.ts';
+/**
+ * Infer the output type from a Codec, StandardSchemaV1, or nuqs parser.
+ *
+ * Used by codegen to reference schema types without hardcoding:
+ *   `InferCodecType<typeof schema.segmentParams['[year]']>`
+ */
+export type InferCodecType<V> = V extends Codec<infer T> ? T : V extends StandardSchemaV1<infer T> ? T : V extends {
+    parseServerSide: (value: string) => infer T;
+} ? T : string;
+/** Acceptable codec value for segment params: a Codec or Standard Schema. */
+export type SegmentParamCodec = Codec<unknown> | StandardSchemaV1<unknown>;
+/** Codec constraint for catch-all segment keys (`[...name]`). */
+export type CatchAllParamCodec = CatchAllCodec<unknown> | StandardSchemaV1<readonly unknown[]>;
+/** Codec constraint for optional catch-all segment keys (`[[...name]]`). */
+export type OptionalCatchAllParamCodec = OptionalCatchAllCodec<unknown> | StandardSchemaV1<readonly unknown[] | undefined>;
+/**
+ * Resolves the required codec type for a given bracket key pattern.
+ * - `[...name]`    → requires a catch-all codec
+ * - `[[...name]]`  → requires an optional catch-all codec
+ * - `[name]`       → accepts any segment param codec
+ */
+export type CodecForKey<K extends string> = K extends `[[...${string}]]` ? OptionalCatchAllParamCodec : K extends `[...${string}]` ? CatchAllParamCodec : SegmentParamCodec;
+/**
+ * Registry interface augmented by codegen with known filesystem bracket keys.
+ * When empty (no codegen yet), ValidDynamicSegmentKeys falls back to string.
+ */
+export interface ValidDynamicSegmentKeysRegistry {
+}
+/**
+ * Union of valid bracket keys for defineSchema.
+ * After codegen runs, this is the set of filesystem segment names.
+ * Before codegen (fresh project), accepts any string.
+ */
+export type ValidDynamicSegmentKeys = keyof ValidDynamicSegmentKeysRegistry extends never ? string : keyof ValidDynamicSegmentKeysRegistry & string;
+/** Configuration object for defineSchema. */
+export interface SchemaConfig<S extends Record<string, SegmentParamCodec>> {
+    segmentParams: S;
+}
+/**
+ * Define the global segment param schema.
+ *
+ * Each key uses the bracket syntax from the filesystem (`[id]`, `[...slug]`,
+ * `[[...slug]]`) mapped to a codec. This makes the relationship between
+ * filesystem segments and codecs visually obvious.
+ *
+ * A dynamic segment with no key here defaults to `string` at codegen time.
+ *
+ * ```ts
+ * // app/schema.ts
+ * import { defineSchema } from '@timber-js/app/params';
+ * import { codec } from '@timber-js/app/codec';
+ * import { z } from 'zod';
+ *
+ * export default defineSchema({
+ *   segmentParams: {
+ *     '[artistSlug]': codec.string,
+ *     '[year]': codec.integer,
+ *     '[id]': z.coerce.number().int(),
+ *   },
+ * });
+ * ```
+ */
+export declare function defineSchema<S extends {
+    [K in keyof S]: K extends ValidDynamicSegmentKeys ? K extends string ? CodecForKey<K> : SegmentParamCodec : never;
+}>(config: {
+    segmentParams: S;
+}): {
+    segmentParams: S;
+};
+//# sourceMappingURL=define-schema.d.ts.map

package/dist/params/define-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-schema.d.ts","sourceRoot":"","sources":["../../src/params/define-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAM5D;;;;;GAKG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAC1B,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,GACpB,CAAC,GACD,CAAC,SAAS,gBAAgB,CAAC,MAAM,CAAC,CAAC,GACjC,CAAC,GACD,CAAC,SAAS;IAAE,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,CAAA;CAAE,GACvD,CAAC,GACD,MAAM,CAAC;AAEjB,6EAA6E;AAC7E,MAAM,MAAM,iBAAiB,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAE3E,iEAAiE;AACjE,MAAM,MAAM,kBAAkB,GAAG,aAAa,CAAC,OAAO,CAAC,GAAG,gBAAgB,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;AAE/F,4EAA4E;AAC5E,MAAM,MAAM,0BAA0B,GAClC,qBAAqB,CAAC,OAAO,CAAC,GAC9B,gBAAgB,CAAC,SAAS,OAAO,EAAE,GAAG,SAAS,CAAC,CAAC;AAErD;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,QAAQ,MAAM,IAAI,GACpE,0BAA0B,GAC1B,CAAC,SAAS,OAAO,MAAM,GAAG,GACxB,kBAAkB,GAClB,iBAAiB,CAAC;AAExB;;;GAGG;AAEH,MAAM,WAAW,+BAA+B;CAAG;AAEnD;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,+BAA+B,SAAS,KAAK,GACrF,MAAM,GACN,MAAM,+BAA+B,GAAG,MAAM,CAAC;AAEnD,6CAA6C;AAC7C,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACvE,aAAa,EAAE,CAAC,CAAC;CAClB;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAC1B,CAAC,SAAS;KACP,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,SAAS,uBAAuB,GAC7C,CAAC,SAAS,MAAM,GACd,WAAW,CAAC,CAAC,CAAC,GACd,iBAAiB,GACnB,KAAK;CACV,EACD,MAAM,EAAE;IAAE,aAAa,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,aAAa,EAAE,CAAC,CAAA;CAAE,CAEpD"}

package/dist/params/index.d.ts

@@ -0,0 +1,5 @@
+export { defineSchema } from './define-schema.ts';
+export type { InferCodecType, SchemaConfig, SegmentParamCodec, ValidDynamicSegmentKeys, ValidDynamicSegmentKeysRegistry, } from './define-schema.ts';
+export { resolveSchemaCodecs, toBracketKey } from './resolve-schema.ts';
+export { setLinkCodecs, getLinkCodec } from './codec-registry.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/params/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/params/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EACV,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,uBAAuB,EACvB,+BAA+B,GAChC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/params/index.js

@@ -0,0 +1,34 @@
+import { n as toBracketKey, t as resolveSchemaCodecs } from "../_chunks/resolve-schema-CBR6Lm4i.js";
+import { n as setLinkCodecs, t as getLinkCodec } from "../_chunks/codec-registry-oOUxugz3.js";
+//#region src/params/define-schema.ts
+/**
+* Define the global segment param schema.
+*
+* Each key uses the bracket syntax from the filesystem (`[id]`, `[...slug]`,
+* `[[...slug]]`) mapped to a codec. This makes the relationship between
+* filesystem segments and codecs visually obvious.
+*
+* A dynamic segment with no key here defaults to `string` at codegen time.
+*
+* ```ts
+* // app/schema.ts
+* import { defineSchema } from '@timber-js/app/params';
+* import { codec } from '@timber-js/app/codec';
+* import { z } from 'zod';
+*
+* export default defineSchema({
+*   segmentParams: {
+*     '[artistSlug]': codec.string,
+*     '[year]': codec.integer,
+*     '[id]': z.coerce.number().int(),
+*   },
+* });
+* ```
+*/
+function defineSchema(config) {
+	return config;
+}
+//#endregion
+export { defineSchema, getLinkCodec, resolveSchemaCodecs, setLinkCodecs, toBracketKey };
+
+//# sourceMappingURL=index.js.map

package/dist/params/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/params/define-schema.ts"],"sourcesContent":["/**\n * defineSchema — global segment param schema definition.\n *\n * Identity function at runtime; the type information is what matters.\n * The Vite plugin reads the schema at build time for codegen, and\n * the pipeline reads it at runtime for coercion.\n *\n * Design doc: design/41-global-params.md\n */\n\nimport type { Codec, CatchAllCodec, OptionalCatchAllCodec } from '../codec.ts';\nimport type { StandardSchemaV1 } from '../schema-bridge.ts';\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/**\n * Infer the output type from a Codec, StandardSchemaV1, or nuqs parser.\n *\n * Used by codegen to reference schema types without hardcoding:\n *   `InferCodecType<typeof schema.segmentParams['[year]']>`\n */\nexport type InferCodecType<V> =\n  V extends Codec<infer T>\n    ? T\n    : V extends StandardSchemaV1<infer T>\n      ? T\n      : V extends { parseServerSide: (value: string) => infer T }\n        ? T\n        : string;\n\n/** Acceptable codec value for segment params: a Codec or Standard Schema. */\nexport type SegmentParamCodec = Codec<unknown> | StandardSchemaV1<unknown>;\n\n/** Codec constraint for catch-all segment keys (`[...name]`). */\nexport type CatchAllParamCodec = CatchAllCodec<unknown> | StandardSchemaV1<readonly unknown[]>;\n\n/** Codec constraint for optional catch-all segment keys (`[[...name]]`). */\nexport type OptionalCatchAllParamCodec =\n  | OptionalCatchAllCodec<unknown>\n  | StandardSchemaV1<readonly unknown[] | undefined>;\n\n/**\n * Resolves the required codec type for a given bracket key pattern.\n * - `[...name]`    → requires a catch-all codec\n * - `[[...name]]`  → requires an optional catch-all codec\n * - `[name]`       → accepts any segment param codec\n */\nexport type CodecForKey<K extends string> = K extends `[[...${string}]]`\n  ? OptionalCatchAllParamCodec\n  : K extends `[...${string}]`\n    ? CatchAllParamCodec\n    : SegmentParamCodec;\n\n/**\n * Registry interface augmented by codegen with known filesystem bracket keys.\n * When empty (no codegen yet), ValidDynamicSegmentKeys falls back to string.\n */\n// eslint-disable-next-line typescript/no-empty-interface -- augmented by codegen\nexport interface ValidDynamicSegmentKeysRegistry {}\n\n/**\n * Union of valid bracket keys for defineSchema.\n * After codegen runs, this is the set of filesystem segment names.\n * Before codegen (fresh project), accepts any string.\n */\nexport type ValidDynamicSegmentKeys = keyof ValidDynamicSegmentKeysRegistry extends never\n  ? string\n  : keyof ValidDynamicSegmentKeysRegistry & string;\n\n/** Configuration object for defineSchema. */\nexport interface SchemaConfig<S extends Record<string, SegmentParamCodec>> {\n  segmentParams: S;\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Define the global segment param schema.\n *\n * Each key uses the bracket syntax from the filesystem (`[id]`, `[...slug]`,\n * `[[...slug]]`) mapped to a codec. This makes the relationship between\n * filesystem segments and codecs visually obvious.\n *\n * A dynamic segment with no key here defaults to `string` at codegen time.\n *\n * ```ts\n * // app/schema.ts\n * import { defineSchema } from '@timber-js/app/params';\n * import { codec } from '@timber-js/app/codec';\n * import { z } from 'zod';\n *\n * export default defineSchema({\n *   segmentParams: {\n *     '[artistSlug]': codec.string,\n *     '[year]': codec.integer,\n *     '[id]': z.coerce.number().int(),\n *   },\n * });\n * ```\n */\nexport function defineSchema<\n  S extends {\n    [K in keyof S]: K extends ValidDynamicSegmentKeys\n      ? K extends string\n        ? CodecForKey<K>\n        : SegmentParamCodec\n      : never;\n  },\n>(config: { segmentParams: S }): { segmentParams: S } {\n  return config;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAwGA,SAAgB,aAQd,QAAoD;CACpD,OAAO;AACT"}

package/dist/params/resolve-schema.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Schema resolution — resolves the global schema's segmentParams into
+ * a runtime-ready codec map keyed by bracket name (e.g. '[id]').
+ *
+ * Bracket keys are preserved so that `[id]`, `[...id]`, and `[[...id]]`
+ * remain distinct entries. The coercion layer reconstructs bracket keys
+ * from matched segment metadata to look up the correct codec.
+ *
+ * Design doc: design/41-global-params.md §Pipeline Integration
+ */
+import type { Codec } from '../codec.ts';
+/**
+ * Reconstruct the bracket key for a segment from its type and param name.
+ * Used by the coercion layer to look up codecs in the bracket-keyed map.
+ *
+ * 'dynamic'          + 'id'   → '[id]'
+ * 'catch-all'        + 'slug' → '[...slug]'
+ * 'optional-catch-all' + 'slug' → '[[...slug]]'
+ */
+export declare function toBracketKey(segmentType: string, paramName: string): string;
+/**
+ * Resolve the global schema's segmentParams into a map of bracket-keyed
+ * param name → resolved Codec.
+ *
+ * Keys are preserved exactly as written in `app/schema.ts` so that
+ * `[id]`, `[...id]`, and `[[...id]]` remain distinct entries.
+ * The coercion layer in `param-coercion.ts` reconstructs bracket keys
+ * from matched segment metadata to look up the correct codec.
+ *
+ * Input:  { '[id]': z.coerce.number(), '[...slug]': codec.string }
+ * Output: { '[id]': Codec<number>, '[...slug]': Codec<string> }
+ */
+export declare function resolveSchemaCodecs(segmentParams: Record<string, unknown>): Record<string, Codec<unknown>>;
+//# sourceMappingURL=resolve-schema.d.ts.map

package/dist/params/resolve-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-schema.d.ts","sourceRoot":"","sources":["../../src/params/resolve-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGzC;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAS3E;AAaD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAyBhC"}

package/dist/plugin-context.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Plugin context — internal types and helpers for timber sub-plugins.
+ *
+ * These are NOT part of the user-facing API. They are consumed by
+ * sub-plugins (routing, entries, shims, etc.) via relative imports.
+ * The root entry point (index.ts) does not re-export them.
+ *
+ * Design doc: 18-build-system.md §"Shared Plugin Context"
+ */
+import type { RouteTree } from './routing/types.ts';
+import type { BuildManifest } from './server/build-manifest.ts';
+import type { StartupTimer } from './utils/startup-timer.ts';
+import type { TimberUserConfig } from './config-types.ts';
+import type { HoldingServer } from './dev-tools/holding-server.ts';
+import type { ProgramNode } from './plugins/callsite-ast.ts';
+import type { TimberConfig, TimberPlatformAdapter } from './adapters/types.ts';
+export type { TimberUserConfig, ClientJavascriptConfig } from './config-types.ts';
+/** Fully resolved client JavaScript configuration (no optionals). */
+export interface ResolvedClientJavascript {
+    disabled: boolean;
+    enableHMRInDev: boolean;
+}
+/**
+ * Resolve `clientJavascript` into a fully resolved config.
+ */
+export declare function resolveClientJavascript(config: TimberUserConfig): ResolvedClientJavascript;
+/**
+ * Shared context object passed to all sub-plugins via closure.
+ *
+ * Sub-plugins communicate through this context — not through Vite's
+ * plugin API or global state.
+ * See design/18-build-system.md §"Shared Plugin Context".
+ */
+export interface PluginContext {
+    config: TimberUserConfig;
+    /** Resolved client JavaScript configuration */
+    clientJavascript: ResolvedClientJavascript;
+    /** The scanned route tree (populated by timber-routing, consumed by timber-entries) */
+    routeTree: RouteTree | null;
+    /** Absolute path to the app/ directory */
+    appDir: string;
+    /** Absolute path to the project root */
+    root: string;
+    /** Whether the dev server is running (set by timber-root-sync in configResolved) */
+    dev: boolean;
+    /**
+     * Vite's resolved `base` (set by timber-root-sync in configResolved).
+     * Always has a trailing slash; `'/'` unless the app is deployed under a
+     * sub-path. Every URL the framework emits — assets, fonts, RSC payloads —
+     * carries this prefix. This is the single copy: sub-plugins read it here
+     * rather than capturing `config.base` in their own configResolved.
+     *
+     * **Availability:** written by timber-root-sync, which has no `enforce`, so
+     * it is populated from `buildStart`/`load`/`generateBundle`/`configureServer`
+     * onward — but NOT during the `configResolved` of an `enforce: 'pre'`
+     * plugin, which Vite runs first. A pre plugin that needs the base inside
+     * its own `configResolved` must read `config.base` there (timber-fonts
+     * does). See TIM-1261.
+     */
+    base: string;
+    /**
+     * The build manifest. Created by timber-build-manifest from the client
+     * bundle and finalized by the post-build phase (plugins/post-build.ts),
+     * which is the only reader. Null in dev.
+     */
+    buildManifest: BuildManifest | null;
+    /** Per-build deployment ID for version skew detection (null in dev) */
+    deploymentId: string | null;
+    /** Startup timer for profiling cold start phases (active in dev, no-op in prod) */
+    timer: StartupTimer;
+    /** Holding server that binds the port during dev startup (closed in timber-dev-server) */
+    holdingServer?: HoldingServer | null;
+    /**
+     * Resolved absolute path to the build output directory.
+     *
+     * Defaults to `<root>/.timber/dist`. Can be overridden via
+     * `timber.config.ts` `buildDir` or Vite's `build.outDir`.
+     * Timber config takes precedence when both are set.
+     *
+     * The `config` hook resolves it into Vite's `build.outDir`, and
+     * `configResolved` reads it back from Vite — the one assignment after
+     * construction, so what the build writes to and what `timber preview`
+     * serves (through {@link TimberPluginApi}) are the same directory.
+     */
+    buildDir: string;
+    /**
+     * Per-route client reference keys captured during the RSC build.
+     * Maps absolute route file paths to the set of client reference
+     * hash keys they transitively import. Used by the post-build phase to
+     * populate per-route modulepreload entries from clientReferenceDeps.
+     */
+    routeClientRefKeys?: Map<string, Set<string>>;
+    /**
+     * Static request-dependency verdict per segment entry file, keyed by the
+     * absolute `filePath` the route scanner produced. Computed once by
+     * `timber-request-dep`'s RSC `buildEnd` and serialized into
+     * `buildManifest.requestDep` by `timber-build-manifest` (build only — dev
+     * answers the same question through the `Symbol.for('timber:request-dep')`
+     * bridge instead).
+     *
+     * `undefined` and `{}` are different states and the difference is the whole
+     * of TIM-1300: an empty object means the analysis ran and found no segments,
+     * `undefined` means it never ran, and the runtime cannot tell them apart —
+     * every key is absent either way, so every segment falls to the conservative
+     * `true` and nothing is ever skipped. The build fails loudly on `undefined`
+     * rather than shipping that silently.
+     */
+    requestDepMap?: Record<string, boolean>;
+    /**
+     * Maps absolute module IDs of client references in non-facade RSC
+     * chunks to the absolute paths of their consuming facade modules.
+     * Built during the RSC `generateBundle` phase by timber-chunks,
+     * consumed by `clientChunkGroup` to reclassify `shared:` modules
+     * that are only used by a single route boundary.
+     * See design/27-chunking-strategy.md, TIM-1107.
+     */
+    sharedModuleFacades?: Map<string, string[]>;
+    /**
+     * Component ID → distinct static call-site prop objects captured from
+     * JSX usage sites during the transform and generateBundle phases.
+     * Consumed by the post-build capture pass to render with actual props
+     * instead of empty `{}`. See design/44 §Props Derivation.
+     */
+    prebuiltCallSiteProps?: Map<string, Record<string, unknown>[]>;
+    /**
+     * Route file path (page or layout, absolute) → prebuilt component IDs
+     * transitively reachable from it. Computed during RSC `generateBundle`,
+     * consumed by the post-build capture pass (TIM-1119) to decide which
+     * components to render under which route's param combos.
+     */
+    routePrebuiltComponents?: Map<string, string[]>;
+    /**
+     * Component ID → built chunk file name for prebuilt-declaring modules
+     * that are only reachable via dynamic imports (import.meta.glob, lazy
+     * routes). The capture pass imports these chunks to trigger
+     * cache.component() registration before rendering. Populated during
+     * RSC generateBundle alongside routePrebuiltComponents.
+     */
+    prebuiltLazyChunks?: Map<string, string>;
+    /**
+     * Content-keyed AST parse memo shared across cache/prebuilt/prerender-sugar
+     * transforms. Collapses both cross-plugin and cross-environment duplicate
+     * parses: identical code hits, rewritten code misses (correct because Vite
+     * transforms chain — a rewrite produces different code). Bounded LRU (32
+     * entries) so it doesn't hold programs for the whole build.
+     *
+     * Consumers MUST treat the returned ProgramNode as read-only — they collect
+     * ranges and rewrite CODE via MagicString; the AST itself is never mutated.
+     */
+    parseCached?: ParseMemo;
+}
+/**
+ * Content-keyed LRU memo for `parseAst`. Transforms for the same module run
+ * back-to-back across plugins and environments, so a tiny window captures the
+ * wins. The returned ProgramNode is shared — callers MUST NOT mutate it.
+ */
+export declare class ParseMemo {
+    private cache;
+    /**
+     * Parse code, returning a cached ProgramNode if the same code was parsed
+     * before. The returned AST MUST NOT be mutated — it may be shared across
+     * multiple consumers.
+     */
+    parse(code: string): ProgramNode;
+    get size(): number;
+}
+/**
+ * What `timber-root-sync` publishes on its Vite `plugin.api`.
+ *
+ * The single supported way to read timber's *resolved* configuration from
+ * outside the plugin pipeline. Re-reading `timber.config.ts` is not equivalent:
+ * config passed inline as `timber({ ... })` in `vite.config.ts` exists only in
+ * the plugin's closure, and `root`/`appDir` are resolved against Vite's root
+ * rather than the caller's cwd.
+ */
+export interface TimberPluginApi {
+    /** The live plugin context. Fully populated from `configResolved` onward. */
+    getContext(): PluginContext;
+}
+/** Narrow an unknown Vite `plugin.api` to timber's. */
+export declare function isTimberPluginApi(api: unknown): api is TimberPluginApi;
+/**
+ * The configured platform adapter. `adapter` is typed `unknown` on the user
+ * config so that `timber.config.ts` does not depend on the adapter types; the
+ * adapter factories are what produce values of this shape.
+ */
+export declare function contextAdapter(ctx: PluginContext): TimberPlatformAdapter | undefined;
+/**
+ * The configuration an adapter is handed, derived once from the resolved
+ * context — by the post-build phase for `buildOutput` and by `timber preview`
+ * for `preview`.
+ */
+export declare function adapterConfig(ctx: PluginContext): TimberConfig;
+/**
+ * Resolve the app directory. Checks (in order):
+ * 1. Explicit `configAppDir` from timber.config.ts
+ * 2. `<root>/app`
+ * 3. `<root>/src/app`
+ *
+ * Throws if none exist.
+ */
+export declare function resolveAppDir(root: string, configAppDir?: string): string;
+export declare function createPluginContext(config?: TimberUserConfig, root?: string): PluginContext;
+/** Default build output directory (relative to root). */
+export declare const DEFAULT_BUILD_DIR: string;
+/**
+ * Resolve the build output directory.
+ *
+ * Priority:
+ * 1. Explicit `timberBuildDir` from timber.config.ts
+ * 2. Explicit `viteBuildOutDir` from Vite's build.outDir (if not the default 'dist')
+ * 3. Default: `.timber/dist`
+ *
+ * Returns an absolute path.
+ */
+export declare function resolveBuildDir(root: string, timberBuildDir?: string, viteBuildOutDir?: string): string;
+/**
+ * Map known timber.config load failures to actionable hints (TIM-1040).
+ * Returns null when the error has no known remedy beyond its own message.
+ *
+ * Known failure modes of loading timber.config.ts via native require():
+ * - Node < 22.18 has no default type stripping → ERR_UNKNOWN_FILE_EXTENSION
+ * - Non-erasable TS syntax (enums, namespaces, parameter properties)
+ *   → ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX / ERR_INVALID_TYPESCRIPT_SYNTAX
+ * - ESM syntax in a `"type": "commonjs"` package → the stripped .ts is
+ *   parsed as CJS and throws SyntaxError: "Unexpected token 'export'"
+ *   (export statements) or "Cannot use import statement outside a
+ *   module" (import statements)
+ */
+export declare function configLoadHint(configName: string, err: unknown): string | null;
+/**
+ * Load timber.config.ts (or .js, .mjs) from the project root.
+ * Returns the config object or null if no config file is found.
+ * Throws a descriptive error naming the file when a config file exists
+ * but fails to load — a broken config must fail loudly, never silently
+ * degrade (see TIM-1066). Known failure modes get an actionable hint
+ * appended (see configLoadHint, TIM-1040).
+ *
+ * Uses require() — Node 22.12+ can require() ESM modules, and Node
+ * 22.18+ strips types from .ts files by default (hence the engines
+ * field requiring >=22.18.0). This keeps timber() synchronous — no
+ * async config loading needed.
+ * This is the single config loader — dev, build, and preview all use it.
+ */
+export declare function loadTimberConfigFile(root: string): TimberUserConfig | null;
+/**
+ * Detect config keys set in both inline (vite.config.ts) and file (timber.config.ts)
+ * and warn the user. Only keys the inline config actually sets count — the
+ * `output` default is applied after the merge (timber-root-sync), so it never
+ * appears here as an inline key.
+ *
+ * Returns the list of conflicting key names (for testing).
+ */
+export declare function warnConfigConflicts(inline: TimberUserConfig, fileConfig: TimberUserConfig): string[];
+/**
+ * Merge file-based config (timber.config.ts) with inline config (vite.config.ts).
+ * Inline config takes precedence — file config only fills in missing fields.
+ * Inline keys explicitly set to `undefined` are treated as absent, matching
+ * the `!== undefined` check in warnConfigConflicts.
+ */
+export declare function mergeFileConfig(inline: TimberUserConfig, fileConfig: TimberUserConfig): TimberUserConfig;
+//# sourceMappingURL=plugin-context.d.ts.map

package/dist/plugin-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-context.d.ts","sourceRoot":"","sources":["../src/plugin-context.ts"],"names":[],"mappings":"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"}

package/dist/plugins/build-manifest.d.ts

@@ -16,8 +16,8 @@
  * Design docs: 18-build-system.md §"Build Manifest", 02-rendering-pipeline.md §"Early Hints"
  */
 import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
-import type { BuildManifest } from '#/server/build-manifest.js';
+import type { PluginContext } from '../plugin-context.ts';
+import { type BuildManifest } from '../server/build-manifest.ts';
 interface OutputChunk {
     type: 'chunk';
     fileName: string;
@@ -28,6 +28,10 @@ interface OutputChunk {
     viteMetadata?: {
         importedCss?: Set<string>;
     };
+    modules?: Record<string, {
+        code: string | null;
+        renderedLength: number;
+    }>;
 }
 interface OutputAsset {
     type: 'asset';
@@ -72,7 +76,7 @@ export declare function buildManifestFromBundle(bundle: OutputBundle, base: stri
 /**
  * Create the timber-build-manifest Vite plugin.
  *
- * Hooks: configResolved, resolveId, load, generateBundle (client env only)
+ * Hooks: configResolved, resolveId, load, generateBundle (client and RSC envs)
  */
 export declare function timberBuildManifest(ctx: PluginContext): Plugin;
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"build-manifest.d.ts","sourceRoot":"","sources":["../../src/plugins/build-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAkB,MAAM,MAAM,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAIhE,UAAU,WAAW;IACnB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC;CAC9C;AAED,UAAU,WAAW;IACnB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAAC,CAAC;AAK9D;;;GAGG;AACH,UAAU,iBAAiB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EAC/C,IAAI,EAAE,MAAM,GACX,aAAa,CAmBf;AAqCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,aAAa,CA0Df;AA8BD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAwF9D"}
+{"version":3,"file":"build-manifest.d.ts","sourceRoot":"","sources":["../../src/plugins/build-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAkB,MAAM,MAAM,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAMvF,UAAU,WAAW;IACnB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3E;AAED,UAAU,WAAW;IACnB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAAC,CAAC;AAK9D;;;GAGG;AACH,UAAU,iBAAiB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EAC/C,IAAI,EAAE,MAAM,GACX,aAAa,CAmBf;AAqCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,aAAa,CA0Cf;AA+ID;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA0J9D"}

package/dist/plugins/build-report.d.ts

@@ -13,9 +13,12 @@
  * Task: TIM-287
  */
 import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
-import type { SegmentNode, RouteTree } from '#/routing/types.js';
-import { formatSize } from '#/utils/format.js';
+import type { PluginContext } from '../plugin-context.ts';
+import type { SegmentNode, RouteTree } from '../routing/types.ts';
+import type { CaptureSummary } from '../server/prebuilt-builder.ts';
+import type { PrebuiltCaptureResult } from './prebuilt-capture.ts';
+import type { PrebuiltManifest } from '../server/prebuilt/payload-source.ts';
+import { formatSize } from '../utils/format.ts';
 export type RouteType = 'static' | 'dynamic' | 'function';
 export interface RouteEntry {
     path: string;
@@ -28,9 +31,10 @@ export interface RouteEntry {
 /**
  * Classify a route by its segment chain and output mode.
  *
- * In server mode (default), all pages are dynamic (rendered per-request).
- * In static mode, only pages with dynamic/catch-all segments are dynamic.
- * API routes (route.ts) are always classified as function.
+ * In server mode (default), all pages are dynamic (rendered per-request)
+ * and API routes (route.ts) are classified as function.
+ * In static mode, everything is pre-rendered at build time — all routes
+ * are static regardless of dynamic segments or route.ts presence.
  */
 export declare function classifyRoute(segments: SegmentNode[], outputMode?: 'server' | 'static'): RouteType;
 export { formatSize };
@@ -42,17 +46,43 @@ interface RouteInfo {
 /**
  * Walk the route tree and collect all leaf routes (pages + API endpoints).
  *
- * Parallel slots (`@artists`, `@shows`, etc.) are intentionally skipped —
- * they render alongside the parent page at the same URL and are not
- * separately URL-addressable. Their JS is captured in shared/layout chunks.
+ * Wraps the shared `collectLeafRoutes` walker (TIM-848). Parallel slots
+ * (`@artists`, `@shows`, etc.) are intentionally skipped — they render
+ * alongside the parent page at the same URL and are not separately
+ * URL-addressable. Their JS is captured in shared/layout chunks.
  *
  * After collection, entries are deduplicated by URL path so that overlapping
  * route groups (e.g. `(browse)` and `(marketing)` both producing `/`) only
- * appear once. The entry with the largest route-specific size wins.
+ * appear once. The entry with the longest segment chain (most specific
+ * match) wins.
  */
 export declare function collectRoutes(tree: RouteTree): RouteInfo[];
 /** Produce formatted report lines for the Vite logger. */
 export declare function buildRouteReport(entries: RouteEntry[], sharedSize: number): string[];
+/** Check route entries against a First-Load-JS budget and return warning lines. */
+export declare function buildWarnings(entries: RouteEntry[], budget?: {
+    firstLoadJs?: number;
+}): string[];
+export interface PrebuiltComponentStats {
+    componentId: string;
+    entryCount: number;
+    totalBytes: number;
+}
+export interface PrebuiltReportData {
+    components: PrebuiltComponentStats[];
+    totalEntries: number;
+    totalBytes: number;
+    skippedCount: number;
+    skippedReasons: Array<{
+        componentId: string;
+        route: string;
+        message: string;
+    }>;
+}
+/** Read the manifest of the prebuilt artifact this build recorded, if any. */
+export declare function loadPrebuiltManifest(prebuiltDir: string | undefined): PrebuiltManifest | null;
+export declare function buildPrebuiltReportData(manifest: PrebuiltManifest | null, summary: CaptureSummary | undefined): PrebuiltReportData | null;
+export declare function buildPrebuiltReport(data: PrebuiltReportData): string[];
 interface ChunkSize {
     raw: number;
     gzip: number;
@@ -60,6 +90,7 @@ interface ChunkSize {
 interface OutputChunkLike {
     type: 'chunk' | 'asset';
     fileName: string;
+    name?: string;
     code?: string;
     source?: string | Uint8Array;
     modules?: Record<string, unknown>;
@@ -69,5 +100,24 @@ interface OutputChunkLike {
 export declare function collectChunkSizes(bundle: Record<string, OutputChunkLike>): Map<string, ChunkSize>;
 /** Find the output chunk that contains a given input file. */
 export declare function findChunkForFile(filePath: string, bundle: Record<string, OutputChunkLike>): string | null;
-export declare function timberBuildReport(ctx: PluginContext): Plugin;
+/**
+ * Find all client bundle chunks belonging to a chunk group.
+ *
+ * Uses the chunk's `name` property (set by Rolldown from the `clientChunks`
+ * callback's return value) for exact matching. The `name` is the group name
+ * itself (e.g. `client-docs`), not the hashed filename.
+ */
+export declare function findChunksForGroup(groupName: string, chunkSizes: Map<string, ChunkSize>, bundle?: Record<string, OutputChunkLike>): string[];
+/**
+ * What the post-build phase asks of the build report (plugins/post-build.ts).
+ * Printed from there, once, after every environment is built and after the
+ * prebuilt capture pass — so nothing here depends on the order in which
+ * Vite closes each environment's bundle.
+ */
+export interface BuildReportStep {
+    print(prebuilt: PrebuiltCaptureResult | null): void;
+}
+export declare function timberBuildReport(ctx: PluginContext): Plugin & {
+    api: BuildReportStep;
+};
 //# sourceMappingURL=build-report.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"build-report.d.ts","sourceRoot":"","sources":["../../src/plugins/build-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAU,MAAM,MAAM,CAAC;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAI/C,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;AAE1D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,aAAa,EAAE,MAAM,CAAC;CACvB;AAUD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,WAAW,EAAE,EACvB,UAAU,GAAE,QAAQ,GAAG,QAAmB,GACzC,SAAS,CAYX;AAID,OAAO,EAAE,UAAU,EAAE,CAAC;AAQtB,UAAU,SAAS;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,EAAE,CA8B1D;AAID,0DAA0D;AAC1D,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAyCpF;AAcD,UAAU,SAAS;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,eAAe;IACvB,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAYjG;AAOD,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GACtC,MAAM,GAAG,IAAI,CAOf;AAwED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAwE5D"}
+{"version":3,"file":"build-report.d.ts","sourceRoot":"","sources":["../../src/plugins/build-report.ts"],"names":[],"mappings":"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"}