@timber-js/app 0.2.0-alpha.13 → 0.2.0-alpha.131

package/dist/cache/sizeof.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Lightweight byte-size estimation for cache entries.
+ *
+ * Estimates the in-memory byte cost of a JavaScript value using
+ * JSON.stringify().length * 2 (UTF-16 char width). This is a rough
+ * approximation — it doesn't account for V8 object overhead, Map
+ * metadata, or non-serializable values — but it's fast and good
+ * enough for cache budget enforcement.
+ *
+ * Values that fail JSON serialization (circular references, BigInt,
+ * etc.) return 0, allowing the entry to be cached without counting
+ * toward the byte budget. This is a conservative choice: it's better
+ * to cache and undercount than to reject the entry.
+ */
+/**
+ * Estimate the byte size of a value.
+ *
+ * Uses `JSON.stringify(value).length * 2` to approximate UTF-16
+ * in-memory size. Returns 0 if the value is not serializable.
+ */
+export declare function estimateByteSize(value: unknown): number;
+//# sourceMappingURL=sizeof.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sizeof.d.ts","sourceRoot":"","sources":["../../src/cache/sizeof.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAWvD"}

package/dist/cache/timber-cache.d.ts

@@ -11,7 +11,7 @@ import type { CacheHandler, CacheOptions } from './index';
  * Cache hits/misses are recorded as OTEL span events on the enclosing
  * span (not child spans). The DevSpanProcessor reads these for dev log output.
  */
-export declare function createCache<Fn extends (...args: any[]) => Promise<any>>(fn: Fn, opts: CacheOptions<Fn>, handler: CacheHandler): (...args: Parameters<Fn>) => Promise<Awaited<ReturnType<Fn>>>;
+export declare function createCache<Fn extends (...args: any[]) => Promise<any>>(fn: Fn, opts: CacheOptions<Fn>, handler: CacheHandler): Fn;
 export declare namespace createCache {
     var invalidate: (handler: CacheHandler, opts: {
         key?: string;

package/dist/cache/timber-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timber-cache.d.ts","sourceRoot":"","sources":["../../src/cache/timber-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAsC1D;;;;;;;;;;;GAWG;AAEH,wBAAgB,WAAW,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EACrE,EAAE,EAAE,EAAE,EACN,IAAI,EAAE,YAAY,CAAC,EAAE,CAAC,EACtB,OAAO,EAAE,YAAY,GACpB,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAyD/D;yBA7De,WAAW;8BAmEhB,YAAY,QACf;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,KACnC,OAAO,CAAC,IAAI,CAAC"}
+{"version":3,"file":"timber-cache.d.ts","sourceRoot":"","sources":["../../src/cache/timber-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAuC1D;;;;;;;;;;;GAWG;AAEH,wBAAgB,WAAW,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EACrE,EAAE,EAAE,EAAE,EACN,IAAI,EAAE,YAAY,CAAC,EAAE,CAAC,EACtB,OAAO,EAAE,YAAY,GACpB,EAAE,CA6DJ;yBAjEe,WAAW;8BAuEhB,YAAY,QACf;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,KACnC,OAAO,CAAC,IAAI,CAAC"}

package/dist/cli-schema-sync.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `timber schema sync` — scan filesystem for dynamic segments, append
+ * missing entries with `codec.string` defaults, and remove stale entries
+ * whose segments no longer exist in the filesystem.
+ *
+ * Design doc: design/41-global-params.md §Auto-Scaffolding
+ */
+/**
+ * Collect all unique bracket-keyed dynamic segment names from the route tree.
+ * Returns entries like '[artistSlug]', '[...slug]', '[[...topic]]'.
+ */
+export declare function collectDynamicSegments(appDir: string): string[];
+/**
+ * Parse existing bracket keys from an app/schema.ts file.
+ * Uses regex to find keys in segmentParams: { '[key]': ... } blocks.
+ */
+export declare function parseExistingSchemaKeys(content: string): string[];
+/**
+ * Find the schema file path if it exists.
+ */
+export declare function findSchemaFile(appDir: string): string | undefined;
+export declare function defaultCodecForSegment(seg: string): string;
+export interface SchemaSyncResult {
+    /** Segments found in the filesystem. */
+    filesystemSegments: string[];
+    /** Segments already defined in app/schema.ts. */
+    existingSegments: string[];
+    /** Segments that were added. */
+    addedSegments: string[];
+    /** Segments that were removed (no longer in filesystem). */
+    removedSegments: string[];
+    /** Whether a new schema file was created. */
+    created: boolean;
+}
+/**
+ * Run the schema sync: scan filesystem, diff against schema, append missing.
+ */
+export declare function runSchemaSync(projectRoot: string): SchemaSyncResult;
+//# sourceMappingURL=cli-schema-sync.d.ts.map

package/dist/cli-schema-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-schema-sync.d.ts","sourceRoot":"","sources":["../src/cli-schema-sync.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAK/D;AAeD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CASjE;AAKD;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMjE;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI1D;AAiJD,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,iDAAiD;IACjD,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,gCAAgC;IAChC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,4DAA4D;IAC5D,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CA8DnE"}

package/dist/cli.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-declare const COMMANDS: readonly ["dev", "build", "preview", "check"];
+declare const COMMANDS: readonly ["dev", "build", "preview", "check", "schema"];
 type Command = (typeof COMMANDS)[number];
 export interface ParsedArgs {
     command: Command;
@@ -21,7 +21,12 @@ export interface ViteDeps {
 }
 /**
  * Start the Vite dev server.
- * Middleware re-runs on file change via HMR wiring in timber-routing.
+ *
+ * The timber plugin binds the port immediately with a holding page
+ * (in rootSync's config hook) so browsers see a "starting..." page
+ * instead of ERR_CONNECTION_REFUSED during initialization.
+ *
+ * See design/21-dev-server.md, TIM-665.
  */
 export declare function runDev(options: CommandOptions, _deps?: ViteDeps): Promise<void>;
 /**
@@ -46,5 +51,12 @@ export declare function runPreview(options: CommandOptions, _deps?: ViteDeps): P
  * Runs tsgo --noEmit for type checking.
  */
 export declare function runCheck(options: CommandOptions): Promise<void>;
+/**
+ * `timber schema sync` — scan filesystem for dynamic segments, diff against
+ * app/schema.ts, and append missing entries with type-appropriate codec defaults.
+ *
+ * See design/41-global-params.md §Auto-Scaffolding
+ */
+export declare function runSchema(args: string[]): Promise<void>;
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAaA,QAAA,MAAM,QAAQ,+CAAgD,CAAC;AAC/D,KAAK,OAAO,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzC,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAuBpD;AAID,kDAAkD;AAClD,MAAM,WAAW,QAAQ;IACvB,YAAY,CAAC,EAAE,cAAc,MAAM,EAAE,YAAY,CAAC;IAClD,aAAa,CAAC,EAAE,cAAc,MAAM,EAAE,aAAa,CAAC;IACpD,OAAO,CAAC,EAAE,cAAc,MAAM,EAAE,OAAO,CAAC;CACzC;AAED;;;GAGG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAOrF;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAMvF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,kBAAkB,EAAE,qBAAqB,GAAG,SAAS,GACpE,SAAS,GAAG,MAAM,CAKpB;AA2BD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBzF;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAerE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAaA,QAAA,MAAM,QAAQ,yDAA0D,CAAC;AACzE,KAAK,OAAO,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzC,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAuBpD;AAID,kDAAkD;AAClD,MAAM,WAAW,QAAQ;IACvB,YAAY,CAAC,EAAE,cAAc,MAAM,EAAE,YAAY,CAAC;IAClD,aAAa,CAAC,EAAE,cAAc,MAAM,EAAE,aAAa,CAAC;IACpD,OAAO,CAAC,EAAE,cAAc,MAAM,EAAE,OAAO,CAAC;CACzC;AAED;;;;;;;;GAQG;AACH,wBAAsB,MAAM,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAOrF;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAMvF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,kBAAkB,EAAE,qBAAqB,GAAG,SAAS,GACpE,SAAS,GAAG,MAAM,CAKpB;AA6BD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBzF;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAerE;AAID;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA6C7D"}

package/dist/cli.js

@@ -4,14 +4,15 @@ var COMMANDS = [
 	"dev",
 	"build",
 	"preview",
-	"check"
+	"check",
+	"schema"
 ];
 /**
 * Parse CLI arguments into a structured command + options.
 * Accepts: timber <command> [--config|-c <path>]
 */
 function parseArgs(args) {
-	if (args.length === 0) throw new Error("No command provided. Usage: timber <dev|build|preview|check> [--config <path>]");
+	if (args.length === 0) throw new Error("No command provided. Usage: timber <dev|build|preview|check|schema> [--config <path>]");
 	const command = args[0];
 	if (!COMMANDS.includes(command)) throw new Error(`Unknown command: ${command}. Available commands: ${COMMANDS.join(", ")}`);
 	let config;
@@ -26,7 +27,12 @@ function parseArgs(args) {
 }
 /**
 * Start the Vite dev server.
-* Middleware re-runs on file change via HMR wiring in timber-routing.
+*
+* The timber plugin binds the port immediately with a holding page
+* (in rootSync's config hook) so browsers see a "starting..." page
+* instead of ERR_CONNECTION_REFUSED during initialization.
+*
+* See design/21-dev-server.md, TIM-665.
 */
 async function runDev(options, _deps) {
 	const server = await (_deps?.createServer ?? (await import("vite")).createServer)({ configFile: options.config });
@@ -77,12 +83,12 @@ async function loadTimberConfig(root) {
 * Otherwise falls back to Vite's built-in preview server.
 */
 async function runPreview(options, _deps) {
-	const { join } = await import("node:path");
+	const { join, resolve } = await import("node:path");
 	const root = process.cwd();
 	const config = await loadTimberConfig(root).catch(() => null);
 	const adapter = config?.adapter;
 	if (resolvePreviewStrategy(adapter) === "adapter") {
-		const buildDir = join(root, "dist");
+		const buildDir = config?.buildDir ? resolve(root, config.buildDir) : join(root, ".timber", "dist");
 		const timberConfig = { output: config?.output ?? "server" };
 		await adapter.preview(timberConfig, buildDir);
 		return;
@@ -104,6 +110,39 @@ async function runCheck(options) {
 		});
 	});
 }
+/**
+* `timber schema sync` — scan filesystem for dynamic segments, diff against
+* app/schema.ts, and append missing entries with type-appropriate codec defaults.
+*
+* See design/41-global-params.md §Auto-Scaffolding
+*/
+async function runSchema(args) {
+	const subcommand = args[0];
+	if (subcommand !== "sync") throw new Error(`Unknown schema subcommand: ${subcommand ?? "(none)"}. Usage: timber schema sync`);
+	const { runSchemaSync, defaultCodecForSegment } = await import("./_chunks/cli-schema-sync-CObqjGWF.js");
+	const result = runSchemaSync(process.cwd());
+	if (result.filesystemSegments.length === 0) {
+		console.log("[timber] No dynamic segments found in app/.");
+		return;
+	}
+	if (result.created) {
+		console.log(`[timber] Created app/schema.ts with ${result.addedSegments.length} segment(s):`);
+		for (const seg of result.addedSegments) console.log(`  + ${seg}: ${defaultCodecForSegment(seg)}`);
+		return;
+	}
+	if (result.addedSegments.length === 0 && result.removedSegments.length === 0) {
+		console.log("[timber] Schema is up to date — all segments are registered.");
+		return;
+	}
+	if (result.addedSegments.length > 0) {
+		console.log(`[timber] Added ${result.addedSegments.length} segment(s) to app/schema.ts:`);
+		for (const seg of result.addedSegments) console.log(`  + ${seg}: ${defaultCodecForSegment(seg)}`);
+	}
+	if (result.removedSegments.length > 0) {
+		console.log(`[timber] Removed ${result.removedSegments.length} stale segment(s) from app/schema.ts:`);
+		for (const seg of result.removedSegments) console.log(`  - ${seg}`);
+	}
+}
 async function main() {
 	const parsed = parseArgs(process.argv.slice(2));
 	const options = { config: parsed.config };
@@ -120,6 +159,9 @@ async function main() {
 		case "check":
 			await runCheck(options);
 			break;
+		case "schema":
+			await runSchema(process.argv.slice(3));
+			break;
 	}
 }
 if (typeof process !== "undefined" && process.argv[1] && (import.meta.url.endsWith(process.argv[1]) || process.argv[1].endsWith("bin/timber.mjs") || process.argv[1].endsWith("bin/timber"))) main().catch((err) => {
@@ -127,6 +169,6 @@ if (typeof process !== "undefined" && process.argv[1] && (import.meta.url.endsWi
 	process.exit(1);
 });
 //#endregion
-export { parseArgs, resolvePreviewStrategy, runBuild, runCheck, runDev, runPreview };
+export { parseArgs, resolvePreviewStrategy, runBuild, runCheck, runDev, runPreview, runSchema };
 
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\n// timber.js CLI\n//\n// Wraps Vite commands with timber-specific behavior.\n// See design/18-build-system.md §\"CLI\".\n//\n// Commands:\n//   timber dev      — Start Vite dev server with HMR\n//   timber build    — Run multi-environment build via createBuilder/buildApp\n//   timber preview  — Serve the production build\n//   timber check    — Validate types + routes without building\n\nconst COMMANDS = ['dev', 'build', 'preview', 'check'] as const;\ntype Command = (typeof COMMANDS)[number];\n\nexport interface ParsedArgs {\n  command: Command;\n  config: string | undefined;\n}\n\nexport interface CommandOptions {\n  config?: string;\n}\n\n/**\n * Parse CLI arguments into a structured command + options.\n * Accepts: timber <command> [--config|-c <path>]\n */\nexport function parseArgs(args: string[]): ParsedArgs {\n  if (args.length === 0) {\n    throw new Error(\n      'No command provided. Usage: timber <dev|build|preview|check> [--config <path>]'\n    );\n  }\n\n  const command = args[0];\n  if (!COMMANDS.includes(command as Command)) {\n    throw new Error(`Unknown command: ${command}. Available commands: ${COMMANDS.join(', ')}`);\n  }\n\n  let config: string | undefined;\n  for (let i = 1; i < args.length; i++) {\n    if (args[i] === '--config' || args[i] === '-c') {\n      config = args[++i];\n      if (!config) {\n        throw new Error('--config requires a path argument');\n      }\n    }\n  }\n\n  return { command: command as Command, config };\n}\n\n// ─── Command Implementations ─────────────────────────────────────────────────\n\n/** @internal Dependency injection for testing. */\nexport interface ViteDeps {\n  createServer?: typeof import('vite').createServer;\n  createBuilder?: typeof import('vite').createBuilder;\n  preview?: typeof import('vite').preview;\n}\n\n/**\n * Start the Vite dev server.\n * Middleware re-runs on file change via HMR wiring in timber-routing.\n */\nexport async function runDev(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const createServer = _deps?.createServer ?? (await import('vite')).createServer;\n  const server = await createServer({\n    configFile: options.config,\n  });\n  await server.listen();\n  server.printUrls();\n}\n\n/**\n * Run the production build using createBuilder + buildApp.\n * Direct build() calls do NOT trigger the RSC plugin's multi-environment\n * pipeline — createBuilder/buildApp is required.\n */\nexport async function runBuild(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const createBuilder = _deps?.createBuilder ?? (await import('vite')).createBuilder;\n  const builder = await createBuilder({\n    configFile: options.config,\n  });\n  await builder.buildApp();\n}\n\n/**\n * Determine whether to use the adapter's preview or Vite's built-in preview.\n * Exported for testing — the actual runPreview function uses this internally.\n */\nexport function resolvePreviewStrategy(\n  adapter: import('./adapters/types').TimberPlatformAdapter | undefined\n): 'adapter' | 'vite' {\n  if (adapter && typeof adapter.preview === 'function') {\n    return 'adapter';\n  }\n  return 'vite';\n}\n\n/**\n * Load timber.config.ts from the project root.\n * Returns the config object with adapter, output, etc.\n * Returns null if no config file is found.\n */\nasync function loadTimberConfig(\n  root: string\n): Promise<{ adapter?: import('./adapters/types').TimberPlatformAdapter; output?: string } | null> {\n  const { existsSync } = await import('node:fs');\n  const { join } = await import('node:path');\n  const { pathToFileURL } = await import('node:url');\n\n  const configNames = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];\n\n  for (const name of configNames) {\n    const configPath = join(root, name);\n    if (existsSync(configPath)) {\n      // Use Vite's built-in config loading to handle TypeScript\n      const mod = await import(pathToFileURL(configPath).href);\n      return mod.default ?? mod;\n    }\n  }\n  return null;\n}\n\n/**\n * Serve the production build for local testing.\n * If the adapter provides a preview() method, it takes priority.\n * Otherwise falls back to Vite's built-in preview server.\n */\nexport async function runPreview(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const { join } = await import('node:path');\n\n  // Try to load timber config for adapter-specific preview\n  const root = process.cwd();\n  const config = await loadTimberConfig(root).catch(() => null);\n  const adapter = config?.adapter as import('./adapters/types').TimberPlatformAdapter | undefined;\n\n  if (resolvePreviewStrategy(adapter) === 'adapter') {\n    const buildDir = join(root, 'dist');\n    const timberConfig = { output: (config?.output ?? 'server') as 'server' | 'static' };\n    await adapter!.preview!(timberConfig, buildDir);\n    return;\n  }\n\n  // Fallback: Vite's built-in preview server\n  const preview = _deps?.preview ?? (await import('vite')).preview;\n  const server = await preview({\n    configFile: options.config,\n  });\n  server.printUrls();\n}\n\n/**\n * Validate types and routes without producing build output.\n * Runs tsgo --noEmit for type checking.\n */\nexport async function runCheck(options: CommandOptions): Promise<void> {\n  const { execFile } = await import('node:child_process');\n\n  await new Promise<void>((resolve, reject) => {\n    const configArgs = options.config ? ['--project', options.config] : [];\n    execFile('tsgo', ['--noEmit', ...configArgs], (err, stdout, stderr) => {\n      if (stdout) process.stdout.write(stdout);\n      if (stderr) process.stderr.write(stderr);\n      if (err) {\n        reject(new Error(`Type check failed with exit code ${err.code}`));\n      } else {\n        resolve();\n      }\n    });\n  });\n}\n\n// ─── Main Entry Point ────────────────────────────────────────────────────────\n\nasync function main(): Promise<void> {\n  const parsed = parseArgs(process.argv.slice(2));\n  const options: CommandOptions = { config: parsed.config };\n\n  switch (parsed.command) {\n    case 'dev':\n      await runDev(options);\n      break;\n    case 'build':\n      await runBuild(options);\n      break;\n    case 'preview':\n      await runPreview(options);\n      break;\n    case 'check':\n      await runCheck(options);\n      break;\n  }\n}\n\n// Run main when executed as a CLI (not imported in tests).\n// The bin shim (bin/timber.mjs) does `import '../dist/cli.js'`, so\n// process.argv[1] points to the shim, not this file. We check both:\n// direct execution AND being imported by the timber bin shim.\nconst isDirectExecution =\n  typeof process !== 'undefined' &&\n  process.argv[1] &&\n  (import.meta.url.endsWith(process.argv[1]) ||\n    process.argv[1].endsWith('bin/timber.mjs') ||\n    process.argv[1].endsWith('bin/timber'));\n\nif (isDirectExecution) {\n  main().catch((err) => {\n    console.error(err.message);\n    process.exit(1);\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\n// timber.js CLI\n//\n// Wraps Vite commands with timber-specific behavior.\n// See design/18-build-system.md §\"CLI\".\n//\n// Commands:\n//   timber dev      — Start Vite dev server with HMR\n//   timber build    — Run multi-environment build via createBuilder/buildApp\n//   timber preview  — Serve the production build\n//   timber check    — Validate types + routes without building\n\nconst COMMANDS = ['dev', 'build', 'preview', 'check', 'schema'] as const;\ntype Command = (typeof COMMANDS)[number];\n\nexport interface ParsedArgs {\n  command: Command;\n  config: string | undefined;\n}\n\nexport interface CommandOptions {\n  config?: string;\n}\n\n/**\n * Parse CLI arguments into a structured command + options.\n * Accepts: timber <command> [--config|-c <path>]\n */\nexport function parseArgs(args: string[]): ParsedArgs {\n  if (args.length === 0) {\n    throw new Error(\n      'No command provided. Usage: timber <dev|build|preview|check|schema> [--config <path>]'\n    );\n  }\n\n  const command = args[0];\n  if (!COMMANDS.includes(command as Command)) {\n    throw new Error(`Unknown command: ${command}. Available commands: ${COMMANDS.join(', ')}`);\n  }\n\n  let config: string | undefined;\n  for (let i = 1; i < args.length; i++) {\n    if (args[i] === '--config' || args[i] === '-c') {\n      config = args[++i];\n      if (!config) {\n        throw new Error('--config requires a path argument');\n      }\n    }\n  }\n\n  return { command: command as Command, config };\n}\n\n// ─── Command Implementations ─────────────────────────────────────────────────\n\n/** @internal Dependency injection for testing. */\nexport interface ViteDeps {\n  createServer?: typeof import('vite').createServer;\n  createBuilder?: typeof import('vite').createBuilder;\n  preview?: typeof import('vite').preview;\n}\n\n/**\n * Start the Vite dev server.\n *\n * The timber plugin binds the port immediately with a holding page\n * (in rootSync's config hook) so browsers see a \"starting...\" page\n * instead of ERR_CONNECTION_REFUSED during initialization.\n *\n * See design/21-dev-server.md, TIM-665.\n */\nexport async function runDev(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const createServer = _deps?.createServer ?? (await import('vite')).createServer;\n  const server = await createServer({\n    configFile: options.config,\n  });\n  await server.listen();\n  server.printUrls();\n}\n\n/**\n * Run the production build using createBuilder + buildApp.\n * Direct build() calls do NOT trigger the RSC plugin's multi-environment\n * pipeline — createBuilder/buildApp is required.\n */\nexport async function runBuild(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const createBuilder = _deps?.createBuilder ?? (await import('vite')).createBuilder;\n  const builder = await createBuilder({\n    configFile: options.config,\n  });\n  await builder.buildApp();\n}\n\n/**\n * Determine whether to use the adapter's preview or Vite's built-in preview.\n * Exported for testing — the actual runPreview function uses this internally.\n */\nexport function resolvePreviewStrategy(\n  adapter: import('./adapters/types').TimberPlatformAdapter | undefined\n): 'adapter' | 'vite' {\n  if (adapter && typeof adapter.preview === 'function') {\n    return 'adapter';\n  }\n  return 'vite';\n}\n\n/**\n * Load timber.config.ts from the project root.\n * Returns the config object with adapter, output, etc.\n * Returns null if no config file is found.\n */\nasync function loadTimberConfig(root: string): Promise<{\n  adapter?: import('./adapters/types').TimberPlatformAdapter;\n  output?: string;\n  buildDir?: string;\n} | null> {\n  const { existsSync } = await import('node:fs');\n  const { join } = await import('node:path');\n  const { pathToFileURL } = await import('node:url');\n\n  const configNames = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];\n\n  for (const name of configNames) {\n    const configPath = join(root, name);\n    if (existsSync(configPath)) {\n      // Use Vite's built-in config loading to handle TypeScript\n      const mod = await import(pathToFileURL(configPath).href);\n      return mod.default ?? mod;\n    }\n  }\n  return null;\n}\n\n/**\n * Serve the production build for local testing.\n * If the adapter provides a preview() method, it takes priority.\n * Otherwise falls back to Vite's built-in preview server.\n */\nexport async function runPreview(options: CommandOptions, _deps?: ViteDeps): Promise<void> {\n  const { join, resolve } = await import('node:path');\n\n  // Try to load timber config for adapter-specific preview\n  const root = process.cwd();\n  const config = await loadTimberConfig(root).catch(() => null);\n  const adapter = config?.adapter as import('./adapters/types').TimberPlatformAdapter | undefined;\n\n  if (resolvePreviewStrategy(adapter) === 'adapter') {\n    // Resolve build directory: timber config > default .timber/dist\n    const buildDir = config?.buildDir\n      ? resolve(root, config.buildDir)\n      : join(root, '.timber', 'dist');\n    const timberConfig = { output: (config?.output ?? 'server') as 'server' | 'static' };\n    await adapter!.preview!(timberConfig, buildDir);\n    return;\n  }\n\n  // Fallback: Vite's built-in preview server\n  const preview = _deps?.preview ?? (await import('vite')).preview;\n  const server = await preview({\n    configFile: options.config,\n  });\n  server.printUrls();\n}\n\n/**\n * Validate types and routes without producing build output.\n * Runs tsgo --noEmit for type checking.\n */\nexport async function runCheck(options: CommandOptions): Promise<void> {\n  const { execFile } = await import('node:child_process');\n\n  await new Promise<void>((resolve, reject) => {\n    const configArgs = options.config ? ['--project', options.config] : [];\n    execFile('tsgo', ['--noEmit', ...configArgs], (err, stdout, stderr) => {\n      if (stdout) process.stdout.write(stdout);\n      if (stderr) process.stderr.write(stderr);\n      if (err) {\n        reject(new Error(`Type check failed with exit code ${err.code}`));\n      } else {\n        resolve();\n      }\n    });\n  });\n}\n\n// ─── Schema Subcommand ───────────────────────────────────────────────────────\n\n/**\n * `timber schema sync` — scan filesystem for dynamic segments, diff against\n * app/schema.ts, and append missing entries with type-appropriate codec defaults.\n *\n * See design/41-global-params.md §Auto-Scaffolding\n */\nexport async function runSchema(args: string[]): Promise<void> {\n  const subcommand = args[0];\n\n  if (subcommand !== 'sync') {\n    throw new Error(\n      `Unknown schema subcommand: ${subcommand ?? '(none)'}. Usage: timber schema sync`\n    );\n  }\n\n  const { runSchemaSync, defaultCodecForSegment } = await import('./cli-schema-sync.js');\n  const result = runSchemaSync(process.cwd());\n\n  if (result.filesystemSegments.length === 0) {\n    console.log('[timber] No dynamic segments found in app/.');\n    return;\n  }\n\n  if (result.created) {\n    console.log(`[timber] Created app/schema.ts with ${result.addedSegments.length} segment(s):`);\n    for (const seg of result.addedSegments) {\n      console.log(`  + ${seg}: ${defaultCodecForSegment(seg)}`);\n    }\n    return;\n  }\n\n  if (result.addedSegments.length === 0 && result.removedSegments.length === 0) {\n    console.log('[timber] Schema is up to date — all segments are registered.');\n    return;\n  }\n\n  if (result.addedSegments.length > 0) {\n    console.log(`[timber] Added ${result.addedSegments.length} segment(s) to app/schema.ts:`);\n    for (const seg of result.addedSegments) {\n      console.log(`  + ${seg}: ${defaultCodecForSegment(seg)}`);\n    }\n  }\n\n  if (result.removedSegments.length > 0) {\n    console.log(\n      `[timber] Removed ${result.removedSegments.length} stale segment(s) from app/schema.ts:`\n    );\n    for (const seg of result.removedSegments) {\n      console.log(`  - ${seg}`);\n    }\n  }\n}\n\n// ─── Main Entry Point ────────────────────────────────────────────────────────\n\nasync function main(): Promise<void> {\n  const parsed = parseArgs(process.argv.slice(2));\n  const options: CommandOptions = { config: parsed.config };\n\n  switch (parsed.command) {\n    case 'dev':\n      await runDev(options);\n      break;\n    case 'build':\n      await runBuild(options);\n      break;\n    case 'preview':\n      await runPreview(options);\n      break;\n    case 'check':\n      await runCheck(options);\n      break;\n    case 'schema':\n      await runSchema(process.argv.slice(3));\n      break;\n  }\n}\n\n// Run main when executed as a CLI (not imported in tests).\n// The bin shim (bin/timber.mjs) does `import '../dist/cli.js'`, so\n// process.argv[1] points to the shim, not this file. We check both:\n// direct execution AND being imported by the timber bin shim.\nconst isDirectExecution =\n  typeof process !== 'undefined' &&\n  process.argv[1] &&\n  (import.meta.url.endsWith(process.argv[1]) ||\n    process.argv[1].endsWith('bin/timber.mjs') ||\n    process.argv[1].endsWith('bin/timber'));\n\nif (isDirectExecution) {\n  main().catch((err) => {\n    console.error(err.message);\n    process.exit(1);\n  });\n}\n"],"mappings":";;AAaA,IAAM,WAAW;CAAC;CAAO;CAAS;CAAW;CAAS;CAAS;;;;;AAgB/D,SAAgB,UAAU,MAA4B;AACpD,KAAI,KAAK,WAAW,EAClB,OAAM,IAAI,MACR,wFACD;CAGH,MAAM,UAAU,KAAK;AACrB,KAAI,CAAC,SAAS,SAAS,QAAmB,CACxC,OAAM,IAAI,MAAM,oBAAoB,QAAQ,wBAAwB,SAAS,KAAK,KAAK,GAAG;CAG5F,IAAI;AACJ,MAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,IAC/B,KAAI,KAAK,OAAO,cAAc,KAAK,OAAO,MAAM;AAC9C,WAAS,KAAK,EAAE;AAChB,MAAI,CAAC,OACH,OAAM,IAAI,MAAM,oCAAoC;;AAK1D,QAAO;EAAW;EAAoB;EAAQ;;;;;;;;;;;AAqBhD,eAAsB,OAAO,SAAyB,OAAiC;CAErF,MAAM,SAAS,OADM,OAAO,iBAAiB,MAAM,OAAO,SAAS,cACjC,EAChC,YAAY,QAAQ,QACrB,CAAC;AACF,OAAM,OAAO,QAAQ;AACrB,QAAO,WAAW;;;;;;;AAQpB,eAAsB,SAAS,SAAyB,OAAiC;AAKvF,QAHgB,OADM,OAAO,kBAAkB,MAAM,OAAO,SAAS,eACjC,EAClC,YAAY,QAAQ,QACrB,CAAC,EACY,UAAU;;;;;;AAO1B,SAAgB,uBACd,SACoB;AACpB,KAAI,WAAW,OAAO,QAAQ,YAAY,WACxC,QAAO;AAET,QAAO;;;;;;;AAQT,eAAe,iBAAiB,MAItB;CACR,MAAM,EAAE,eAAe,MAAM,OAAO;CACpC,MAAM,EAAE,SAAS,MAAM,OAAO;CAC9B,MAAM,EAAE,kBAAkB,MAAM,OAAO;AAIvC,MAAK,MAAM,QAFS;EAAC;EAAoB;EAAoB;EAAoB,EAEjD;EAC9B,MAAM,aAAa,KAAK,MAAM,KAAK;AACnC,MAAI,WAAW,WAAW,EAAE;GAE1B,MAAM,MAAM,MAAM,OAAO,cAAc,WAAW,CAAC;AACnD,UAAO,IAAI,WAAW;;;AAG1B,QAAO;;;;;;;AAQT,eAAsB,WAAW,SAAyB,OAAiC;CACzF,MAAM,EAAE,MAAM,YAAY,MAAM,OAAO;CAGvC,MAAM,OAAO,QAAQ,KAAK;CAC1B,MAAM,SAAS,MAAM,iBAAiB,KAAK,CAAC,YAAY,KAAK;CAC7D,MAAM,UAAU,QAAQ;AAExB,KAAI,uBAAuB,QAAQ,KAAK,WAAW;EAEjD,MAAM,WAAW,QAAQ,WACrB,QAAQ,MAAM,OAAO,SAAS,GAC9B,KAAK,MAAM,WAAW,OAAO;EACjC,MAAM,eAAe,EAAE,QAAS,QAAQ,UAAU,UAAkC;AACpF,QAAM,QAAS,QAAS,cAAc,SAAS;AAC/C;;AAQF,EAHe,OADC,OAAO,YAAY,MAAM,OAAO,SAAS,SAC5B,EAC3B,YAAY,QAAQ,QACrB,CAAC,EACK,WAAW;;;;;;AAOpB,eAAsB,SAAS,SAAwC;CACrE,MAAM,EAAE,aAAa,MAAM,OAAO;AAElC,OAAM,IAAI,SAAe,SAAS,WAAW;AAE3C,WAAS,QAAQ,CAAC,YAAY,GADX,QAAQ,SAAS,CAAC,aAAa,QAAQ,OAAO,GAAG,EAAE,CAC1B,GAAG,KAAK,QAAQ,WAAW;AACrE,OAAI,OAAQ,SAAQ,OAAO,MAAM,OAAO;AACxC,OAAI,OAAQ,SAAQ,OAAO,MAAM,OAAO;AACxC,OAAI,IACF,wBAAO,IAAI,MAAM,oCAAoC,IAAI,OAAO,CAAC;OAEjE,UAAS;IAEX;GACF;;;;;;;;AAWJ,eAAsB,UAAU,MAA+B;CAC7D,MAAM,aAAa,KAAK;AAExB,KAAI,eAAe,OACjB,OAAM,IAAI,MACR,8BAA8B,cAAc,SAAS,6BACtD;CAGH,MAAM,EAAE,eAAe,2BAA2B,MAAM,OAAO;CAC/D,MAAM,SAAS,cAAc,QAAQ,KAAK,CAAC;AAE3C,KAAI,OAAO,mBAAmB,WAAW,GAAG;AAC1C,UAAQ,IAAI,8CAA8C;AAC1D;;AAGF,KAAI,OAAO,SAAS;AAClB,UAAQ,IAAI,uCAAuC,OAAO,cAAc,OAAO,cAAc;AAC7F,OAAK,MAAM,OAAO,OAAO,cACvB,SAAQ,IAAI,OAAO,IAAI,IAAI,uBAAuB,IAAI,GAAG;AAE3D;;AAGF,KAAI,OAAO,cAAc,WAAW,KAAK,OAAO,gBAAgB,WAAW,GAAG;AAC5E,UAAQ,IAAI,+DAA+D;AAC3E;;AAGF,KAAI,OAAO,cAAc,SAAS,GAAG;AACnC,UAAQ,IAAI,kBAAkB,OAAO,cAAc,OAAO,+BAA+B;AACzF,OAAK,MAAM,OAAO,OAAO,cACvB,SAAQ,IAAI,OAAO,IAAI,IAAI,uBAAuB,IAAI,GAAG;;AAI7D,KAAI,OAAO,gBAAgB,SAAS,GAAG;AACrC,UAAQ,IACN,oBAAoB,OAAO,gBAAgB,OAAO,uCACnD;AACD,OAAK,MAAM,OAAO,OAAO,gBACvB,SAAQ,IAAI,OAAO,MAAM;;;AAO/B,eAAe,OAAsB;CACnC,MAAM,SAAS,UAAU,QAAQ,KAAK,MAAM,EAAE,CAAC;CAC/C,MAAM,UAA0B,EAAE,QAAQ,OAAO,QAAQ;AAEzD,SAAQ,OAAO,SAAf;EACE,KAAK;AACH,SAAM,OAAO,QAAQ;AACrB;EACF,KAAK;AACH,SAAM,SAAS,QAAQ;AACvB;EACF,KAAK;AACH,SAAM,WAAW,QAAQ;AACzB;EACF,KAAK;AACH,SAAM,SAAS,QAAQ;AACvB;EACF,KAAK;AACH,SAAM,UAAU,QAAQ,KAAK,MAAM,EAAE,CAAC;AACtC;;;AAeN,IANE,OAAO,YAAY,eACnB,QAAQ,KAAK,OACZ,OAAO,KAAK,IAAI,SAAS,QAAQ,KAAK,GAAG,IACxC,QAAQ,KAAK,GAAG,SAAS,iBAAiB,IAC1C,QAAQ,KAAK,GAAG,SAAS,aAAa,EAGxC,OAAM,CAAC,OAAO,QAAQ;AACpB,SAAQ,MAAM,IAAI,QAAQ;AAC1B,SAAQ,KAAK,EAAE;EACf"}

package/dist/client/browser-dev.d.ts

@@ -1,5 +1,6 @@
 /**
- * Dev-only browser helpers — server log replay and client error forwarding.
+ * Dev-only browser helpers — server log replay, client error forwarding,
+ * and compiling overlay.
  *
  * These are only active when import.meta.hot is available (Vite dev mode).
  * Extracted from browser-entry.ts to keep files under 500 lines.
@@ -18,6 +19,31 @@ export interface HotInterface {
  * a styled "[SERVER]" badge and call the matching console method.
  */
 export declare function setupServerLogReplay(hot: Pick<HotInterface, 'on'>): void;
+/**
+ * Signal that an HMR/module update has started.
+ *
+ * If an update is already tracked, this increments the counter.
+ * The overlay is shown after SHOW_DELAY_MS to avoid flashing
+ * for fast updates.
+ *
+ * When the delay is 0 (E2E test override), the overlay is shown
+ * synchronously to eliminate the race where hideCompilingOverlay()
+ * clears the show timeout before it fires.
+ */
+export declare function showCompilingOverlay(): void;
+/**
+ * Signal that an HMR/module update has completed.
+ *
+ * When all pending updates are resolved, the overlay is hidden.
+ * If the overlay was never shown (update completed within the
+ * debounce window), the timeout is cleared — no visual flash.
+ *
+ * Test hook: if `window.__timber_hold_compiling_overlay` is true,
+ * the overlay stays visible. E2E tests use this to avoid a race
+ * where the RSC refresh completes between polling intervals,
+ * making the overlay impossible to observe.
+ */
+export declare function hideCompilingOverlay(): void;
 /**
  * Set up global error handlers that forward uncaught client-side
  * errors to the dev server via Vite's HMR channel.
@@ -26,4 +52,11 @@ export declare function setupServerLogReplay(hot: Pick<HotInterface, 'on'>): voi
  * back as Vite '{ type: "error" }' payloads to trigger the overlay.
  */
 export declare function setupClientErrorForwarding(hot: Pick<HotInterface, 'send'>): void;
+/**
+ * Detect errors whose `digest` marks them as a framework control-flow signal
+ * (RedirectSignal, DenySignal). These must never surface as dev overlays —
+ * they are expected during navigation and are handled by the error boundary
+ * and router. Exported for tests.
+ */
+export declare function isFrameworkSignalError(error: unknown): boolean;
 //# sourceMappingURL=browser-dev.d.ts.map

package/dist/client/browser-dev.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-dev.d.ts","sourceRoot":"","sources":["../../src/client/browser-dev.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,gDAAgD;AAChD,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC1D,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CAC1C;AAqDD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,GAAG,IAAI,CAwBxE;AAID;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,GAAG,IAAI,CA8BhF"}
+{"version":3,"file":"browser-dev.d.ts","sourceRoot":"","sources":["../../src/client/browser-dev.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,gDAAgD;AAChD,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC1D,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CAC1C;AAqDD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,GAAG,IAAI,CAwBxE;AAoED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAmB3C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAc3C;AAID;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,GAAG,IAAI,CAoChF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAW9D"}

package/dist/client/browser-entry/action-dispatch.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Server Action Dispatch — registers the callServer callback.
+ *
+ * When React encounters a server reference (from `'use server'` modules),
+ * it calls `callServer(id, args)` to dispatch the action to the server.
+ * The RSC plugin delegates to `globalThis.__viteRscCallServer` which is
+ * set by `setServerCallback`.
+ *
+ * The callback:
+ * 1. Serializes args via `encodeReply` (RSC wire format)
+ * 2. POSTs to the current URL with `Accept: text/x-component`
+ * 3. Decodes the RSC response stream
+ *
+ * See design/08-forms-and-actions.md §"Client-Side Form Mechanics"
+ */
+export declare function setupServerActions(): void;
+//# sourceMappingURL=action-dispatch.d.ts.map

package/dist/client/browser-entry/action-dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-dispatch.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/action-dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAQH,wBAAgB,kBAAkB,IAAI,IAAI,CAsGzC"}

package/dist/client/browser-entry/hmr.d.ts

@@ -0,0 +1,21 @@
+/**
+ * HMR & Dev Tooling — dev-only wiring for hot module replacement.
+ *
+ * Handles:
+ * - RSC module invalidation (rsc:update → router.refresh())
+ * - Dev warnings forwarded from server via WebSocket
+ * - Server console log replay in browser
+ * - Client error forwarding to Vite error overlay
+ *
+ * See design/21-dev-server.md §"HMR Wiring"
+ */
+import type { RouterInstance } from '#client-internal';
+/**
+ * Set up HMR and dev tool integration.
+ *
+ * Reads `import.meta.hot` to register dev-only event listeners.
+ * In production builds, `import.meta.hot` is undefined and this
+ * function is a no-op.
+ */
+export declare function setupHmr(router: RouterInstance): void;
+//# sourceMappingURL=hmr.d.ts.map

package/dist/client/browser-entry/hmr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmr.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/hmr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAavD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAgDrD"}

package/dist/client/browser-entry/hydrate.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Hydration — pre-hydration sequence and React root creation.
+ *
+ * Handles two paths:
+ * 1. RSC payload available: hydrateRoot with NavigationProvider wrapping
+ * 2. No RSC payload: deferred root creation via installDeferredNavigation
+ *
+ * Pre-hydration ordering contract (MUST execute in this order):
+ *   1. initRouter()        — creates the global router so useRouter()
+ *                            works during render
+ *   2. setCurrentParams()  — populates params snapshot so
+ *      + setNavigationState()  useSegmentParams() and usePathname()
+ *                            return correct values during hydration
+ *   3. hydrateRoot()       — synchronously executes component render
+ *                            functions that depend on steps 1-2
+ *
+ * See design/19-client-navigation.md §"NavigationContext"
+ */
+import type { TopLoaderConfig } from '../top-loader.js';
+import type { RscStreamResult } from './rsc-stream.js';
+interface HydrateOptions {
+    /** RSC stream result (null if no inlined payload) */
+    rscResult: RscStreamResult | null;
+    /** Runtime config from virtual:timber-config */
+    config: {
+        topLoader?: TopLoaderConfig;
+    };
+}
+/**
+ * Run the pre-hydration sequence: read server-embedded params and
+ * set navigation state. Must be called AFTER initRouter().
+ */
+export declare function runPreHydration(): void;
+/**
+ * Hydrate the React tree or set up deferred root creation.
+ *
+ * When an RSC payload is available, wraps it with NavigationProvider +
+ * TimberNuqsAdapter + NavigationRoot and calls hydrateRoot on the
+ * document.
+ *
+ * When no RSC payload is available (JS-only client), sets up deferred
+ * navigation so the first client navigation creates the React root.
+ */
+export declare function hydrateApp({ rscResult, config }: HydrateOptions): void;
+export {};
+//# sourceMappingURL=hydrate.d.ts.map

package/dist/client/browser-entry/hydrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/hydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAcH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,UAAU,cAAc;IACtB,qDAAqD;IACrD,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAClC,gDAAgD;IAChD,MAAM,EAAE;QAAE,SAAS,CAAC,EAAE,eAAe,CAAA;KAAE,CAAC;CACzC;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAiBtC;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,cAAc,GAAG,IAAI,CA6EtE"}

package/dist/client/browser-entry/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Browser Entry — Client-side hydration and navigation bootstrap.
+ *
+ * This is the thin orchestrator that coordinates the bootstrap sequence.
+ * Each responsibility is extracted into a focused module:
+ *
+ *   action-dispatch.ts  — server action callServer callback
+ *   rsc-stream.ts       — __timber_f chunk handling + ReadableStream
+ *   router-init.ts      — createRouter + Navigation API setup
+ *   hydrate.ts          — pre-hydration sequence + hydrateRoot/createRoot
+ *   post-hydration.ts   — history stack, segment cache, popstate, scroll
+ *   hmr.ts              — dev-only HMR + error forwarding
+ *   scroll.ts           — getScrollY helper
+ *
+ * Bootstrap call order contract:
+ *
+ *   1. setupServerActions()      — register callServer (independent)
+ *   2. createRscPayloadStream()  — decode inlined RSC payload
+ *   3. createTimberRouter()      — create router + Navigation API
+ *   4. runPreHydration()         — set params + navigation state
+ *   5. hydrateApp()              — hydrateRoot or deferred createRoot
+ *   6. setupPostHydration()      — history stack, popstate, scroll
+ *   7. setupHmr()                — dev-only HMR wiring
+ *   8. stale reload handlers     — global error listeners
+ *   9. timber-ready signal       — E2E test readiness indicator
+ *
+ * Design docs: 18-build-system.md §"Entry Files", 19-client-navigation.md
+ */
+import 'virtual:timber-search-params-registry';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/browser-entry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAQH,OAAO,uCAAuC,CAAC"}

package/dist/client/browser-entry/post-hydration.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Post-Hydration Wiring — history stack, segment cache, popstate, scroll.
+ *
+ * Sets up everything that needs to happen after the React root exists:
+ * - Stores initial page in history stack for instant back navigation
+ * - Initializes scroll state for the initial entry
+ * - Populates segment cache from server-embedded metadata
+ * - Registers popstate handler for back/forward navigation
+ * - Sets up debounced scroll position saving
+ *
+ * See design/19-client-navigation.md §"History Stack"
+ */
+import type { RouterInstance } from '#client-internal';
+import type { NavigationApiController } from '../navigation-api.js';
+interface PostHydrationOptions {
+    router: RouterInstance;
+    navApiController: NavigationApiController | null;
+    /** Decoded RSC element from initial SSR (null if no RSC payload) */
+    initialElement: unknown;
+}
+/**
+ * Wire up post-hydration event handlers and state.
+ */
+export declare function setupPostHydration({ router, navApiController, initialElement, }: PostHydrationOptions): void;
+export {};
+//# sourceMappingURL=post-hydration.d.ts.map

package/dist/client/browser-entry/post-hydration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-hydration.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/post-hydration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAGpE,UAAU,oBAAoB;IAC5B,MAAM,EAAE,cAAc,CAAC;IACvB,gBAAgB,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACjD,oEAAoE;IACpE,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,MAAM,EACN,gBAAgB,EAChB,cAAc,GACf,EAAE,oBAAoB,GAAG,IAAI,CA+E7B"}

package/dist/client/browser-entry/router-init.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Router Initialization — creates the timber router with all dependencies.
+ *
+ * Wires up RouterDeps (fetch, history, scroll, RSC decoding, render
+ * callbacks) and optionally sets up Navigation API integration.
+ *
+ * See design/19-client-navigation.md §"Navigation API Integration"
+ */
+import type { RouterInstance } from '#client-internal';
+import { type NavigationApiController } from '../navigation-api.js';
+export interface RouterInitOptions {
+    initialElement?: unknown;
+}
+export interface RouterInitResult {
+    router: RouterInstance;
+    navApiController: NavigationApiController | null;
+}
+/**
+ * Create and register the global timber router.
+ *
+ * Must be called before hydrateRoot so `useRouter()` works during
+ * the initial render (methods lazily resolve the router at invocation,
+ * not render time, but initRouter must still run first).
+ */
+export declare function createTimberRouter(options?: RouterInitOptions): RouterInitResult;
+//# sourceMappingURL=router-init.d.ts.map

package/dist/client/browser-entry/router-init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-init.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/router-init.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAc,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAQnE,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,sBAAsB,CAAC;AAG9B,MAAM,WAAW,iBAAiB;IAChC,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,cAAc,CAAC;IACvB,gBAAgB,EAAE,uBAAuB,GAAG,IAAI,CAAC;CAClD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,gBAAgB,CA+KhF"}

package/dist/client/browser-entry/rsc-stream.d.ts

@@ -0,0 +1,24 @@
+/**
+ * RSC Stream Bootstrap — decodes the server-inlined RSC payload.
+ *
+ * The RSC payload is embedded in the HTML as progressive inline script
+ * tags that call `self.__timber_f.push([type, data])` as RSC chunks arrive.
+ * Typed tuples: [0] = bootstrap signal, [1, string] = Flight data chunk.
+ *
+ * This module sets up a ReadableStream fed by those push() calls so
+ * `createFromReadableStream` can decode the Flight protocol progressively.
+ *
+ * See design/18-build-system.md §"Entry Files"
+ */
+export interface RscStreamResult {
+    /** The decoded RSC element (thenable/lazy — resolved by React during render) */
+    element: unknown;
+}
+/**
+ * Create the RSC payload stream from server-inlined `__timber_f` chunks.
+ *
+ * Returns null if no RSC payload was inlined (e.g., JS-only client).
+ * When a payload exists, returns the decoded element for hydration.
+ */
+export declare function createRscPayloadStream(): RscStreamResult | null;
+//# sourceMappingURL=rsc-stream.d.ts.map

package/dist/client/browser-entry/rsc-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsc-stream.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/rsc-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,GAAG,IAAI,CA+H/D"}

package/dist/client/browser-entry/scroll.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Scroll position helpers for the browser entry.
+ *
+ * Reads scroll position from the document viewport or explicitly marked
+ * `data-timber-scroll-restoration` containers.
+ *
+ * See design/19-client-navigation.md §"Overflow Scroll Containers".
+ */
+/**
+ * Read the current scroll position.
+ *
+ * Checks window scroll first, then explicit `data-timber-scroll-restoration`
+ * containers. With segment tree merging, shared layouts are reconciled in
+ * place via `cloneElement` — React preserves their DOM and scroll state
+ * naturally. We don't need to auto-detect overflow containers; only
+ * explicitly marked containers are tracked.
+ */
+export declare function getScrollY(): number;
+//# sourceMappingURL=scroll.d.ts.map

package/dist/client/browser-entry/scroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll.d.ts","sourceRoot":"","sources":["../../../src/client/browser-entry/scroll.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAQnC"}

package/dist/client/error-boundary.d.ts

@@ -18,17 +18,24 @@
 import { Component, type ReactNode } from 'react';
 export interface TimberErrorBoundaryProps {
     /** The component to render when an error is caught. */
-    fallbackComponent: (...args: unknown[]) => ReactNode;
+    fallbackComponent?: (...args: unknown[]) => ReactNode;
+    /**
+     * Pre-rendered fallback element. Used for MDX status files which are server
+     * components and cannot be passed as function props across the RSC→client
+     * boundary. When set, rendered directly instead of calling fallbackComponent.
+     *
+     * See design/10-error-handling.md §"Status-Code File Variants" — MDX status
+     * files are server components by default (zero client JS).
+     */
+    fallbackElement?: ReactNode;
     /**
      * Status code filter. If set, only catches errors matching this status.
      * 400 = any 4xx, 500 = any 5xx, specific number = exact match.
      */
     status?: number;
     /**
-     * When true, catching a DenySignal sets _denyHandledByBoundary on the
-     * nav context to prevent page-level deny promotion. Only slot catch-all
-     * boundaries should set this — segment boundaries (403.tsx, 4xx.tsx,
-     * error.tsx) must NOT, otherwise normal page denies get swallowed.
+     * When true, this boundary wraps a parallel slot. Slot denials are
+     * graceful degradation — they must NOT change the HTTP status code.
      */
     isSlotBoundary?: boolean;
     children: ReactNode;