@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.190

package/dist/_chunks/plugin-context-rCinWLiE.js

@@ -0,0 +1,321 @@
+import { o as __exportAll } from "./dist-BA3u1z3W.js";
+import { parseAst } from "vite";
+import { join, resolve } from "node:path";
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { performance } from "node:perf_hooks";
+//#region src/utils/startup-timer.ts
+/**
+* Startup timer — records named phases with their durations.
+*
+* Used by the plugin system to instrument cold start and report a
+* timing breakdown in dev mode. Zero overhead in production (disabled).
+*
+* See design/18-build-system.md, TIM-155.
+*/
+/**
+* Create a startup timer that records phase durations.
+*/
+function createStartupTimer() {
+	const pending = /* @__PURE__ */ new Map();
+	const phases = [];
+	return {
+		start(phase) {
+			pending.set(phase, performance.now());
+		},
+		end(phase) {
+			const startMs = pending.get(phase);
+			if (startMs === void 0) return 0;
+			pending.delete(phase);
+			const durationMs = performance.now() - startMs;
+			phases.push({
+				name: phase,
+				startMs,
+				durationMs
+			});
+			return durationMs;
+		},
+		getPhases() {
+			return [...phases].sort((a, b) => a.startMs - b.startMs);
+		},
+		totalMs() {
+			if (phases.length === 0) return 0;
+			const sorted = this.getPhases();
+			const first = sorted[0];
+			const last = sorted[sorted.length - 1];
+			return last.startMs + last.durationMs - first.startMs;
+		},
+		formatSummary() {
+			const sorted = this.getPhases();
+			if (sorted.length === 0) return "No phases recorded.";
+			const lines = sorted.map((p) => {
+				const ms = p.durationMs.toFixed(1);
+				return `  ${p.name.padEnd(30)} ${ms.padStart(8)}ms`;
+			});
+			const total = this.totalMs().toFixed(1);
+			lines.push(`  ${"total".padEnd(30)} ${total.padStart(8)}ms`);
+			return ["[timber] startup timing:", ...lines].join("\n");
+		}
+	};
+}
+/**
+* No-op timer for production builds — all methods are empty.
+*/
+function createNoopTimer() {
+	return {
+		start() {},
+		end() {
+			return 0;
+		},
+		getPhases() {
+			return [];
+		},
+		totalMs() {
+			return 0;
+		},
+		formatSummary() {
+			return "";
+		}
+	};
+}
+//#endregion
+//#region src/plugin-context.ts
+/**
+* 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"
+*/
+var plugin_context_exports = /* @__PURE__ */ __exportAll({
+	DEFAULT_BUILD_DIR: () => DEFAULT_BUILD_DIR,
+	ParseMemo: () => ParseMemo,
+	configLoadHint: () => configLoadHint,
+	createPluginContext: () => createPluginContext,
+	isTimberPluginApi: () => isTimberPluginApi,
+	loadTimberConfigFile: () => loadTimberConfigFile,
+	mergeFileConfig: () => mergeFileConfig,
+	resolveAppDir: () => resolveAppDir,
+	resolveBuildDir: () => resolveBuildDir,
+	resolveClientJavascript: () => resolveClientJavascript,
+	warnConfigConflicts: () => warnConfigConflicts
+});
+/**
+* Resolve `clientJavascript` into a fully resolved config.
+*/
+function resolveClientJavascript(config) {
+	if (config.clientJavascript !== void 0) {
+		if (typeof config.clientJavascript === "boolean") return {
+			disabled: !config.clientJavascript,
+			enableHMRInDev: !config.clientJavascript
+		};
+		return {
+			disabled: config.clientJavascript.disabled,
+			enableHMRInDev: config.clientJavascript.enableHMRInDev ?? config.clientJavascript.disabled
+		};
+	}
+	return {
+		disabled: false,
+		enableHMRInDev: false
+	};
+}
+var PARSE_MEMO_CAPACITY = 32;
+/**
+* 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.
+*/
+var ParseMemo = class {
+	cache = /* @__PURE__ */ new Map();
+	/**
+	* 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) {
+		const existing = this.cache.get(code);
+		if (existing) {
+			this.cache.delete(code);
+			this.cache.set(code, existing);
+			return existing;
+		}
+		const program = parseAst(code, { lang: "tsx" });
+		if (this.cache.size >= PARSE_MEMO_CAPACITY) {
+			const firstKey = this.cache.keys().next().value;
+			this.cache.delete(firstKey);
+		}
+		this.cache.set(code, program);
+		return program;
+	}
+	get size() {
+		return this.cache.size;
+	}
+};
+/** Narrow an unknown Vite `plugin.api` to timber's. */
+function isTimberPluginApi(api) {
+	return typeof api === "object" && api !== null && "getContext" in api && typeof api.getContext === "function";
+}
+/**
+* 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.
+*/
+function resolveAppDir(root, configAppDir) {
+	if (configAppDir) {
+		const explicit = join(root, configAppDir);
+		if (!existsSync(explicit)) throw new Error(`[timber] Configured appDir "${configAppDir}" does not exist at ${explicit}`);
+		return explicit;
+	}
+	const rootApp = join(root, "app");
+	if (existsSync(rootApp)) return rootApp;
+	const srcApp = join(root, "src", "app");
+	if (existsSync(srcApp)) return srcApp;
+	throw new Error(`[timber] Could not find app directory. Expected "app/" or "src/app/" in ${root}. You can set appDir in timber.config.ts to specify a custom location.`);
+}
+function createPluginContext(config, root) {
+	const projectRoot = root ?? process.cwd();
+	const resolvedConfig = { ...config };
+	return {
+		config: resolvedConfig,
+		clientJavascript: resolveClientJavascript(resolvedConfig),
+		routeTree: null,
+		appDir: join(projectRoot, "app"),
+		root: projectRoot,
+		dev: false,
+		base: "/",
+		buildManifest: null,
+		deploymentId: null,
+		timer: createStartupTimer(),
+		holdingServer: null,
+		buildDir: resolveBuildDir(projectRoot, resolvedConfig.buildDir),
+		parseCached: new ParseMemo()
+	};
+}
+/** Default build output directory (relative to root). */
+var DEFAULT_BUILD_DIR = join(".timber", "dist");
+/**
+* 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.
+*/
+function resolveBuildDir(root, timberBuildDir, viteBuildOutDir) {
+	if (timberBuildDir) return resolve(root, timberBuildDir);
+	if (viteBuildOutDir && viteBuildOutDir !== "dist") return resolve(root, viteBuildOutDir);
+	return join(root, DEFAULT_BUILD_DIR);
+}
+/**
+* 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)
+*/
+function configLoadHint(configName, err) {
+	const code = err?.code;
+	const isTs = configName.endsWith(".ts");
+	if (isTs && code === "ERR_UNKNOWN_FILE_EXTENSION") return "Loading a TypeScript config requires Node.js 22.18+ (built-in type stripping). Upgrade Node.js or rewrite the config as timber.config.js.";
+	if (code === "ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX" || code === "ERR_INVALID_TYPESCRIPT_SYNTAX") return "Node.js loads the config with type stripping, which only supports erasable TypeScript syntax — replace enums, namespaces, and constructor parameter properties with plain objects and types.";
+	if (isTs && err instanceof SyntaxError && /Unexpected token '(export|import)'|Cannot use import statement outside a module/.test(err.message)) return "The config uses ESM syntax but Node.js parsed it as CommonJS — set \"type\": \"module\" in package.json, or use module.exports instead of export default.";
+	return 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.
+*/
+function loadTimberConfigFile(root) {
+	const configNames = [
+		"timber.config.ts",
+		"timber.config.js",
+		"timber.config.mjs"
+	];
+	const req = createRequire(join(root, "package.json"));
+	for (const name of configNames) {
+		const configPath = join(root, name);
+		if (existsSync(configPath)) try {
+			const mod = req(configPath);
+			return mod.default ?? mod;
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			const hint = configLoadHint(name, err);
+			throw new Error(`[timber] Failed to load ${configPath}: ${message}${hint ? `\n${hint}` : ""}`, { cause: err });
+		}
+	}
+	return null;
+}
+/**
+* Detect config keys set in both inline (vite.config.ts) and file (timber.config.ts)
+* and warn the user. The `output` key is excluded because it defaults to 'server'
+* in createPluginContext and would always appear as an inline key.
+*
+* Returns the list of conflicting key names (for testing).
+*/
+function warnConfigConflicts(inline, fileConfig) {
+	const conflicts = [];
+	for (const key of Object.keys(fileConfig)) if (key in inline && inline[key] !== void 0) conflicts.push(key);
+	if (conflicts.length > 0) console.warn(`[timber] Config conflict: ${conflicts.map((k) => `"${k}"`).join(", ")} set in both vite.config.ts (inline) and timber.config.ts. Move all config to timber.config.ts to avoid confusion. The inline value from vite.config.ts will be used.`);
+	return conflicts;
+}
+/**
+* Drop own keys whose value is `undefined` so they don't clobber file
+* config during spread merging. `timber({ buildDir: process.env.BUILD_DIR })`
+* with the var unset must not erase the timber.config.ts value.
+*/
+function stripUndefined(obj) {
+	return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== void 0));
+}
+/**
+* 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.
+*/
+function mergeFileConfig(inline, fileConfig) {
+	warnConfigConflicts(inline, fileConfig);
+	const definedInline = stripUndefined(inline);
+	return {
+		...fileConfig,
+		...definedInline,
+		...fileConfig.limits && definedInline.limits ? { limits: {
+			...fileConfig.limits,
+			...stripUndefined(definedInline.limits)
+		} } : {},
+		...fileConfig.dev && definedInline.dev ? { dev: {
+			...fileConfig.dev,
+			...stripUndefined(definedInline.dev)
+		} } : {},
+		...fileConfig.mdx && definedInline.mdx ? { mdx: {
+			...fileConfig.mdx,
+			...stripUndefined(definedInline.mdx)
+		} } : {}
+	};
+}
+//#endregion
+export { plugin_context_exports as a, resolveClientJavascript as c, mergeFileConfig as i, createNoopTimer as l, isTimberPluginApi as n, resolveAppDir as o, loadTimberConfigFile as r, resolveBuildDir as s, createPluginContext as t };
+
+//# sourceMappingURL=plugin-context-rCinWLiE.js.map

package/dist/_chunks/plugin-context-rCinWLiE.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-context-rCinWLiE.js","names":[],"sources":["../../src/utils/startup-timer.ts","../../src/plugin-context.ts"],"sourcesContent":["/**\n * Startup timer — records named phases with their durations.\n *\n * Used by the plugin system to instrument cold start and report a\n * timing breakdown in dev mode. Zero overhead in production (disabled).\n *\n * See design/18-build-system.md, TIM-155.\n */\n\nimport { performance } from 'node:perf_hooks';\n\nexport interface PhaseRecord {\n  name: string;\n  startMs: number;\n  durationMs: number;\n}\n\nexport interface StartupTimer {\n  /** Mark the beginning of a named phase. */\n  start(phase: string): void;\n  /** Mark the end of a named phase. Returns duration in ms. */\n  end(phase: string): number;\n  /** Get all completed phase records, ordered by start time. */\n  getPhases(): PhaseRecord[];\n  /** Total elapsed time from first start() to last end(). */\n  totalMs(): number;\n  /** Format a human-readable summary string. */\n  formatSummary(): string;\n}\n\n/**\n * Create a startup timer that records phase durations.\n */\nexport function createStartupTimer(): StartupTimer {\n  const pending = new Map<string, number>();\n  const phases: PhaseRecord[] = [];\n\n  return {\n    start(phase: string): void {\n      pending.set(phase, performance.now());\n    },\n\n    end(phase: string): number {\n      const startMs = pending.get(phase);\n      if (startMs === undefined) {\n        return 0;\n      }\n      pending.delete(phase);\n      const durationMs = performance.now() - startMs;\n      phases.push({ name: phase, startMs, durationMs });\n      return durationMs;\n    },\n\n    getPhases(): PhaseRecord[] {\n      return [...phases].sort((a, b) => a.startMs - b.startMs);\n    },\n\n    totalMs(): number {\n      if (phases.length === 0) return 0;\n      const sorted = this.getPhases();\n      const first = sorted[0];\n      const last = sorted[sorted.length - 1];\n      return last.startMs + last.durationMs - first.startMs;\n    },\n\n    formatSummary(): string {\n      const sorted = this.getPhases();\n      if (sorted.length === 0) return 'No phases recorded.';\n\n      const lines = sorted.map((p) => {\n        const ms = p.durationMs.toFixed(1);\n        return `  ${p.name.padEnd(30)} ${ms.padStart(8)}ms`;\n      });\n\n      const total = this.totalMs().toFixed(1);\n      lines.push(`  ${'total'.padEnd(30)} ${total.padStart(8)}ms`);\n\n      return ['[timber] startup timing:', ...lines].join('\\n');\n    },\n  };\n}\n\n/**\n * No-op timer for production builds — all methods are empty.\n */\nexport function createNoopTimer(): StartupTimer {\n  return {\n    start() {},\n    end() {\n      return 0;\n    },\n    getPhases() {\n      return [];\n    },\n    totalMs() {\n      return 0;\n    },\n    formatSummary() {\n      return '';\n    },\n  };\n}\n","/**\n * Plugin context — internal types and helpers for timber sub-plugins.\n *\n * These are NOT part of the user-facing API. They are consumed by\n * sub-plugins (routing, entries, shims, etc.) via relative imports.\n * The root entry point (index.ts) does not re-export them.\n *\n * Design doc: 18-build-system.md §\"Shared Plugin Context\"\n */\n\nimport { existsSync } from 'node:fs';\nimport { join, resolve } from 'node:path';\nimport { createRequire } from 'node:module';\nimport { parseAst } from 'vite';\nimport type { RouteTree } from './routing/types';\nimport type { BuildManifest } from './server/build-manifest';\nimport type { CaptureSummary } from './server/prebuilt-builder';\nimport type { StartupTimer } from './utils/startup-timer';\nimport { createStartupTimer } from './utils/startup-timer';\nimport type { TimberUserConfig, ClientJavascriptConfig } from './config-types.js';\nimport type { RscManifest } from './plugins/static-build.js';\nimport type { HoldingServer } from './dev-tools/holding-server.js';\nimport type { ProgramNode } from './plugins/callsite-ast.js';\n\n// Re-export for sub-plugin convenience — they import from plugin-context.ts\nexport type { TimberUserConfig, ClientJavascriptConfig } from './config-types.js';\n\n// ── Client JavaScript config ─────────────────────────────────────────────\n\n/** Fully resolved client JavaScript configuration (no optionals). */\nexport interface ResolvedClientJavascript {\n  disabled: boolean;\n  enableHMRInDev: boolean;\n}\n\n/**\n * Resolve `clientJavascript` into a fully resolved config.\n */\nexport function resolveClientJavascript(config: TimberUserConfig): ResolvedClientJavascript {\n  if (config.clientJavascript !== undefined) {\n    if (typeof config.clientJavascript === 'boolean') {\n      return {\n        disabled: !config.clientJavascript,\n        enableHMRInDev: !config.clientJavascript,\n      };\n    }\n    return {\n      disabled: config.clientJavascript.disabled,\n      enableHMRInDev: config.clientJavascript.enableHMRInDev ?? config.clientJavascript.disabled,\n    };\n  }\n  return { disabled: false, enableHMRInDev: false };\n}\n\n// ── Plugin Context ────────────────────────────────────────────────────────\n\n/**\n * Shared context object passed to all sub-plugins via closure.\n *\n * Sub-plugins communicate through this context — not through Vite's\n * plugin API or global state.\n * See design/18-build-system.md §\"Shared Plugin Context\".\n */\nexport interface PluginContext {\n  config: TimberUserConfig;\n  /** Resolved client JavaScript configuration */\n  clientJavascript: ResolvedClientJavascript;\n  /** The scanned route tree (populated by timber-routing, consumed by timber-entries) */\n  routeTree: RouteTree | null;\n  /** Absolute path to the app/ directory */\n  appDir: string;\n  /** Absolute path to the project root */\n  root: string;\n  /** Whether the dev server is running (set by timber-root-sync in configResolved) */\n  dev: boolean;\n  /**\n   * Vite's resolved `base` (set by timber-root-sync in configResolved).\n   * Always has a trailing slash; `'/'` unless the app is deployed under a\n   * sub-path. Every URL the framework emits — assets, fonts, RSC payloads —\n   * carries this prefix. This is the single copy: sub-plugins read it here\n   * rather than capturing `config.base` in their own configResolved.\n   *\n   * **Availability:** written by timber-root-sync, which has no `enforce`, so\n   * it is populated from `buildStart`/`load`/`generateBundle`/`configureServer`\n   * onward — but NOT during the `configResolved` of an `enforce: 'pre'`\n   * plugin, which Vite runs first. A pre plugin that needs the base inside\n   * its own `configResolved` must read `config.base` there (timber-fonts\n   * does). See TIM-1261.\n   */\n  base: string;\n  /** CSS build manifest (populated by adapter after client build, null in dev) */\n  buildManifest: BuildManifest | null;\n  /** Per-build deployment ID for version skew detection (null in dev) */\n  deploymentId: string | null;\n  /** Startup timer for profiling cold start phases (active in dev, no-op in prod) */\n  timer: StartupTimer;\n  /** Holding server that binds the port during dev startup (closed in timber-dev-server) */\n  holdingServer?: HoldingServer | null;\n  /**\n   * Resolved absolute path to the build output directory.\n   *\n   * Defaults to `<root>/.timber/dist`. Can be overridden via\n   * `timber.config.ts` `buildDir` or Vite's `build.outDir`.\n   * Timber config takes precedence when both are set.\n   *\n   * Used by adapter-build and cli preview.\n   */\n  buildDir: string;\n  /**\n   * Per-route client reference keys captured during the RSC build.\n   * Maps absolute route file paths to the set of client reference\n   * hash keys they transitively import. Used by adapter-build to\n   * populate per-route modulepreload entries from clientReferenceDeps.\n   */\n  routeClientRefKeys?: Map<string, Set<string>>;\n  /**\n   * Static request-dependency verdict per segment entry file, keyed by the\n   * absolute `filePath` the route scanner produced. Computed once by\n   * `timber-request-dep`'s RSC `buildEnd` and serialized into\n   * `buildManifest.requestDep` by `timber-build-manifest` (build only — dev\n   * answers the same question through the `Symbol.for('timber:request-dep')`\n   * bridge instead).\n   *\n   * `undefined` and `{}` are different states and the difference is the whole\n   * of TIM-1300: an empty object means the analysis ran and found no segments,\n   * `undefined` means it never ran, and the runtime cannot tell them apart —\n   * every key is absent either way, so every segment falls to the conservative\n   * `true` and nothing is ever skipped. The build fails loudly on `undefined`\n   * rather than shipping that silently.\n   */\n  requestDepMap?: Record<string, boolean>;\n  /**\n   * Maps absolute module IDs of client references in non-facade RSC\n   * chunks to the absolute paths of their consuming facade modules.\n   * Built during the RSC `generateBundle` phase by timber-chunks,\n   * consumed by `clientChunkGroup` to reclassify `shared:` modules\n   * that are only used by a single route boundary.\n   * See design/27-chunking-strategy.md, TIM-1107.\n   */\n  sharedModuleFacades?: Map<string, string[]>;\n  /**\n   * Module ID → prebuilt component IDs declared in it. Recorded by the\n   * timber-prebuilt transform (RSC environment, production builds only),\n   * consumed by the RSC `generateBundle` module-graph walk that computes\n   * `routePrebuiltComponents`. See design/44-render-at-build-time.md.\n   */\n  prebuiltModuleComponents?: Map<string, string[]>;\n  /**\n   * Module ID → mapping of variable name to component ID for the prebuilt\n   * components declared in that module. Used at `generateBundle` time to\n   * trace imports from other modules back to specific component IDs.\n   */\n  prebuiltBindingNames?: Map<string, Map<string, string>>;\n  /**\n   * Component ID → distinct static call-site prop objects captured from\n   * JSX usage sites during the transform and generateBundle phases.\n   * Consumed by the post-build capture pass to render with actual props\n   * instead of empty `{}`. See design/44 §Props Derivation.\n   */\n  prebuiltCallSiteProps?: Map<string, Record<string, unknown>[]>;\n  /**\n   * Route file path (page or layout, absolute) → prebuilt component IDs\n   * transitively reachable from it. Computed during RSC `generateBundle`,\n   * consumed by the post-build capture pass (TIM-1119) to decide which\n   * components to render under which route's param combos.\n   */\n  routePrebuiltComponents?: Map<string, string[]>;\n  /**\n   * Page file paths that were desugared from `export const prerender` by\n   * timber-prerender-sugar. The prebuilt transform uses this to verify\n   * the generated `cache.component(...)` call was picked up.\n   */\n  prerenderSugarPages?: Set<string>;\n  /**\n   * Component ID → built chunk file name for prebuilt-declaring modules\n   * that are only reachable via dynamic imports (import.meta.glob, lazy\n   * routes). The capture pass imports these chunks to trigger\n   * cache.component() registration before rendering. Populated during\n   * RSC generateBundle alongside routePrebuiltComponents.\n   */\n  prebuiltLazyChunks?: Map<string, string>;\n  /** Post-build prebuilt capture summary (populated by timber-prebuilt, consumed by build-report). */\n  captureSummary?: CaptureSummary;\n  /**\n   * Content-keyed AST parse memo shared across cache/prebuilt/prerender-sugar\n   * transforms. Collapses both cross-plugin and cross-environment duplicate\n   * parses: identical code hits, rewritten code misses (correct because Vite\n   * transforms chain — a rewrite produces different code). Bounded LRU (32\n   * entries) so it doesn't hold programs for the whole build.\n   *\n   * Consumers MUST treat the returned ProgramNode as read-only — they collect\n   * ranges and rewrite CODE via MagicString; the AST itself is never mutated.\n   */\n  parseCached?: ParseMemo;\n  /**\n   * Content-Type mappings for extensionless static API route outputs.\n   * Populated during static generation, consumed by adapter-build to\n   * write per-path Content-Type rules in _headers. See TIM-1241.\n   */\n  staticContentTypes?: Record<string, string>;\n  /**\n   * RSC flight payload manifest mapping unhashed → hashed URLs.\n   * Populated during static generation, consumed by adapters to set\n   * immutable cache headers for `_rsc/` files. See TIM-1254.\n   */\n  rscManifest?: RscManifest;\n}\n\n// ── AST parse memo ───────────────────────────────────────────────────────\n\nconst PARSE_MEMO_CAPACITY = 32;\n\n/**\n * Content-keyed LRU memo for `parseAst`. Transforms for the same module run\n * back-to-back across plugins and environments, so a tiny window captures the\n * wins. The returned ProgramNode is shared — callers MUST NOT mutate it.\n */\nexport class ParseMemo {\n  private cache = new Map<string, ProgramNode>();\n\n  /**\n   * Parse code, returning a cached ProgramNode if the same code was parsed\n   * before. The returned AST MUST NOT be mutated — it may be shared across\n   * multiple consumers.\n   */\n  parse(code: string): ProgramNode {\n    const existing = this.cache.get(code);\n    if (existing) {\n      // LRU refresh: move to end\n      this.cache.delete(code);\n      this.cache.set(code, existing);\n      return existing;\n    }\n    const program = parseAst(code, { lang: 'tsx' }) as unknown as ProgramNode;\n    if (this.cache.size >= PARSE_MEMO_CAPACITY) {\n      // Evict oldest (first inserted)\n      const firstKey = this.cache.keys().next().value!;\n      this.cache.delete(firstKey);\n    }\n    this.cache.set(code, program);\n    return program;\n  }\n\n  get size(): number {\n    return this.cache.size;\n  }\n}\n\n// ── App directory resolution ──────────────────────────────────────────────\n\n// ── Plugin API (Vite `plugin.api`) ────────────────────────────────────────\n\n/**\n * What `timber-root-sync` publishes on its Vite `plugin.api`.\n *\n * The single supported way to read timber's *resolved* configuration from\n * outside the plugin pipeline. Re-reading `timber.config.ts` is not equivalent:\n * config passed inline as `timber({ ... })` in `vite.config.ts` exists only in\n * the plugin's closure, and `root`/`appDir` are resolved against Vite's root\n * rather than the caller's cwd.\n */\nexport interface TimberPluginApi {\n  /** The live plugin context. Fully populated from `configResolved` onward. */\n  getContext(): PluginContext;\n}\n\n/** Narrow an unknown Vite `plugin.api` to timber's. */\nexport function isTimberPluginApi(api: unknown): api is TimberPluginApi {\n  return (\n    typeof api === 'object' &&\n    api !== null &&\n    'getContext' in api &&\n    typeof api.getContext === 'function'\n  );\n}\n\n/**\n * Resolve the app directory. Checks (in order):\n * 1. Explicit `configAppDir` from timber.config.ts\n * 2. `<root>/app`\n * 3. `<root>/src/app`\n *\n * Throws if none exist.\n */\nexport function resolveAppDir(root: string, configAppDir?: string): string {\n  if (configAppDir) {\n    const explicit = join(root, configAppDir);\n    if (!existsSync(explicit)) {\n      throw new Error(`[timber] Configured appDir \"${configAppDir}\" does not exist at ${explicit}`);\n    }\n    return explicit;\n  }\n\n  const rootApp = join(root, 'app');\n  if (existsSync(rootApp)) return rootApp;\n\n  const srcApp = join(root, 'src', 'app');\n  if (existsSync(srcApp)) return srcApp;\n\n  throw new Error(\n    `[timber] Could not find app directory. Expected \"app/\" or \"src/app/\" in ${root}. ` +\n      `You can set appDir in timber.config.ts to specify a custom location.`\n  );\n}\n\n// ── Plugin context factory ────────────────────────────────────────────────\n\nexport function createPluginContext(config?: TimberUserConfig, root?: string): PluginContext {\n  const projectRoot = root ?? process.cwd();\n  const resolvedConfig: TimberUserConfig = { ...config };\n  return {\n    config: resolvedConfig,\n    clientJavascript: resolveClientJavascript(resolvedConfig),\n    routeTree: null,\n    appDir: join(projectRoot, 'app'),\n    root: projectRoot,\n    dev: false,\n    base: '/',\n    buildManifest: null,\n    deploymentId: null,\n    timer: createStartupTimer(),\n    holdingServer: null,\n    buildDir: resolveBuildDir(projectRoot, resolvedConfig.buildDir),\n    parseCached: new ParseMemo(),\n  };\n}\n\n// ── Build directory resolution ────────────────────────────────────────────\n\n/** Default build output directory (relative to root). */\nexport const DEFAULT_BUILD_DIR = join('.timber', 'dist');\n\n/**\n * Resolve the build output directory.\n *\n * Priority:\n * 1. Explicit `timberBuildDir` from timber.config.ts\n * 2. Explicit `viteBuildOutDir` from Vite's build.outDir (if not the default 'dist')\n * 3. Default: `.timber/dist`\n *\n * Returns an absolute path.\n */\nexport function resolveBuildDir(\n  root: string,\n  timberBuildDir?: string,\n  viteBuildOutDir?: string\n): string {\n  if (timberBuildDir) {\n    return resolve(root, timberBuildDir);\n  }\n  if (viteBuildOutDir && viteBuildOutDir !== 'dist') {\n    return resolve(root, viteBuildOutDir);\n  }\n  return join(root, DEFAULT_BUILD_DIR);\n}\n\n// ── Config file loading ───────────────────────────────────────────────────\n\n/**\n * Map known timber.config load failures to actionable hints (TIM-1040).\n * Returns null when the error has no known remedy beyond its own message.\n *\n * Known failure modes of loading timber.config.ts via native require():\n * - Node < 22.18 has no default type stripping → ERR_UNKNOWN_FILE_EXTENSION\n * - Non-erasable TS syntax (enums, namespaces, parameter properties)\n *   → ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX / ERR_INVALID_TYPESCRIPT_SYNTAX\n * - ESM syntax in a `\"type\": \"commonjs\"` package → the stripped .ts is\n *   parsed as CJS and throws SyntaxError: \"Unexpected token 'export'\"\n *   (export statements) or \"Cannot use import statement outside a\n *   module\" (import statements)\n */\nexport function configLoadHint(configName: string, err: unknown): string | null {\n  const code = (err as NodeJS.ErrnoException | null)?.code;\n  const isTs = configName.endsWith('.ts');\n\n  if (isTs && code === 'ERR_UNKNOWN_FILE_EXTENSION') {\n    return (\n      'Loading a TypeScript config requires Node.js 22.18+ (built-in type stripping). ' +\n      'Upgrade Node.js or rewrite the config as timber.config.js.'\n    );\n  }\n  if (code === 'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX' || code === 'ERR_INVALID_TYPESCRIPT_SYNTAX') {\n    return (\n      'Node.js loads the config with type stripping, which only supports erasable TypeScript syntax — ' +\n      'replace enums, namespaces, and constructor parameter properties with plain objects and types.'\n    );\n  }\n  if (\n    isTs &&\n    err instanceof SyntaxError &&\n    /Unexpected token '(export|import)'|Cannot use import statement outside a module/.test(\n      err.message\n    )\n  ) {\n    return (\n      'The config uses ESM syntax but Node.js parsed it as CommonJS — ' +\n      'set \"type\": \"module\" in package.json, or use module.exports instead of export default.'\n    );\n  }\n  return null;\n}\n\n/**\n * Load timber.config.ts (or .js, .mjs) from the project root.\n * Returns the config object or null if no config file is found.\n * Throws a descriptive error naming the file when a config file exists\n * but fails to load — a broken config must fail loudly, never silently\n * degrade (see TIM-1066). Known failure modes get an actionable hint\n * appended (see configLoadHint, TIM-1040).\n *\n * Uses require() — Node 22.12+ can require() ESM modules, and Node\n * 22.18+ strips types from .ts files by default (hence the engines\n * field requiring >=22.18.0). This keeps timber() synchronous — no\n * async config loading needed.\n * This is the single config loader — dev, build, and preview all use it.\n */\nexport function loadTimberConfigFile(root: string): TimberUserConfig | null {\n  const configNames = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];\n  const req = createRequire(join(root, 'package.json'));\n\n  for (const name of configNames) {\n    const configPath = join(root, name);\n    if (existsSync(configPath)) {\n      try {\n        const mod = req(configPath);\n        return (mod.default ?? mod) as TimberUserConfig;\n      } catch (err) {\n        const message = err instanceof Error ? err.message : String(err);\n        const hint = configLoadHint(name, err);\n        throw new Error(\n          `[timber] Failed to load ${configPath}: ${message}${hint ? `\\n${hint}` : ''}`,\n          { cause: err }\n        );\n      }\n    }\n  }\n  return null;\n}\n\n/**\n * Detect config keys set in both inline (vite.config.ts) and file (timber.config.ts)\n * and warn the user. The `output` key is excluded because it defaults to 'server'\n * in createPluginContext and would always appear as an inline key.\n *\n * Returns the list of conflicting key names (for testing).\n */\nexport function warnConfigConflicts(\n  inline: TimberUserConfig,\n  fileConfig: TimberUserConfig\n): string[] {\n  const conflicts: string[] = [];\n  for (const key of Object.keys(fileConfig) as (keyof TimberUserConfig)[]) {\n    if (key in inline && inline[key] !== undefined) {\n      conflicts.push(key);\n    }\n  }\n  if (conflicts.length > 0) {\n    console.warn(\n      `[timber] Config conflict: ${conflicts.map((k) => `\"${k}\"`).join(', ')} set in both ` +\n        `vite.config.ts (inline) and timber.config.ts. ` +\n        `Move all config to timber.config.ts to avoid confusion. ` +\n        `The inline value from vite.config.ts will be used.`\n    );\n  }\n  return conflicts;\n}\n\n/**\n * Drop own keys whose value is `undefined` so they don't clobber file\n * config during spread merging. `timber({ buildDir: process.env.BUILD_DIR })`\n * with the var unset must not erase the timber.config.ts value.\n */\nfunction stripUndefined<T extends object>(obj: T): T {\n  return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined)) as T;\n}\n\n/**\n * Merge file-based config (timber.config.ts) with inline config (vite.config.ts).\n * Inline config takes precedence — file config only fills in missing fields.\n * Inline keys explicitly set to `undefined` are treated as absent, matching\n * the `!== undefined` check in warnConfigConflicts.\n */\nexport function mergeFileConfig(\n  inline: TimberUserConfig,\n  fileConfig: TimberUserConfig\n): TimberUserConfig {\n  warnConfigConflicts(inline, fileConfig);\n  const definedInline = stripUndefined(inline);\n\n  return {\n    ...fileConfig,\n    ...definedInline,\n    ...(fileConfig.limits && definedInline.limits\n      ? { limits: { ...fileConfig.limits, ...stripUndefined(definedInline.limits) } }\n      : {}),\n    ...(fileConfig.dev && definedInline.dev\n      ? { dev: { ...fileConfig.dev, ...stripUndefined(definedInline.dev) } }\n      : {}),\n    ...(fileConfig.mdx && definedInline.mdx\n      ? { mdx: { ...fileConfig.mdx, ...stripUndefined(definedInline.mdx) } }\n      : {}),\n  };\n}\n"],"mappings":"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"}

package/dist/_chunks/purge-store-Byr8XOjU.js

@@ -0,0 +1,14 @@
+//#region src/cdn/purge-store.ts
+var handler;
+/** Install a CDN purge handler. Called by the framework at boot from timber.config.ts. */
+function setCdnPurgeHandler(h) {
+	handler = h;
+}
+/** Get the current CDN purge handler, if configured. */
+function getCdnPurgeHandler() {
+	return handler;
+}
+//#endregion
+export { setCdnPurgeHandler as n, getCdnPurgeHandler as t };
+
+//# sourceMappingURL=purge-store-Byr8XOjU.js.map

package/dist/_chunks/purge-store-Byr8XOjU.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"purge-store-Byr8XOjU.js","names":[],"sources":["../../src/cdn/purge-store.ts"],"sourcesContent":["/**\n * CDN purge handler singleton — same pattern as cache/handler-store.ts.\n *\n * Set via timber.config.ts or setCdnPurgeHandler() at boot. When set,\n * cache.invalidate({ tag }) also triggers CDN purge for the invalidated\n * tags, so revalidateTag() composes with CDN caching out of the box.\n *\n * See design/25-production-deployments.md §Layer 2.\n */\n\nexport interface CdnPurgeHandler {\n  /**\n   * Purge the given cache tags from the CDN.\n   * Called by cache.invalidate when a tag is invalidated.\n   */\n  purgeTags(tags: string[]): Promise<void>;\n}\n\nlet handler: CdnPurgeHandler | undefined;\n\n/** Install a CDN purge handler. Called by the framework at boot from timber.config.ts. */\nexport function setCdnPurgeHandler(h: CdnPurgeHandler): void {\n  handler = h;\n}\n\n/** Get the current CDN purge handler, if configured. */\nexport function getCdnPurgeHandler(): CdnPurgeHandler | undefined {\n  return handler;\n}\n\n/** @internal — reset for tests only. */\nexport function _resetCdnPurgeHandler(): void {\n  handler = undefined;\n}\n"],"mappings":";AAkBA,IAAI;;AAGJ,SAAgB,mBAAmB,GAA0B;CAC3D,UAAU;AACZ;;AAGA,SAAgB,qBAAkD;CAChE,OAAO;AACT"}

package/dist/_chunks/resolve-schema-CBR6Lm4i.js

@@ -0,0 +1,50 @@
+import { a as resolveCodecOrSchema, r as isCodec } from "./schema-bridge-C83xa9lT.js";
+//#region src/params/resolve-schema.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]]'
+*/
+function toBracketKey(segmentType, paramName) {
+	switch (segmentType) {
+		case "catch-all": return `[...${paramName}]`;
+		case "optional-catch-all": return `[[...${paramName}]]`;
+		default: return `[${paramName}]`;
+	}
+}
+var CATCH_ALL_RE = /^\[\.\.\..+\]$/;
+var OPTIONAL_CATCH_ALL_RE = /^\[\[\.\.\..+\]\]$/;
+function isCatchAllKey(key) {
+	return CATCH_ALL_RE.test(key) || OPTIONAL_CATCH_ALL_RE.test(key);
+}
+function isOptionalCatchAllKey(key) {
+	return OPTIONAL_CATCH_ALL_RE.test(key);
+}
+/**
+* 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> }
+*/
+function resolveSchemaCodecs(segmentParams) {
+	const resolved = Object.create(null);
+	for (const [bracketName, value] of Object.entries(segmentParams)) {
+		if (isCatchAllKey(bracketName) && isCodec(value) && !("__catchAll" in value)) throw new Error(`[timber] Schema error: '${bracketName}' is a catch-all segment and requires an array codec (e.g. codec.catchAll(codec.string)). Got a scalar codec.`);
+		if (isOptionalCatchAllKey(bracketName) && isCodec(value) && "__catchAll" in value && !("__optional" in value)) throw new Error(`[timber] Schema error: '${bracketName}' is an optional catch-all segment and requires codec.optionalCatchAll() (e.g. codec.optionalCatchAll(codec.string)). Got a non-optional catch-all codec.`);
+		resolved[bracketName] = resolveCodecOrSchema(bracketName, value, "param");
+	}
+	return resolved;
+}
+//#endregion
+export { toBracketKey as n, resolveSchemaCodecs as t };
+
+//# sourceMappingURL=resolve-schema-CBR6Lm4i.js.map

package/dist/_chunks/resolve-schema-CBR6Lm4i.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-schema-CBR6Lm4i.js","names":[],"sources":["../../src/params/resolve-schema.ts"],"sourcesContent":["/**\n * Schema resolution — resolves the global schema's segmentParams into\n * a runtime-ready codec map keyed by bracket name (e.g. '[id]').\n *\n * Bracket keys are preserved so that `[id]`, `[...id]`, and `[[...id]]`\n * remain distinct entries. The coercion layer reconstructs bracket keys\n * from matched segment metadata to look up the correct codec.\n *\n * Design doc: design/41-global-params.md §Pipeline Integration\n */\n\nimport type { Codec } from '../codec.js';\nimport { isCodec, resolveCodecOrSchema } from '../schema-bridge.js';\n\n/**\n * Reconstruct the bracket key for a segment from its type and param name.\n * Used by the coercion layer to look up codecs in the bracket-keyed map.\n *\n * 'dynamic'          + 'id'   → '[id]'\n * 'catch-all'        + 'slug' → '[...slug]'\n * 'optional-catch-all' + 'slug' → '[[...slug]]'\n */\nexport function toBracketKey(segmentType: string, paramName: string): string {\n  switch (segmentType) {\n    case 'catch-all':\n      return `[...${paramName}]`;\n    case 'optional-catch-all':\n      return `[[...${paramName}]]`;\n    default:\n      return `[${paramName}]`;\n  }\n}\n\nconst CATCH_ALL_RE = /^\\[\\.\\.\\..+\\]$/;\nconst OPTIONAL_CATCH_ALL_RE = /^\\[\\[\\.\\.\\..+\\]\\]$/;\n\nfunction isCatchAllKey(key: string): boolean {\n  return CATCH_ALL_RE.test(key) || OPTIONAL_CATCH_ALL_RE.test(key);\n}\n\nfunction isOptionalCatchAllKey(key: string): boolean {\n  return OPTIONAL_CATCH_ALL_RE.test(key);\n}\n\n/**\n * Resolve the global schema's segmentParams into a map of bracket-keyed\n * param name → resolved Codec.\n *\n * Keys are preserved exactly as written in `app/schema.ts` so that\n * `[id]`, `[...id]`, and `[[...id]]` remain distinct entries.\n * The coercion layer in `param-coercion.ts` reconstructs bracket keys\n * from matched segment metadata to look up the correct codec.\n *\n * Input:  { '[id]': z.coerce.number(), '[...slug]': codec.string }\n * Output: { '[id]': Codec<number>, '[...slug]': Codec<string> }\n */\nexport function resolveSchemaCodecs(\n  segmentParams: Record<string, unknown>\n): Record<string, Codec<unknown>> {\n  const resolved: Record<string, Codec<unknown>> = Object.create(null);\n\n  for (const [bracketName, value] of Object.entries(segmentParams)) {\n    if (isCatchAllKey(bracketName) && isCodec(value) && !('__catchAll' in value)) {\n      throw new Error(\n        `[timber] Schema error: '${bracketName}' is a catch-all segment and requires an array codec ` +\n          `(e.g. codec.catchAll(codec.string)). Got a scalar codec.`\n      );\n    }\n    if (\n      isOptionalCatchAllKey(bracketName) &&\n      isCodec(value) &&\n      '__catchAll' in value &&\n      !('__optional' in value)\n    ) {\n      throw new Error(\n        `[timber] Schema error: '${bracketName}' is an optional catch-all segment and requires codec.optionalCatchAll() ` +\n          `(e.g. codec.optionalCatchAll(codec.string)). Got a non-optional catch-all codec.`\n      );\n    }\n    resolved[bracketName] = resolveCodecOrSchema(bracketName, value, 'param');\n  }\n\n  return resolved;\n}\n"],"mappings":";;;;;;;;;;AAsBA,SAAgB,aAAa,aAAqB,WAA2B;CAC3E,QAAQ,aAAR;EACE,KAAK,aACH,OAAO,OAAO,UAAU;EAC1B,KAAK,sBACH,OAAO,QAAQ,UAAU;EAC3B,SACE,OAAO,IAAI,UAAU;CACzB;AACF;AAEA,IAAM,eAAe;AACrB,IAAM,wBAAwB;AAE9B,SAAS,cAAc,KAAsB;CAC3C,OAAO,aAAa,KAAK,GAAG,KAAK,sBAAsB,KAAK,GAAG;AACjE;AAEA,SAAS,sBAAsB,KAAsB;CACnD,OAAO,sBAAsB,KAAK,GAAG;AACvC;;;;;;;;;;;;;AAcA,SAAgB,oBACd,eACgC;CAChC,MAAM,WAA2C,OAAO,OAAO,IAAI;CAEnE,KAAK,MAAM,CAAC,aAAa,UAAU,OAAO,QAAQ,aAAa,GAAG;EAChE,IAAI,cAAc,WAAW,KAAK,QAAQ,KAAK,KAAK,EAAE,gBAAgB,QACpE,MAAM,IAAI,MACR,2BAA2B,YAAY,8GAEzC;EAEF,IACE,sBAAsB,WAAW,KACjC,QAAQ,KAAK,KACb,gBAAgB,SAChB,EAAE,gBAAgB,QAElB,MAAM,IAAI,MACR,2BAA2B,YAAY,0JAEzC;EAEF,SAAS,eAAe,qBAAqB,aAAa,OAAO,OAAO;CAC1E;CAEA,OAAO;AACT"}

package/dist/_chunks/router-ref-DuYuV_0Q.js

@@ -0,0 +1,28 @@
+import { p as globalRouter, s as _setGlobalRouter } from "./ssr-data-14MXm7Pj.js";
+//#region src/client/router-ref.ts
+/**
+* Set the global router instance. Called once during bootstrap.
+*/
+function setGlobalRouter(router) {
+	_setGlobalRouter(router);
+}
+/**
+* Get the global router instance. Throws if called before bootstrap.
+* Used by client-side hooks (usePendingNavigation, etc.)
+*/
+function getRouter() {
+	if (!globalRouter) throw new Error("[timber] Router not initialized. getRouter() was called before bootstrap().");
+	return globalRouter;
+}
+/**
+* Get the global router instance or null if not yet initialized.
+* Used by useRouter() methods to avoid silent failures — callers
+* can log a meaningful warning instead of silently no-oping.
+*/
+function getRouterOrNull() {
+	return globalRouter;
+}
+//#endregion
+export { getRouterOrNull as n, setGlobalRouter as r, getRouter as t };
+
+//# sourceMappingURL=router-ref-DuYuV_0Q.js.map

package/dist/_chunks/router-ref-DuYuV_0Q.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-ref-DuYuV_0Q.js","names":[],"sources":["../../src/client/router-ref.ts"],"sourcesContent":["// Global router reference — shared between browser-entry and client hooks.\n//\n// Delegates to client/state.ts for the actual module-level variable.\n// This ensures singleton semantics regardless of import path — all\n// callers converge on the same state.ts instance via the barrel.\n//\n// See design/18-build-system.md §\"Module Singleton Strategy\"\n\nimport type { RouterInstance } from './router-types.js';\nimport { globalRouter, _setGlobalRouter } from './state.js';\n\n/**\n * Set the global router instance. Called once during bootstrap.\n */\nexport function setGlobalRouter(router: RouterInstance): void {\n  _setGlobalRouter(router);\n}\n\n/**\n * Get the global router instance. Throws if called before bootstrap.\n * Used by client-side hooks (usePendingNavigation, etc.)\n */\nexport function getRouter(): RouterInstance {\n  if (!globalRouter) {\n    throw new Error('[timber] Router not initialized. getRouter() was called before bootstrap().');\n  }\n  return globalRouter;\n}\n\n/**\n * Get the global router instance or null if not yet initialized.\n * Used by useRouter() methods to avoid silent failures — callers\n * can log a meaningful warning instead of silently no-oping.\n */\nexport function getRouterOrNull(): RouterInstance | null {\n  return globalRouter;\n}\n\n/**\n * Reset the global router to null. Used only in tests to isolate\n * module-level state between test cases.\n * @internal\n */\nexport function resetGlobalRouter(): void {\n  _setGlobalRouter(null);\n}\n"],"mappings":";;;;;AAcA,SAAgB,gBAAgB,QAA8B;CAC5D,iBAAiB,MAAM;AACzB;;;;;AAMA,SAAgB,YAA4B;CAC1C,IAAI,CAAC,cACH,MAAM,IAAI,MAAM,6EAA6E;CAE/F,OAAO;AACT;;;;;;AAOA,SAAgB,kBAAyC;CACvD,OAAO;AACT"}