@timber-js/app 0.2.0-alpha.12 → 0.2.0-alpha.121

package/dist/_chunks/handler-store-CcwNX-gk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-store-CcwNX-gk.js","names":[],"sources":["../../src/cache/handler-store.ts"],"sourcesContent":["/**\n * Module-level cache handler singleton.\n *\n * Lazily initialized to MemoryCacheHandler on first access. The framework\n * replaces this at boot from timber.config.ts via setCacheHandler().\n *\n * This module avoids importing from ./index to prevent circular dependencies.\n */\n\n// Inline the interface to avoid circular import with index.ts\ninterface CacheHandlerLike {\n  get(key: string): Promise<{ value: unknown; stale: boolean } | null>;\n  set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void>;\n  invalidate(opts: { key?: string; tag?: string }): Promise<void>;\n}\n\nlet handler: CacheHandlerLike | null = null;\n\n/** Replace the active cache handler. Called by the framework at boot. */\nexport function setCacheHandler(h: CacheHandlerLike): void {\n  handler = h;\n}\n\n/**\n * Get the active cache handler. Creates a default MemoryCacheHandler on\n * first access if none has been set via setCacheHandler().\n */\nexport function getCacheHandler(): CacheHandlerLike {\n  if (!handler) {\n    // Inline a minimal LRU cache to avoid circular dep with index.ts.\n    // In production, the framework always calls setCacheHandler() at boot.\n    handler = createDefaultHandler();\n  }\n  return handler;\n}\n\nfunction createDefaultHandler(): CacheHandlerLike {\n  const store = new Map<string, { value: unknown; expiresAt: number; tags: string[] }>();\n  const maxEntries = 1000;\n\n  return {\n    async get(key) {\n      const entry = store.get(key);\n      if (!entry) return null;\n      store.delete(key);\n      store.set(key, entry);\n      const stale = Date.now() > entry.expiresAt;\n      return { value: entry.value, stale };\n    },\n    async set(key, value, opts) {\n      if (store.has(key)) store.delete(key);\n      while (store.size >= maxEntries) {\n        const oldest = store.keys().next().value;\n        if (oldest !== undefined) store.delete(oldest);\n        else break;\n      }\n      store.set(key, { value, expiresAt: Date.now() + opts.ttl * 1000, tags: opts.tags });\n    },\n    async invalidate(opts) {\n      if (opts.key) store.delete(opts.key);\n      if (opts.tag) {\n        for (const [key, entry] of store) {\n          if (entry.tags.includes(opts.tag)) store.delete(key);\n        }\n      }\n    },\n  };\n}\n"],"mappings":";AAgBA,IAAI,UAAmC;;AAGvC,SAAgB,gBAAgB,GAA2B;AACzD,WAAU;;;;;;AAOZ,SAAgB,kBAAoC;AAClD,KAAI,CAAC,QAGH,WAAU,sBAAsB;AAElC,QAAO;;AAGT,SAAS,uBAAyC;CAChD,MAAM,wBAAQ,IAAI,KAAoE;CACtF,MAAM,aAAa;AAEnB,QAAO;EACL,MAAM,IAAI,KAAK;GACb,MAAM,QAAQ,MAAM,IAAI,IAAI;AAC5B,OAAI,CAAC,MAAO,QAAO;AACnB,SAAM,OAAO,IAAI;AACjB,SAAM,IAAI,KAAK,MAAM;GACrB,MAAM,QAAQ,KAAK,KAAK,GAAG,MAAM;AACjC,UAAO;IAAE,OAAO,MAAM;IAAO;IAAO;;EAEtC,MAAM,IAAI,KAAK,OAAO,MAAM;AAC1B,OAAI,MAAM,IAAI,IAAI,CAAE,OAAM,OAAO,IAAI;AACrC,UAAO,MAAM,QAAQ,YAAY;IAC/B,MAAM,SAAS,MAAM,MAAM,CAAC,MAAM,CAAC;AACnC,QAAI,WAAW,KAAA,EAAW,OAAM,OAAO,OAAO;QACzC;;AAEP,SAAM,IAAI,KAAK;IAAE;IAAO,WAAW,KAAK,KAAK,GAAG,KAAK,MAAM;IAAM,MAAM,KAAK;IAAM,CAAC;;EAErF,MAAM,WAAW,MAAM;AACrB,OAAI,KAAK,IAAK,OAAM,OAAO,KAAK,IAAI;AACpC,OAAI,KAAK;SACF,MAAM,CAAC,KAAK,UAAU,MACzB,KAAI,MAAM,KAAK,SAAS,KAAK,IAAI,CAAE,OAAM,OAAO,IAAI;;;EAI3D"}

package/dist/_chunks/logger-DDmK5skc.js

@@ -0,0 +1,291 @@
+import { s as getTraceStore, v as isDebug, y as isDevMode } from "./tracing-DvKLzCFa.js";
+//#region src/server/error-formatter.ts
+/**
+* Error Formatter — rewrites SSR/RSC error messages to surface user code.
+*
+* When React or Vite throw errors during SSR, stack traces reference
+* vendored dependency paths (e.g. `.vite/deps_ssr/@vitejs_plugin-rsc_vendor_...`)
+* and mangled export names (`__vite_ssr_export_default__`). This module
+* rewrites error messages and stack traces to point at user code instead.
+*
+* Dev-only — in production, errors go through the structured logger
+* without formatting.
+*/
+/**
+* Patterns that identify internal Vite/RSC vendor paths in stack traces.
+* These are replaced with human-readable labels.
+*/
+var VENDOR_PATH_PATTERNS = [
+	{
+		pattern: /node_modules\/\.vite\/deps_ssr\/@vitejs_plugin-rsc_vendor_react-server-dom[^\s)]+/g,
+		replacement: "<react-server-dom>"
+	},
+	{
+		pattern: /node_modules\/\.vite\/deps_ssr\/@vitejs_plugin-rsc_vendor[^\s)]+/g,
+		replacement: "<rsc-vendor>"
+	},
+	{
+		pattern: /node_modules\/\.vite\/deps_ssr\/[^\s)]+/g,
+		replacement: "<vite-dep>"
+	},
+	{
+		pattern: /node_modules\/\.vite\/deps\/[^\s)]+/g,
+		replacement: "<vite-dep>"
+	}
+];
+/**
+* Patterns that identify Vite-mangled export names in error messages.
+*/
+var MANGLED_NAME_PATTERNS = [{
+	pattern: /__vite_ssr_export_default__/g,
+	replacement: "<default export>"
+}, {
+	pattern: /__vite_ssr_export_(\w+)__/g,
+	replacement: "<export $1>"
+}];
+/**
+* Rewrite an error's message and stack to replace internal Vite paths
+* and mangled names with human-readable labels.
+*/
+function formatSsrError(error) {
+	if (!(error instanceof Error)) return String(error);
+	let message = error.message;
+	let stack = error.stack ?? "";
+	for (const { pattern, replacement } of MANGLED_NAME_PATTERNS) message = message.replace(pattern, replacement);
+	for (const { pattern, replacement } of VENDOR_PATH_PATTERNS) stack = stack.replace(pattern, replacement);
+	for (const { pattern, replacement } of MANGLED_NAME_PATTERNS) stack = stack.replace(pattern, replacement);
+	const hint = extractErrorHint(error.message);
+	const parts = [];
+	parts.push(message);
+	if (hint) parts.push(`  → ${hint}`);
+	const userFrames = extractUserFrames(stack);
+	if (userFrames.length > 0) {
+		parts.push("");
+		parts.push("  User code in stack:");
+		for (const frame of userFrames) parts.push(`    ${frame}`);
+	}
+	return parts.join("\n");
+}
+/**
+* Extract a human-readable hint from common React/RSC error messages.
+*
+* React error messages contain useful information but the surrounding
+* context (vendor paths, mangled names) obscures it. This extracts the
+* actionable part as a one-line hint.
+*/
+function extractErrorHint(message) {
+	if (message.match(/Functions cannot be passed directly to Client Components/)) {
+		const propMatch = message.match(/<[^>]*?\s(\w+)=\{function/);
+		if (propMatch) return `Prop "${propMatch[1]}" is a function — mark it "use server" or call it before passing`;
+		return "A function prop was passed to a Client Component — mark it \"use server\" or call it before passing";
+	}
+	if (message.includes("Objects are not valid as a React child")) return "An object was rendered as JSX children — convert to string or extract the value";
+	const nullRefMatch = message.match(/Cannot read propert(?:y|ies) of (undefined|null) \(reading '(\w+)'\)/);
+	if (nullRefMatch) return `Accessed .${nullRefMatch[2]} on ${nullRefMatch[1]} — check that the value exists`;
+	const notFnMatch = message.match(/(\w+) is not a function/);
+	if (notFnMatch) return `"${notFnMatch[1]}" is not a function — check imports and exports`;
+	if (message.includes("Element type is invalid")) return "A component resolved to undefined/null — check default exports and import paths";
+	if (message.includes("Invalid hook call")) return "A hook was called outside of a React component render. If this is a 'use client' component, ensure the directive is at the very top of the file (before any imports) and that @vitejs/plugin-rsc is loaded correctly. Barrel re-exports from non-'use client' files do not propagate the directive.";
+	return null;
+}
+/**
+* Extract stack frames that reference user code (not node_modules,
+* not framework internals).
+*
+* Returns at most 5 frames to keep output concise.
+*/
+function extractUserFrames(stack) {
+	const lines = stack.split("\n");
+	const userFrames = [];
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (!trimmed.startsWith("at ")) continue;
+		if (trimmed.includes("node_modules") || trimmed.includes("<react-server-dom>") || trimmed.includes("<rsc-vendor>") || trimmed.includes("<vite-dep>") || trimmed.includes("node:internal")) continue;
+		userFrames.push(trimmed);
+		if (userFrames.length >= 5) break;
+	}
+	return userFrames;
+}
+//#endregion
+//#region src/server/default-logger.ts
+/**
+* DefaultLogger — human-readable stderr logging when no custom logger is configured.
+*
+* Ships as the fallback so production deployments always have error visibility,
+* even without an `instrumentation.ts` logger export. Output is one line per
+* event, designed for `fly logs`, `kubectl logs`, Cloudflare dashboard tails, etc.
+*
+* Format:
+*   [timber] ERROR  message  key=value key=value  trace_id=4bf92f35
+*   [timber] WARN   message  key=value key=value  trace_id=4bf92f35
+*   [timber] INFO   message  method=GET path=/dashboard status=200 durationMs=43  trace_id=4bf92f35
+*
+* Behavior:
+* - Suppressed entirely in dev mode (dev logging handles all output)
+* - `debug` suppressed unless TIMBER_DEBUG is set
+* - Replaced entirely when a custom logger is set via `setLogger()`
+*
+* See design/17-logging.md §"DefaultLogger"
+*/
+/**
+* Format data fields as `key=value` pairs for human-readable output.
+* - `error` key is serialized via formatSsrError for stack trace cleanup
+* - `trace_id` is truncated to 8 chars for readability (full ID in OTEL)
+* - Other values are stringified inline
+*/
+function formatDataFields(data) {
+	if (!data) return "";
+	const parts = [];
+	let traceId;
+	for (const [key, value] of Object.entries(data)) {
+		if (key === "trace_id") {
+			traceId = typeof value === "string" ? value : String(value);
+			continue;
+		}
+		if (key === "error") {
+			parts.push(`error=${formatSsrError(value)}`);
+			continue;
+		}
+		if (value === void 0 || value === null) continue;
+		parts.push(`${key}=${value}`);
+	}
+	if (traceId) parts.push(`trace_id=${traceId.slice(0, 8)}`);
+	return parts.length > 0 ? "  " + parts.join("  ") : "";
+}
+/** Pad level string to fixed width for alignment. */
+function padLevel(level) {
+	return level.padEnd(5);
+}
+function createDefaultLogger() {
+	return {
+		error(msg, data) {
+			const fields = formatDataFields(data);
+			process.stderr.write(`[timber] ${padLevel("ERROR")}  ${msg}${fields}\n`);
+		},
+		warn(msg, data) {
+			const fields = formatDataFields(data);
+			process.stderr.write(`[timber] ${padLevel("WARN")}  ${msg}${fields}\n`);
+		},
+		info(msg, data) {
+			if (isDevMode()) return;
+			if (!isDebug()) return;
+			const fields = formatDataFields(data);
+			process.stderr.write(`[timber] ${padLevel("INFO")}  ${msg}${fields}\n`);
+		},
+		debug(msg, data) {
+			if (isDevMode()) return;
+			if (!isDebug()) return;
+			const fields = formatDataFields(data);
+			process.stderr.write(`[timber] ${padLevel("DEBUG")}  ${msg}${fields}\n`);
+		}
+	};
+}
+//#endregion
+//#region src/server/logger.ts
+/**
+* Logger — structured logging with environment-aware formatting.
+*
+* timber.js ships a DefaultLogger that writes human-readable lines to stderr
+* in production. Users can export a custom logger from instrumentation.ts to
+* replace it with pino, winston, or any TimberLogger-compatible object.
+*
+* See design/17-logging.md §"Production Logging"
+*/
+var _logger = createDefaultLogger();
+/**
+* Set the user-provided logger. Called by the instrumentation loader
+* when it finds a `logger` export in instrumentation.ts. Replaces
+* the DefaultLogger entirely.
+*/
+function setLogger(logger) {
+	_logger = logger;
+}
+/**
+* Get the current logger. Always non-null — returns DefaultLogger when
+* no custom logger is configured.
+*/
+function getLogger() {
+	return _logger;
+}
+/**
+* Inject trace_id and span_id into log data for log–trace correlation.
+* Always injects trace_id (never undefined). Injects span_id only when OTEL is active.
+*/
+function withTraceContext(data) {
+	const store = getTraceStore();
+	const enriched = { ...data };
+	if (store) {
+		enriched.trace_id = store.traceId;
+		if (store.spanId) enriched.span_id = store.spanId;
+	}
+	return enriched;
+}
+/** Log a completed request. Level: info. */
+function logRequestCompleted(data) {
+	_logger.info("request completed", withTraceContext(data));
+}
+/** Log request received. Level: debug. */
+function logRequestReceived(data) {
+	_logger.debug("request received", withTraceContext(data));
+}
+/** Log a slow request warning. Level: warn. */
+function logSlowRequest(data) {
+	_logger.warn("slow request exceeded threshold", withTraceContext(data));
+}
+/** Log middleware short-circuit. Level: debug. */
+function logMiddlewareShortCircuit(data) {
+	_logger.debug("middleware short-circuited", withTraceContext(data));
+}
+/** Log unhandled error in middleware phase. Level: error. */
+function logMiddlewareError(data) {
+	_logger.error("unhandled error in middleware phase", withTraceContext(data));
+}
+/** Log unhandled render-phase error. Level: error. */
+function logRenderError(data) {
+	_logger.error("unhandled render-phase error", withTraceContext(data));
+}
+/** Log proxy.ts uncaught error. Level: error. */
+function logProxyError(data) {
+	_logger.error("proxy.ts threw uncaught error", withTraceContext(data));
+}
+/** Log unhandled error in route handler. Level: error. */
+function logRouteError(data) {
+	_logger.error("unhandled route handler error", withTraceContext(data));
+}
+/** Log waitUntil() adapter missing (once at startup). Level: warn. */
+function logWaitUntilUnsupported() {
+	_logger.warn("adapter does not support waitUntil()");
+}
+/** Log waitUntil() promise rejection. Level: warn. */
+function logWaitUntilRejected(data) {
+	_logger.warn("waitUntil() promise rejected", withTraceContext(data));
+}
+/** Log staleWhileRevalidate refetch failure. Level: warn. */
+function logSwrRefetchFailed(data) {
+	_logger.warn("staleWhileRevalidate refetch failed", withTraceContext(data));
+}
+/** Log cache miss. Level: debug. */
+function logCacheMiss(data) {
+	_logger.debug("timber.cache MISS", withTraceContext(data));
+}
+/**
+* Log an intentionally swallowed error. Provides observability into catch
+* blocks that are deliberately empty — the error is consumed, never rethrown.
+*
+* Default level: `warn` in dev (so the overlay surfaces patterns), `debug`
+* in production (low noise unless TIMBER_DEBUG is set). Pass `opts.level`
+* to override.
+*
+* **Infallible** — swallow() itself never throws, even if the logger is
+* broken. A thrown swallow would turn a benign catch into a crash.
+*/
+function swallow(err, reason, opts) {
+	try {
+		const level = opts?.level ?? (isDevMode() ? "warn" : "debug");
+		_logger[level](`swallowed: ${reason}`, withTraceContext({ error: err }));
+	} catch {}
+}
+//#endregion
+export { logProxyError as a, logRequestReceived as c, logSwrRefetchFailed as d, logWaitUntilRejected as f, swallow as h, logMiddlewareShortCircuit as i, logRouteError as l, setLogger as m, logCacheMiss as n, logRenderError as o, logWaitUntilUnsupported as p, logMiddlewareError as r, logRequestCompleted as s, getLogger as t, logSlowRequest as u };
+
+//# sourceMappingURL=logger-DDmK5skc.js.map

package/dist/_chunks/logger-DDmK5skc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger-DDmK5skc.js","names":[],"sources":["../../src/server/error-formatter.ts","../../src/server/default-logger.ts","../../src/server/logger.ts"],"sourcesContent":["/**\n * Error Formatter — rewrites SSR/RSC error messages to surface user code.\n *\n * When React or Vite throw errors during SSR, stack traces reference\n * vendored dependency paths (e.g. `.vite/deps_ssr/@vitejs_plugin-rsc_vendor_...`)\n * and mangled export names (`__vite_ssr_export_default__`). This module\n * rewrites error messages and stack traces to point at user code instead.\n *\n * Dev-only — in production, errors go through the structured logger\n * without formatting.\n */\n\n// ─── Stack Trace Rewriting ──────────────────────────────────────────────────\n\n/**\n * Patterns that identify internal Vite/RSC vendor paths in stack traces.\n * These are replaced with human-readable labels.\n */\nconst VENDOR_PATH_PATTERNS: Array<{ pattern: RegExp; replacement: string }> = [\n  {\n    pattern: /node_modules\\/\\.vite\\/deps_ssr\\/@vitejs_plugin-rsc_vendor_react-server-dom[^\\s)]+/g,\n    replacement: '<react-server-dom>',\n  },\n  {\n    pattern: /node_modules\\/\\.vite\\/deps_ssr\\/@vitejs_plugin-rsc_vendor[^\\s)]+/g,\n    replacement: '<rsc-vendor>',\n  },\n  {\n    pattern: /node_modules\\/\\.vite\\/deps_ssr\\/[^\\s)]+/g,\n    replacement: '<vite-dep>',\n  },\n  {\n    pattern: /node_modules\\/\\.vite\\/deps\\/[^\\s)]+/g,\n    replacement: '<vite-dep>',\n  },\n];\n\n/**\n * Patterns that identify Vite-mangled export names in error messages.\n */\nconst MANGLED_NAME_PATTERNS: Array<{ pattern: RegExp; replacement: string }> = [\n  {\n    pattern: /__vite_ssr_export_default__/g,\n    replacement: '<default export>',\n  },\n  {\n    pattern: /__vite_ssr_export_(\\w+)__/g,\n    replacement: '<export $1>',\n  },\n];\n\n/**\n * Rewrite an error's message and stack to replace internal Vite paths\n * and mangled names with human-readable labels.\n */\nexport function formatSsrError(error: unknown): string {\n  if (!(error instanceof Error)) {\n    return String(error);\n  }\n\n  let message = error.message;\n  let stack = error.stack ?? '';\n\n  // Rewrite mangled names in the message\n  for (const { pattern, replacement } of MANGLED_NAME_PATTERNS) {\n    message = message.replace(pattern, replacement);\n  }\n\n  // Rewrite vendor paths in the stack\n  for (const { pattern, replacement } of VENDOR_PATH_PATTERNS) {\n    stack = stack.replace(pattern, replacement);\n  }\n\n  // Rewrite mangled names in the stack too\n  for (const { pattern, replacement } of MANGLED_NAME_PATTERNS) {\n    stack = stack.replace(pattern, replacement);\n  }\n\n  // Extract hints from React-specific error patterns\n  const hint = extractErrorHint(error.message);\n\n  // Build formatted output: cleaned message, hint (if any), then cleaned stack\n  const parts: string[] = [];\n  parts.push(message);\n  if (hint) {\n    parts.push(`  → ${hint}`);\n  }\n\n  // Include only the user-code frames from the stack (skip the first line\n  // which is the message itself, and filter out vendor-only frames)\n  const userFrames = extractUserFrames(stack);\n  if (userFrames.length > 0) {\n    parts.push('');\n    parts.push('  User code in stack:');\n    for (const frame of userFrames) {\n      parts.push(`    ${frame}`);\n    }\n  }\n\n  return parts.join('\\n');\n}\n\n// ─── Error Hint Extraction ──────────────────────────────────────────────────\n\n/**\n * Extract a human-readable hint from common React/RSC error messages.\n *\n * React error messages contain useful information but the surrounding\n * context (vendor paths, mangled names) obscures it. This extracts the\n * actionable part as a one-line hint.\n */\nfunction extractErrorHint(message: string): string | null {\n  // \"Functions cannot be passed directly to Client Components\"\n  // Extract the component and prop name from the JSX-like syntax in the message\n  const fnPassedMatch = message.match(/Functions cannot be passed directly to Client Components/);\n  if (fnPassedMatch) {\n    // Try to extract the prop name from the message\n    // React formats: <... propName={function ...} ...>\n    const propMatch = message.match(/<[^>]*?\\s(\\w+)=\\{function/);\n    if (propMatch) {\n      return `Prop \"${propMatch[1]}\" is a function — mark it \"use server\" or call it before passing`;\n    }\n    return 'A function prop was passed to a Client Component — mark it \"use server\" or call it before passing';\n  }\n\n  // \"Objects are not valid as a React child\"\n  if (message.includes('Objects are not valid as a React child')) {\n    return 'An object was rendered as JSX children — convert to string or extract the value';\n  }\n\n  // \"Cannot read properties of undefined/null\"\n  const nullRefMatch = message.match(\n    /Cannot read propert(?:y|ies) of (undefined|null) \\(reading '(\\w+)'\\)/\n  );\n  if (nullRefMatch) {\n    return `Accessed .${nullRefMatch[2]} on ${nullRefMatch[1]} — check that the value exists`;\n  }\n\n  // \"X is not a function\"\n  const notFnMatch = message.match(/(\\w+) is not a function/);\n  if (notFnMatch) {\n    return `\"${notFnMatch[1]}\" is not a function — check imports and exports`;\n  }\n\n  // \"Element type is invalid\"\n  if (message.includes('Element type is invalid')) {\n    return 'A component resolved to undefined/null — check default exports and import paths';\n  }\n\n  // \"Invalid hook call\" — hooks called outside React's render context.\n  // In RSC, this typically means a 'use client' component was executed as a\n  // server component instead of being serialized as a client reference.\n  if (message.includes('Invalid hook call')) {\n    return (\n      'A hook was called outside of a React component render. ' +\n      \"If this is a 'use client' component, ensure the directive is at the very top of the file \" +\n      '(before any imports) and that @vitejs/plugin-rsc is loaded correctly. ' +\n      \"Barrel re-exports from non-'use client' files do not propagate the directive.\"\n    );\n  }\n\n  return null;\n}\n\n// ─── Stack Frame Filtering ──────────────────────────────────────────────────\n\n/**\n * Extract stack frames that reference user code (not node_modules,\n * not framework internals).\n *\n * Returns at most 5 frames to keep output concise.\n */\nfunction extractUserFrames(stack: string): string[] {\n  const lines = stack.split('\\n');\n  const userFrames: string[] = [];\n\n  for (const line of lines) {\n    const trimmed = line.trim();\n    // Skip non-frame lines\n    if (!trimmed.startsWith('at ')) continue;\n    // Skip node_modules, vendor, and internal frames\n    if (\n      trimmed.includes('node_modules') ||\n      trimmed.includes('<react-server-dom>') ||\n      trimmed.includes('<rsc-vendor>') ||\n      trimmed.includes('<vite-dep>') ||\n      trimmed.includes('node:internal')\n    ) {\n      continue;\n    }\n    userFrames.push(trimmed);\n    if (userFrames.length >= 5) break;\n  }\n\n  return userFrames;\n}\n","/**\n * DefaultLogger — human-readable stderr logging when no custom logger is configured.\n *\n * Ships as the fallback so production deployments always have error visibility,\n * even without an `instrumentation.ts` logger export. Output is one line per\n * event, designed for `fly logs`, `kubectl logs`, Cloudflare dashboard tails, etc.\n *\n * Format:\n *   [timber] ERROR  message  key=value key=value  trace_id=4bf92f35\n *   [timber] WARN   message  key=value key=value  trace_id=4bf92f35\n *   [timber] INFO   message  method=GET path=/dashboard status=200 durationMs=43  trace_id=4bf92f35\n *\n * Behavior:\n * - Suppressed entirely in dev mode (dev logging handles all output)\n * - `debug` suppressed unless TIMBER_DEBUG is set\n * - Replaced entirely when a custom logger is set via `setLogger()`\n *\n * See design/17-logging.md §\"DefaultLogger\"\n */\n\nimport { isDevMode, isDebug } from './debug.js';\nimport { formatSsrError } from './error-formatter.js';\nimport type { TimberLogger } from './logger.js';\n\n/**\n * Format data fields as `key=value` pairs for human-readable output.\n * - `error` key is serialized via formatSsrError for stack trace cleanup\n * - `trace_id` is truncated to 8 chars for readability (full ID in OTEL)\n * - Other values are stringified inline\n */\nfunction formatDataFields(data?: Record<string, unknown>): string {\n  if (!data) return '';\n\n  const parts: string[] = [];\n  let traceId: string | undefined;\n\n  for (const [key, value] of Object.entries(data)) {\n    if (key === 'trace_id') {\n      // Defer trace_id to the end\n      traceId = typeof value === 'string' ? value : String(value);\n      continue;\n    }\n    if (key === 'error') {\n      // Serialize errors with formatSsrError for clean output\n      parts.push(`error=${formatSsrError(value)}`);\n      continue;\n    }\n    if (value === undefined || value === null) continue;\n    parts.push(`${key}=${value}`);\n  }\n\n  // trace_id always last, truncated to 8 chars for readability\n  if (traceId) {\n    parts.push(`trace_id=${traceId.slice(0, 8)}`);\n  }\n\n  return parts.length > 0 ? '  ' + parts.join('  ') : '';\n}\n\n/** Pad level string to fixed width for alignment. */\nfunction padLevel(level: string): string {\n  return level.padEnd(5);\n}\n\nexport function createDefaultLogger(): TimberLogger {\n  return {\n    error(msg: string, data?: Record<string, unknown>): void {\n      // Errors are ALWAYS logged, including dev mode. Suppressing errors\n      // in dev causes silent 500s with no stack trace, making route.ts\n      // and render errors impossible to debug. See TIM-555.\n      const fields = formatDataFields(data);\n      process.stderr.write(`[timber] ${padLevel('ERROR')}  ${msg}${fields}\\n`);\n    },\n\n    warn(msg: string, data?: Record<string, unknown>): void {\n      // Warnings are always logged — same rationale as errors.\n      const fields = formatDataFields(data);\n      process.stderr.write(`[timber] ${padLevel('WARN')}  ${msg}${fields}\\n`);\n    },\n\n    info(msg: string, data?: Record<string, unknown>): void {\n      // info is suppressed by default — per-request lines are too noisy\n      // without a custom logger. Enable with TIMBER_DEBUG.\n      if (isDevMode()) return;\n      if (!isDebug()) return;\n      const fields = formatDataFields(data);\n      process.stderr.write(`[timber] ${padLevel('INFO')}  ${msg}${fields}\\n`);\n    },\n\n    debug(msg: string, data?: Record<string, unknown>): void {\n      // debug is suppressed in dev (dev logger handles it) and in\n      // production unless TIMBER_DEBUG is explicitly set.\n      if (isDevMode()) return;\n      if (!isDebug()) return;\n      const fields = formatDataFields(data);\n      process.stderr.write(`[timber] ${padLevel('DEBUG')}  ${msg}${fields}\\n`);\n    },\n  };\n}\n","/**\n * Logger — structured logging with environment-aware formatting.\n *\n * timber.js ships a DefaultLogger that writes human-readable lines to stderr\n * in production. Users can export a custom logger from instrumentation.ts to\n * replace it with pino, winston, or any TimberLogger-compatible object.\n *\n * See design/17-logging.md §\"Production Logging\"\n */\n\nimport { getTraceStore } from './tracing.js';\nimport { createDefaultLogger } from './default-logger.js';\nimport { isDevMode } from './debug.js';\n\n// ─── Logger Interface ─────────────────────────────────────────────────────\n\n/** Any object with standard log methods satisfies this — pino, winston, consola, console. */\nexport interface TimberLogger {\n  info(msg: string, data?: Record<string, unknown>): void;\n  warn(msg: string, data?: Record<string, unknown>): void;\n  error(msg: string, data?: Record<string, unknown>): void;\n  debug(msg: string, data?: Record<string, unknown>): void;\n}\n\n// ─── Logger Registry ──────────────────────────────────────────────────────\n\n// Initialize with DefaultLogger so production errors are never silent.\n// Replaced when setLogger() is called from instrumentation.ts.\nlet _logger: TimberLogger = createDefaultLogger();\n\n/**\n * Set the user-provided logger. Called by the instrumentation loader\n * when it finds a `logger` export in instrumentation.ts. Replaces\n * the DefaultLogger entirely.\n */\nexport function setLogger(logger: TimberLogger): void {\n  _logger = logger;\n}\n\n/**\n * Get the current logger. Always non-null — returns DefaultLogger when\n * no custom logger is configured.\n */\nexport function getLogger(): TimberLogger {\n  return _logger;\n}\n\n// ─── Framework Log Helpers ────────────────────────────────────────────────\n\n/**\n * Inject trace_id and span_id into log data for log–trace correlation.\n * Always injects trace_id (never undefined). Injects span_id only when OTEL is active.\n */\nfunction withTraceContext(data?: Record<string, unknown>): Record<string, unknown> {\n  const store = getTraceStore();\n  const enriched: Record<string, unknown> = { ...data };\n  if (store) {\n    enriched.trace_id = store.traceId;\n    if (store.spanId) {\n      enriched.span_id = store.spanId;\n    }\n  }\n  return enriched;\n}\n\n// ─── Framework Event Emitters ─────────────────────────────────────────────\n\n/** Log a completed request. Level: info. */\nexport function logRequestCompleted(data: {\n  method: string;\n  path: string;\n  status: number;\n  durationMs: number;\n  /** Number of concurrent in-flight requests (including this one) at completion time. */\n  concurrency?: number;\n}): void {\n  _logger.info('request completed', withTraceContext(data));\n}\n\n/** Log request received. Level: debug. */\nexport function logRequestReceived(data: { method: string; path: string }): void {\n  _logger.debug('request received', withTraceContext(data));\n}\n\n/** Log a slow request warning. Level: warn. */\nexport function logSlowRequest(data: {\n  method: string;\n  path: string;\n  durationMs: number;\n  threshold: number;\n  /** Number of concurrent in-flight requests at the time the slow request completed. */\n  concurrency?: number;\n}): void {\n  _logger.warn('slow request exceeded threshold', withTraceContext(data));\n}\n\n/** Log middleware short-circuit. Level: debug. */\nexport function logMiddlewareShortCircuit(data: {\n  method: string;\n  path: string;\n  status: number;\n}): void {\n  _logger.debug('middleware short-circuited', withTraceContext(data));\n}\n\n/** Log unhandled error in middleware phase. Level: error. */\nexport function logMiddlewareError(data: { method: string; path: string; error: unknown }): void {\n  _logger.error('unhandled error in middleware phase', withTraceContext(data));\n}\n\n/** Log unhandled render-phase error. Level: error. */\nexport function logRenderError(data: {\n  method: string;\n  path: string;\n  error: unknown;\n  errorId?: string;\n}): void {\n  _logger.error('unhandled render-phase error', withTraceContext(data));\n}\n\n/** Log proxy.ts uncaught error. Level: error. */\nexport function logProxyError(data: { error: unknown }): void {\n  _logger.error('proxy.ts threw uncaught error', withTraceContext(data));\n}\n\n/** Log unhandled error in server action. Level: error. */\nexport function logActionError(data: { method: string; path: string; error: unknown }): void {\n  _logger.error('unhandled server action error', withTraceContext(data));\n}\n\n/** Log unhandled error in route handler. Level: error. */\nexport function logRouteError(data: { method: string; path: string; error: unknown }): void {\n  _logger.error('unhandled route handler error', withTraceContext(data));\n}\n\n/** Log SSR streaming error (post-shell). Level: error. */\nexport function logStreamingError(data: { error: unknown }): void {\n  _logger.error('SSR streaming error (post-shell)', withTraceContext(data));\n}\n\n/** Log waitUntil() adapter missing (once at startup). Level: warn. */\nexport function logWaitUntilUnsupported(): void {\n  _logger.warn('adapter does not support waitUntil()');\n}\n\n/** Log waitUntil() promise rejection. Level: warn. */\nexport function logWaitUntilRejected(data: { error: unknown }): void {\n  _logger.warn('waitUntil() promise rejected', withTraceContext(data));\n}\n\n/** Log staleWhileRevalidate refetch failure. Level: warn. */\nexport function logSwrRefetchFailed(data: { cacheKey: string; error: unknown }): void {\n  _logger.warn('staleWhileRevalidate refetch failed', withTraceContext(data));\n}\n\n/** Log cache miss. Level: debug. */\nexport function logCacheMiss(data: { cacheKey: string }): void {\n  _logger.debug('timber.cache MISS', withTraceContext(data));\n}\n\n// ─── Swallow Helper ───────────────────────────────────────────────────────\n\n/**\n * Log an intentionally swallowed error. Provides observability into catch\n * blocks that are deliberately empty — the error is consumed, never rethrown.\n *\n * Default level: `warn` in dev (so the overlay surfaces patterns), `debug`\n * in production (low noise unless TIMBER_DEBUG is set). Pass `opts.level`\n * to override.\n *\n * **Infallible** — swallow() itself never throws, even if the logger is\n * broken. A thrown swallow would turn a benign catch into a crash.\n */\nexport function swallow(err: unknown, reason: string, opts?: { level?: 'debug' | 'warn' }): void {\n  try {\n    const level = opts?.level ?? (isDevMode() ? 'warn' : 'debug');\n    _logger[level](`swallowed: ${reason}`, withTraceContext({ error: err }));\n  } catch {\n    // swallow() must never throw.\n  }\n}\n"],"mappings":"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"}

package/dist/_chunks/merge-search-params-az6ZiBeU.js

@@ -0,0 +1,41 @@
+//#region src/shared/merge-search-params.ts
+/**
+* Shared utility for merging preserved search params into a target URL.
+*
+* Used by both <Link> (client) and redirect() (server). Extracted to a shared
+* module to avoid importing client code ('use client') from server modules.
+*/
+/**
+* Merge preserved search params from the current URL into a target href.
+*
+* When `preserve` is `true`, all current search params are merged.
+* When `preserve` is a `string[]`, only the named params are merged.
+*
+* The target href's own search params take precedence — preserved params
+* are only added if the target doesn't already define them.
+*
+* @param targetHref - The resolved target href (may already contain query string)
+* @param currentSearch - The current URL's search string (e.g. "?private=access&page=2")
+* @param preserve - `true` to preserve all, or `string[]` to preserve specific params
+* @returns The target href with preserved search params merged in
+*/
+function mergePreservedSearchParams(targetHref, currentSearch, preserve) {
+	const currentParams = new URLSearchParams(currentSearch);
+	if (currentParams.size === 0) return targetHref;
+	const hashIdx = targetHref.indexOf("#");
+	const hrefWithoutHash = hashIdx >= 0 ? targetHref.slice(0, hashIdx) : targetHref;
+	const hash = hashIdx >= 0 ? targetHref.slice(hashIdx) : "";
+	const qIdx = hrefWithoutHash.indexOf("?");
+	const targetPath = qIdx >= 0 ? hrefWithoutHash.slice(0, qIdx) : hrefWithoutHash;
+	const targetParams = new URLSearchParams(qIdx >= 0 ? hrefWithoutHash.slice(qIdx + 1) : "");
+	const merged = new URLSearchParams(targetParams);
+	for (const [key, value] of currentParams) if (!targetParams.has(key)) {
+		if (preserve === true || preserve.includes(key)) merged.append(key, value);
+	}
+	const qs = merged.toString();
+	return (qs ? `${targetPath}?${qs}` : targetPath) + hash;
+}
+//#endregion
+export { mergePreservedSearchParams as t };
+
+//# sourceMappingURL=merge-search-params-az6ZiBeU.js.map

package/dist/_chunks/merge-search-params-az6ZiBeU.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-search-params-az6ZiBeU.js","names":[],"sources":["../../src/shared/merge-search-params.ts"],"sourcesContent":["/**\n * Shared utility for merging preserved search params into a target URL.\n *\n * Used by both <Link> (client) and redirect() (server). Extracted to a shared\n * module to avoid importing client code ('use client') from server modules.\n */\n\n/**\n * Merge preserved search params from the current URL into a target href.\n *\n * When `preserve` is `true`, all current search params are merged.\n * When `preserve` is a `string[]`, only the named params are merged.\n *\n * The target href's own search params take precedence — preserved params\n * are only added if the target doesn't already define them.\n *\n * @param targetHref - The resolved target href (may already contain query string)\n * @param currentSearch - The current URL's search string (e.g. \"?private=access&page=2\")\n * @param preserve - `true` to preserve all, or `string[]` to preserve specific params\n * @returns The target href with preserved search params merged in\n */\nexport function mergePreservedSearchParams(\n  targetHref: string,\n  currentSearch: string,\n  preserve: true | string[]\n): string {\n  const currentParams = new URLSearchParams(currentSearch);\n  if (currentParams.size === 0) return targetHref;\n\n  // Split hash fragment from target before processing query params.\n  // Hash must come after query string: /path?query=value#hash\n  const hashIdx = targetHref.indexOf('#');\n  const hrefWithoutHash = hashIdx >= 0 ? targetHref.slice(0, hashIdx) : targetHref;\n  const hash = hashIdx >= 0 ? targetHref.slice(hashIdx) : '';\n\n  // Split target into path and existing query\n  const qIdx = hrefWithoutHash.indexOf('?');\n  const targetPath = qIdx >= 0 ? hrefWithoutHash.slice(0, qIdx) : hrefWithoutHash;\n  const targetParams = new URLSearchParams(qIdx >= 0 ? hrefWithoutHash.slice(qIdx + 1) : '');\n\n  // Collect params to preserve (that aren't already in the target)\n  const merged = new URLSearchParams(targetParams);\n  for (const [key, value] of currentParams) {\n    // Only preserve if: (a) not already in target, and (b) included in preserve list\n    if (!targetParams.has(key)) {\n      if (preserve === true || preserve.includes(key)) {\n        merged.append(key, value);\n      }\n    }\n  }\n\n  const qs = merged.toString();\n  const pathWithQuery = qs ? `${targetPath}?${qs}` : targetPath;\n  return pathWithQuery + hash;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,2BACd,YACA,eACA,UACQ;CACR,MAAM,gBAAgB,IAAI,gBAAgB,cAAc;AACxD,KAAI,cAAc,SAAS,EAAG,QAAO;CAIrC,MAAM,UAAU,WAAW,QAAQ,IAAI;CACvC,MAAM,kBAAkB,WAAW,IAAI,WAAW,MAAM,GAAG,QAAQ,GAAG;CACtE,MAAM,OAAO,WAAW,IAAI,WAAW,MAAM,QAAQ,GAAG;CAGxD,MAAM,OAAO,gBAAgB,QAAQ,IAAI;CACzC,MAAM,aAAa,QAAQ,IAAI,gBAAgB,MAAM,GAAG,KAAK,GAAG;CAChE,MAAM,eAAe,IAAI,gBAAgB,QAAQ,IAAI,gBAAgB,MAAM,OAAO,EAAE,GAAG,GAAG;CAG1F,MAAM,SAAS,IAAI,gBAAgB,aAAa;AAChD,MAAK,MAAM,CAAC,KAAK,UAAU,cAEzB,KAAI,CAAC,aAAa,IAAI,IAAI;MACpB,aAAa,QAAQ,SAAS,SAAS,IAAI,CAC7C,QAAO,OAAO,KAAK,MAAM;;CAK/B,MAAM,KAAK,OAAO,UAAU;AAE5B,SADsB,KAAK,GAAG,WAAW,GAAG,OAAO,cAC5B"}

package/dist/_chunks/navigation-root-DoRTeBm5.js

@@ -0,0 +1,96 @@
+import "./use-segment-params-CtIAjqK0.js";
+import "react";
+//#region src/client/link-pending-store.ts
+var LINK_PENDING_KEY = Symbol.for("__timber_link_pending");
+/** Status object: link idle */
+var LINK_IDLE = { isPending: false };
+function getStore() {
+	const g = globalThis;
+	if (!g[LINK_PENDING_KEY]) g[LINK_PENDING_KEY] = { current: null };
+	return g[LINK_PENDING_KEY];
+}
+/**
+* Register the link instance that initiated the current navigation.
+* Called from Link's click handler. Does NOT call setIsPending —
+* that happens inside NavigationRoot's startTransition via
+* activateLinkPending().
+*
+* Resets the previous link to idle immediately (the old link's
+* useOptimistic reverts since its transition already settled).
+*/
+function setLinkForCurrentNavigation(link) {
+	const store = getStore();
+	store.current = link;
+}
+/**
+* Unmount a link instance from navigation tracking.
+*/
+function unmountLinkForCurrentNavigation(link) {
+	const store = getStore();
+	if (store.current === link) store.current = null;
+}
+//#endregion
+//#region src/client/top-loader.tsx
+/**
+* TopLoader — Built-in progress bar for client navigations.
+*
+* Shows an animated progress bar at the top of the viewport while an RSC
+* navigation is in flight. Injected automatically by the framework into
+* NavigationRoot — users never render this component directly.
+*
+* Configuration is via timber.config.ts `topLoader` key. Enabled by default.
+* Users who want a fully custom progress indicator disable the built-in one
+* (`topLoader: { enabled: false }`) and use `usePendingNavigation()` directly.
+*
+* Animation approach: pure CSS @keyframes. The bar crawls from 0% to ~90%
+* width over ~30s using ease-out timing. When navigation completes, the bar
+* snaps to 100% and fades out over 200ms. No JS animation loops (RAF, setInterval).
+*
+* Phase transitions are derived synchronously during render (React's
+* getDerivedStateFromProps pattern) — no useEffect needed for state tracking.
+* The finishing → hidden cleanup uses onTransitionEnd from the CSS transition.
+*
+* When delay > 0, CSS animation-delay + a visibility keyframe ensure the bar
+* stays invisible during the delay period. If navigation finishes before the
+* delay, the bar was never visible so the finish transition is also invisible.
+*
+* See design/19-client-navigation.md §"usePendingNavigation()"
+* See LOCAL-336 for design decisions.
+*/
+//#endregion
+//#region src/client/navigation-root.tsx
+/**
+* Module-level flag indicating a hard (MPA) navigation is in progress.
+*
+* When true:
+* - NavigationRoot throws an unresolved thenable to suspend forever,
+*   preventing React from rendering children during page teardown
+*   (avoids "Rendered more hooks" crashes).
+* - The Navigation API handler skips interception, letting the browser
+*   perform a full page load (prevents infinite loops where
+*   window.location.href → navigate event → router.navigate → 500 →
+*   window.location.href → ...).
+*
+* Uses globalThis for singleton guarantee across chunks (same pattern
+* as NavigationContext). See design/19-client-navigation.md §"Singleton
+* Guarantee via globalThis".
+*/
+var HARD_NAV_KEY = Symbol.for("__timber_hard_navigating");
+function getHardNavStore() {
+	const g = globalThis;
+	if (!g[HARD_NAV_KEY]) g[HARD_NAV_KEY] = { value: false };
+	return g[HARD_NAV_KEY];
+}
+/**
+* Set the hard-navigating flag. Call this BEFORE setting
+* window.location.href or window.location.reload() to prevent:
+* 1. React from rendering children during page teardown
+* 2. Navigation API from intercepting the hard navigation
+*/
+function setHardNavigating(value) {
+	getHardNavStore().value = value;
+}
+//#endregion
+export { unmountLinkForCurrentNavigation as i, LINK_IDLE as n, setLinkForCurrentNavigation as r, setHardNavigating as t };
+
+//# sourceMappingURL=navigation-root-DoRTeBm5.js.map

package/dist/_chunks/navigation-root-DoRTeBm5.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-root-DoRTeBm5.js","names":[],"sources":["../../src/client/link-pending-store.ts","../../src/client/top-loader.tsx","../../src/client/navigation-root.tsx"],"sourcesContent":["/**\n * Link Pending Store — per-link optimistic pending state.\n *\n * Tracks which link instance is currently navigating so that only the\n * clicked link shows pending. Uses `useOptimistic` from React 19 —\n * the optimistic value (isPending=true) is set inside NavigationRoot's\n * async startTransition so it persists for the duration of the RSC\n * fetch, then auto-reverts to idle when the transition settles.\n *\n * Flow:\n * 1. Link click → setLinkForCurrentNavigation(instance) stores the ref\n * 2. NavigationRoot startTransition → activateLinkPending() calls\n *    instance.setIsPending(LINK_PENDING) inside the async transition\n * 3. Transition settles → useOptimistic auto-reverts to LINK_IDLE\n *\n * SINGLETON GUARANTEE: Uses `globalThis` via `Symbol.for` keys because\n * the RSC client bundler can duplicate this module across chunks.\n *\n * See design/19-client-navigation.md §\"Per-Link Pending State\"\n */\n\nimport type { LinkStatus } from './use-link-status.js';\n\n// ─── Types ───────────────────────────────────────────────────────\n\nexport interface LinkPendingInstance {\n  setIsPending: (status: LinkStatus) => void;\n}\n\n// ─── Constants ───────────────────────────────────────────────────\n\nconst LINK_PENDING_KEY = Symbol.for('__timber_link_pending');\n\n/** Status object: link navigation in flight */\nexport const LINK_PENDING: LinkStatus = { isPending: true };\n\n/** Status object: link idle */\nexport const LINK_IDLE: LinkStatus = { isPending: false };\n\n// ─── Singleton Storage ───────────────────────────────────────────\n\nfunction getStore(): { current: LinkPendingInstance | null } {\n  const g = globalThis as Record<symbol, unknown>;\n  if (!g[LINK_PENDING_KEY]) {\n    g[LINK_PENDING_KEY] = { current: null };\n  }\n  return g[LINK_PENDING_KEY] as { current: LinkPendingInstance | null };\n}\n\n// ─── Public API ──────────────────────────────────────────────────\n\n/**\n * Register the link instance that initiated the current navigation.\n * Called from Link's click handler. Does NOT call setIsPending —\n * that happens inside NavigationRoot's startTransition via\n * activateLinkPending().\n *\n * Resets the previous link to idle immediately (the old link's\n * useOptimistic reverts since its transition already settled).\n */\nexport function setLinkForCurrentNavigation(link: LinkPendingInstance | null): void {\n  const store = getStore();\n  store.current = link;\n}\n\n/**\n * Activate pending state on the current link instance.\n * MUST be called inside NavigationRoot's async startTransition —\n * this is what makes useOptimistic persist for the navigation duration.\n */\nexport function activateLinkPending(): void {\n  const store = getStore();\n  store.current?.setIsPending(LINK_PENDING);\n}\n\n/**\n * Reset the current link's pending state. With useOptimistic this is\n * handled automatically when the transition settles. Kept for callers\n * that explicitly need to clear on error paths.\n */\nexport function resetLinkPending(): void {\n  const store = getStore();\n  if (store.current) {\n    store.current.setIsPending(LINK_IDLE);\n    store.current = null;\n  }\n}\n\n/**\n * @deprecated No longer needed with useOptimistic. Kept for callers.\n */\nexport function getCurrentNavId(): number {\n  return 0;\n}\n\n/**\n * Clean up the link pending store entirely.\n */\nexport function clearLinkPendingSetter(): void {\n  getStore().current = null;\n}\n\n/**\n * Unmount a link instance from navigation tracking.\n */\nexport function unmountLinkForCurrentNavigation(link: LinkPendingInstance): void {\n  const store = getStore();\n  if (store.current === link) {\n    store.current = null;\n  }\n}\n","/**\n * TopLoader — Built-in progress bar for client navigations.\n *\n * Shows an animated progress bar at the top of the viewport while an RSC\n * navigation is in flight. Injected automatically by the framework into\n * NavigationRoot — users never render this component directly.\n *\n * Configuration is via timber.config.ts `topLoader` key. Enabled by default.\n * Users who want a fully custom progress indicator disable the built-in one\n * (`topLoader: { enabled: false }`) and use `usePendingNavigation()` directly.\n *\n * Animation approach: pure CSS @keyframes. The bar crawls from 0% to ~90%\n * width over ~30s using ease-out timing. When navigation completes, the bar\n * snaps to 100% and fades out over 200ms. No JS animation loops (RAF, setInterval).\n *\n * Phase transitions are derived synchronously during render (React's\n * getDerivedStateFromProps pattern) — no useEffect needed for state tracking.\n * The finishing → hidden cleanup uses onTransitionEnd from the CSS transition.\n *\n * When delay > 0, CSS animation-delay + a visibility keyframe ensure the bar\n * stays invisible during the delay period. If navigation finishes before the\n * delay, the bar was never visible so the finish transition is also invisible.\n *\n * See design/19-client-navigation.md §\"usePendingNavigation()\"\n * See LOCAL-336 for design decisions.\n */\n\n'use client';\n\nimport { useState, createElement } from 'react';\nimport { usePendingNavigationUrl } from './navigation-context.js';\n\n// ─── Types ───────────────────────────────────────────────────────\n\nexport interface TopLoaderConfig {\n  /** Whether the top-loader is enabled. Default: true. */\n  enabled?: boolean;\n  /** Bar color. Default: '#2299DD'. */\n  color?: string;\n  /** Bar height in pixels. Default: 3. */\n  height?: number;\n  /** Show subtle glow/shadow effect. Default: false. */\n  shadow?: boolean;\n  /** Delay in ms before showing the bar. Default: 0. */\n  delay?: number;\n  /** CSS z-index. Default: 1600. */\n  zIndex?: number;\n}\n\n// ─── Defaults ────────────────────────────────────────────────────\n\nconst DEFAULT_COLOR = '#2299DD';\nconst DEFAULT_HEIGHT = 3;\nconst DEFAULT_SHADOW = false;\nconst DEFAULT_DELAY = 0;\nconst DEFAULT_Z_INDEX = 1600;\n\n// ─── Keyframes ───────────────────────────────────────────────────\n\n// Unique keyframes name to avoid collisions with user styles.\nconst CRAWL_KEYFRAMES = '__timber_top_loader_crawl';\nconst APPEAR_KEYFRAMES = '__timber_top_loader_appear';\nconst FINISH_KEYFRAMES = '__timber_top_loader_finish';\n\n// Track whether the @keyframes rules have been injected into the document.\nlet keyframesInjected = false;\n\n/**\n * Inject the @keyframes rules into the document head once.\n * Called during render (idempotent). Uses a <style> tag so the\n * animations are available for inline-styled elements.\n */\nfunction ensureKeyframes(): void {\n  if (keyframesInjected) return;\n  if (typeof document === 'undefined') return;\n\n  const style = document.createElement('style');\n  style.textContent = `\n@keyframes ${CRAWL_KEYFRAMES} {\n  0% { width: 0%; }\n  100% { width: 90%; }\n}\n@keyframes ${APPEAR_KEYFRAMES} {\n  from { opacity: 0; }\n  to { opacity: 1; }\n}\n@keyframes ${FINISH_KEYFRAMES} {\n  0% { width: 90%; opacity: 1; }\n  50% { width: 100%; opacity: 1; }\n  100% { width: 100%; opacity: 0; }\n}\n`;\n  document.head.appendChild(style);\n  keyframesInjected = true;\n}\n\n// ─── Component ───────────────────────────────────────────────────\n\n/**\n * Internal top-loader component. Injected by NavigationRoot.\n *\n * Reads pending navigation state from PendingNavigationContext.\n * Phase transitions are derived synchronously during render:\n *\n *   hidden → crawling:   when isPending becomes true\n *   crawling → finishing: when isPending becomes false\n *   finishing → hidden:   when CSS transition ends (onTransitionEnd)\n *   finishing → crawling: when isPending becomes true again\n *\n * No useEffect — all state changes are either derived during render\n * (getDerivedStateFromProps pattern) or triggered by DOM events.\n */\nexport function TopLoader({ config }: { config?: TopLoaderConfig }): React.ReactElement | null {\n  const pendingUrl = usePendingNavigationUrl();\n  // Navigation is pending when the React-based pending URL is set.\n  // pendingUrl is set as an urgent update in navigateTransition() —\n  // React commits it before the next paint, so the TopLoader appears\n  // immediately when a real RSC navigation starts.\n  //\n  // We intentionally do NOT check hasNativeNavigationTransition() here.\n  // The Navigation API's transition is active for ALL intercepted\n  // navigations, including shallow URL updates (nuqs search param\n  // changes with shallow: true) and prevented navigations. Those\n  // briefly set navigation.transition via event.intercept() but do\n  // NOT trigger RSC fetches — showing the TopLoader would be incorrect.\n  // pendingUrl is the authoritative signal for \"we're fetching RSC data.\"\n  const isPending = pendingUrl !== null;\n\n  const color = config?.color ?? DEFAULT_COLOR;\n  const height = config?.height ?? DEFAULT_HEIGHT;\n  const shadow = config?.shadow ?? DEFAULT_SHADOW;\n  const delay = config?.delay ?? DEFAULT_DELAY;\n  const zIndex = config?.zIndex ?? DEFAULT_Z_INDEX;\n\n  const [phase, setPhase] = useState<'hidden' | 'crawling' | 'finishing'>('hidden');\n\n  // ─── Synchronous phase derivation (getDerivedStateFromProps) ──\n  // React allows setState during render if the value changes — it\n  // immediately re-renders with the updated state before committing.\n\n  if (isPending && (phase === 'hidden' || phase === 'finishing')) {\n    setPhase('crawling');\n  }\n  if (!isPending && phase === 'crawling') {\n    setPhase('finishing');\n  }\n\n  // Inject keyframes on first visible render (idempotent)\n  if (phase !== 'hidden') {\n    ensureKeyframes();\n  }\n\n  if (phase === 'hidden') return null;\n\n  // ─── Styles ──────────────────────────────────────────────────\n\n  const containerStyle: React.CSSProperties = {\n    position: 'fixed',\n    top: 0,\n    left: 0,\n    width: '100%',\n    height: `${height}px`,\n    zIndex,\n    pointerEvents: 'none',\n  };\n\n  const barStyle: React.CSSProperties = {\n    height: '100%',\n    backgroundColor: color,\n    ...(phase === 'crawling'\n      ? {\n          // Crawl from 0% to 90% over 30s. When delay > 0, both the crawl\n          // and a visibility animation are delayed — the bar stays at width 0%\n          // and opacity 0 during the delay, then appears and starts crawling.\n          // With delay 0, the appear animation is instant (0s duration, no delay).\n          animation: [\n            `${CRAWL_KEYFRAMES} 30s ease-out ${delay}ms forwards`,\n            `${APPEAR_KEYFRAMES} 0s ${delay}ms both`,\n          ].join(', '),\n        }\n      : {\n          // Finishing: fill to 100% then fade out via a keyframe animation.\n          // We use a keyframe instead of a CSS transition because the\n          // animation-to-transition handoff is unreliable — the browser\n          // may not capture the animated width as the transition's \"from\"\n          // value when both the animation removal and transition are\n          // applied in the same render frame.\n          animation: `${FINISH_KEYFRAMES} 400ms ease forwards`,\n        }),\n    ...(shadow\n      ? {\n          boxShadow: `0 0 10px ${color}, 0 0 5px ${color}`,\n        }\n      : {}),\n  };\n\n  // Clean up the finishing phase when the finish animation completes.\n  const handleAnimationEnd =\n    phase === 'finishing'\n      ? (e: React.AnimationEvent) => {\n          if (e.animationName === FINISH_KEYFRAMES) {\n            setPhase('hidden');\n          }\n        }\n      : undefined;\n\n  return createElement(\n    'div',\n    {\n      'style': containerStyle,\n      'aria-hidden': 'true',\n      'data-timber-top-loader': '',\n    },\n    createElement('div', { style: barStyle, onAnimationEnd: handleAnimationEnd })\n  );\n}\n","/**\n * NavigationRoot — Wrapper component for transition-based rendering.\n *\n * Solves the \"new boundary has no old content\" problem for client-side\n * navigation. When React renders a completely new Suspense boundary via\n * root.render(), it shows the fallback immediately — root.render() is\n * always an urgent update regardless of startTransition.\n *\n * NavigationRoot holds the current element in React state. Navigation\n * updates call startTransition(() => setState(newElement)), which IS\n * a transition update. React keeps the old committed tree visible while\n * any new Suspense boundaries in the transition resolve.\n *\n * Also manages `pendingUrl` as React state with an urgent/transition split:\n * - Navigation START: `setPendingUrl(url)` is an urgent update — React\n *   commits it before the next paint, showing the spinner immediately.\n * - Navigation END: `setPendingUrl(null)` is inside `startTransition`\n *   alongside `setElement(newTree)` — both commit atomically, so the\n *   spinner disappears in the same frame as the new content appears.\n *\n * Hard navigation guard: When a hard navigation is triggered (500 error,\n * version skew), the component throws an unresolved thenable AFTER all\n * hooks to suspend forever — preventing React from rendering children\n * during page teardown. The throw must come after hooks to satisfy\n * React's rules (same hook count every render) while still preventing\n * child renders that could hit hook count mismatches in components\n * whose positions shift during teardown. This pattern is borrowed from\n * Next.js (app-router.tsx pushRef.mpaNavigation — also after hooks).\n *\n * See design/05-streaming.md §\"deferSuspenseFor\"\n * See design/19-client-navigation.md §\"NavigationContext\"\n */\n\nimport { createElement, Fragment, startTransition, useState, type ReactNode } from 'react';\nimport { activateLinkPending, resetLinkPending } from './link-pending-store.js';\nimport { PendingNavigationProvider } from './navigation-context.js';\nimport { TopLoader, type TopLoaderConfig } from './top-loader.js';\n\n// ─── Navigation Transition Counter ──────────────────────────────\n// Monotonically increasing counter that increments each time\n// navigateTransition() is called. Used to detect stale transitions:\n// if a newer transition started while the current one's perform()\n// was in flight, the current transition is stale and should reject.\n//\n// Separate from the link-pending navId (which only increments on\n// link clicks). This counter covers all navigation types: link clicks,\n// programmatic navigate(), refresh(), and handlePopState().\n//\n// Uses globalThis for singleton guarantee across chunks — same pattern\n// as NavigationContext and the link pending store.\n\nconst NAV_TRANSITION_KEY = Symbol.for('__timber_nav_transition_counter');\n\nfunction getTransitionCounter(): { id: number } {\n  const g = globalThis as Record<symbol, unknown>;\n  if (!g[NAV_TRANSITION_KEY]) {\n    g[NAV_TRANSITION_KEY] = { id: 0 };\n  }\n  return g[NAV_TRANSITION_KEY] as { id: number };\n}\n\n// ─── Hard Navigation Guard ──────────────────────────────────────\n\n/**\n * Module-level flag indicating a hard (MPA) navigation is in progress.\n *\n * When true:\n * - NavigationRoot throws an unresolved thenable to suspend forever,\n *   preventing React from rendering children during page teardown\n *   (avoids \"Rendered more hooks\" crashes).\n * - The Navigation API handler skips interception, letting the browser\n *   perform a full page load (prevents infinite loops where\n *   window.location.href → navigate event → router.navigate → 500 →\n *   window.location.href → ...).\n *\n * Uses globalThis for singleton guarantee across chunks (same pattern\n * as NavigationContext). See design/19-client-navigation.md §\"Singleton\n * Guarantee via globalThis\".\n */\nconst HARD_NAV_KEY = Symbol.for('__timber_hard_navigating');\n\nfunction getHardNavStore(): { value: boolean } {\n  const g = globalThis as Record<symbol, unknown>;\n  if (!g[HARD_NAV_KEY]) {\n    g[HARD_NAV_KEY] = { value: false };\n  }\n  return g[HARD_NAV_KEY] as { value: boolean };\n}\n\n/**\n * Set the hard-navigating flag. Call this BEFORE setting\n * window.location.href or window.location.reload() to prevent:\n * 1. React from rendering children during page teardown\n * 2. Navigation API from intercepting the hard navigation\n */\nexport function setHardNavigating(value: boolean): void {\n  getHardNavStore().value = value;\n}\n\n/**\n * Check if a hard navigation is in progress.\n * Used by NavigationRoot (throw unresolvedThenable) and by the\n * Navigation API handler (skip interception).\n */\nexport function isHardNavigating(): boolean {\n  return getHardNavStore().value;\n}\n\n/**\n * A thenable that never resolves. When thrown during React render,\n * it causes the component to suspend forever — React keeps the\n * old committed tree visible and never attempts to render children.\n *\n * This is the same pattern Next.js uses in app-router.tsx for MPA\n * navigations (pushRef.mpaNavigation → throw unresolvedThenable).\n */\n// for React's Suspense mechanism. Same pattern as Next.js's unresolvedThenable.\n// eslint-disable-next-line unicorn/no-thenable -- Intentionally a never-resolving thenable\nconst unresolvedThenable = { then() {} } as PromiseLike<never>;\n\n// ─── Module-level functions ──────────────────────────────────────\n\n/**\n * Module-level reference to the state setter wrapped in startTransition.\n * Used for non-navigation renders (applyRevalidation, popstate replay).\n */\nlet _transitionRender: ((element: ReactNode) => void) | null = null;\n\n/**\n * Module-level reference to the navigation transition function.\n * Wraps a full navigation (fetch + render) in a single startTransition\n * with the pending URL.\n */\nlet _navigateTransition:\n  | ((pendingUrl: string, perform: () => Promise<ReactNode>) => Promise<void>)\n  | null = null;\n\n// ─── Component ───────────────────────────────────────────────────\n\n/**\n * Root wrapper component that enables transition-based rendering.\n *\n * Renders PendingNavigationProvider around children for the pending URL\n * context. The DOM tree matches the server-rendered HTML during hydration\n * (the provider renders no extra DOM elements).\n *\n * Usage in browser-entry.ts:\n *   const rootEl = createElement(NavigationRoot, { initial: wrapped });\n *   reactRoot = hydrateRoot(document, rootEl);\n *\n * Subsequent navigations:\n *   navigateTransition(url, async () => { fetch; return wrappedElement; });\n *\n * Non-navigation renders:\n *   transitionRender(newWrappedElement);\n */\nexport function NavigationRoot({\n  initial,\n  topLoaderConfig,\n}: {\n  initial: ReactNode;\n  topLoaderConfig?: TopLoaderConfig;\n}): ReactNode {\n  const [element, setElement] = useState<ReactNode>(initial);\n  const [pendingUrl, setPendingUrl] = useState<string | null>(null);\n\n  // NOTE: We use standalone `startTransition` (imported from 'react'),\n  // NOT `useTransition`. The `useTransition` hook's `startTransition`\n  // is tied to a single fiber and tracks one async callback at a time.\n  // When two navigations overlap (click slow-page, then click dashboard),\n  // calling useTransition's startTransition twice with concurrent async\n  // callbacks corrupts React's internal hook tracking — causing\n  // \"Rendered more hooks than during the previous render.\"\n  //\n  // Standalone `startTransition` creates independent transition lanes\n  // for each call, so concurrent navigations don't interfere. We don't\n  // need useTransition's `isPending` — we track pending state via our\n  // own `pendingUrl` useState.\n  //\n  // This matches the Next.js pattern (TIM-625): \"No useTransition in\n  // the router at all — only standalone startTransition.\"\n\n  // Non-navigation render (revalidation, popstate cached replay).\n  _transitionRender = (newElement: ReactNode) => {\n    startTransition(() => {\n      setElement(newElement);\n    });\n  };\n\n  // Full navigation transition.\n  // setPendingUrl(url) is an URGENT update — React commits it before the next\n  // paint, so the pending spinner appears immediately when navigation starts.\n  // Inside startTransition: the async fetch + setElement + setPendingUrl(null)\n  // are deferred. When the transition commits, the new tree and pendingUrl=null\n  // both apply in the same React commit — making the pending→active transition\n  // atomic (no frame where pending is false but the old tree is still visible).\n  _navigateTransition = (url: string, perform: () => Promise<ReactNode>) => {\n    // Urgent: show pending state immediately (for TopLoader / usePendingNavigation)\n    setPendingUrl(url);\n\n    // Increment the transition counter SYNCHRONOUSLY (before startTransition\n    // schedules the async work). Each call gets a unique transId; the counter\n    // is the same globalThis singleton, so a newer call always has a higher id.\n    const counter = getTransitionCounter();\n    const transId = ++counter.id;\n\n    return new Promise<void>((resolve, reject) => {\n      startTransition(async () => {\n        // Activate per-link pending state inside this async transition.\n        // useOptimistic persists the isPending=true value for the duration\n        // of this transition, then auto-reverts when it settles.\n        activateLinkPending();\n        try {\n          const newElement = await perform();\n          // Only commit state if this is still the active navigation.\n          // A superseded transition's updates must be dropped entirely.\n          if (counter.id === transId) {\n            setElement(newElement);\n            setPendingUrl(null);\n            resolve();\n          } else {\n            // Stale transition — a newer navigation has superseded this one.\n            // Reject so the caller (navigate/refresh/handlePopState) doesn't\n            // run post-transition side effects (applyHead, scroll, event\n            // dispatch) with stale data. All callers catch AbortError.\n            reject(new DOMException('Navigation superseded', 'AbortError'));\n          }\n        } catch (err) {\n          // Only clear pending if this is still the active navigation.\n          if (counter.id === transId) {\n            setPendingUrl(null);\n            resetLinkPending();\n          }\n          reject(err);\n        }\n      });\n    });\n  };\n\n  // ─── Hard navigation guard ─────────────────────────────────\n  // When a hard navigation is in progress (500 error, version skew),\n  // suspend forever to prevent React from rendering children during\n  // page teardown. This avoids \"Rendered more hooks\" crashes in\n  // CHILD components whose hook counts may shift during teardown.\n  //\n  // CRITICAL: This throw MUST come AFTER all hooks (the two\n  // useState calls above). React requires the same hooks to run on\n  // every render. If we threw before hooks, React would see 0 hooks\n  // on the re-render vs 2 hooks on the initial render — triggering\n  // the exact \"Rendered more hooks\" error we're trying to prevent.\n  //\n  // By placing it after hooks but before the return, all hooks\n  // satisfy React's rules, but the thrown thenable prevents any\n  // children from rendering. Same pattern as Next.js app-router.tsx\n  // (pushRef.mpaNavigation — also placed after all hooks).\n  if (isHardNavigating()) {\n    throw unresolvedThenable;\n  }\n\n  // Inject TopLoader alongside the element tree inside PendingNavigationProvider.\n  // The TopLoader reads pendingUrl from context to show/hide the progress bar.\n  // It is rendered only when not explicitly disabled via config.\n  const showTopLoader = topLoaderConfig?.enabled !== false;\n  const children = showTopLoader\n    ? createElement(Fragment, null, createElement(TopLoader, { config: topLoaderConfig }), element)\n    : element;\n  return createElement(PendingNavigationProvider, { value: pendingUrl }, children);\n}\n\n// ─── Public API ──────────────────────────────────────────────────\n\n/**\n * Trigger a transition render for non-navigation updates.\n * React keeps the old committed tree visible while any new Suspense\n * boundaries in the update resolve.\n *\n * Used for: applyRevalidation, popstate replay with cached payload.\n */\nexport function transitionRender(element: ReactNode): void {\n  if (_transitionRender) {\n    _transitionRender(element);\n  }\n}\n\n/**\n * Run a full navigation inside a React transition with optimistic pending URL.\n *\n * The `perform` callback runs inside `startTransition` — it should fetch the\n * RSC payload, update router state, and return the wrapped React element.\n * The pending URL shows immediately (urgent update) and reverts\n * to null when the transition commits (atomic with the new tree).\n *\n * Returns a Promise that resolves when the async work completes (note: the\n * React transition may not have committed yet, but all state updates are done).\n *\n * Used for: navigate(), refresh(), popstate with fetch.\n */\nexport function navigateTransition(\n  pendingUrl: string,\n  perform: () => Promise<ReactNode>\n): Promise<void> {\n  if (_navigateTransition) {\n    return _navigateTransition(pendingUrl, perform);\n  }\n  // Fallback: no NavigationRoot mounted (shouldn't happen in production)\n  return perform().then(() => {});\n}\n\n/**\n * Check if the NavigationRoot is mounted and ready for renders.\n * Used by browser-entry.ts to guard against renders before hydration.\n */\nexport function isNavigationRootReady(): boolean {\n  return _transitionRender !== null;\n}\n\n/**\n * Install one-shot deferred callbacks for the no-RSC bootstrap path (TIM-600).\n *\n * When there's no RSC payload, we can't create a React root immediately —\n * `createRoot(document).render(...)` would blank the SSR HTML. Instead,\n * this sets up `_transitionRender` and `_navigateTransition` so that the\n * first client navigation triggers root creation via `createAndMount`.\n *\n * After `createAndMount` runs, NavigationRoot renders and overwrites these\n * callbacks with its real `startTransition`-based implementations.\n */\nexport function installDeferredNavigation(createAndMount: (initial: ReactNode) => void): void {\n  let mounted = false;\n  const mountOnce = (element: ReactNode) => {\n    if (mounted) return;\n    mounted = true;\n    createAndMount(element);\n  };\n  _transitionRender = (element: ReactNode) => {\n    mountOnce(element);\n  };\n  _navigateTransition = async (_pendingUrl: string, perform: () => Promise<ReactNode>) => {\n    const element = await perform();\n    mountOnce(element);\n  };\n}\n"],"mappings":";;;AA+BA,IAAM,mBAAmB,OAAO,IAAI,wBAAwB;;AAM5D,IAAa,YAAwB,EAAE,WAAW,OAAO;AAIzD,SAAS,WAAoD;CAC3D,MAAM,IAAI;AACV,KAAI,CAAC,EAAE,kBACL,GAAE,oBAAoB,EAAE,SAAS,MAAM;AAEzC,QAAO,EAAE;;;;;;;;;;;AAcX,SAAgB,4BAA4B,MAAwC;CAClF,MAAM,QAAQ,UAAU;AACxB,OAAM,UAAU;;;;;AA2ClB,SAAgB,gCAAgC,MAAiC;CAC/E,MAAM,QAAQ,UAAU;AACxB,KAAI,MAAM,YAAY,KACpB,OAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AE7BpB,IAAM,eAAe,OAAO,IAAI,2BAA2B;AAE3D,SAAS,kBAAsC;CAC7C,MAAM,IAAI;AACV,KAAI,CAAC,EAAE,cACL,GAAE,gBAAgB,EAAE,OAAO,OAAO;AAEpC,QAAO,EAAE;;;;;;;;AASX,SAAgB,kBAAkB,OAAsB;AACtD,kBAAiB,CAAC,QAAQ"}

package/dist/_chunks/registry-BI9cgCt7.js

@@ -0,0 +1,20 @@
+//#region src/search-params/registry.ts
+var registry = /* @__PURE__ */ new Map();
+/**
+* Register a route's search params definition.
+* Called by the generated route manifest loader when a route's modules load.
+*/
+function registerSearchParams(route, definition) {
+	registry.set(route, definition);
+}
+/**
+* Look up a route's search params definition.
+* Returns undefined if the route hasn't been loaded yet.
+*/
+function getSearchParamsDefinition(route) {
+	return registry.get(route);
+}
+//#endregion
+export { registerSearchParams as n, getSearchParamsDefinition as t };
+
+//# sourceMappingURL=registry-BI9cgCt7.js.map

package/dist/_chunks/registry-BI9cgCt7.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-BI9cgCt7.js","names":[],"sources":["../../src/search-params/registry.ts"],"sourcesContent":["/**\n * Runtime registry for route-scoped search params definitions.\n *\n * When a route's modules load, the framework registers its search-params\n * definition here. useQueryStates('/route') resolves codecs from this map.\n *\n * Design doc: design/23-search-params.md §\"Runtime: Registration at Route Load\"\n */\n\nimport type { SearchParamsDefinition } from './define.js';\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nconst registry = new Map<string, SearchParamsDefinition<any>>();\n\n/**\n * Register a route's search params definition.\n * Called by the generated route manifest loader when a route's modules load.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function registerSearchParams(route: string, definition: SearchParamsDefinition<any>): void {\n  registry.set(route, definition);\n}\n\n/**\n * Look up a route's search params definition.\n * Returns undefined if the route hasn't been loaded yet.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function getSearchParamsDefinition(route: string): SearchParamsDefinition<any> | undefined {\n  return registry.get(route);\n}\n"],"mappings":";AAYA,IAAM,2BAAW,IAAI,KAA0C;;;;;AAO/D,SAAgB,qBAAqB,OAAe,YAA+C;AACjG,UAAS,IAAI,OAAO,WAAW;;;;;;AAQjC,SAAgB,0BAA0B,OAAwD;AAChG,QAAO,SAAS,IAAI,MAAM"}