@timber-js/app 0.2.0-alpha.15 → 0.2.0-alpha.151

package/dist/_chunks/registry-DbJPKoBp.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-DbJPKoBp.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry-DbJPKoBp.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,IAAyC;;;;;AAO9D,SAAgB,qBAAqB,OAAe,YAA+C;CACjG,SAAS,IAAI,OAAO,UAAU;AAChC;;;;;AAOA,SAAgB,0BAA0B,OAAwD;CAChG,OAAO,SAAS,IAAI,KAAK;AAC3B"}

package/dist/_chunks/resolve-schema-3iUvBV5T.js

@@ -0,0 +1,50 @@
+import { a as resolveCodecOrSchema, r as isCodec } from "./schema-bridge-BY3QLBL7.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-3iUvBV5T.js.map

package/dist/_chunks/resolve-schema-3iUvBV5T.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-schema-3iUvBV5T.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-CtmF-aPv.js

@@ -0,0 +1,28 @@
+import { o as _setGlobalRouter, u as globalRouter } from "./ssr-data-BOWsq18U.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-CtmF-aPv.js.map

package/dist/_chunks/router-ref-CtmF-aPv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-ref-CtmF-aPv.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.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"}

package/dist/_chunks/schema-bridge-BY3QLBL7.js

@@ -0,0 +1,119 @@
+//#region src/schema-bridge.ts
+/**
+* Run a Standard Schema's `~standard.validate()` synchronously.
+*
+* Zod v4's signature includes `Promise` in the return union to satisfy the
+* Standard Schema spec, but in practice Zod always validates synchronously
+* for the schema types we use. We assert the result is sync and throw if
+* it isn't — codec parsing must be synchronous.
+*/
+function validateSync(schema, value) {
+	const result = schema["~standard"].validate(value);
+	if (result instanceof Promise) throw new Error("[timber] fromSchema: schema returned a Promise — only sync schemas are supported.");
+	return result;
+}
+/** Check if a value is a Standard Schema object. */
+function isStandardSchema(value) {
+	return typeof value === "object" && value !== null && "~standard" in value && typeof value["~standard"]?.validate === "function";
+}
+/** Check if a value is a Codec (has parse + serialize methods). */
+function isCodec(value) {
+	return typeof value === "object" && value !== null && typeof value.parse === "function" && typeof value.serialize === "function";
+}
+/**
+* Bridge a Standard Schema to a Codec for route params.
+* Parse throws on failure (invalid param → 404). Serialize returns string.
+*/
+function fromParamSchema(fieldName, schema) {
+	return {
+		parse(value) {
+			const result = validateSync(schema, value);
+			if (!result.issues) return result.value;
+			const messages = result.issues.map((i) => i.message).join(", ");
+			throw new Error(`[timber] Param '${fieldName}' coercion failed: ${messages}`);
+		},
+		serialize(value) {
+			if (value === null || value === void 0) return null;
+			if (Array.isArray(value)) return value.join("/");
+			return String(value);
+		}
+	};
+}
+/**
+* Resolve a field value to a Codec. Accepts Codec<T>, StandardSchemaV1<T>,
+* or (for route params) auto-wraps via fromParamSchema.
+*
+* @param fieldName - used in error messages
+* @param value - the codec or schema to resolve
+* @param mode - 'param' uses fromParamSchema (throws on parse failure),
+*               'search' uses fromSchema (falls back to default on failure)
+*/
+function resolveCodecOrSchema(fieldName, value, mode = "search") {
+	if (isCodec(value)) return value;
+	if (isStandardSchema(value)) return mode === "param" ? fromParamSchema(fieldName, value) : fromSchema(value);
+	throw new Error(`[timber] Field '${fieldName}' is not a valid codec or Standard Schema. Expected an object with { parse, serialize } methods, or a Standard Schema object (Zod, Valibot, ArkType).`);
+}
+/**
+* Bridge a Standard Schema-compatible schema (Zod, Valibot, ArkType) to a
+* Codec<T>.
+*
+* Parse: coerces the raw string through the schema. On validation failure,
+* parses `undefined` to get the schema's default value (the schema should have
+* a `.default()` call). If that also fails, returns `undefined`.
+*
+* Serialize: uses `String()` for primitives, `null` for null/undefined.
+*
+* ```ts
+* import { fromSchema } from '@timber-js/app/codec'
+* import { z } from 'zod/v4'
+*
+* const pageCodec = fromSchema(z.coerce.number().int().min(1).default(1))
+* ```
+*/
+function fromSchema(schema) {
+	return {
+		parse(value) {
+			const result = validateSync(schema, Array.isArray(value) ? value[0] : value);
+			if (!result.issues) return result.value;
+			const defaultResult = validateSync(schema, void 0);
+			if (!defaultResult.issues) return defaultResult.value;
+		},
+		serialize(value) {
+			if (value === null || value === void 0) return null;
+			return String(value);
+		}
+	};
+}
+/**
+* Bridge a Standard Schema for array values. Handles both single strings
+* and repeated query keys (`?tag=a&tag=b`).
+*
+* ```ts
+* import { fromArraySchema } from '@timber-js/app/codec'
+* import { z } from 'zod/v4'
+*
+* const tagsCodec = fromArraySchema(z.array(z.string()).default([]))
+* ```
+*/
+function fromArraySchema(schema) {
+	return {
+		parse(value) {
+			let input = value;
+			if (typeof value === "string") input = [value];
+			else if (value === void 0) input = void 0;
+			const result = validateSync(schema, input);
+			if (!result.issues) return result.value;
+			const defaultResult = validateSync(schema, void 0);
+			if (!defaultResult.issues) return defaultResult.value;
+		},
+		serialize(value) {
+			if (value === null || value === void 0) return null;
+			if (Array.isArray(value)) return value.length === 0 ? null : value.join(",");
+			return String(value);
+		}
+	};
+}
+//#endregion
+export { resolveCodecOrSchema as a, isStandardSchema as i, fromSchema as n, validateSync as o, isCodec as r, fromArraySchema as t };
+
+//# sourceMappingURL=schema-bridge-BY3QLBL7.js.map

package/dist/_chunks/schema-bridge-BY3QLBL7.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-bridge-BY3QLBL7.js","names":[],"sources":["../../src/schema-bridge.ts"],"sourcesContent":["/**\n * Standard Schema bridge — shared helpers for bridging Standard Schema-compatible\n * validation libraries (Zod, Valibot, ArkType) to the Codec<T> protocol.\n *\n * This module is the single source of truth for:\n * - StandardSchemaV1 interface (subset of the Standard Schema spec)\n * - validateSync() helper\n * - fromSchema() — bridge from Standard Schema to Codec<T>\n * - fromArraySchema() — bridge for array-valued codecs\n *\n * These are re-exported from @timber-js/app/search-params, @timber-js/app/segment-params,\n * and @timber-js/app/cookies for convenience. The canonical import is\n * @timber-js/app/codec.\n *\n * Design doc: design/23a-search-params-triage.md §\"Unify Codec<T> type\"\n */\n\nimport type { Codec } from './codec.js';\n\n// ---------------------------------------------------------------------------\n// Standard Schema interface (subset)\n//\n// Standard Schema (https://github.com/standard-schema/standard-schema) defines\n// a minimal interface that Zod ≥3.24, Valibot ≥1.0, and ArkType all implement.\n// We depend only on `~standard.validate` to avoid coupling to any specific lib.\n// ---------------------------------------------------------------------------\n\n/** Minimal Standard Schema interface for auto-detection. */\nexport interface StandardSchemaV1<Output = unknown> {\n  '~standard': {\n    validate(value: unknown): StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;\n  };\n}\n\nexport type StandardSchemaResult<Output> =\n  | { value: Output; issues?: undefined }\n  | { value?: undefined; issues: ReadonlyArray<{ message: string }> };\n\n// ---------------------------------------------------------------------------\n// Sync validate helper\n// ---------------------------------------------------------------------------\n\n/**\n * Run a Standard Schema's `~standard.validate()` synchronously.\n *\n * Zod v4's signature includes `Promise` in the return union to satisfy the\n * Standard Schema spec, but in practice Zod always validates synchronously\n * for the schema types we use. We assert the result is sync and throw if\n * it isn't — codec parsing must be synchronous.\n */\nexport function validateSync<Output>(\n  schema: StandardSchemaV1<Output>,\n  value: unknown\n): StandardSchemaResult<Output> {\n  const result = schema['~standard'].validate(value);\n  if (result instanceof Promise) {\n    throw new Error(\n      '[timber] fromSchema: schema returned a Promise — only sync schemas are supported.'\n    );\n  }\n  return result;\n}\n\n// ---------------------------------------------------------------------------\n// Type guards\n// ---------------------------------------------------------------------------\n\n/** Check if a value is a Standard Schema object. */\nexport function isStandardSchema(value: unknown): value is StandardSchemaV1 {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    '~standard' in value &&\n    typeof (value as StandardSchemaV1)['~standard']?.validate === 'function'\n  );\n}\n\n/** Check if a value is a Codec (has parse + serialize methods). */\nexport function isCodec(value: unknown): value is Codec<unknown> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof (value as Codec<unknown>).parse === 'function' &&\n    typeof (value as Codec<unknown>).serialize === 'function'\n  );\n}\n\n// ---------------------------------------------------------------------------\n// fromParamSchema — bridge from Standard Schema to Codec<T> for route params\n// ---------------------------------------------------------------------------\n\n/**\n * Bridge a Standard Schema to a Codec for route params.\n * Parse throws on failure (invalid param → 404). Serialize returns string.\n */\nexport function fromParamSchema<T>(fieldName: string, schema: StandardSchemaV1<T>): Codec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      const result = validateSync(schema, value);\n      if (!result.issues) {\n        return result.value;\n      }\n      const messages = result.issues.map((i) => i.message).join(', ');\n      throw new Error(`[timber] Param '${fieldName}' coercion failed: ${messages}`);\n    },\n    serialize(value: T): string | null {\n      if (value === null || value === undefined) return null;\n      if (Array.isArray(value)) return value.join('/');\n      return String(value);\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// resolveCodecOrSchema — generic resolver for any codec-or-schema field\n// ---------------------------------------------------------------------------\n\n/**\n * Resolve a field value to a Codec. Accepts Codec<T>, StandardSchemaV1<T>,\n * or (for route params) auto-wraps via fromParamSchema.\n *\n * @param fieldName - used in error messages\n * @param value - the codec or schema to resolve\n * @param mode - 'param' uses fromParamSchema (throws on parse failure),\n *               'search' uses fromSchema (falls back to default on failure)\n */\nexport function resolveCodecOrSchema(\n  fieldName: string,\n  value: unknown,\n  mode: 'param' | 'search' = 'search'\n): Codec<unknown> {\n  if (isCodec(value)) return value;\n  if (isStandardSchema(value)) {\n    return mode === 'param'\n      ? fromParamSchema(fieldName, value)\n      : (fromSchema(value) as Codec<unknown>);\n  }\n  throw new Error(\n    `[timber] Field '${fieldName}' is not a valid codec or Standard Schema. ` +\n      `Expected an object with { parse, serialize } methods, or a Standard Schema object ` +\n      `(Zod, Valibot, ArkType).`\n  );\n}\n\n// ---------------------------------------------------------------------------\n// fromSchema — bridge from Standard Schema to Codec<T>\n// ---------------------------------------------------------------------------\n\n/**\n * Bridge a Standard Schema-compatible schema (Zod, Valibot, ArkType) to a\n * Codec<T>.\n *\n * Parse: coerces the raw string through the schema. On validation failure,\n * parses `undefined` to get the schema's default value (the schema should have\n * a `.default()` call). If that also fails, returns `undefined`.\n *\n * Serialize: uses `String()` for primitives, `null` for null/undefined.\n *\n * ```ts\n * import { fromSchema } from '@timber-js/app/codec'\n * import { z } from 'zod/v4'\n *\n * const pageCodec = fromSchema(z.coerce.number().int().min(1).default(1))\n * ```\n */\nexport function fromSchema<T>(schema: StandardSchemaV1<T>): Codec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      // For array inputs (duplicate query keys), use the first value.\n      // Browsers and URLSearchParams.get() return the first occurrence.\n      const input = Array.isArray(value) ? value[0] : value;\n\n      // Try parsing the raw value\n      const result = validateSync(schema, input);\n      if (!result.issues) {\n        return result.value;\n      }\n\n      // On failure, try parsing undefined to get the default.\n      // Re-validate each time so factory defaults (e.g. .default(() => []))\n      // produce fresh values.\n      const defaultResult = validateSync(schema, undefined);\n      if (!defaultResult.issues) {\n        return defaultResult.value;\n      }\n\n      // No default available — return undefined (codec design choice).\n      // Callers like defineSearchParams validate this at definition time\n      // via validateSchemaDefaults() to catch it early.\n      return undefined as T;\n    },\n\n    serialize(value: T): string | null {\n      if (value === null || value === undefined) {\n        return null;\n      }\n      return String(value);\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// fromArraySchema — bridge for array-valued codecs\n// ---------------------------------------------------------------------------\n\n/**\n * Bridge a Standard Schema for array values. Handles both single strings\n * and repeated query keys (`?tag=a&tag=b`).\n *\n * ```ts\n * import { fromArraySchema } from '@timber-js/app/codec'\n * import { z } from 'zod/v4'\n *\n * const tagsCodec = fromArraySchema(z.array(z.string()).default([]))\n * ```\n */\nexport function fromArraySchema<T>(schema: StandardSchemaV1<T>): Codec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      // Coerce single string to array for array schemas\n      let input: unknown = value;\n      if (typeof value === 'string') {\n        input = [value];\n      } else if (value === undefined) {\n        input = undefined;\n      }\n\n      const result = validateSync(schema, input);\n      if (!result.issues) {\n        return result.value;\n      }\n\n      // On failure, try undefined for default\n      const defaultResult = validateSync(schema, undefined);\n      if (!defaultResult.issues) {\n        return defaultResult.value;\n      }\n\n      return undefined as T;\n    },\n\n    serialize(value: T): string | null {\n      if (value === null || value === undefined) {\n        return null;\n      }\n      if (Array.isArray(value)) {\n        return value.length === 0 ? null : value.join(',');\n      }\n      return String(value);\n    },\n  };\n}\n"],"mappings":";;;;;;;;;AAkDA,SAAgB,aACd,QACA,OAC8B;CAC9B,MAAM,SAAS,OAAO,aAAa,SAAS,KAAK;CACjD,IAAI,kBAAkB,SACpB,MAAM,IAAI,MACR,mFACF;CAEF,OAAO;AACT;;AAOA,SAAgB,iBAAiB,OAA2C;CAC1E,OACE,OAAO,UAAU,YACjB,UAAU,QACV,eAAe,SACf,OAAQ,MAA2B,cAAc,aAAa;AAElE;;AAGA,SAAgB,QAAQ,OAAyC;CAC/D,OACE,OAAO,UAAU,YACjB,UAAU,QACV,OAAQ,MAAyB,UAAU,cAC3C,OAAQ,MAAyB,cAAc;AAEnD;;;;;AAUA,SAAgB,gBAAmB,WAAmB,QAAuC;CAC3F,OAAO;EACL,MAAM,OAAyC;GAC7C,MAAM,SAAS,aAAa,QAAQ,KAAK;GACzC,IAAI,CAAC,OAAO,QACV,OAAO,OAAO;GAEhB,MAAM,WAAW,OAAO,OAAO,KAAK,MAAM,EAAE,OAAO,EAAE,KAAK,IAAI;GAC9D,MAAM,IAAI,MAAM,mBAAmB,UAAU,qBAAqB,UAAU;EAC9E;EACA,UAAU,OAAyB;GACjC,IAAI,UAAU,QAAQ,UAAU,KAAA,GAAW,OAAO;GAClD,IAAI,MAAM,QAAQ,KAAK,GAAG,OAAO,MAAM,KAAK,GAAG;GAC/C,OAAO,OAAO,KAAK;EACrB;CACF;AACF;;;;;;;;;;AAeA,SAAgB,qBACd,WACA,OACA,OAA2B,UACX;CAChB,IAAI,QAAQ,KAAK,GAAG,OAAO;CAC3B,IAAI,iBAAiB,KAAK,GACxB,OAAO,SAAS,UACZ,gBAAgB,WAAW,KAAK,IAC/B,WAAW,KAAK;CAEvB,MAAM,IAAI,MACR,mBAAmB,UAAU,sJAG/B;AACF;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,WAAc,QAAuC;CACnE,OAAO;EACL,MAAM,OAAyC;GAM7C,MAAM,SAAS,aAAa,QAHd,MAAM,QAAQ,KAAK,IAAI,MAAM,KAAK,KAGP;GACzC,IAAI,CAAC,OAAO,QACV,OAAO,OAAO;GAMhB,MAAM,gBAAgB,aAAa,QAAQ,KAAA,CAAS;GACpD,IAAI,CAAC,cAAc,QACjB,OAAO,cAAc;EAOzB;EAEA,UAAU,OAAyB;GACjC,IAAI,UAAU,QAAQ,UAAU,KAAA,GAC9B,OAAO;GAET,OAAO,OAAO,KAAK;EACrB;CACF;AACF;;;;;;;;;;;;AAiBA,SAAgB,gBAAmB,QAAuC;CACxE,OAAO;EACL,MAAM,OAAyC;GAE7C,IAAI,QAAiB;GACrB,IAAI,OAAO,UAAU,UACnB,QAAQ,CAAC,KAAK;QACT,IAAI,UAAU,KAAA,GACnB,QAAQ,KAAA;GAGV,MAAM,SAAS,aAAa,QAAQ,KAAK;GACzC,IAAI,CAAC,OAAO,QACV,OAAO,OAAO;GAIhB,MAAM,gBAAgB,aAAa,QAAQ,KAAA,CAAS;GACpD,IAAI,CAAC,cAAc,QACjB,OAAO,cAAc;EAIzB;EAEA,UAAU,OAAyB;GACjC,IAAI,UAAU,QAAQ,UAAU,KAAA,GAC9B,OAAO;GAET,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,MAAM,WAAW,IAAI,OAAO,MAAM,KAAK,GAAG;GAEnD,OAAO,OAAO,KAAK;EACrB;CACF;AACF"}

package/dist/_chunks/segment-classify-CDDRVKs7.js

@@ -0,0 +1,137 @@
+//#region src/routing/types.ts
+/** All recognized interception markers, ordered longest-first for parsing. */
+var INTERCEPTION_MARKERS = [
+	"(..)(..)",
+	"(.)",
+	"(..)",
+	"(...)"
+];
+/** Default page extensions */
+var DEFAULT_PAGE_EXTENSIONS = [
+	"tsx",
+	"ts",
+	"jsx",
+	"js"
+];
+//#endregion
+//#region src/routing/segment-classify.ts
+/**
+* Classify a URL path segment token.
+*
+* Walks the string left-to-right in one pass:
+*   1. If it doesn't start with '[', it's static.
+*   2. Count opening brackets (1 or 2) to detect optional.
+*   3. Check for '...' to detect catch-all.
+*   4. Read the param name up to the closing bracket.
+*   5. Validate the expected closing sequence (']' or ']]').
+*   6. Reject if there are leftover characters after the close.
+*
+* Any structural violation → static (safe default).
+*/
+function classifyUrlSegment(token) {
+	const len = token.length;
+	if (len === 0 || token[0] !== "[") return {
+		kind: "static",
+		value: token
+	};
+	let i = 1;
+	const optional = token[i] === "[";
+	if (optional) i++;
+	const catchAll = i + 2 < len && token[i] === "." && token[i + 1] === "." && token[i + 2] === ".";
+	if (catchAll) i += 3;
+	const nameStart = i;
+	while (i < len && token[i] !== "]") i++;
+	if (i >= len || i === nameStart) return {
+		kind: "static",
+		value: token
+	};
+	const name = token.slice(nameStart, i);
+	i++;
+	if (optional) {
+		if (i >= len || token[i] !== "]") return {
+			kind: "static",
+			value: token
+		};
+		i++;
+	}
+	if (i !== len) return {
+		kind: "static",
+		value: token
+	};
+	if (optional && catchAll) return {
+		kind: "optional-catch-all",
+		name
+	};
+	if (catchAll) return {
+		kind: "catch-all",
+		name
+	};
+	if (optional) return {
+		kind: "static",
+		value: token
+	};
+	return {
+		kind: "dynamic",
+		name
+	};
+}
+/**
+* Classify a directory name into its segment type.
+*
+* Recognizes all timber file-system conventions in priority order:
+*   1. Private folders: `_name` (excluded from routing)
+*   2. Parallel route slots: `@name`
+*   3. Intercepting routes: `(.)name`, `(..)name`, `(...)name`, `(..)(..)name`
+*   4. Route groups: `(name)`
+*   5. Bracket syntax: `[id]`, `[...slug]`, `[[...path]]` (delegated to
+*      `classifyUrlSegment`)
+*   6. Static: anything else
+*
+* If you change the bracket syntax, update only `classifyUrlSegment`.
+* If you change the directory-prefix conventions, update this function.
+*/
+function classifySegment(dirName) {
+	if (dirName.startsWith("_")) return { type: "private" };
+	if (dirName.startsWith("@")) return { type: "slot" };
+	const interception = parseInterceptionMarker(dirName);
+	if (interception) return {
+		type: "intercepting",
+		interceptionMarker: interception.marker,
+		interceptedSegmentName: interception.segmentName
+	};
+	if (dirName.startsWith("(") && dirName.endsWith(")")) return { type: "group" };
+	const urlSeg = classifyUrlSegment(dirName);
+	if (urlSeg.kind !== "static") return {
+		type: urlSeg.kind,
+		paramName: urlSeg.name
+	};
+	return { type: "static" };
+}
+/**
+* Parse an interception marker from a directory name.
+*
+* Returns the marker and the remaining segment name, or null if not an
+* intercepting route. Markers are checked longest-first to avoid `(..)`
+* matching before `(..)(..)`.
+*
+* Examples:
+*   "(.)photo"      → { marker: "(.)", segmentName: "photo" }
+*   "(..)feed"      → { marker: "(..)", segmentName: "feed" }
+*   "(...)photos"   → { marker: "(...)", segmentName: "photos" }
+*   "(..)(..)admin" → { marker: "(..)(..)", segmentName: "admin" }
+*   "(marketing)"   → null (route group, not interception)
+*/
+function parseInterceptionMarker(dirName) {
+	for (const marker of INTERCEPTION_MARKERS) if (dirName.startsWith(marker)) {
+		const rest = dirName.slice(marker.length);
+		if (rest.length > 0 && !rest.endsWith(")")) return {
+			marker,
+			segmentName: rest
+		};
+	}
+	return null;
+}
+//#endregion
+export { INTERCEPTION_MARKERS as i, classifyUrlSegment as n, DEFAULT_PAGE_EXTENSIONS as r, classifySegment as t };
+
+//# sourceMappingURL=segment-classify-CDDRVKs7.js.map

package/dist/_chunks/segment-classify-CDDRVKs7.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"segment-classify-CDDRVKs7.js","names":[],"sources":["../../src/routing/types.ts","../../src/routing/segment-classify.ts"],"sourcesContent":["/**\n * Route tree types for timber.js file-system routing.\n *\n * The route tree is built by scanning the app/ directory and recognizing\n * file conventions (page.*, layout.*, middleware.ts, access.ts, route.ts, etc.).\n *\n * **Single shape, two specializations** (TIM-848):\n *\n * `SegmentNode<TFile>` is the one canonical in-memory shape for the\n * timber route tree. The same interface is used at build time (with\n * `TFile = RouteFile`) and at request time (with `TFile = ManifestFile`,\n * see `server/route-matcher.ts`). Walkers parameterized over `TFile`\n * work on either, eliminating the previous duplication between\n * `SegmentNode` (Map-based) and `ManifestSegmentNode` (object-based).\n *\n * Keyed groups (`slots`, `statusFiles`, `jsonStatusFiles`,\n * `legacyStatusFiles`, `metadataRoutes`) are plain `Record<string, …>`\n * objects rather than `Map`s so that the build-time tree can be\n * serialized into the virtual route manifest with no shape transform.\n *\n * See design/07-routing.md §\"Route Tree Shape\" and design/18-build-system.md\n * §\"Route Manifest Shape\".\n */\n\n/** Segment type classification */\nexport type SegmentType =\n  | 'static' // e.g. \"dashboard\"\n  | 'dynamic' // e.g. \"[id]\"\n  | 'catch-all' // e.g. \"[...slug]\"\n  | 'optional-catch-all' // e.g. \"[[...slug]]\"\n  | 'group' // e.g. \"(marketing)\"\n  | 'slot' // e.g. \"@sidebar\"\n  | 'intercepting' // e.g. \"(.)photo\", \"(..)photo\", \"(...)photo\"\n  | 'private'; // e.g. \"_components\", \"_lib\" — excluded from routing\n\n/**\n * Intercepting route marker — indicates how many levels up to resolve the\n * intercepted route from the intercepting route's location.\n *\n * See design/07-routing.md §\"Intercepting Routes\"\n */\nexport type InterceptionMarker = '(.)' | '(..)' | '(...)' | '(..)(..)';\n\n/** All recognized interception markers, ordered longest-first for parsing. */\nexport const INTERCEPTION_MARKERS: InterceptionMarker[] = ['(..)(..)', '(.)', '(..)', '(...)'];\n\n/**\n * A single file discovered in a route segment at build time.\n *\n * The runtime equivalent (`ManifestFile`, defined in\n * `server/route-matcher.ts`) replaces `extension` with a lazy `load`\n * function. Walkers that only need `filePath` are parameterized over\n * `TFile` and accept either.\n */\nexport interface RouteFile {\n  /** Absolute path to the file */\n  filePath: string;\n  /** File extension without leading dot (e.g. \"tsx\", \"ts\", \"mdx\") */\n  extension: string;\n}\n\n/**\n * A node in the segment tree.\n *\n * Generic over `TFile` so the same interface describes both the\n * build-time tree (`SegmentNode<RouteFile>`, the default) and the\n * runtime manifest tree (`SegmentNode<ManifestFile>`, aliased as\n * `ManifestSegmentNode`). All keyed groups use `Record` (not `Map`)\n * so the build-time tree serializes to the virtual route manifest\n * with no shape transform.\n */\nexport interface SegmentNode<TFile = RouteFile> {\n  /** The raw directory name (e.g. \"dashboard\", \"[id]\", \"(auth)\", \"@sidebar\") */\n  segmentName: string;\n  /** Classified segment type */\n  segmentType: SegmentType;\n  /** The dynamic param name, if dynamic (e.g. \"id\" for \"[id]\", \"slug\" for \"[...slug]\") */\n  paramName?: string;\n  /** The URL path prefix at this segment level (e.g. \"/dashboard\") */\n  urlPath: string;\n  /** For intercepting segments: the marker used, e.g. \"(.)\". */\n  interceptionMarker?: InterceptionMarker;\n  /**\n   * For intercepting segments: the segment name after stripping the marker.\n   * E.g., for \"(.)photo\" this is \"photo\".\n   */\n  interceptedSegmentName?: string;\n\n  // --- File conventions ---\n  page?: TFile;\n  layout?: TFile;\n  middleware?: TFile;\n  access?: TFile;\n  route?: TFile;\n  /**\n   * params.ts — isomorphic convention file exporting segmentParams and/or searchParams.\n   * Discovered by the scanner like middleware.ts and access.ts.\n   * See design/07-routing.md §\"params.ts Convention File\"\n   */\n  params?: TFile;\n  error?: TFile;\n  default?: TFile;\n  /** Status-code files: 4xx.tsx, 5xx.tsx, {status}.tsx (component format) */\n  statusFiles?: Record<string, TFile>;\n  /** JSON status-code files: 4xx.json, 5xx.json, {status}.json */\n  jsonStatusFiles?: Record<string, TFile>;\n  /** denied.tsx — slot-only denial rendering */\n  denied?: TFile;\n  /** Legacy compat: not-found.tsx (maps to 404), forbidden.tsx (403), unauthorized.tsx (401) */\n  legacyStatusFiles?: Record<string, TFile>;\n\n  /** Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.) keyed by base name */\n  metadataRoutes?: Record<string, TFile>;\n\n  // --- Children ---\n  children: SegmentNode<TFile>[];\n  /** Parallel route slots (keyed by slot name without @) */\n  slots: Record<string, SegmentNode<TFile>>;\n}\n\n/**\n * The full route tree output from the scanner (or the root of the\n * runtime route manifest, when `TFile = ManifestFile`).\n *\n * Generic so the same wrapper carries app-root metadata for both\n * shapes. The runtime manifest extends this with `viteRoot` (see\n * `ManifestRoot` in `server/route-matcher.ts`).\n */\nexport interface RouteTree<TFile = RouteFile> {\n  /** The root segment node (representing app/) */\n  root: SegmentNode<TFile>;\n  /** All discovered proxy.ts files (should be at most one, in app/) */\n  proxy?: TFile;\n  /**\n   * Global error page: app/global-error.{tsx,ts,jsx,js}\n   *\n   * Rendered as a standalone full-page replacement (no layout wrapping)\n   * when no segment-level error file is found. SSR-only render path.\n   * Must provide its own <html> and <body>.\n   *\n   * See design/10-error-handling.md §\"Tier 2 — Global Error Page\"\n   */\n  globalError?: TFile;\n}\n\n/** Configuration passed to the scanner */\nexport interface ScannerConfig {\n  /** Recognized page/layout extensions (without dots). Default: ['tsx', 'ts', 'jsx', 'js'] */\n  pageExtensions?: string[];\n}\n\n/** Default page extensions */\nexport const DEFAULT_PAGE_EXTENSIONS = ['tsx', 'ts', 'jsx', 'js'];\n","/**\n * Shared segment classifier — both URL tokens and filesystem directory names.\n *\n * `classifyUrlSegment(token)` is a pure single-pass character parser that\n * classifies a route segment token (e.g. \"dashboard\", \"[id]\", \"[...slug]\",\n * \"[[...path]]\") into a typed discriminated union. NO regex, NO Node.js-only\n * APIs — safe to import from browser code (used by `Link` interpolation).\n *\n * `classifySegment(dirName)` is the build-time directory-name classifier\n * used by the scanner. It recognizes timber-only conventions (private\n * `_*`, parallel `@*`, route groups `(name)`, intercepting routes\n * `(.)`/`(..)`/`(...)`/`(..)(..)`) and delegates bracket syntax to\n * `classifyUrlSegment`. It is the **single source of truth** for what\n * counts as a routing segment — there is no separate copy in the\n * scanner. (TIM-848.)\n *\n * Malformed input falls through to `{ kind: 'static' }` — the safe default.\n *\n * If you change the bracket syntax, update ONLY this file. Every\n * consumer imports from here.\n *\n * See design/07-routing.md §\"Route Segments\"\n */\n\nimport type { InterceptionMarker, SegmentType } from './types.js';\nimport { INTERCEPTION_MARKERS } from './types.js';\n\nexport type UrlSegment =\n  | { kind: 'static'; value: string }\n  | { kind: 'dynamic'; name: string }\n  | { kind: 'catch-all'; name: string }\n  | { kind: 'optional-catch-all'; name: string };\n\n/**\n * Classify a URL path segment token.\n *\n * Walks the string left-to-right in one pass:\n *   1. If it doesn't start with '[', it's static.\n *   2. Count opening brackets (1 or 2) to detect optional.\n *   3. Check for '...' to detect catch-all.\n *   4. Read the param name up to the closing bracket.\n *   5. Validate the expected closing sequence (']' or ']]').\n *   6. Reject if there are leftover characters after the close.\n *\n * Any structural violation → static (safe default).\n */\nexport function classifyUrlSegment(token: string): UrlSegment {\n  const len = token.length;\n\n  // Must start with '[' to be dynamic\n  if (len === 0 || token[0] !== '[') {\n    return { kind: 'static', value: token };\n  }\n\n  let i = 1;\n\n  // Check for optional: '[[...'\n  const optional = token[i] === '[';\n  if (optional) i++;\n\n  // Check for catch-all: '...'\n  const catchAll = i + 2 < len && token[i] === '.' && token[i + 1] === '.' && token[i + 2] === '.';\n  if (catchAll) i += 3;\n\n  // Read param name — everything up to ']'\n  const nameStart = i;\n  while (i < len && token[i] !== ']') i++;\n\n  // Must have found a ']' and name must be non-empty\n  if (i >= len || i === nameStart) {\n    return { kind: 'static', value: token };\n  }\n\n  const name = token.slice(nameStart, i);\n  i++; // skip first ']'\n\n  // Optional requires a second ']'\n  if (optional) {\n    if (i >= len || token[i] !== ']') {\n      return { kind: 'static', value: token };\n    }\n    i++;\n  }\n\n  // Must be at end of string — no trailing characters\n  if (i !== len) {\n    return { kind: 'static', value: token };\n  }\n\n  if (optional && catchAll) return { kind: 'optional-catch-all', name };\n  if (catchAll) return { kind: 'catch-all', name };\n  if (optional) {\n    // '[[name]]' without '...' is malformed — not a valid segment syntax\n    return { kind: 'static', value: token };\n  }\n  return { kind: 'dynamic', name };\n}\n\n// ─── Directory-name classifier (build-time scanner) ─────────────────────────\n\n/** Result of classifying a filesystem directory name. */\nexport interface SegmentClassification {\n  type: SegmentType;\n  paramName?: string;\n  interceptionMarker?: InterceptionMarker;\n  interceptedSegmentName?: string;\n}\n\n/**\n * Classify a directory name into its segment type.\n *\n * Recognizes all timber file-system conventions in priority order:\n *   1. Private folders: `_name` (excluded from routing)\n *   2. Parallel route slots: `@name`\n *   3. Intercepting routes: `(.)name`, `(..)name`, `(...)name`, `(..)(..)name`\n *   4. Route groups: `(name)`\n *   5. Bracket syntax: `[id]`, `[...slug]`, `[[...path]]` (delegated to\n *      `classifyUrlSegment`)\n *   6. Static: anything else\n *\n * If you change the bracket syntax, update only `classifyUrlSegment`.\n * If you change the directory-prefix conventions, update this function.\n */\nexport function classifySegment(dirName: string): SegmentClassification {\n  // Private folder: _name (excluded from routing)\n  if (dirName.startsWith('_')) {\n    return { type: 'private' };\n  }\n\n  // Parallel route slot: @name\n  if (dirName.startsWith('@')) {\n    return { type: 'slot' };\n  }\n\n  // Intercepting routes: (.)name, (..)name, (...)name, (..)(..)name\n  // Check before route groups since intercepting markers also start with (\n  const interception = parseInterceptionMarker(dirName);\n  if (interception) {\n    return {\n      type: 'intercepting',\n      interceptionMarker: interception.marker,\n      interceptedSegmentName: interception.segmentName,\n    };\n  }\n\n  // Route group: (name)\n  if (dirName.startsWith('(') && dirName.endsWith(')')) {\n    return { type: 'group' };\n  }\n\n  // Bracket-syntax segments: [param], [...param], [[...param]]\n  const urlSeg = classifyUrlSegment(dirName);\n  if (urlSeg.kind !== 'static') {\n    return { type: urlSeg.kind, paramName: urlSeg.name };\n  }\n\n  return { type: 'static' };\n}\n\n/**\n * Parse an interception marker from a directory name.\n *\n * Returns the marker and the remaining segment name, or null if not an\n * intercepting route. Markers are checked longest-first to avoid `(..)`\n * matching before `(..)(..)`.\n *\n * Examples:\n *   \"(.)photo\"      → { marker: \"(.)\", segmentName: \"photo\" }\n *   \"(..)feed\"      → { marker: \"(..)\", segmentName: \"feed\" }\n *   \"(...)photos\"   → { marker: \"(...)\", segmentName: \"photos\" }\n *   \"(..)(..)admin\" → { marker: \"(..)(..)\", segmentName: \"admin\" }\n *   \"(marketing)\"   → null (route group, not interception)\n */\nfunction parseInterceptionMarker(\n  dirName: string\n): { marker: InterceptionMarker; segmentName: string } | null {\n  for (const marker of INTERCEPTION_MARKERS) {\n    if (dirName.startsWith(marker)) {\n      const rest = dirName.slice(marker.length);\n      // Must have a segment name after the marker, and the rest must not\n      // be empty or end with ) (which would be a route group like \"(auth)\")\n      if (rest.length > 0 && !rest.endsWith(')')) {\n        return { marker, segmentName: rest };\n      }\n    }\n  }\n  return null;\n}\n"],"mappings":";;AA4CA,IAAa,uBAA6C;CAAC;CAAY;CAAO;CAAQ;AAAO;;AA4G7F,IAAa,0BAA0B;CAAC;CAAO;CAAM;CAAO;AAAI;;;;;;;;;;;;;;;;AC1GhE,SAAgB,mBAAmB,OAA2B;CAC5D,MAAM,MAAM,MAAM;CAGlB,IAAI,QAAQ,KAAK,MAAM,OAAO,KAC5B,OAAO;EAAE,MAAM;EAAU,OAAO;CAAM;CAGxC,IAAI,IAAI;CAGR,MAAM,WAAW,MAAM,OAAO;CAC9B,IAAI,UAAU;CAGd,MAAM,WAAW,IAAI,IAAI,OAAO,MAAM,OAAO,OAAO,MAAM,IAAI,OAAO,OAAO,MAAM,IAAI,OAAO;CAC7F,IAAI,UAAU,KAAK;CAGnB,MAAM,YAAY;CAClB,OAAO,IAAI,OAAO,MAAM,OAAO,KAAK;CAGpC,IAAI,KAAK,OAAO,MAAM,WACpB,OAAO;EAAE,MAAM;EAAU,OAAO;CAAM;CAGxC,MAAM,OAAO,MAAM,MAAM,WAAW,CAAC;CACrC;CAGA,IAAI,UAAU;EACZ,IAAI,KAAK,OAAO,MAAM,OAAO,KAC3B,OAAO;GAAE,MAAM;GAAU,OAAO;EAAM;EAExC;CACF;CAGA,IAAI,MAAM,KACR,OAAO;EAAE,MAAM;EAAU,OAAO;CAAM;CAGxC,IAAI,YAAY,UAAU,OAAO;EAAE,MAAM;EAAsB;CAAK;CACpE,IAAI,UAAU,OAAO;EAAE,MAAM;EAAa;CAAK;CAC/C,IAAI,UAEF,OAAO;EAAE,MAAM;EAAU,OAAO;CAAM;CAExC,OAAO;EAAE,MAAM;EAAW;CAAK;AACjC;;;;;;;;;;;;;;;;AA2BA,SAAgB,gBAAgB,SAAwC;CAEtE,IAAI,QAAQ,WAAW,GAAG,GACxB,OAAO,EAAE,MAAM,UAAU;CAI3B,IAAI,QAAQ,WAAW,GAAG,GACxB,OAAO,EAAE,MAAM,OAAO;CAKxB,MAAM,eAAe,wBAAwB,OAAO;CACpD,IAAI,cACF,OAAO;EACL,MAAM;EACN,oBAAoB,aAAa;EACjC,wBAAwB,aAAa;CACvC;CAIF,IAAI,QAAQ,WAAW,GAAG,KAAK,QAAQ,SAAS,GAAG,GACjD,OAAO,EAAE,MAAM,QAAQ;CAIzB,MAAM,SAAS,mBAAmB,OAAO;CACzC,IAAI,OAAO,SAAS,UAClB,OAAO;EAAE,MAAM,OAAO;EAAM,WAAW,OAAO;CAAK;CAGrD,OAAO,EAAE,MAAM,SAAS;AAC1B;;;;;;;;;;;;;;;AAgBA,SAAS,wBACP,SAC4D;CAC5D,KAAK,MAAM,UAAU,sBACnB,IAAI,QAAQ,WAAW,MAAM,GAAG;EAC9B,MAAM,OAAO,QAAQ,MAAM,OAAO,MAAM;EAGxC,IAAI,KAAK,SAAS,KAAK,CAAC,KAAK,SAAS,GAAG,GACvC,OAAO;GAAE;GAAQ,aAAa;EAAK;CAEvC;CAEF,OAAO;AACT"}

package/dist/_chunks/segment-context-ZDnXDkbz.js

@@ -0,0 +1,34 @@
+import { createContext, createElement, useContext, useMemo } from "react";
+//#region src/client/segment-context.ts
+/**
+* Segment Context — provides layout segment position for useSelectedLayoutSegment hooks.
+*
+* Each layout in the segment tree is wrapped with a SegmentProvider that stores
+* the URL segments from root to the current layout level. The hooks read this
+* context to determine which child segments are active below the calling layout.
+*
+* The context value is intentionally minimal: just the segment path array and
+* parallel route keys. No internal cache details are exposed.
+*
+* Design docs: design/19-client-navigation.md, design/14-ecosystem.md
+*/
+var SegmentContext = createContext(null);
+/** Read the segment context. Returns null if no provider is above this component. */
+function useSegmentContext() {
+	return useContext(SegmentContext);
+}
+/**
+* Wraps each layout to provide segment position context.
+* Injected by rsc-entry.ts during element tree construction.
+*/
+function SegmentProvider({ segments, segmentId: _segmentId, parallelRouteKeys, children }) {
+	const value = useMemo(() => ({
+		segments,
+		parallelRouteKeys
+	}), [segments.join("/"), parallelRouteKeys.join(",")]);
+	return createElement(SegmentContext.Provider, { value }, children);
+}
+//#endregion
+export { useSegmentContext as n, SegmentProvider as t };
+
+//# sourceMappingURL=segment-context-ZDnXDkbz.js.map

package/dist/_chunks/segment-context-ZDnXDkbz.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"segment-context-ZDnXDkbz.js","names":[],"sources":["../../src/client/segment-context.ts"],"sourcesContent":["/**\n * Segment Context — provides layout segment position for useSelectedLayoutSegment hooks.\n *\n * Each layout in the segment tree is wrapped with a SegmentProvider that stores\n * the URL segments from root to the current layout level. The hooks read this\n * context to determine which child segments are active below the calling layout.\n *\n * The context value is intentionally minimal: just the segment path array and\n * parallel route keys. No internal cache details are exposed.\n *\n * Design docs: design/19-client-navigation.md, design/14-ecosystem.md\n */\n\n'use client';\n\nimport { createContext, useContext, createElement, useMemo } from 'react';\n\n// ─── Types ───────────────────────────────────────────────────────\n\nexport interface SegmentContextValue {\n  /** URL segments from root to this layout (e.g. ['', 'dashboard', 'settings']) */\n  segments: string[];\n  /** Parallel route slot keys available at this layout level (e.g. ['sidebar', 'modal']) */\n  parallelRouteKeys: string[];\n}\n\n// ─── Context ─────────────────────────────────────────────────────\n\nconst SegmentContext = createContext<SegmentContextValue | null>(null);\n\n/** Read the segment context. Returns null if no provider is above this component. */\nexport function useSegmentContext(): SegmentContextValue | null {\n  return useContext(SegmentContext);\n}\n\n// ─── Provider ────────────────────────────────────────────────────\n\ninterface SegmentProviderProps {\n  segments: string[];\n  /**\n   * Unique identifier for this segment, used by the client-side segment\n   * merger for element caching. For route groups this includes the group\n   * name (e.g., \"/(marketing)\") since groups share their parent's urlPath.\n   * Falls back to the reconstructed path from `segments` if not provided.\n   */\n  segmentId?: string;\n  parallelRouteKeys: string[];\n  children: React.ReactNode;\n}\n\n/**\n * Wraps each layout to provide segment position context.\n * Injected by rsc-entry.ts during element tree construction.\n */\nexport function SegmentProvider({\n  segments,\n  segmentId: _segmentId,\n  parallelRouteKeys,\n  children,\n}: SegmentProviderProps) {\n  const value = useMemo(\n    () => ({ segments, parallelRouteKeys }),\n    // segments and parallelRouteKeys are static per layout — they don't change\n    // across navigations. The layout's position in the tree is fixed.\n    // Intentionally using derived keys — segments/parallelRouteKeys are static per layout\n    [segments.join('/'), parallelRouteKeys.join(',')]\n  );\n  return createElement(SegmentContext.Provider, { value }, children);\n}\n"],"mappings":";;;;;;;;;;;;;;AA4BA,IAAM,iBAAiB,cAA0C,IAAI;;AAGrE,SAAgB,oBAAgD;CAC9D,OAAO,WAAW,cAAc;AAClC;;;;;AAqBA,SAAgB,gBAAgB,EAC9B,UACA,WAAW,YACX,mBACA,YACuB;CACvB,MAAM,QAAQ,eACL;EAAE;EAAU;CAAkB,IAIrC,CAAC,SAAS,KAAK,GAAG,GAAG,kBAAkB,KAAK,GAAG,CAAC,CAClD;CACA,OAAO,cAAc,eAAe,UAAU,EAAE,MAAM,GAAG,QAAQ;AACnE"}

package/dist/_chunks/{ssr-data-MjmprTmO.js → ssr-data-BOWsq18U.js}

@@ -85,4 +85,4 @@ function getSsrData() {
 //#endregion
 export { _setCurrentParams as a, cachedSearchParams as c, _setCachedSearch as i, currentParams as l, getSsrData as n, _setGlobalRouter as o, setSsrData as r, cachedSearch as s, clearSsrData as t, globalRouter as u };
 
-//# sourceMappingURL=ssr-data-MjmprTmO.js.map
+//# sourceMappingURL=ssr-data-BOWsq18U.js.map

package/dist/_chunks/ssr-data-BOWsq18U.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssr-data-BOWsq18U.js","names":[],"sources":["../../src/client/state.ts","../../src/client/ssr-data.ts"],"sourcesContent":["/**\n * Centralized client singleton state registry.\n *\n * ALL mutable module-level state that must have singleton semantics across\n * the client bundle lives here. Individual modules (router-ref.ts, ssr-data.ts,\n * use-segment-params.ts, use-search-params.ts, unload-guard.ts) import from this file\n * and re-export thin wrapper functions.\n *\n * Why: In Vite dev, a module is instantiated separately if reached via different\n * import paths (e.g., relative `./foo.js` vs barrel `@timber-js/app/client`).\n * By centralizing all mutable state in a single module that is always reached\n * through the same dependency chain (barrel → wrapper → state.ts), we guarantee\n * a single instance of every piece of shared state.\n *\n * DO NOT import this file from outside client/. Server code must never depend\n * on client state. The barrel (client/index.ts) is the public entry point.\n *\n * See design/18-build-system.md §\"Module Singleton Strategy\" and\n * §\"Singleton State Registry\".\n */\n\nimport type { RouterInstance } from './router.js';\nimport type { SsrData } from './ssr-data.js';\n\n// ─── Router (from router-ref.ts) ──────────────────────────────────────────\n\n/** The global router singleton — set once during bootstrap. */\nexport let globalRouter: RouterInstance | null = null;\n\nexport function _setGlobalRouter(router: RouterInstance | null): void {\n  globalRouter = router;\n}\n\n// ─── SSR Data Provider (from ssr-data.ts) ──────────────────────────────────\n\n/**\n * ALS-backed SSR data provider. When registered, getSsrData() reads from\n * this function (ALS store) instead of module-level currentSsrData.\n */\nexport let ssrDataProvider: (() => SsrData | undefined) | undefined;\n\nexport function _setSsrDataProvider(provider: (() => SsrData | undefined) | undefined): void {\n  ssrDataProvider = provider;\n}\n\n/** Fallback SSR data for tests and environments without ALS. */\nexport let currentSsrData: SsrData | undefined;\n\nexport function _setCurrentSsrData(data: SsrData | undefined): void {\n  currentSsrData = data;\n}\n\n// ─── Route Params (from use-segment-params.ts) ──────────────────────────────────────\n\n/** Current route params snapshot — replaced (not mutated) on each navigation. */\nexport let currentParams: Record<string, string | string[]> = {};\n\nexport function _setCurrentParams(params: Record<string, string | string[]>): void {\n  currentParams = params;\n}\n\n/** Listeners notified when currentParams changes. */\nexport const paramsListeners = new Set<() => void>();\n\n// ─── Search Params Cache (from use-search-params.ts) ────────────────────────\n\n/** Cached search string — avoids reparsing when URL hasn't changed. */\nexport let cachedSearch = '';\nexport let cachedSearchParams = new URLSearchParams();\n\nexport function _setCachedSearch(search: string, params: URLSearchParams): void {\n  cachedSearch = search;\n  cachedSearchParams = params;\n}\n\n// ─── Unload Guard (from unload-guard.ts) ─────────────────────────────────────\n\n/** Whether the page is currently being unloaded. */\nexport let unloading = false;\n\nexport function _setUnloading(value: boolean): void {\n  unloading = value;\n}\n","/**\n * SSR Data — per-request state for client hooks during server-side rendering.\n *\n * RSC and SSR are separate Vite module graphs (see design/18-build-system.md),\n * so the RSC environment's request-context ALS is not visible to SSR modules.\n * This module provides getter/setter functions that ssr-entry.ts uses to\n * populate per-request data for React's render.\n *\n * Request isolation: On the server, ssr-entry.ts registers an ALS-backed\n * provider via registerSsrDataProvider(). getSsrData() reads from the ALS\n * store, ensuring correct per-request data even when Suspense boundaries\n * resolve asynchronously across concurrent requests. The module-level\n * setSsrData/clearSsrData functions are kept as a fallback for tests\n * and environments without ALS.\n *\n * IMPORTANT: This module must NOT import node:async_hooks or any Node.js-only\n * APIs, as it's imported by 'use client' hooks that are bundled for the browser.\n * The ALS instance lives in ssr-entry.ts (server-only); this module only holds\n * a reference to the provider function.\n *\n * All mutable state is delegated to client/state.ts for singleton guarantees.\n * See design/18-build-system.md §\"Singleton State Registry\"\n */\n\nimport {\n  ssrDataProvider,\n  currentSsrData,\n  _setSsrDataProvider,\n  _setCurrentSsrData,\n} from './state.js';\n\n// ─── Types ────────────────────────────────────────────────────────\n\nexport interface SsrData {\n  /** The request's URL pathname (e.g. '/dashboard/settings') */\n  pathname: string;\n  /** The request's search params as a plain record */\n  searchParams: Record<string, string>;\n  /** The request's cookies as name→value pairs */\n  cookies: Map<string, string>;\n  /** The request's route params (e.g. { id: '123' }) */\n  params: Record<string, string | string[]>;\n  /**\n   * Mutable reference to NavContext for error boundary → pipeline communication.\n   *\n   * When TimberErrorBoundary catches a DenySignal during SSR, it:\n   * 1. Sets `statusCode` to the deny status (e.g., 403) — so the HTTP\n   *    Response has the correct status code without a re-render.\n   * 2. Sets `_denyHandledByBoundary = true` — so the pipeline skips\n   *    the redundant renderDenyPage() re-render.\n   *\n   * This runs synchronously during Fizz rendering, BEFORE onShellReady,\n   * so the status code is committed before any bytes are sent.\n   *\n   * See TIM-664, design/04-authorization.md §\"React.cache Scope in Deny/Error Re-renders\"\n   */\n  _navContext?: { statusCode?: number; _denyHandledByBoundary?: boolean };\n}\n\n// ─── ALS-Backed Provider ─────────────────────────────────────────\n//\n// Server-side code (ssr-entry.ts) registers a provider that reads\n// from AsyncLocalStorage. This avoids importing node:async_hooks\n// in this browser-bundled module.\n//\n// Module singleton guarantee: In Vite's SSR environment, both\n// ssr-entry.ts (via #/client/ssr-data.js) and client component hooks\n// (via @timber-js/app/client) must resolve to the SAME module instance\n// of this file. The timber-shims plugin ensures this by remapping\n// @timber-js/app/client → src/client/index.ts in the SSR environment.\n// Without this remap, @timber-js/app/client resolves to dist/ (via\n// package.json exports), creating a split where registerSsrDataProvider\n// writes to one instance but getSsrData reads from another.\n// See timber-shims plugin resolveId for details.\n\n/**\n * Register an ALS-backed SSR data provider. Called once at module load\n * by ssr-entry.ts to wire up per-request data via AsyncLocalStorage.\n *\n * When registered, getSsrData() reads from the provider (ALS store)\n * instead of module-level state, ensuring correct isolation for\n * concurrent requests with streaming Suspense.\n */\nexport function registerSsrDataProvider(provider: () => SsrData | undefined): void {\n  _setSsrDataProvider(provider);\n}\n\n// ─── Module-Level Fallback ────────────────────────────────────────\n//\n// Used by tests and as a fallback when no ALS provider is registered.\n\n/**\n * Set the SSR data for the current request via module-level state.\n *\n * In production, ssr-entry.ts uses ALS (runWithSsrData) instead.\n * This function is retained for tests and as a fallback.\n */\nexport function setSsrData(data: SsrData): void {\n  _setCurrentSsrData(data);\n}\n\n/**\n * Clear the SSR data after rendering completes.\n *\n * In production, ALS scope handles cleanup automatically.\n * This function is retained for tests and as a fallback.\n */\nexport function clearSsrData(): void {\n  _setCurrentSsrData(undefined);\n}\n\n/**\n * Read the current request's SSR data. Returns undefined when called\n * outside an SSR render (i.e. on the client after hydration).\n *\n * Prefers the ALS-backed provider when registered (server-side),\n * falling back to module-level state (tests, legacy).\n *\n * Used by client hooks' server snapshot functions.\n */\nexport function getSsrData(): SsrData | undefined {\n  if (ssrDataProvider) {\n    return ssrDataProvider();\n  }\n  return currentSsrData;\n}\n"],"mappings":";;AA2BA,IAAW,eAAsC;AAEjD,SAAgB,iBAAiB,QAAqC;CACpE,eAAe;AACjB;;;;;AAQA,IAAW;;AAOX,IAAW;AAEX,SAAgB,mBAAmB,MAAiC;CAClE,iBAAiB;AACnB;;AAKA,IAAW,gBAAmD,CAAC;AAE/D,SAAgB,kBAAkB,QAAiD;CACjF,gBAAgB;AAClB;;AAQA,IAAW,eAAe;AAC1B,IAAW,qBAAqB,IAAI,gBAAgB;AAEpD,SAAgB,iBAAiB,QAAgB,QAA+B;CAC9E,eAAe;CACf,qBAAqB;AACvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACwBA,SAAgB,WAAW,MAAqB;CAC9C,mBAAmB,IAAI;AACzB;;;;;;;AAQA,SAAgB,eAAqB;CACnC,mBAAmB,KAAA,CAAS;AAC9B;;;;;;;;;;AAWA,SAAgB,aAAkC;CAChD,IAAI,iBACF,OAAO,gBAAgB;CAEzB,OAAO;AACT"}

package/dist/_chunks/tree-match-D2l830j2.js

@@ -0,0 +1,102 @@
+//#region src/server/tree-match.ts
+/**
+* Match URL path parts against a segment tree.
+*
+* Walks the tree depth-first with backtracking, applying priority
+* ordering globally across group boundaries. Returns the matched
+* segment chain and collected params, or null if no route matches.
+*
+* By default, a match requires a terminal node (one with `page` or
+* `route`) at the leaf. Pass `{ requireTerminal: false }` to match
+* any segment (used by metadata route matching).
+*
+* @param root  The root segment node to start matching from.
+* @param parts URL path parts (e.g. ['blog', 'hello-world']).
+*              Empty array matches the root itself (if terminal).
+*/
+function matchUrlParts(root, parts, options) {
+	const chain = [];
+	const params = {};
+	if (matchNode(root, parts, 0, chain, params, options?.requireTerminal ?? true)) return {
+		chain,
+		params
+	};
+	return null;
+}
+/**
+* Flatten children through group segments.
+*
+* Groups are transparent for URL matching — their non-group descendants
+* are returned with the chain of group nodes leading to them. This lets
+* the caller apply priority ordering (static > dynamic > catch-all >
+* optional-catch-all) across all groups uniformly instead of per-group.
+*/
+function collectEffectiveChildren(node, groupChain = []) {
+	const result = [];
+	for (const child of node.children) if (child.segmentType === "group") {
+		const nested = collectEffectiveChildren(child, [...groupChain, child]);
+		result.push(...nested);
+	} else result.push({
+		child,
+		groupChain
+	});
+	return result;
+}
+/** A node is terminal if it can serve a response (has a page or route handler). */
+function isTerminal(node) {
+	return !!(node.page || node.route);
+}
+/**
+* Recursive depth-first matcher with backtracking.
+*
+* Mutates `chain` and `params` in place for performance; backtracks
+* (restores previous state) when a candidate doesn't lead to a match.
+*/
+function matchNode(node, parts, index, chain, params, requireTerminal) {
+	chain.push(node);
+	if (index >= parts.length) {
+		if (!requireTerminal || isTerminal(node)) return true;
+		for (const child of node.children) if (child.segmentType === "group") {
+			if (matchNode(child, parts, index, chain, params, requireTerminal)) return true;
+		}
+		const effective = collectEffectiveChildren(node);
+		for (const { child, groupChain } of effective) if (child.segmentType === "optional-catch-all" && (!requireTerminal || isTerminal(child))) {
+			chain.push(...groupChain, child);
+			return true;
+		}
+		chain.pop();
+		return false;
+	}
+	const part = parts[index];
+	const effective = collectEffectiveChildren(node);
+	for (const { child, groupChain } of effective) if (child.segmentType === "static" && child.segmentName === part) {
+		chain.push(...groupChain);
+		if (matchNode(child, parts, index + 1, chain, params, requireTerminal)) return true;
+		chain.length -= groupChain.length;
+	}
+	for (const { child, groupChain } of effective) if (child.segmentType === "dynamic" && child.paramName) {
+		chain.push(...groupChain);
+		const prev = params[child.paramName];
+		params[child.paramName] = part;
+		if (matchNode(child, parts, index + 1, chain, params, requireTerminal)) return true;
+		chain.length -= groupChain.length;
+		if (prev !== void 0) params[child.paramName] = prev;
+		else delete params[child.paramName];
+	}
+	for (const { child, groupChain } of effective) if (child.segmentType === "catch-all" && child.paramName && (!requireTerminal || isTerminal(child))) {
+		chain.push(...groupChain, child);
+		params[child.paramName] = parts.slice(index);
+		return true;
+	}
+	for (const { child, groupChain } of effective) if (child.segmentType === "optional-catch-all" && child.paramName && (!requireTerminal || isTerminal(child))) {
+		chain.push(...groupChain, child);
+		params[child.paramName] = parts.slice(index);
+		return true;
+	}
+	chain.pop();
+	return false;
+}
+//#endregion
+export { matchUrlParts as t };
+
+//# sourceMappingURL=tree-match-D2l830j2.js.map