@timber-js/app 0.2.0-alpha.186 → 0.2.0-alpha.188

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

@@ -1 +1 @@
-{"version":3,"file":"segment-classify-C539Pa2O.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 * `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  /** Literal prefix before the dynamic bracket (e.g. \"img-\" for \"img-[id].png\") */\n  paramPrefix?: string;\n  /** Literal suffix after the dynamic bracket (e.g. \".png\" for \"img-[id].png\") */\n  paramSuffix?: 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\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; prefix?: string; suffix?: 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. Find the first '[' — characters before it are the prefix.\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. Characters after the close are the suffix.\n *   7. Reject affixes on catch-all/optional-catch-all.\n *   8. Reject affixes that contain '[' or ']' (no multi-param segments).\n *\n * Any structural violation → static (safe default).\n */\nexport function classifyUrlSegment(token: string): UrlSegment {\n  const len = token.length;\n  if (len === 0) return { kind: 'static', value: token };\n\n  // Find first '[' — characters before it are the prefix\n  const bracketStart = token.indexOf('[');\n  if (bracketStart === -1) return { kind: 'static', value: token };\n\n  const prefix = token.slice(0, bracketStart);\n\n  let i = bracketStart + 1;\n\n  // Check for optional: '[[...'\n  const optional = i < len && 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  const suffix = token.slice(i);\n\n  // Reject affixes containing brackets (no multi-param segments like [foo]-[bar])\n  if (suffix.includes('[') || suffix.includes(']')) {\n    return { kind: 'static', value: token };\n  }\n  if (prefix.includes(']')) {\n    return { kind: 'static', value: token };\n  }\n\n  const hasAffixes = prefix.length > 0 || suffix.length > 0;\n\n  if (optional && catchAll) {\n    // No affixes on optional catch-all\n    if (hasAffixes) return { kind: 'static', value: token };\n    return { kind: 'optional-catch-all', name };\n  }\n  if (catchAll) {\n    // No affixes on catch-all\n    if (hasAffixes) return { kind: 'static', value: token };\n    return { kind: 'catch-all', name };\n  }\n  if (optional) {\n    // '[[name]]' without '...' is malformed — not a valid segment syntax\n    return { kind: 'static', value: token };\n  }\n\n  if (hasAffixes) {\n    return {\n      kind: 'dynamic',\n      name,\n      prefix: prefix || undefined,\n      suffix: suffix || undefined,\n    };\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  paramPrefix?: string;\n  paramSuffix?: 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    const result: SegmentClassification = { type: urlSeg.kind, paramName: urlSeg.name };\n    if (urlSeg.kind === 'dynamic') {\n      if (urlSeg.prefix) result.paramPrefix = urlSeg.prefix;\n      if (urlSeg.suffix) result.paramSuffix = urlSeg.suffix;\n    }\n    return result;\n  }\n\n  return { type: 'static' };\n}\n\n/**\n * The URL-matching identity of a segment node.\n *\n * For every node except an intercepting one this is the node itself. An\n * intercepting node is different: its directory name carries a marker\n * (`(.)photo`, `(.)[id]`), so the node's own `segmentType` is\n * `'intercepting'` and the bracket syntax of the segment it intercepts was\n * never classified. Everything that has to reason about *the URL part this\n * node stands for* — matching it, and keying its param for codec coercion —\n * needs that classification.\n *\n * Deriving it here, from `interceptedSegmentName`, keeps interception out\n * of `classifySegment`'s output and out of the serialized manifest: there\n * is no second copy of the classification to drift from this one. The\n * returned `segmentName` is the intercepted name (`photo`, `[id]`), NOT the\n * node's directory name — callers that need the directory name for tree\n * paths must keep reading the node. See TIM-1281.\n */\nexport interface UrlSegmentIdentity {\n  segmentName: string;\n  segmentType: SegmentType;\n  paramName?: string;\n  paramPrefix?: string;\n  paramSuffix?: string;\n}\n\nexport function effectiveUrlSegment(node: {\n  segmentName: string;\n  segmentType: SegmentType;\n  paramName?: string;\n  paramPrefix?: string;\n  paramSuffix?: string;\n  interceptedSegmentName?: string;\n}): UrlSegmentIdentity {\n  if (node.segmentType !== 'intercepting' || !node.interceptedSegmentName) {\n    return {\n      segmentName: node.segmentName,\n      segmentType: node.segmentType,\n      paramName: node.paramName,\n      paramPrefix: node.paramPrefix,\n      paramSuffix: node.paramSuffix,\n    };\n  }\n\n  const seg = classifyUrlSegment(node.interceptedSegmentName);\n  if (seg.kind === 'static') {\n    return { segmentName: seg.value, segmentType: 'static' };\n  }\n  return {\n    segmentName: node.interceptedSegmentName,\n    segmentType: seg.kind,\n    paramName: seg.name,\n    paramPrefix: seg.kind === 'dynamic' ? seg.prefix : undefined,\n    paramSuffix: seg.kind === 'dynamic' ? seg.suffix : undefined,\n  };\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;;AA8G7F,IAAa,0BAA0B;CAAC;CAAO;CAAM;CAAO;AAAI;;;;;;;;;;;;;;;;;;AC1GhE,SAAgB,mBAAmB,OAA2B;CAC5D,MAAM,MAAM,MAAM;CAClB,IAAI,QAAQ,GAAG,OAAO;EAAE,MAAM;EAAU,OAAO;CAAM;CAGrD,MAAM,eAAe,MAAM,QAAQ,GAAG;CACtC,IAAI,iBAAiB,IAAI,OAAO;EAAE,MAAM;EAAU,OAAO;CAAM;CAE/D,MAAM,SAAS,MAAM,MAAM,GAAG,YAAY;CAE1C,IAAI,IAAI,eAAe;CAGvB,MAAM,WAAW,IAAI,OAAO,MAAM,OAAO;CACzC,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;CAEA,MAAM,SAAS,MAAM,MAAM,CAAC;CAG5B,IAAI,OAAO,SAAS,GAAG,KAAK,OAAO,SAAS,GAAG,GAC7C,OAAO;EAAE,MAAM;EAAU,OAAO;CAAM;CAExC,IAAI,OAAO,SAAS,GAAG,GACrB,OAAO;EAAE,MAAM;EAAU,OAAO;CAAM;CAGxC,MAAM,aAAa,OAAO,SAAS,KAAK,OAAO,SAAS;CAExD,IAAI,YAAY,UAAU;EAExB,IAAI,YAAY,OAAO;GAAE,MAAM;GAAU,OAAO;EAAM;EACtD,OAAO;GAAE,MAAM;GAAsB;EAAK;CAC5C;CACA,IAAI,UAAU;EAEZ,IAAI,YAAY,OAAO;GAAE,MAAM;GAAU,OAAO;EAAM;EACtD,OAAO;GAAE,MAAM;GAAa;EAAK;CACnC;CACA,IAAI,UAEF,OAAO;EAAE,MAAM;EAAU,OAAO;CAAM;CAGxC,IAAI,YACF,OAAO;EACL,MAAM;EACN;EACA,QAAQ,UAAU,KAAA;EAClB,QAAQ,UAAU,KAAA;CACpB;CAEF,OAAO;EAAE,MAAM;EAAW;CAAK;AACjC;;;;;;;;;;;;;;;;AA6BA,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,UAAU;EAC5B,MAAM,SAAgC;GAAE,MAAM,OAAO;GAAM,WAAW,OAAO;EAAK;EAClF,IAAI,OAAO,SAAS,WAAW;GAC7B,IAAI,OAAO,QAAQ,OAAO,cAAc,OAAO;GAC/C,IAAI,OAAO,QAAQ,OAAO,cAAc,OAAO;EACjD;EACA,OAAO;CACT;CAEA,OAAO,EAAE,MAAM,SAAS;AAC1B;AA4BA,SAAgB,oBAAoB,MAOb;CACrB,IAAI,KAAK,gBAAgB,kBAAkB,CAAC,KAAK,wBAC/C,OAAO;EACL,aAAa,KAAK;EAClB,aAAa,KAAK;EAClB,WAAW,KAAK;EAChB,aAAa,KAAK;EAClB,aAAa,KAAK;CACpB;CAGF,MAAM,MAAM,mBAAmB,KAAK,sBAAsB;CAC1D,IAAI,IAAI,SAAS,UACf,OAAO;EAAE,aAAa,IAAI;EAAO,aAAa;CAAS;CAEzD,OAAO;EACL,aAAa,KAAK;EAClB,aAAa,IAAI;EACjB,WAAW,IAAI;EACf,aAAa,IAAI,SAAS,YAAY,IAAI,SAAS,KAAA;EACnD,aAAa,IAAI,SAAS,YAAY,IAAI,SAAS,KAAA;CACrD;AACF;;;;;;;;;;;;;;;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"}
+{"version":3,"file":"segment-classify-C539Pa2O.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 * `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  /** Literal prefix before the dynamic bracket (e.g. \"img-\" for \"img-[id].png\") */\n  paramPrefix?: string;\n  /** Literal suffix after the dynamic bracket (e.g. \".png\" for \"img-[id].png\") */\n  paramSuffix?: 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  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\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; prefix?: string; suffix?: 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. Find the first '[' — characters before it are the prefix.\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. Characters after the close are the suffix.\n *   7. Reject affixes on catch-all/optional-catch-all.\n *   8. Reject affixes that contain '[' or ']' (no multi-param segments).\n *\n * Any structural violation → static (safe default).\n */\nexport function classifyUrlSegment(token: string): UrlSegment {\n  const len = token.length;\n  if (len === 0) return { kind: 'static', value: token };\n\n  // Find first '[' — characters before it are the prefix\n  const bracketStart = token.indexOf('[');\n  if (bracketStart === -1) return { kind: 'static', value: token };\n\n  const prefix = token.slice(0, bracketStart);\n\n  let i = bracketStart + 1;\n\n  // Check for optional: '[[...'\n  const optional = i < len && 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  const suffix = token.slice(i);\n\n  // Reject affixes containing brackets (no multi-param segments like [foo]-[bar])\n  if (suffix.includes('[') || suffix.includes(']')) {\n    return { kind: 'static', value: token };\n  }\n  if (prefix.includes(']')) {\n    return { kind: 'static', value: token };\n  }\n\n  const hasAffixes = prefix.length > 0 || suffix.length > 0;\n\n  if (optional && catchAll) {\n    // No affixes on optional catch-all\n    if (hasAffixes) return { kind: 'static', value: token };\n    return { kind: 'optional-catch-all', name };\n  }\n  if (catchAll) {\n    // No affixes on catch-all\n    if (hasAffixes) return { kind: 'static', value: token };\n    return { kind: 'catch-all', name };\n  }\n  if (optional) {\n    // '[[name]]' without '...' is malformed — not a valid segment syntax\n    return { kind: 'static', value: token };\n  }\n\n  if (hasAffixes) {\n    return {\n      kind: 'dynamic',\n      name,\n      prefix: prefix || undefined,\n      suffix: suffix || undefined,\n    };\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  paramPrefix?: string;\n  paramSuffix?: 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    const result: SegmentClassification = { type: urlSeg.kind, paramName: urlSeg.name };\n    if (urlSeg.kind === 'dynamic') {\n      if (urlSeg.prefix) result.paramPrefix = urlSeg.prefix;\n      if (urlSeg.suffix) result.paramSuffix = urlSeg.suffix;\n    }\n    return result;\n  }\n\n  return { type: 'static' };\n}\n\n/**\n * The URL-matching identity of a segment node.\n *\n * For every node except an intercepting one this is the node itself. An\n * intercepting node is different: its directory name carries a marker\n * (`(.)photo`, `(.)[id]`), so the node's own `segmentType` is\n * `'intercepting'` and the bracket syntax of the segment it intercepts was\n * never classified. Everything that has to reason about *the URL part this\n * node stands for* — matching it, and keying its param for codec coercion —\n * needs that classification.\n *\n * Deriving it here, from `interceptedSegmentName`, keeps interception out\n * of `classifySegment`'s output and out of the serialized manifest: there\n * is no second copy of the classification to drift from this one. The\n * returned `segmentName` is the intercepted name (`photo`, `[id]`), NOT the\n * node's directory name — callers that need the directory name for tree\n * paths must keep reading the node. See TIM-1281.\n */\nexport interface UrlSegmentIdentity {\n  segmentName: string;\n  segmentType: SegmentType;\n  paramName?: string;\n  paramPrefix?: string;\n  paramSuffix?: string;\n}\n\nexport function effectiveUrlSegment(node: {\n  segmentName: string;\n  segmentType: SegmentType;\n  paramName?: string;\n  paramPrefix?: string;\n  paramSuffix?: string;\n  interceptedSegmentName?: string;\n}): UrlSegmentIdentity {\n  if (node.segmentType !== 'intercepting' || !node.interceptedSegmentName) {\n    return {\n      segmentName: node.segmentName,\n      segmentType: node.segmentType,\n      paramName: node.paramName,\n      paramPrefix: node.paramPrefix,\n      paramSuffix: node.paramSuffix,\n    };\n  }\n\n  const seg = classifyUrlSegment(node.interceptedSegmentName);\n  if (seg.kind === 'static') {\n    return { segmentName: seg.value, segmentType: 'static' };\n  }\n  return {\n    segmentName: node.interceptedSegmentName,\n    segmentType: seg.kind,\n    paramName: seg.name,\n    paramPrefix: seg.kind === 'dynamic' ? seg.prefix : undefined,\n    paramSuffix: seg.kind === 'dynamic' ? seg.suffix : undefined,\n  };\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":"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"}

package/dist/_chunks/{param-value-C8TNYchQ.js → segment-context-CjOlyB8Y.js}

@@ -1,3 +1,4 @@
+import { createContext, createElement, useContext, useMemo } from "react";
 //#region src/shared/param-value.ts
 /** The domain, for error messages. Derived, never a second hand-written list. */
 var DOMAIN = `a string, number, boolean, bigint, null, undefined, a plain object, an array, or ${[
@@ -61,6 +62,36 @@ function keyLabel(key) {
 	return typeof key === "string" ? JSON.stringify(key) : String(key);
 }
 //#endregion
-export { normalizeParamValue as t };
+//#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, normalizeParamValue as r, SegmentProvider as t };
 
-//# sourceMappingURL=param-value-C8TNYchQ.js.map
+//# sourceMappingURL=segment-context-CjOlyB8Y.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"segment-context-CjOlyB8Y.js","names":[],"sources":["../../src/shared/param-value.ts","../../src/client/segment-context.ts"],"sourcesContent":["/**\n * The canonical form of a segment param value.\n *\n * `getSegmentParams()` on the server and `useSegmentParams()` on the client\n * must return the same value — same prototype, same own properties. This\n * module is how that is guaranteed, and the mechanism matters:\n *\n * **Both sides are images of one normalizer.** A codec's output is deep-cloned\n * into a closed canonical domain at coercion time, and *that clone* is what the\n * server returns and what goes on the wire. Server and client agree by\n * construction, because neither holds the codec's original.\n *\n * That replaces predicting what React Flight would do to an arbitrary value.\n * Prediction is what the previous design attempted and it cannot be finished:\n * the question \"will Flight's decode output be observably identical to this\n * input?\" ranges over every way a JS object can carry state that is not in its\n * serialization — own keys, enumerability, symbols, holes, accessors,\n * subclassing, exotic objects — and a `Proxy` defeats it outright, since a\n * lying `getPrototypeOf` trap makes any static check unsound. Twelve review\n * findings on PR #992 were each one more case of that set, and the set does\n * not close.\n *\n * Normalizing closes it. The only remaining question is whether Flight\n * round-trips the normalizer's *output range* — a finite domain we defined,\n * covered by `tests/e2e/segment-params.test.ts` against the real serializer.\n *\n * ## The domain\n *\n * - `undefined`, `null`, `string`, `number`, `boolean`, `bigint`\n * - null-prototype objects, own enumerable string keys only\n * - dense arrays\n * - `Date`, `Map`, `Set` — rebuilt, never the codec's instance\n *\n * ...and it is a **tree**: no value appears twice, and nothing is cyclic.\n * That is not a simplification, it is the last prediction being removed.\n * Flight encodes a `Date` by value at each occurrence but tracks plain objects\n * for reference dedup, so preserving aliasing would carry it across for some\n * types and drop it for others — and knowing which is exactly the kind of\n * guess this design exists to stop making (codex, PR #992). A tree has no\n * sharing to preserve or lose, so what Flight does about it is unobservable.\n *\n * Anything else throws, naming the param and what it was. Note what is *not*\n * a rejection: a `Date` subclass normalizes to a `Date`, a decorated array to\n * a plain one, a sparse array to a dense one, a getter to the value it\n * returned. Those used to be twelve separate checks. They are not divergences\n * any more, because the normalization happens once and both sides see its\n * result — so they need no checks at all.\n *\n * Own properties that Flight would drop (non-enumerable, symbol-keyed) are\n * dropped here instead, symmetrically. Prototype pollution is handled by the\n * same pass: `__proto__` is never copied, and every object is\n * `Object.create(null)` (design/13-security.md #36b/#36c, TIM-873).\n *\n * ## The prototype flip\n *\n * Flight refuses to serialize a null-prototype object, so the canonical form\n * cannot go on the wire as-is. `toPlainRecord` and `toNullProtoRecord` flip\n * the prototype on the way out and back. They are exact inverses and both\n * total, because they only ever see canonical values — there is nothing to\n * validate and no shape to special-case.\n *\n * See design/41-global-params.md §\"Transport\".\n */\n\n/** Types the canonical form rebuilds rather than rejects. */\nconst REBUILT = ['Date', 'Map', 'Set'] as const;\n\n/** The domain, for error messages. Derived, never a second hand-written list. */\nconst DOMAIN = `a string, number, boolean, bigint, null, undefined, a plain object, an array, or ${REBUILT.join('/')}`;\n\nfunction reject(path: string, was: string, hint: string): never {\n  throw new Error(\n    `[timber] Segment param \"${path || '(root)'}\" was coerced to ${was}, which cannot ` +\n      `cross to the client. A param value may be ${DOMAIN}.\\n` +\n      `  ${hint}\\n` +\n      `  See design/41-global-params.md §\"Transport\".`\n  );\n}\n\nfunction describe(value: object): string {\n  return (value as { constructor?: { name?: string } }).constructor?.name ?? 'an object';\n}\n\n/**\n * Deep-clone a codec's output into the canonical form, or throw.\n *\n * `seen` accumulates every object the walk has entered, and a second encounter\n * is rejected. That is one rule for two things — a shared reference and a cycle\n * are both \"this object again\" — and it is what keeps the result a tree.\n */\nexport function normalizeParamValue(value: unknown, path = ''): unknown {\n  return normalize(value, path, new Set());\n}\n\nfunction normalize(value: unknown, path: string, seen: Set<object>): unknown {\n  if (value === null) return null;\n\n  const kind = typeof value;\n  if (kind === 'string' || kind === 'number' || kind === 'boolean' || kind === 'bigint') {\n    return value;\n  }\n  if (kind === 'undefined') return undefined;\n  if (kind === 'function') {\n    reject(path, 'a function', 'Return the data it would produce, not the function.');\n  }\n  if (kind === 'symbol') {\n    reject(path, 'a symbol', 'Return a string instead — a symbol has no wire representation.');\n  }\n\n  const object = value as object;\n  if (seen.has(object)) {\n    throw new Error(\n      `[timber] Segment param \"${path || '(root)'}\" is a value that already appears ` +\n        `elsewhere in the same param — a shared reference or a cycle. A param value is a ` +\n        `tree: React Flight carries a repeated \\`Date\\` by value and a repeated object by ` +\n        `reference, so sharing would survive for some types and not others.\\n` +\n        `  Return separate values, or move the shared part outside the params.\\n` +\n        `  See design/41-global-params.md §\"Transport\".`\n    );\n  }\n  seen.add(object);\n\n  if (Array.isArray(object)) {\n    // Read by index, so holes become `undefined` — on both sides, which is\n    // the point. A subclass and any own properties are left behind for the\n    // same reason: the clone is a plain, dense array either way.\n    const out: unknown[] = [];\n    for (let index = 0; index < object.length; index++) {\n      out.push(normalize((object as unknown[])[index], `${path}[${index}]`, seen));\n    }\n    return out;\n  }\n\n  if (object instanceof Date) {\n    // A fresh Date, so a subclass or an attached property cannot travel half\n    // way and be dropped by the wire.\n    return new Date(object.getTime());\n  }\n\n  if (object instanceof Map) {\n    const out = new Map<unknown, unknown>();\n    for (const [key, entry] of object) {\n      out.set(\n        normalize(key, `${path}<key>`, seen),\n        normalize(entry, `${path}.get(${keyLabel(key)})`, seen)\n      );\n    }\n    return out;\n  }\n\n  if (object instanceof Set) {\n    const out = new Set<unknown>();\n    let index = 0;\n    for (const entry of object) out.add(normalize(entry, `${path}[${index++}]`, seen));\n    return out;\n  }\n\n  // Everything else is judged by its prototype. A `Proxy` can lie here, and\n  // that is fine: whatever it answers, the clone below reads through it once\n  // and both sides see the same snapshot.\n  const prototype = Object.getPrototypeOf(object);\n  if (prototype !== null && prototype !== Object.prototype) {\n    reject(\n      path,\n      `a ${describe(object)} instance`,\n      'Return a plain object with the fields you need.'\n    );\n  }\n\n  // Own *enumerable string* keys only — the rest is what Flight would drop,\n  // so dropping it here keeps the two sides identical. `__proto__` is skipped\n  // rather than copied: it has a language-level setter that would change the\n  // prototype chain of the copy (TIM-655, TIM-855, TIM-873).\n  const out: Record<string, unknown> = Object.create(null);\n  for (const key of Object.keys(object)) {\n    if (key === '__proto__') continue;\n    out[key] = normalize(\n      (object as Record<string, unknown>)[key],\n      path ? `${path}.${key}` : key,\n      seen\n    );\n  }\n  return out;\n}\n\nfunction keyLabel(key: unknown): string {\n  return typeof key === 'string' ? JSON.stringify(key) : String(key);\n}\n\n// ─── Prototype flip ──────────────────────────────────────────────\n\n/**\n * Canonical form → wire form. React Flight rejects a null prototype\n * (\"Classes or null prototypes are not supported\"), so objects cross as plain\n * ones and are restored on arrival.\n */\nexport function toPlainRecord<T>(value: T): T {\n  return reproto(value, {}) as T;\n}\n\n/** Wire form → canonical form. The exact inverse of `toPlainRecord`. */\nexport function toNullProtoRecord<T>(value: T): T {\n  return reproto(value, null) as T;\n}\n\n/**\n * Rebuild a canonical value with objects on `proto`.\n *\n * Total by construction: its input is always canonical, so the cases are the\n * domain and nothing else. No validation, no shape it might not have seen, and\n * no cycle to guard — a canonical value is a tree. That is what moving the\n * checking to `normalizeParamValue` bought.\n */\nfunction reproto(value: unknown, proto: object | null): unknown {\n  if (value === null || typeof value !== 'object') return value;\n\n  const object = value as object;\n\n  // A Date carries no nested values, so it crosses as itself.\n  if (object instanceof Date) return object;\n\n  if (Array.isArray(object)) {\n    return (object as unknown[]).map((item) => reproto(item, proto));\n  }\n\n  if (object instanceof Map) {\n    const out = new Map<unknown, unknown>();\n    for (const [key, entry] of object) out.set(reproto(key, proto), reproto(entry, proto));\n    return out;\n  }\n\n  if (object instanceof Set) {\n    const out = new Set<unknown>();\n    for (const entry of object) out.add(reproto(entry, proto));\n    return out;\n  }\n\n  const out: Record<string, unknown> = proto === null ? Object.create(null) : {};\n  for (const key of Object.keys(object)) {\n    if (key === '__proto__') continue;\n    out[key] = reproto((object as Record<string, unknown>)[key], proto);\n  }\n  return out;\n}\n","/**\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":";;;AAoEA,IAAM,SAAS,oFAAoF;CAHlF;CAAQ;CAAO;AAGmE,CAAA,CAAQ,KAAK,GAAG;AAEnH,SAAS,OAAO,MAAc,KAAa,MAAqB;CAC9D,MAAM,IAAI,MACR,2BAA2B,QAAQ,SAAS,mBAAmB,IAAI,2DACpB,OAAO,OAC/C,KAAK,iDAEd;AACF;AAEA,SAAS,SAAS,OAAuB;CACvC,OAAQ,MAA8C,aAAa,QAAQ;AAC7E;;;;;;;;AASA,SAAgB,oBAAoB,OAAgB,OAAO,IAAa;CACtE,OAAO,UAAU,OAAO,sBAAM,IAAI,IAAI,CAAC;AACzC;AAEA,SAAS,UAAU,OAAgB,MAAc,MAA4B;CAC3E,IAAI,UAAU,MAAM,OAAO;CAE3B,MAAM,OAAO,OAAO;CACpB,IAAI,SAAS,YAAY,SAAS,YAAY,SAAS,aAAa,SAAS,UAC3E,OAAO;CAET,IAAI,SAAS,aAAa,OAAO,KAAA;CACjC,IAAI,SAAS,YACX,OAAO,MAAM,cAAc,qDAAqD;CAElF,IAAI,SAAS,UACX,OAAO,MAAM,YAAY,gEAAgE;CAG3F,MAAM,SAAS;CACf,IAAI,KAAK,IAAI,MAAM,GACjB,MAAM,IAAI,MACR,2BAA2B,QAAQ,SAAS,6XAM9C;CAEF,KAAK,IAAI,MAAM;CAEf,IAAI,MAAM,QAAQ,MAAM,GAAG;EAIzB,MAAM,MAAiB,CAAC;EACxB,KAAK,IAAI,QAAQ,GAAG,QAAQ,OAAO,QAAQ,SACzC,IAAI,KAAK,UAAW,OAAqB,QAAQ,GAAG,KAAK,GAAG,MAAM,IAAI,IAAI,CAAC;EAE7E,OAAO;CACT;CAEA,IAAI,kBAAkB,MAGpB,OAAO,IAAI,KAAK,OAAO,QAAQ,CAAC;CAGlC,IAAI,kBAAkB,KAAK;EACzB,MAAM,sBAAM,IAAI,IAAsB;EACtC,KAAK,MAAM,CAAC,KAAK,UAAU,QACzB,IAAI,IACF,UAAU,KAAK,GAAG,KAAK,QAAQ,IAAI,GACnC,UAAU,OAAO,GAAG,KAAK,OAAO,SAAS,GAAG,EAAE,IAAI,IAAI,CACxD;EAEF,OAAO;CACT;CAEA,IAAI,kBAAkB,KAAK;EACzB,MAAM,sBAAM,IAAI,IAAa;EAC7B,IAAI,QAAQ;EACZ,KAAK,MAAM,SAAS,QAAQ,IAAI,IAAI,UAAU,OAAO,GAAG,KAAK,GAAG,QAAQ,IAAI,IAAI,CAAC;EACjF,OAAO;CACT;CAKA,MAAM,YAAY,OAAO,eAAe,MAAM;CAC9C,IAAI,cAAc,QAAQ,cAAc,OAAO,WAC7C,OACE,MACA,KAAK,SAAS,MAAM,EAAE,YACtB,iDACF;CAOF,MAAM,MAA+B,OAAO,OAAO,IAAI;CACvD,KAAK,MAAM,OAAO,OAAO,KAAK,MAAM,GAAG;EACrC,IAAI,QAAQ,aAAa;EACzB,IAAI,OAAO,UACR,OAAmC,MACpC,OAAO,GAAG,KAAK,GAAG,QAAQ,KAC1B,IACF;CACF;CACA,OAAO;AACT;AAEA,SAAS,SAAS,KAAsB;CACtC,OAAO,OAAO,QAAQ,WAAW,KAAK,UAAU,GAAG,IAAI,OAAO,GAAG;AACnE;;;;;;;;;;;;;;;AC/JA,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/segment-keys-BawYuNFO.js.map

@@ -1 +1 @@
-{"version":3,"file":"segment-keys-BawYuNFO.js","names":[],"sources":["../../src/server/metadata-routes.ts","../../src/server/canonicalize.ts","../../src/routing/segment-keys.ts"],"sourcesContent":["/**\n * Metadata route classification for timber.js.\n *\n * Metadata routes are file-based endpoints that generate well-known URLs for\n * crawlers and browsers (sitemap.xml, robots.txt, OG images, etc.).\n *\n * These routes run through proxy.ts but NOT through middleware.ts or access.ts —\n * they are public endpoints by nature.\n *\n * See design/16-metadata.md §\"Metadata Routes\"\n */\n\nimport { randomUUID } from 'node:crypto';\nimport type { HeadElement } from './metadata.js';\nimport type { Metadata } from './types.js';\nimport type { ManifestSegmentNode } from './route-matcher.js';\n\n// ─── Types ───────────────────────────────────────────────────────────────────\n\n/** Classification of a metadata route file. */\nexport interface MetadataRouteInfo {\n  /** The metadata route type. */\n  type: MetadataRouteType;\n  /** The content type to serve this route with. */\n  contentType: string;\n  /** Whether this route can appear in nested segments (not just app root). */\n  nestable: boolean;\n}\n\nexport type MetadataRouteType =\n  | 'sitemap'\n  | 'robots'\n  | 'manifest'\n  | 'favicon'\n  | 'icon'\n  | 'opengraph-image'\n  | 'apple-icon';\n\n// ─── Convention Table ────────────────────────────────────────────────────────\n\n/**\n * All recognized metadata route file conventions.\n *\n * Each entry maps a base file name (without extension) to its route info.\n * The extensions determine whether the file is static or dynamic.\n *\n * Static extensions: .xml, .txt, .json, .png, .jpg, .ico, .svg\n * Dynamic extensions: .ts, .tsx\n */\nexport const METADATA_ROUTE_CONVENTIONS: Record<\n  string,\n  {\n    type: MetadataRouteType;\n    contentType: string;\n    nestable: boolean;\n    staticExtensions: string[];\n    dynamicExtensions: string[];\n    /**\n     * The URL path basename this file serves at (relative to segment).\n     * For image routes, the full serve path includes an extension via\n     * `resolveServePathForFile()`.\n     */\n    servePath: string;\n    /**\n     * When set, image routes append `.{serveExtension}` to the serve path.\n     * Dynamic handlers (`.ts`/`.tsx`) use this as the default. Static files\n     * use their own extension instead. Non-image routes leave this undefined.\n     */\n    serveExtension?: string;\n  }\n> = {\n  'sitemap': {\n    type: 'sitemap',\n    contentType: 'application/xml',\n    nestable: true,\n    staticExtensions: ['xml'],\n    dynamicExtensions: ['ts'],\n    servePath: 'sitemap.xml',\n  },\n  'robots': {\n    type: 'robots',\n    contentType: 'text/plain',\n    nestable: false,\n    staticExtensions: ['txt'],\n    dynamicExtensions: ['ts'],\n    servePath: 'robots.txt',\n  },\n  'manifest': {\n    type: 'manifest',\n    contentType: 'application/manifest+json',\n    nestable: false,\n    staticExtensions: ['json'],\n    dynamicExtensions: ['ts'],\n    servePath: 'manifest.webmanifest',\n  },\n  'favicon': {\n    type: 'favicon',\n    contentType: 'image/x-icon',\n    nestable: false,\n    staticExtensions: ['ico'],\n    dynamicExtensions: ['ts', 'tsx'],\n    servePath: 'favicon.ico',\n  },\n  'icon': {\n    type: 'icon',\n    contentType: 'image/*',\n    nestable: true,\n    staticExtensions: ['png', 'jpg', 'svg'],\n    dynamicExtensions: ['ts', 'tsx'],\n    servePath: 'icon',\n    serveExtension: 'png',\n  },\n  'opengraph-image': {\n    type: 'opengraph-image',\n    contentType: 'image/*',\n    nestable: true,\n    staticExtensions: ['png', 'jpg'],\n    dynamicExtensions: ['ts', 'tsx'],\n    servePath: 'opengraph-image',\n    serveExtension: 'png',\n  },\n\n  'apple-icon': {\n    type: 'apple-icon',\n    contentType: 'image/*',\n    nestable: true,\n    staticExtensions: ['png'],\n    dynamicExtensions: ['ts', 'tsx'],\n    servePath: 'apple-icon',\n    serveExtension: 'png',\n  },\n};\n\n// ─── MIME Type Resolution ─────────────────────────────────────────────────────\n\n/**\n * Map of file extensions to MIME types for static metadata route files.\n * Used to resolve the generic `image/*` content type for static image files.\n */\nconst EXTENSION_MIME_TYPES: Record<string, string> = {\n  xml: 'application/xml',\n  txt: 'text/plain',\n  json: 'application/json',\n  ico: 'image/x-icon',\n  png: 'image/png',\n  jpg: 'image/jpeg',\n  jpeg: 'image/jpeg',\n  svg: 'image/svg+xml',\n  webp: 'image/webp',\n};\n\n/**\n * Resolve the concrete MIME type for a static metadata route file.\n *\n * For generic content types like `image/*`, this resolves to the actual\n * MIME type based on the file extension (e.g. `image/png` for `.png`).\n *\n * @param conventionContentType - The content type from the convention table (may be generic like `image/*`)\n * @param extension - The file extension without leading dot (e.g. \"png\", \"xml\")\n * @returns The resolved MIME type\n */\nexport function resolveStaticContentType(conventionContentType: string, extension: string): string {\n  if (conventionContentType.includes('*')) {\n    return EXTENSION_MIME_TYPES[extension] ?? 'application/octet-stream';\n  }\n  return conventionContentType;\n}\n\n/**\n * Check if a file extension represents a static (non-code) metadata route file.\n *\n * @param baseName - The base file name without extension (e.g. \"sitemap\", \"icon\")\n * @param extension - The file extension without leading dot (e.g. \"xml\", \"png\", \"ts\")\n * @returns true if this is a static file, false if dynamic or unrecognized\n */\nexport function isStaticMetadataExtension(baseName: string, extension: string): boolean {\n  const convention = METADATA_ROUTE_CONVENTIONS[baseName];\n  if (!convention) return false;\n  return convention.staticExtensions.includes(extension);\n}\n\n/**\n * Check if a file extension represents a dynamic (code) metadata route file.\n *\n * @param baseName - The base file name without extension (e.g. \"sitemap\", \"icon\")\n * @param extension - The file extension without leading dot (e.g. \"ts\", \"tsx\")\n * @returns true if this is a dynamic file, false if static or unrecognized\n */\nexport function isDynamicMetadataExtension(baseName: string, extension: string): boolean {\n  const convention = METADATA_ROUTE_CONVENTIONS[baseName];\n  if (!convention) return false;\n  return convention.dynamicExtensions.includes(extension);\n}\n\n// ─── Classification ──────────────────────────────────────────────────────────\n\n/**\n * Classify a file name as a metadata route, or return null if it's not one.\n *\n * @param fileName - The full file name including extension (e.g. \"sitemap.xml\", \"icon.tsx\")\n * @returns Classification info, or null if not a metadata route\n */\nexport function classifyMetadataRoute(fileName: string): MetadataRouteInfo | null {\n  const dotIndex = fileName.lastIndexOf('.');\n  if (dotIndex === -1) return null;\n\n  const baseName = fileName.slice(0, dotIndex);\n  const ext = fileName.slice(dotIndex + 1);\n\n  const convention = METADATA_ROUTE_CONVENTIONS[baseName];\n  if (!convention) return null;\n\n  const isStatic = convention.staticExtensions.includes(ext);\n  const isDynamic = convention.dynamicExtensions.includes(ext);\n\n  if (!isStatic && !isDynamic) return null;\n\n  return {\n    type: convention.type,\n    contentType: convention.contentType,\n    nestable: convention.nestable,\n  };\n}\n\n/**\n * Resolve the serve path for a metadata route file.\n *\n * For image routes (icon, opengraph-image, apple-icon), the serve path includes\n * a file extension so CDNs cache correctly:\n * - Dynamic handlers (.ts/.tsx) use the convention's `serveExtension` (default: .png)\n * - Static files use their own extension (e.g., icon.svg → icon.svg)\n *\n * Non-image routes return the convention's `servePath` as-is (already includes\n * extension: sitemap.xml, robots.txt, etc.).\n */\nexport function resolveServePathForFile(baseName: string, filePath: string): string {\n  const convention = METADATA_ROUTE_CONVENTIONS[baseName];\n  if (!convention) return baseName;\n\n  if (!convention.serveExtension) return convention.servePath;\n\n  const ext = filePath.slice(filePath.lastIndexOf('.') + 1);\n  if (convention.staticExtensions.includes(ext)) {\n    return `${convention.servePath}.${ext}`;\n  }\n  return `${convention.servePath}.${convention.serveExtension}`;\n}\n\n/**\n * Get the default serve path for a metadata route type (using default extension\n * for image routes). Used for auto-link generation when only the type is known.\n */\nexport function getMetadataRouteServePath(type: MetadataRouteType): string {\n  for (const convention of Object.values(METADATA_ROUTE_CONVENTIONS)) {\n    if (convention.type === type) {\n      if (convention.serveExtension) {\n        return `${convention.servePath}.${convention.serveExtension}`;\n      }\n      return convention.servePath;\n    }\n  }\n  throw new Error(`[timber] Unknown metadata route type: ${type}`);\n}\n\n/**\n * All possible serve path segments for metadata routes (includes extension\n * variants for image routes).\n */\nconst METADATA_SERVE_PATHS = new Set<string>();\nfor (const convention of Object.values(METADATA_ROUTE_CONVENTIONS)) {\n  if (convention.serveExtension) {\n    for (const ext of [...convention.staticExtensions, convention.serveExtension]) {\n      METADATA_SERVE_PATHS.add(`${convention.servePath}.${ext}`);\n    }\n  } else {\n    METADATA_SERVE_PATHS.add(convention.servePath);\n  }\n}\n\nexport function isMetadataRouteServePath(pathname: string): boolean {\n  let lastSegment = pathname.slice(pathname.lastIndexOf('/') + 1);\n  const qIdx = lastSegment.indexOf('?');\n  let query = '';\n  if (qIdx !== -1) {\n    query = lastSegment.slice(qIdx + 1);\n    lastSegment = lastSegment.slice(0, qIdx);\n  }\n  if (!METADATA_SERVE_PATHS.has(lastSegment)) return false;\n  // Vite module requests (e.g., /src/icon.svg?import) use special query params.\n  // These are source assets, not metadata routes.\n  if (/(?:^|&)(?:import|url|raw|worker|inline)(?:&|$)/.test(query)) return false;\n  return true;\n}\n\n/** A <link> auto-link tag. */\nexport interface AutoLinkLink {\n  tag: 'link';\n  rel: string;\n  href: string;\n  type?: string;\n}\n\n/** A <meta> auto-link tag. */\nexport interface AutoLinkMeta {\n  tag: 'meta';\n  property?: string;\n  name?: string;\n  content: string;\n}\n\nexport type AutoLinkTag = AutoLinkLink | AutoLinkMeta;\n\n/**\n * Get the auto-link tags to inject into <head> for metadata route files\n * discovered in a segment.\n *\n * Returns link tags for icon/apple-icon/manifest, and meta tags for\n * opengraph-image (emits both og:image and twitter:image). Returns null\n * for types that don't auto-link (favicon, sitemap, robots).\n *\n * @param type - The metadata route type\n * @param href - The resolved URL path to the metadata route\n * @returns Tag descriptor(s) for the <head>, or null if no auto-link\n */\nexport function getMetadataRouteAutoLink(type: MetadataRouteType, href: string): AutoLinkTag[] {\n  switch (type) {\n    case 'icon':\n      return [{ tag: 'link', rel: 'icon', href }];\n    case 'apple-icon':\n      return [{ tag: 'link', rel: 'apple-touch-icon', href }];\n    case 'manifest':\n      return [{ tag: 'link', rel: 'manifest', href }];\n    case 'opengraph-image':\n      return [\n        { tag: 'meta', property: 'og:image', content: href },\n        { tag: 'meta', name: 'twitter:image', content: href },\n      ];\n    default:\n      return [];\n  }\n}\n\n// ─── Auto-Linking ──────────────────────────────────────────────────────────\n\n// In dev mode, use a per-startup nonce for metadata route cache busting\n// instead of per-file content hashes (avoids rehashing on every request).\nlet _devNonce: string | undefined;\nfunction getDevNonce(): string {\n  _devNonce ??= randomUUID().slice(0, 8);\n  return _devNonce;\n}\n\n/**\n * Collect auto-linked head elements from metadata route files in the segment chain.\n *\n * Walks each segment's metadataRoutes, resolves serve paths and URLs, and\n * emits HeadElement descriptors for <link> and <meta> tags that React Float\n * hoists into <head>.\n *\n * See design/16-metadata.md §\"Auto-Linking\"\n */\nexport function collectMetadataRouteHeadElements(\n  segments: ManifestSegmentNode[],\n  firstDeniedIndex: number,\n  resolvedMetadata: Metadata,\n  requestUrl: URL,\n  metadataRouteHashes?: Record<string, string>\n): HeadElement[] {\n  const elements: HeadElement[] = [];\n  const hasUserOgImage = Boolean(resolvedMetadata.openGraph?.images);\n  const hasUserTwitterImage = Boolean(resolvedMetadata.twitter?.images);\n  const requestPathname = requestUrl.pathname;\n  // In dev mode, use the request origin so OG URLs resolve to localhost.\n  // In production, use metadataBase (the canonical domain).\n  const ogBase =\n    process.env.NODE_ENV !== 'production'\n      ? new URL(requestUrl.origin)\n      : resolvedMetadata.metadataBase;\n\n  for (let si = 0; si < segments.length; si++) {\n    const segment = segments[si];\n    if (!segment.metadataRoutes) continue;\n    if (si >= firstDeniedIndex) continue;\n    for (const baseName of Object.keys(segment.metadataRoutes)) {\n      const convention = METADATA_ROUTE_CONVENTIONS[baseName];\n      if (!convention) continue;\n      if (!convention.nestable && segment.urlPath !== '/') continue;\n      if (convention.type === 'opengraph-image' && hasUserOgImage) continue;\n      const resolvedPrefix = convention.nestable\n        ? requestPathname === '/'\n          ? ''\n          : requestPathname\n        : '';\n      const metaFile = segment.metadataRoutes[baseName];\n      const fileServePath = metaFile?.filePath\n        ? resolveServePathForFile(baseName, metaFile.filePath)\n        : convention.serveExtension\n          ? `${convention.servePath}.${convention.serveExtension}`\n          : convention.servePath;\n      let href = `${resolvedPrefix}/${fileServePath}`;\n      if (convention.type === 'opengraph-image') {\n        const fileHash = metaFile?.filePath ? metadataRouteHashes?.[metaFile.filePath] : undefined;\n        const cacheBust = fileHash ?? getDevNonce();\n        href = `${href}?${cacheBust}`;\n      }\n      if (ogBase && convention.type === 'opengraph-image') {\n        href = new URL(href, ogBase).toString();\n      }\n      for (const autoLink of getMetadataRouteAutoLink(convention.type, href)) {\n        if (\n          hasUserTwitterImage &&\n          autoLink.tag === 'meta' &&\n          'name' in autoLink &&\n          autoLink.name === 'twitter:image'\n        )\n          continue;\n        if (autoLink.tag === 'link') {\n          const attrs: Record<string, string> = { rel: autoLink.rel, href: autoLink.href };\n          if (autoLink.type) attrs.type = autoLink.type;\n          elements.push({ tag: 'link', attrs });\n        } else {\n          const attrs: Record<string, string> = { content: autoLink.content };\n          if (autoLink.property) attrs.property = autoLink.property;\n          if (autoLink.name) attrs.name = autoLink.name;\n          elements.push({ tag: 'meta', attrs });\n        }\n      }\n    }\n  }\n  return elements;\n}\n","/**\n * URL canonicalization — runs once at the request boundary.\n *\n * Every layer (proxy.ts, middleware.ts, access.ts, components) sees the same\n * canonical path. No re-decoding occurs at any later stage.\n *\n * See design/07-routing.md §\"URL Canonicalization & Security\"\n */\n\n/** Result of canonicalization — either a clean path or a rejection. */\nexport type CanonicalizeResult = { ok: true; pathname: string } | { ok: false; status: 400 };\n\n/**\n * Encoded separators that produce a 400 rejection.\n * %2f (/) and %5c (\\) cause path-confusion attacks.\n *\n * Shared between the runtime canonicalizer and the build-time route scanner\n * to ensure both enforce identical security rules. See design/13-security.md.\n */\nexport const ENCODED_SEPARATOR_RE = /%2f|%5c/i;\n\n/** Null byte — rejected. Shared with the route scanner. */\nexport const NULL_BYTE_RE = /%00/i;\n\n/**\n * Canonicalize a URL pathname.\n *\n * 1. Reject encoded separators (%2f, %5c) and null bytes (%00)\n * 2. Single percent-decode\n * 3. Collapse // → /\n * 4. Resolve .. segments (reject if escaping root)\n * 5. Strip trailing slash (except root \"/\")\n *\n * @param rawPathname - The raw pathname from the request URL (percent-encoded)\n * @param stripTrailingSlash - Whether to strip trailing slashes. Default: true.\n */\nexport function canonicalize(rawPathname: string, stripTrailingSlash = true): CanonicalizeResult {\n  // Step 1: Reject dangerous encoded sequences BEFORE decoding.\n  // This must happen on the raw input so %252f doesn't bypass after a single decode.\n  if (ENCODED_SEPARATOR_RE.test(rawPathname)) {\n    return { ok: false, status: 400 };\n  }\n  if (NULL_BYTE_RE.test(rawPathname)) {\n    return { ok: false, status: 400 };\n  }\n\n  // Step 2: Single percent-decode.\n  // Double-encoded input (%2561 → %61) stays as %61 — not decoded again.\n  let decoded: string;\n  try {\n    decoded = decodeURIComponent(rawPathname);\n  } catch {\n    // Malformed percent-encoding → 400\n    return { ok: false, status: 400 };\n  }\n\n  // Reject null bytes that appeared after decoding (from valid %00-like sequences\n  // that weren't caught above — belt and suspenders).\n  if (decoded.includes('\\0')) {\n    return { ok: false, status: 400 };\n  }\n\n  // Backslash is NOT a path separator — keep as literal character.\n  // But reject if it would create // after normalization (e.g., /\\evil.com).\n  // We do NOT convert \\ to / — it stays as a literal.\n\n  // Step 3: Collapse consecutive slashes.\n  let pathname = decoded.replace(/\\/\\/+/g, '/');\n\n  // Step 4: Resolve .. and . segments.\n  const segments = pathname.split('/');\n  const resolved: string[] = [];\n  for (const seg of segments) {\n    if (seg === '..') {\n      if (resolved.length <= 1) {\n        // Trying to escape root — 400\n        return { ok: false, status: 400 };\n      }\n      resolved.pop();\n    } else if (seg !== '.') {\n      resolved.push(seg);\n    }\n  }\n\n  pathname = resolved.join('/') || '/';\n\n  // Step 5: Strip trailing slash (except root \"/\").\n  if (stripTrailingSlash && pathname.length > 1 && pathname.endsWith('/')) {\n    pathname = pathname.slice(0, -1);\n  }\n\n  return { ok: true, pathname };\n}\n","/**\n * Segment key computation — the stable identity of a segment in the route tree.\n *\n * A segment key is the string that names a segment across the RSC/SSR/client\n * boundary: it appears in the X-Timber-State-Tree header, the X-Timber-Segments\n * header, SegmentOutlet props, the client segment cache, and (since TIM-1279)\n * interception scoping.\n *\n * This module lives in `routing/` rather than `server/` because the keys are a\n * property of the route tree itself — both the build-time scanner tree and the\n * runtime manifest tree produce identical keys for the same directory, which is\n * what lets a build-time value (an interception scope) be compared against a\n * request-time matched chain.\n *\n * See design/19-client-navigation.md §\"X-Timber-State-Tree Header\"\n */\n\n/**\n * Segment node shape expected by computeSegmentKeys.\n *\n * Structurally satisfied by both `SegmentNode` (build time) and\n * `ManifestSegmentNode` (request time) — keys depend only on the\n * URL path and the segment classification, never on file payloads.\n */\nexport interface SegmentKeyInput {\n  urlPath: string;\n  segmentName?: string;\n  segmentType?: string;\n}\n\n/**\n * Compute state-tree keys for a segment chain.\n *\n * Non-group segments use their urlPath as-is. Route groups accumulate\n * ancestor group names to produce globally unique keys:\n *   app/(a)/(shared)/dashboard → keys: ['/', '/(a)', '/(a)/(shared)', '/dashboard']\n *\n * **An intercepting segment switches the chain to name accumulation for good.**\n * A children-path interception (TIM-1280) puts an intercepting node and its\n * descendants into the *main* rendered chain, and their `urlPath`s are not\n * URLs: interception adds no URL depth, so `app/(browse)/(...)[artistSlug]/[year]`\n * carries `/` and `/[year]`. Keyed by urlPath the intercepting node would\n * collide with its own owner, and `[year]` with any top-level `[year]` route —\n * so a client that had one mounted would reuse the wrong cached layout. The\n * switch is sticky rather than per-node because the *descendants* are where\n * the false URLs are; the intercepting node alone is not the problem.\n *\n * This is the single source of truth for segment keys — used by the\n * element builder (skip decisions, SegmentOutlet props), segment info\n * (X-Timber-Segments header), the client cache/state tree, and\n * interception scoping (`routing/interception.ts`).\n */\nexport function computeSegmentKeys(segments: SegmentKeyInput[]): string[] {\n  const keys: string[] = [];\n  let prevKey = '';\n  let insideIntercepting = false;\n\n  for (const segment of segments) {\n    if (segment.segmentType === 'intercepting') insideIntercepting = true;\n    if (segment.segmentType === 'group' || insideIntercepting) {\n      const base = prevKey === '/' ? '' : prevKey;\n      const key = `${base}/${segment.segmentName}`;\n      keys.push(key);\n      prevKey = key;\n    } else {\n      keys.push(segment.urlPath);\n      prevKey = segment.urlPath;\n    }\n  }\n\n  return keys;\n}\n\n/**\n * Compute tree paths for a segment chain — the directory path of each segment\n * with slots elided, e.g. `app/(browse)/feed` → `/(browse)/feed`.\n *\n * This is `computeSegmentKeys` with the group branch applied to *every*\n * segment rather than only to groups. That one difference is the whole point:\n * `computeSegmentKeys` resets to `urlPath` at each URL-visible segment, so\n * `(browse)/feed` and `(landing)/feed` both key as `/feed`. Two directories\n * that render different layouts must not share an identity.\n *\n * Used for interception scoping (`routing/interception.ts`), where the\n * question is \"does this route pass through *that* directory?\" — not \"does it\n * render this URL?\". Not interchangeable with `computeSegmentKeys`: the state\n * tree is keyed by URL on purpose, because the client caches by URL.\n */\nexport function computeSegmentTreePaths(segments: SegmentKeyInput[]): string[] {\n  const paths: string[] = [];\n  let prev = '';\n\n  for (const segment of segments) {\n    const name = segment.segmentName ?? '';\n    if (!name) {\n      // The app root — no directory name of its own.\n      paths.push('/');\n      prev = '/';\n      continue;\n    }\n    const base = prev === '/' ? '' : prev;\n    const path = `${base}/${name}`;\n    paths.push(path);\n    prev = path;\n  }\n\n  return paths;\n}\n\n/**\n * The directory names a tree path is built from — `/` is none, `/feed/(a)` is\n * `['feed', '(a)']`.\n *\n * The inverse of the walk above, and it lives beside it so the format is\n * stated once: `findChainByTreePath` (`server/children-interception.ts`) walks\n * these names back down the tree to the directory the path addresses, and\n * `treePathDepth` counts them. Both are readings of the same string, and a\n * reader that disagreed with the producer about what separates two names\n * resolves an interception to the wrong node or to none.\n */\nexport function treePathNames(treePath: string): string[] {\n  return treePath === '/' ? [] : treePath.slice(1).split('/');\n}\n\n/**\n * How many directories a tree path names — `/` is 0, `/feed` is 1,\n * `/feed/(a)` is 2.\n *\n * Two tree paths on a single rendered chain are strictly nested, so on that\n * chain depth orders them totally — which is what makes it usable as \"the\n * deeper of these two directories\" wherever a route passes through both\n * (`routing/interception.ts`).\n */\nexport function treePathDepth(treePath: string): number {\n  return treePathNames(treePath).length;\n}\n\n/**\n * Compute a unique key for a parallel route slot.\n * Format: `{parentSegmentId}/@{slotName}`, e.g. `/@sidebar` or `/dashboard/@modal`.\n */\nexport function computeSlotKey(parentSegmentId: string, slotName: string): string {\n  const name = slotName.startsWith('@') ? slotName : `@${slotName}`;\n  const prefix = parentSegmentId === '/' ? '' : parentSegmentId;\n  return `${prefix}/${name}`;\n}\n"],"mappings":"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"}
+{"version":3,"file":"segment-keys-BawYuNFO.js","names":[],"sources":["../../src/server/metadata-routes.ts","../../src/server/canonicalize.ts","../../src/routing/segment-keys.ts"],"sourcesContent":["/**\n * Metadata route classification for timber.js.\n *\n * Metadata routes are file-based endpoints that generate well-known URLs for\n * crawlers and browsers (sitemap.xml, robots.txt, OG images, etc.).\n *\n * These routes run through proxy.ts but NOT through middleware.ts or access.ts —\n * they are public endpoints by nature.\n *\n * See design/16-metadata.md §\"Metadata Routes\"\n */\n\nimport { randomUUID } from 'node:crypto';\nimport type { HeadElement } from './metadata.js';\nimport type { Metadata } from './types.js';\nimport type { ManifestSegmentNode } from './route-matcher.js';\n\n// ─── Types ───────────────────────────────────────────────────────────────────\n\n/** Classification of a metadata route file. */\nexport interface MetadataRouteInfo {\n  /** The metadata route type. */\n  type: MetadataRouteType;\n  /** The content type to serve this route with. */\n  contentType: string;\n  /** Whether this route can appear in nested segments (not just app root). */\n  nestable: boolean;\n}\n\nexport type MetadataRouteType =\n  | 'sitemap'\n  | 'robots'\n  | 'manifest'\n  | 'favicon'\n  | 'icon'\n  | 'opengraph-image'\n  | 'apple-icon';\n\n// ─── Convention Table ────────────────────────────────────────────────────────\n\n/**\n * All recognized metadata route file conventions.\n *\n * Each entry maps a base file name (without extension) to its route info.\n * The extensions determine whether the file is static or dynamic.\n *\n * Static extensions: .xml, .txt, .json, .png, .jpg, .ico, .svg\n * Dynamic extensions: .ts, .tsx\n */\nexport const METADATA_ROUTE_CONVENTIONS: Record<\n  string,\n  {\n    type: MetadataRouteType;\n    contentType: string;\n    nestable: boolean;\n    staticExtensions: string[];\n    dynamicExtensions: string[];\n    /**\n     * The URL path basename this file serves at (relative to segment).\n     * For image routes, the full serve path includes an extension via\n     * `resolveServePathForFile()`.\n     */\n    servePath: string;\n    /**\n     * When set, image routes append `.{serveExtension}` to the serve path.\n     * Dynamic handlers (`.ts`/`.tsx`) use this as the default. Static files\n     * use their own extension instead. Non-image routes leave this undefined.\n     */\n    serveExtension?: string;\n  }\n> = {\n  'sitemap': {\n    type: 'sitemap',\n    contentType: 'application/xml',\n    nestable: true,\n    staticExtensions: ['xml'],\n    dynamicExtensions: ['ts'],\n    servePath: 'sitemap.xml',\n  },\n  'robots': {\n    type: 'robots',\n    contentType: 'text/plain',\n    nestable: false,\n    staticExtensions: ['txt'],\n    dynamicExtensions: ['ts'],\n    servePath: 'robots.txt',\n  },\n  'manifest': {\n    type: 'manifest',\n    contentType: 'application/manifest+json',\n    nestable: false,\n    staticExtensions: ['json'],\n    dynamicExtensions: ['ts'],\n    servePath: 'manifest.webmanifest',\n  },\n  'favicon': {\n    type: 'favicon',\n    contentType: 'image/x-icon',\n    nestable: false,\n    staticExtensions: ['ico'],\n    dynamicExtensions: ['ts', 'tsx'],\n    servePath: 'favicon.ico',\n  },\n  'icon': {\n    type: 'icon',\n    contentType: 'image/*',\n    nestable: true,\n    staticExtensions: ['png', 'jpg', 'svg'],\n    dynamicExtensions: ['ts', 'tsx'],\n    servePath: 'icon',\n    serveExtension: 'png',\n  },\n  'opengraph-image': {\n    type: 'opengraph-image',\n    contentType: 'image/*',\n    nestable: true,\n    staticExtensions: ['png', 'jpg'],\n    dynamicExtensions: ['ts', 'tsx'],\n    servePath: 'opengraph-image',\n    serveExtension: 'png',\n  },\n\n  'apple-icon': {\n    type: 'apple-icon',\n    contentType: 'image/*',\n    nestable: true,\n    staticExtensions: ['png'],\n    dynamicExtensions: ['ts', 'tsx'],\n    servePath: 'apple-icon',\n    serveExtension: 'png',\n  },\n};\n\n// ─── MIME Type Resolution ─────────────────────────────────────────────────────\n\n/**\n * Map of file extensions to MIME types for static metadata route files.\n * Used to resolve the generic `image/*` content type for static image files.\n */\nconst EXTENSION_MIME_TYPES: Record<string, string> = {\n  xml: 'application/xml',\n  txt: 'text/plain',\n  json: 'application/json',\n  ico: 'image/x-icon',\n  png: 'image/png',\n  jpg: 'image/jpeg',\n  jpeg: 'image/jpeg',\n  svg: 'image/svg+xml',\n  webp: 'image/webp',\n};\n\n/**\n * Resolve the concrete MIME type for a static metadata route file.\n *\n * For generic content types like `image/*`, this resolves to the actual\n * MIME type based on the file extension (e.g. `image/png` for `.png`).\n *\n * @param conventionContentType - The content type from the convention table (may be generic like `image/*`)\n * @param extension - The file extension without leading dot (e.g. \"png\", \"xml\")\n * @returns The resolved MIME type\n */\nexport function resolveStaticContentType(conventionContentType: string, extension: string): string {\n  if (conventionContentType.includes('*')) {\n    return EXTENSION_MIME_TYPES[extension] ?? 'application/octet-stream';\n  }\n  return conventionContentType;\n}\n\n/**\n * Check if a file extension represents a static (non-code) metadata route file.\n *\n * @param baseName - The base file name without extension (e.g. \"sitemap\", \"icon\")\n * @param extension - The file extension without leading dot (e.g. \"xml\", \"png\", \"ts\")\n * @returns true if this is a static file, false if dynamic or unrecognized\n */\nexport function isStaticMetadataExtension(baseName: string, extension: string): boolean {\n  const convention = METADATA_ROUTE_CONVENTIONS[baseName];\n  if (!convention) return false;\n  return convention.staticExtensions.includes(extension);\n}\n\n/**\n * Check if a file extension represents a dynamic (code) metadata route file.\n *\n * @param baseName - The base file name without extension (e.g. \"sitemap\", \"icon\")\n * @param extension - The file extension without leading dot (e.g. \"ts\", \"tsx\")\n * @returns true if this is a dynamic file, false if static or unrecognized\n */\nexport function isDynamicMetadataExtension(baseName: string, extension: string): boolean {\n  const convention = METADATA_ROUTE_CONVENTIONS[baseName];\n  if (!convention) return false;\n  return convention.dynamicExtensions.includes(extension);\n}\n\n// ─── Classification ──────────────────────────────────────────────────────────\n\n/**\n * Classify a file name as a metadata route, or return null if it's not one.\n *\n * @param fileName - The full file name including extension (e.g. \"sitemap.xml\", \"icon.tsx\")\n * @returns Classification info, or null if not a metadata route\n */\nexport function classifyMetadataRoute(fileName: string): MetadataRouteInfo | null {\n  const dotIndex = fileName.lastIndexOf('.');\n  if (dotIndex === -1) return null;\n\n  const baseName = fileName.slice(0, dotIndex);\n  const ext = fileName.slice(dotIndex + 1);\n\n  const convention = METADATA_ROUTE_CONVENTIONS[baseName];\n  if (!convention) return null;\n\n  const isStatic = convention.staticExtensions.includes(ext);\n  const isDynamic = convention.dynamicExtensions.includes(ext);\n\n  if (!isStatic && !isDynamic) return null;\n\n  return {\n    type: convention.type,\n    contentType: convention.contentType,\n    nestable: convention.nestable,\n  };\n}\n\n/**\n * Resolve the serve path for a metadata route file.\n *\n * For image routes (icon, opengraph-image, apple-icon), the serve path includes\n * a file extension so CDNs cache correctly:\n * - Dynamic handlers (.ts/.tsx) use the convention's `serveExtension` (default: .png)\n * - Static files use their own extension (e.g., icon.svg → icon.svg)\n *\n * Non-image routes return the convention's `servePath` as-is (already includes\n * extension: sitemap.xml, robots.txt, etc.).\n */\nexport function resolveServePathForFile(baseName: string, filePath: string): string {\n  const convention = METADATA_ROUTE_CONVENTIONS[baseName];\n  if (!convention) return baseName;\n\n  if (!convention.serveExtension) return convention.servePath;\n\n  const ext = filePath.slice(filePath.lastIndexOf('.') + 1);\n  if (convention.staticExtensions.includes(ext)) {\n    return `${convention.servePath}.${ext}`;\n  }\n  return `${convention.servePath}.${convention.serveExtension}`;\n}\n\n/**\n * Get the default serve path for a metadata route type (using default extension\n * for image routes). Used for auto-link generation when only the type is known.\n */\nexport function getMetadataRouteServePath(type: MetadataRouteType): string {\n  for (const convention of Object.values(METADATA_ROUTE_CONVENTIONS)) {\n    if (convention.type === type) {\n      if (convention.serveExtension) {\n        return `${convention.servePath}.${convention.serveExtension}`;\n      }\n      return convention.servePath;\n    }\n  }\n  throw new Error(`[timber] Unknown metadata route type: ${type}`);\n}\n\n/**\n * All possible serve path segments for metadata routes (includes extension\n * variants for image routes).\n */\nconst METADATA_SERVE_PATHS = new Set<string>();\nfor (const convention of Object.values(METADATA_ROUTE_CONVENTIONS)) {\n  if (convention.serveExtension) {\n    for (const ext of [...convention.staticExtensions, convention.serveExtension]) {\n      METADATA_SERVE_PATHS.add(`${convention.servePath}.${ext}`);\n    }\n  } else {\n    METADATA_SERVE_PATHS.add(convention.servePath);\n  }\n}\n\nexport function isMetadataRouteServePath(pathname: string): boolean {\n  let lastSegment = pathname.slice(pathname.lastIndexOf('/') + 1);\n  const qIdx = lastSegment.indexOf('?');\n  let query = '';\n  if (qIdx !== -1) {\n    query = lastSegment.slice(qIdx + 1);\n    lastSegment = lastSegment.slice(0, qIdx);\n  }\n  if (!METADATA_SERVE_PATHS.has(lastSegment)) return false;\n  // Vite module requests (e.g., /src/icon.svg?import) use special query params.\n  // These are source assets, not metadata routes.\n  if (/(?:^|&)(?:import|url|raw|worker|inline)(?:&|$)/.test(query)) return false;\n  return true;\n}\n\n/** A <link> auto-link tag. */\nexport interface AutoLinkLink {\n  tag: 'link';\n  rel: string;\n  href: string;\n  type?: string;\n}\n\n/** A <meta> auto-link tag. */\nexport interface AutoLinkMeta {\n  tag: 'meta';\n  property?: string;\n  name?: string;\n  content: string;\n}\n\nexport type AutoLinkTag = AutoLinkLink | AutoLinkMeta;\n\n/**\n * Get the auto-link tags to inject into <head> for metadata route files\n * discovered in a segment.\n *\n * Returns link tags for icon/apple-icon/manifest, and meta tags for\n * opengraph-image (emits both og:image and twitter:image). Returns null\n * for types that don't auto-link (favicon, sitemap, robots).\n *\n * @param type - The metadata route type\n * @param href - The resolved URL path to the metadata route\n * @returns Tag descriptor(s) for the <head>, or null if no auto-link\n */\nexport function getMetadataRouteAutoLink(type: MetadataRouteType, href: string): AutoLinkTag[] {\n  switch (type) {\n    case 'icon':\n      return [{ tag: 'link', rel: 'icon', href }];\n    case 'apple-icon':\n      return [{ tag: 'link', rel: 'apple-touch-icon', href }];\n    case 'manifest':\n      return [{ tag: 'link', rel: 'manifest', href }];\n    case 'opengraph-image':\n      return [\n        { tag: 'meta', property: 'og:image', content: href },\n        { tag: 'meta', name: 'twitter:image', content: href },\n      ];\n    default:\n      return [];\n  }\n}\n\n// ─── Auto-Linking ──────────────────────────────────────────────────────────\n\n// In dev mode, use a per-startup nonce for metadata route cache busting\n// instead of per-file content hashes (avoids rehashing on every request).\nlet _devNonce: string | undefined;\nfunction getDevNonce(): string {\n  _devNonce ??= randomUUID().slice(0, 8);\n  return _devNonce;\n}\n\n/**\n * Collect auto-linked head elements from metadata route files in the segment chain.\n *\n * Walks each segment's metadataRoutes, resolves serve paths and URLs, and\n * emits HeadElement descriptors for <link> and <meta> tags that React Float\n * hoists into <head>.\n *\n * See design/16-metadata.md §\"Auto-Linking\"\n */\nexport function collectMetadataRouteHeadElements(\n  segments: ManifestSegmentNode[],\n  firstDeniedIndex: number,\n  resolvedMetadata: Metadata,\n  requestUrl: URL,\n  metadataRouteHashes?: Record<string, string>\n): HeadElement[] {\n  const elements: HeadElement[] = [];\n  const hasUserOgImage = Boolean(resolvedMetadata.openGraph?.images);\n  const hasUserTwitterImage = Boolean(resolvedMetadata.twitter?.images);\n  const requestPathname = requestUrl.pathname;\n  // In dev mode, use the request origin so OG URLs resolve to localhost.\n  // In production, use metadataBase (the canonical domain).\n  const ogBase =\n    process.env.NODE_ENV !== 'production'\n      ? new URL(requestUrl.origin)\n      : resolvedMetadata.metadataBase;\n\n  for (let si = 0; si < segments.length; si++) {\n    const segment = segments[si];\n    if (!segment.metadataRoutes) continue;\n    if (si >= firstDeniedIndex) continue;\n    for (const baseName of Object.keys(segment.metadataRoutes)) {\n      const convention = METADATA_ROUTE_CONVENTIONS[baseName];\n      if (!convention) continue;\n      if (!convention.nestable && segment.urlPath !== '/') continue;\n      if (convention.type === 'opengraph-image' && hasUserOgImage) continue;\n      const resolvedPrefix = convention.nestable\n        ? requestPathname === '/'\n          ? ''\n          : requestPathname\n        : '';\n      const metaFile = segment.metadataRoutes[baseName];\n      const fileServePath = metaFile?.filePath\n        ? resolveServePathForFile(baseName, metaFile.filePath)\n        : convention.serveExtension\n          ? `${convention.servePath}.${convention.serveExtension}`\n          : convention.servePath;\n      let href = `${resolvedPrefix}/${fileServePath}`;\n      if (convention.type === 'opengraph-image') {\n        const fileHash = metaFile?.filePath ? metadataRouteHashes?.[metaFile.filePath] : undefined;\n        const cacheBust = fileHash ?? getDevNonce();\n        href = `${href}?${cacheBust}`;\n      }\n      if (ogBase && convention.type === 'opengraph-image') {\n        href = new URL(href, ogBase).toString();\n      }\n      for (const autoLink of getMetadataRouteAutoLink(convention.type, href)) {\n        if (\n          hasUserTwitterImage &&\n          autoLink.tag === 'meta' &&\n          'name' in autoLink &&\n          autoLink.name === 'twitter:image'\n        )\n          continue;\n        if (autoLink.tag === 'link') {\n          const attrs: Record<string, string> = { rel: autoLink.rel, href: autoLink.href };\n          if (autoLink.type) attrs.type = autoLink.type;\n          elements.push({ tag: 'link', attrs });\n        } else {\n          const attrs: Record<string, string> = { content: autoLink.content };\n          if (autoLink.property) attrs.property = autoLink.property;\n          if (autoLink.name) attrs.name = autoLink.name;\n          elements.push({ tag: 'meta', attrs });\n        }\n      }\n    }\n  }\n  return elements;\n}\n","/**\n * URL canonicalization — runs once at the request boundary.\n *\n * Every layer (proxy.ts, middleware.ts, access.ts, components) sees the same\n * canonical path. No re-decoding occurs at any later stage.\n *\n * See design/07-routing.md §\"URL Canonicalization & Security\"\n */\n\n/** Result of canonicalization — either a clean path or a rejection. */\nexport type CanonicalizeResult = { ok: true; pathname: string } | { ok: false; status: 400 };\n\n/**\n * Encoded separators that produce a 400 rejection.\n * %2f (/) and %5c (\\) cause path-confusion attacks.\n *\n * Shared between the runtime canonicalizer and the build-time route scanner\n * to ensure both enforce identical security rules. See design/13-security.md.\n */\nexport const ENCODED_SEPARATOR_RE = /%2f|%5c/i;\n\n/** Null byte — rejected. Shared with the route scanner. */\nexport const NULL_BYTE_RE = /%00/i;\n\n/**\n * Canonicalize a URL pathname.\n *\n * 1. Reject encoded separators (%2f, %5c) and null bytes (%00)\n * 2. Single percent-decode\n * 3. Collapse // → /\n * 4. Resolve .. segments (reject if escaping root)\n * 5. Strip trailing slash (except root \"/\")\n *\n * @param rawPathname - The raw pathname from the request URL (percent-encoded)\n * @param stripTrailingSlash - Whether to strip trailing slashes. Default: true.\n */\nexport function canonicalize(rawPathname: string, stripTrailingSlash = true): CanonicalizeResult {\n  // Step 1: Reject dangerous encoded sequences BEFORE decoding.\n  // This must happen on the raw input so %252f doesn't bypass after a single decode.\n  if (ENCODED_SEPARATOR_RE.test(rawPathname)) {\n    return { ok: false, status: 400 };\n  }\n  if (NULL_BYTE_RE.test(rawPathname)) {\n    return { ok: false, status: 400 };\n  }\n\n  // Step 2: Single percent-decode.\n  // Double-encoded input (%2561 → %61) stays as %61 — not decoded again.\n  let decoded: string;\n  try {\n    decoded = decodeURIComponent(rawPathname);\n  } catch {\n    // Malformed percent-encoding → 400\n    return { ok: false, status: 400 };\n  }\n\n  // Reject null bytes that appeared after decoding (from valid %00-like sequences\n  // that weren't caught above — belt and suspenders).\n  if (decoded.includes('\\0')) {\n    return { ok: false, status: 400 };\n  }\n\n  // Backslash is NOT a path separator — keep as literal character.\n  // But reject if it would create // after normalization (e.g., /\\evil.com).\n  // We do NOT convert \\ to / — it stays as a literal.\n\n  // Step 3: Collapse consecutive slashes.\n  let pathname = decoded.replace(/\\/\\/+/g, '/');\n\n  // Step 4: Resolve .. and . segments.\n  const segments = pathname.split('/');\n  const resolved: string[] = [];\n  for (const seg of segments) {\n    if (seg === '..') {\n      if (resolved.length <= 1) {\n        // Trying to escape root — 400\n        return { ok: false, status: 400 };\n      }\n      resolved.pop();\n    } else if (seg !== '.') {\n      resolved.push(seg);\n    }\n  }\n\n  pathname = resolved.join('/') || '/';\n\n  // Step 5: Strip trailing slash (except root \"/\").\n  if (stripTrailingSlash && pathname.length > 1 && pathname.endsWith('/')) {\n    pathname = pathname.slice(0, -1);\n  }\n\n  return { ok: true, pathname };\n}\n","/**\n * Segment key computation — the stable identity of a segment in the route tree.\n *\n * A segment key is the string that names a segment across the RSC/SSR/client\n * boundary: it appears in the X-Timber-State-Tree header, the X-Timber-Segments\n * header, SegmentOutlet props, the client segment cache, and (since TIM-1279)\n * interception scoping.\n *\n * This module lives in `routing/` rather than `server/` because the keys are a\n * property of the route tree itself — both the build-time scanner tree and the\n * runtime manifest tree produce identical keys for the same directory, which is\n * what lets a build-time value (an interception scope) be compared against a\n * request-time matched chain.\n *\n * See design/19-client-navigation.md §\"X-Timber-State-Tree Header\"\n */\n\n/**\n * Segment node shape expected by computeSegmentKeys.\n *\n * Structurally satisfied by both `SegmentNode` (build time) and\n * `ManifestSegmentNode` (request time) — keys depend only on the\n * URL path and the segment classification, never on file payloads.\n */\nexport interface SegmentKeyInput {\n  urlPath: string;\n  segmentName?: string;\n  segmentType?: string;\n}\n\n/**\n * Compute state-tree keys for a segment chain.\n *\n * Non-group segments use their urlPath as-is. Route groups accumulate\n * ancestor group names to produce globally unique keys:\n *   app/(a)/(shared)/dashboard → keys: ['/', '/(a)', '/(a)/(shared)', '/dashboard']\n *\n * **An intercepting segment switches the chain to name accumulation for good.**\n * A children-path interception (TIM-1280) puts an intercepting node and its\n * descendants into the *main* rendered chain, and their `urlPath`s are not\n * URLs: interception adds no URL depth, so `app/(browse)/(...)[artistSlug]/[year]`\n * carries `/` and `/[year]`. Keyed by urlPath the intercepting node would\n * collide with its own owner, and `[year]` with any top-level `[year]` route —\n * so a client that had one mounted would reuse the wrong cached layout. The\n * switch is sticky rather than per-node because the *descendants* are where\n * the false URLs are; the intercepting node alone is not the problem.\n *\n * This is the single source of truth for segment keys — used by the\n * element builder (skip decisions, SegmentOutlet props), segment info\n * (X-Timber-Segments header), the client cache/state tree, and\n * interception scoping (`routing/interception.ts`).\n */\nexport function computeSegmentKeys(segments: SegmentKeyInput[]): string[] {\n  const keys: string[] = [];\n  let prevKey = '';\n  let insideIntercepting = false;\n\n  for (const segment of segments) {\n    if (segment.segmentType === 'intercepting') insideIntercepting = true;\n    if (segment.segmentType === 'group' || insideIntercepting) {\n      const base = prevKey === '/' ? '' : prevKey;\n      const key = `${base}/${segment.segmentName}`;\n      keys.push(key);\n      prevKey = key;\n    } else {\n      keys.push(segment.urlPath);\n      prevKey = segment.urlPath;\n    }\n  }\n\n  return keys;\n}\n\n/**\n * Compute tree paths for a segment chain — the directory path of each segment\n * with slots elided, e.g. `app/(browse)/feed` → `/(browse)/feed`.\n *\n * This is `computeSegmentKeys` with the group branch applied to *every*\n * segment rather than only to groups. That one difference is the whole point:\n * `computeSegmentKeys` resets to `urlPath` at each URL-visible segment, so\n * `(browse)/feed` and `(landing)/feed` both key as `/feed`. Two directories\n * that render different layouts must not share an identity.\n *\n * Used for interception scoping (`routing/interception.ts`), where the\n * question is \"does this route pass through *that* directory?\" — not \"does it\n * render this URL?\". Not interchangeable with `computeSegmentKeys`: the state\n * tree is keyed by URL on purpose, because the client caches by URL.\n */\nexport function computeSegmentTreePaths(segments: SegmentKeyInput[]): string[] {\n  const paths: string[] = [];\n  let prev = '';\n\n  for (const segment of segments) {\n    const name = segment.segmentName ?? '';\n    if (!name) {\n      // The app root — no directory name of its own.\n      paths.push('/');\n      prev = '/';\n      continue;\n    }\n    const base = prev === '/' ? '' : prev;\n    const path = `${base}/${name}`;\n    paths.push(path);\n    prev = path;\n  }\n\n  return paths;\n}\n\n/**\n * The directory names a tree path is built from — `/` is none, `/feed/(a)` is\n * `['feed', '(a)']`.\n *\n * The inverse of the walk above, and it lives beside it so the format is\n * stated once: `findChainByTreePath` (`server/children-interception.ts`) walks\n * these names back down the tree to the directory the path addresses, and\n * `treePathDepth` counts them. Both are readings of the same string, and a\n * reader that disagreed with the producer about what separates two names\n * resolves an interception to the wrong node or to none.\n */\nexport function treePathNames(treePath: string): string[] {\n  return treePath === '/' ? [] : treePath.slice(1).split('/');\n}\n\n/**\n * How many directories a tree path names — `/` is 0, `/feed` is 1,\n * `/feed/(a)` is 2.\n *\n * Two tree paths on a single rendered chain are strictly nested, so on that\n * chain depth orders them totally — which is what makes it usable as \"the\n * deeper of these two directories\" wherever a route passes through both\n * (`routing/interception.ts`).\n */\nexport function treePathDepth(treePath: string): number {\n  return treePathNames(treePath).length;\n}\n\n/**\n * Compute a unique key for a parallel route slot.\n * Format: `{parentSegmentId}/@{slotName}`, e.g. `/@sidebar` or `/dashboard/@modal`.\n */\nexport function computeSlotKey(parentSegmentId: string, slotName: string): string {\n  const name = slotName.startsWith('@') ? slotName : `@${slotName}`;\n  const prefix = parentSegmentId === '/' ? '' : parentSegmentId;\n  return `${prefix}/${name}`;\n}\n\n/**\n * Compute a content key for a parallel route slot.\n *\n * The content key encodes everything that determines the slot's rendered\n * output for a given navigation: the slot key (which includes the owning\n * segment's identity and the slot name), the URL parts consumed by the\n * owning segment (which determine parent params the slot page might\n * read), the matched page file (or a sentinel for `default.tsx`), and\n * the slot's own extracted params.\n *\n * The slot key prevents cross-group collisions: two route groups at the\n * same URL level each owning a `@sidebar` slot produce different keys\n * even when both fall back to `default.tsx`.\n *\n * The key is opaque to the client — it stores whatever the server sent\n * and advertises it back. The server computes the destination key and\n * checks membership. This eliminates the need for the server to\n * reconstruct the client's state from a departing URL.\n *\n * See design/07-routing.md §\"Segment Tree Diffing on Navigation\"\n */\nexport function computeSlotContentKey(\n  slotKey: string,\n  ownerParts: string[],\n  entryFile: string | null,\n  slotParams: Record<string, string | string[]>\n): string {\n  const owner = ownerParts.join('/');\n  const entry = entryFile ?? '\\x01';\n  const paramKeys = Object.keys(slotParams).sort();\n  const paramParts = paramKeys.map((k) => {\n    const v = slotParams[k];\n    return Array.isArray(v) ? `${k}=${v.join('\\x02')}` : `${k}=${v}`;\n  });\n  return [slotKey, owner, entry, ...paramParts].join('\\0');\n}\n"],"mappings":"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"}

package/dist/_chunks/{use-query-states-DFvWd-EA.js → use-query-states-BbU5Ge1V.js}

@@ -1,5 +1,21 @@
-import { t as getSearchParamsDefinition } from "./registry-DbJPKoBp.js";
 import { useQueryStates } from "nuqs";
+//#region src/search-params/parse-total.ts
+function hasParseServerSide(codec) {
+	return typeof codec.parseServerSide === "function";
+}
+/**
+* Parse a raw URL value through a codec, using the codec's total entry
+* point when it publishes one.
+*
+* Returns `T`, from both branches. A `null` for an absent param is part of
+* the codec's own `T` — see TotalCodec above — so this signature does not
+* widen it, and a caller that must handle "no value" (`withDefault`) sees
+* it because `T` carries it.
+*/
+function parseTotal(codec, raw) {
+	return hasParseServerSide(codec) ? codec.parseServerSide(raw) : codec.parse(raw);
+}
+//#endregion
 //#region src/client/use-query-states.ts
 /**
 * useQueryStates — client-side hook for URL-synced search params.
@@ -23,30 +39,43 @@ function unwrapNuqsValue(value) {
 	return value;
 }
 /**
-* Bridge a timber SearchParamCodec to a nuqs-compatible SingleParser.
+* Bridge a timber SearchParamCodec to a nuqs-compatible MultiParser.
 *
 * nuqs parsers: { parse(string) → T|null, serialize?(T) → string, eq?, defaultValue? }
 * timber codecs: { parse(string|string[]|undefined) → T, serialize(T) → string|null }
 *
-* The defaultValue is computed eagerly. Codecs are documented to return a
-* default rather than throw, but a throwing codec must not crash every
-* component that mounts the hook — treat its default as undefined and let
-* its error surface from server-side parse() instead.
+* The defaultValue is computed eagerly, through `parseTotal` — the same
+* entry point server-side `parse()` uses, so the hook and the server agree
+* on what an absent param means (a bare nuqs parser answers `null`, not
+* `undefined`; TIM-1350). Codecs are documented to return a default rather
+* than throw, but a throwing codec must not crash every component that
+* mounts the hook — treat its default as undefined and let its error
+* surface from server-side parse() instead.
+*
+* A `null` absent-value is NOT registered as the nuqs default. nuqs
+* already represents an absent key as `null`, so the hook reads the same
+* value either way — but registering it makes `clearOnDefault` fire on
+* `setParams({ q: null })` and delete the key before the bridged
+* `serialize` runs. For a codec that encodes `null` as a real query value
+* (`serialize(null) === 'none'`), that silently disagrees with
+* `buildSearchParams({ q: null })`, which writes it. Same reasoning as
+* `getDefaultSerialized` on the server: a codec with no value for an
+* absent param has no default to register.
 */
 function bridgeCodec(codec) {
-	let defaultValue;
+	let absent;
 	try {
-		defaultValue = codec.parse(void 0);
+		absent = parseTotal(codec, void 0);
 	} catch {
-		defaultValue = void 0;
+		absent = void 0;
 	}
-	return {
-		parse: (v) => wrapNuqsValue(codec.parse(v)),
+	const parser = {
+		type: "multi",
+		parse: (v) => wrapNuqsValue(parseTotal(codec, v.length === 1 ? v[0] : [...v])),
 		serialize: (v) => {
 			const value = unwrapNuqsValue(v);
-			return value === void 0 ? "" : codec.serialize(value) ?? "";
+			return [value === void 0 ? "" : codec.serialize(value) ?? ""];
 		},
-		defaultValue: wrapNuqsValue(defaultValue),
 		eq: (a, b) => {
 			if (a === b) return true;
 			try {
@@ -56,6 +85,23 @@ function bridgeCodec(codec) {
 			}
 		}
 	};
+	if (absent !== null) parser.defaultValue = wrapNuqsValue(absent);
+	return parser;
+}
+/**
+* Collect `withUrlKey` aliases off a codec map.
+*
+* `withUrlKey(codec, 'q')` returns a codec carrying `urlKey: 'q'`, so the map
+* alone is enough to reconstruct the aliases — `defineSearchParams` builds its
+* own `urlKeys` from exactly this property.
+*/
+function deriveUrlKeys(codecs) {
+	const result = {};
+	for (const key of Object.keys(codecs)) {
+		const alias = codecs[key]?.urlKey;
+		if (alias) result[key] = alias;
+	}
+	return result;
 }
 /**
 * Bridge an entire codec map to nuqs-compatible parsers.
@@ -73,7 +119,7 @@ function bridgeCodecs(codecs) {
 *
 * Usage:
 * ```ts
-* // Via a SearchParamsDefinition
+* // Via a SearchParamsDefinition imported from the route's params.ts
 * const [params, setParams] = definition.useQueryStates()
 *
 * // Standalone with inline codecs
@@ -81,22 +127,24 @@ function bridgeCodecs(codecs) {
 *   page: fromSchema(z.coerce.number().int().min(1).default(1)),
 * })
 * ```
+*
+* There is deliberately no route-string form (`useQueryStates('/products')`).
+* Importing the definition from `params.ts` is the documented way to reach
+* another route's codecs — it needs no runtime registry lookup and so has no
+* "not registered yet" failure mode. See design/23-search-params.md
+* §"Client Access".
 */
-function useQueryStates$1(codecsOrRoute, _options, urlKeys) {
-	let codecs;
-	let resolvedUrlKeys = urlKeys;
-	if (typeof codecsOrRoute === "string") {
-		const definition = getSearchParamsDefinition(codecsOrRoute);
-		if (!definition) throw new Error(`useQueryStates('${codecsOrRoute}'): no search params registered for this route. Either the route has no search-params.ts file, or it hasn't been loaded yet. For cross-route usage, import the definition explicitly.`);
-		codecs = definition.codecs;
-		resolvedUrlKeys = definition.urlKeys;
-	} else codecs = codecsOrRoute;
+function useQueryStates$1(codecs, _options, urlKeys) {
 	const bridged = bridgeCodecs(codecs);
 	const nuqsOptions = {};
 	if (_options?.shallow !== void 0) nuqsOptions.shallow = _options.shallow;
 	if (_options?.scroll !== void 0) nuqsOptions.scroll = _options.scroll;
 	if (_options?.history !== void 0) nuqsOptions.history = _options.history;
-	if (resolvedUrlKeys && Object.keys(resolvedUrlKeys).length > 0) nuqsOptions.urlKeys = resolvedUrlKeys;
+	const resolvedUrlKeys = {
+		...deriveUrlKeys(codecs),
+		...urlKeys
+	};
+	if (Object.keys(resolvedUrlKeys).length > 0) nuqsOptions.urlKeys = resolvedUrlKeys;
 	let values;
 	let setValues;
 	try {
@@ -149,6 +197,6 @@ function bindUseQueryStates(definition) {
 	};
 }
 //#endregion
-export { useQueryStates$1 as n, bindUseQueryStates as t };
+export { useQueryStates$1 as n, parseTotal as r, bindUseQueryStates as t };
 
-//# sourceMappingURL=use-query-states-DFvWd-EA.js.map
+//# sourceMappingURL=use-query-states-BbU5Ge1V.js.map

package/dist/_chunks/use-query-states-BbU5Ge1V.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-query-states-BbU5Ge1V.js","names":[],"sources":["../../src/search-params/parse-total.ts","../../src/client/use-query-states.ts"],"sourcesContent":["/**\n * parseTotal — invoke a codec over the FULL raw domain.\n *\n * `SearchParamCodec.parse` is documented to be total over\n * `string | string[] | undefined`, because that is exactly what a URL\n * hands it: a param can be absent (`undefined`) or repeated (`string[]`).\n * Timber's own codecs and the Standard Schema bridges honour that.\n *\n * nuqs parsers do not. Their `parse` expects a **present scalar string** —\n * nuqs checks presence itself before ever calling it — so `parseAsBoolean`\n * and `parseAsIsoDate` threw a render-phase 500 on an absent param and\n * `parseAsString` returned an array on a repeated one (TIM-1350).\n *\n * nuqs ships the missing adapter: every parser builder exposes\n * `parseServerSide(value: string | string[] | undefined)`, which maps\n * absent → `null` (or the parser's `withDefault` value), takes the FIRST\n * entry of a repeated param (matching `URLSearchParams.get()`), and wraps\n * the inner `parse` so a throw becomes `null`. That is precisely timber's\n * domain, so we call it in preference to `parse` rather than hand-rolling\n * a second normalization that could disagree with the client hook.\n *\n * Feature detection, not an instanceof check: any codec MAY publish\n * `parseServerSide` to declare \"this is my total entry point\" — it is an\n * optional member of `SearchParamCodec` — and a codec that does not is\n * assumed already total and called through `parse`. Timber codecs and\n * schema bridges take the second branch untouched; several of them rely on\n * `parse(undefined)` to produce their default.\n *\n * **Search params only.** Segment params (`server/param-coercion.ts`) call\n * `codec.parse` directly and must keep doing so: their domain is a value\n * the router matched, never absent, and a codec that REJECTS one is how a\n * route produces a 404. Routing a rejection through nuqs's `safeParse`\n * would turn that 404 into a silent `null` param. The two domains differ\n * in what \"no value\" means, not just in plumbing. Cookies are a third\n * domain (`cookies/define-cookie.ts`) and are likewise untouched.\n *\n * `parseServerSide` carries a `@deprecated` tag in nuqs (it steers users to\n * loaders, which timber does not use). It remains public, typed and\n * exercised; `tests/nuqs-codec-boundary.test.ts` asserts totality for every\n * parser through timber's own API, so a nuqs release that drops it fails\n * loudly rather than silently reinstating the 500s.\n *\n * Design doc: design/23-search-params.md §\"nuqs parsers, made total\"\n */\n\nimport type { Codec } from '../codec.js';\n\n/**\n * A codec that publishes a total entry point over the raw URL domain.\n *\n * The return is `T`, not `T | null`: this is the entry point timber calls,\n * so whatever it answers IS the field's type. A `null` for an absent param\n * belongs in `T` — a bare nuqs parser is a codec of `string | null`, and\n * `parseAsInteger.withDefault(1)` is a codec of `number`, because nuqs\n * narrows its own `parseServerSide` return to `NonNullable<T>`. Declaring\n * `T | null` here would let a codec annotated `SearchParamCodec<string>`\n * hand back `null` under a non-nullable type (TIM-1350 review).\n */\nexport interface TotalCodec<T> {\n  parseServerSide(value: string | string[] | undefined): T;\n}\n\nfunction hasParseServerSide<T>(codec: Codec<T>): codec is Codec<T> & TotalCodec<T> {\n  return typeof (codec as Partial<TotalCodec<T>>).parseServerSide === 'function';\n}\n\n/**\n * Parse a raw URL value through a codec, using the codec's total entry\n * point when it publishes one.\n *\n * Returns `T`, from both branches. A `null` for an absent param is part of\n * the codec's own `T` — see TotalCodec above — so this signature does not\n * widen it, and a caller that must handle \"no value\" (`withDefault`) sees\n * it because `T` carries it.\n */\nexport function parseTotal<T>(codec: Codec<T>, raw: string | string[] | undefined): T {\n  return hasParseServerSide(codec) ? codec.parseServerSide(raw) : codec.parse(raw);\n}\n","/**\n * useQueryStates — client-side hook for URL-synced search params.\n *\n * Delegates to nuqs for URL synchronization, batching, React 19 transitions,\n * and throttled URL writes. Bridges timber's SearchParamCodec protocol to\n * nuqs-compatible parsers.\n *\n * Design doc: design/23-search-params.md §\"Codec Bridge\"\n */\n\n'use client';\n\nimport { useQueryStates as nuqsUseQueryStates } from 'nuqs';\nimport type { MultiParser } from 'nuqs';\nimport type {\n  SearchParamCodec,\n  SearchParamsDefinition,\n  SetParams,\n  QueryStatesOptions,\n} from '../search-params/define.js';\nimport { parseTotal } from '../search-params/parse-total.js';\n\n// ─── Codec Bridge ─────────────────────────────────────────────────\n\n// nuqs's parser contract conflates values timber codecs distinguish:\n// parse() returning null means \"unparseable, substitute defaultValue\",\n// and undefined entries are skipped entirely. Timber codecs can\n// legitimately produce both — bare z.string() yields undefined for absent\n// params (implicit optionality), and a codec may map a present value to\n// null. Wrap those two values in sentinels across the nuqs boundary and\n// unwrap them before handing values back to the caller, so the client\n// hook returns exactly what server-side parse() returns.\n// Unique object references compared by identity — a codec can never\n// produce these from URL input, so user-controlled strings cannot collide\n// with them (unlike string sentinels), and unlike Symbols they survive\n// nuqs's internal string coercion without throwing.\nconst NULL_SENTINEL: object = { timberSentinel: 'null' };\nconst UNDEFINED_SENTINEL: object = { timberSentinel: 'undefined' };\n\nfunction wrapNuqsValue(value: unknown): unknown {\n  if (value === null) return NULL_SENTINEL;\n  if (value === undefined) return UNDEFINED_SENTINEL;\n  return value;\n}\n\nfunction unwrapNuqsValue(value: unknown): unknown {\n  if (value === NULL_SENTINEL) return null;\n  if (value === UNDEFINED_SENTINEL) return undefined;\n  return value;\n}\n\n/**\n * Bridge a timber SearchParamCodec to a nuqs-compatible MultiParser.\n *\n * nuqs parsers: { parse(string) → T|null, serialize?(T) → string, eq?, defaultValue? }\n * timber codecs: { parse(string|string[]|undefined) → T, serialize(T) → string|null }\n *\n * The defaultValue is computed eagerly, through `parseTotal` — the same\n * entry point server-side `parse()` uses, so the hook and the server agree\n * on what an absent param means (a bare nuqs parser answers `null`, not\n * `undefined`; TIM-1350). Codecs are documented to return a default rather\n * than throw, but a throwing codec must not crash every component that\n * mounts the hook — treat its default as undefined and let its error\n * surface from server-side parse() instead.\n *\n * A `null` absent-value is NOT registered as the nuqs default. nuqs\n * already represents an absent key as `null`, so the hook reads the same\n * value either way — but registering it makes `clearOnDefault` fire on\n * `setParams({ q: null })` and delete the key before the bridged\n * `serialize` runs. For a codec that encodes `null` as a real query value\n * (`serialize(null) === 'none'`), that silently disagrees with\n * `buildSearchParams({ q: null })`, which writes it. Same reasoning as\n * `getDefaultSerialized` on the server: a codec with no value for an\n * absent param has no default to register.\n */\nfunction bridgeCodec<T>(codec: SearchParamCodec<T>): MultiParser<T> & { defaultValue: T } {\n  let absent: unknown;\n  try {\n    absent = parseTotal(codec, undefined);\n  } catch {\n    absent = undefined;\n  }\n\n  const parser = {\n    // `multi`, so nuqs reads the key with `searchParams.getAll()` and hands\n    // us EVERY value. A single parser reads `.get()` — the first value only\n    // — which is not the domain a timber codec is defined over. The server\n    // parses `?tags=a&tags=b` as `['a','b']`; a single parser made the hook\n    // answer `['a']` for the same URL, under a declared `string[]` that\n    // admitted no such disagreement (TIM-1352). Scalar codecs are unaffected:\n    // they receive the array and take `value[0]`, exactly as they do on the\n    // server, so first-value-wins is preserved through the same code path\n    // rather than through nuqs's reader.\n    //\n    // nuqs never calls this with an empty array — `isAbsentFromUrl` treats\n    // `[]` as absent and answers `defaultValue` directly — which is what\n    // keeps the absent case agreeing with the server's `undefined`.\n    //\n    // Reading every value is only half of it: the values must arrive in the\n    // SAME SHAPE the server would have produced, or the divergence just\n    // moves. `normalizeRaw` (search-params/define.ts) collapses a\n    // single-valued key to a bare string and keeps an array only for a\n    // repeated one, so this mirrors that rule exactly. Handing a codec\n    // `['3']` where the server hands it `'3'` breaks every codec whose\n    // `parse` is written for the scalar case — which is most hand-written\n    // ones, contract or no contract.\n    type: 'multi' as const,\n    // Through parseTotal, not codec.parse. nuqs's own `.withDefault(d)`\n    // overrides ONLY `parseServerSide`, so `parseAsInteger.withDefault(1)`\n    // on `?page=abc` returned 1 from the server and null from the hook —\n    // a divergence the declared non-nullable `number` did not admit.\n    parse: (v: readonly string[]) =>\n      wrapNuqsValue(parseTotal(codec, v.length === 1 ? v[0] : [...v])),\n    serialize: (v: unknown) => {\n      const value = unwrapNuqsValue(v);\n      // Delegate null to the codec — some codecs encode null as a real\n      // query value. undefined has no encoding; nuqs requires a string.\n      //\n      // ONE element, always. A multi parser may return several — nuqs\n      // appends one key per entry — but `Codec.serialize` returns a single\n      // string by construction, so timber cannot emit repeated keys here\n      // any more than `buildSearchParams` can. Widening that protocol is\n      // TIM-1353. Wrapping the same string keeps the URL the hook writes\n      // byte-identical to the one `buildSearchParams` writes.\n      return [value === undefined ? '' : (codec.serialize(value as T) ?? '')];\n    },\n    eq: (a: unknown, b: unknown) => {\n      if (a === b) return true;\n      try {\n        return (\n          codec.serialize(unwrapNuqsValue(a) as T) === codec.serialize(unwrapNuqsValue(b) as T)\n        );\n      } catch {\n        return false;\n      }\n    },\n  } as MultiParser<T> & { defaultValue: T };\n\n  if (absent !== null) parser.defaultValue = wrapNuqsValue(absent) as T;\n  return parser;\n}\n\n/**\n * Collect `withUrlKey` aliases off a codec map.\n *\n * `withUrlKey(codec, 'q')` returns a codec carrying `urlKey: 'q'`, so the map\n * alone is enough to reconstruct the aliases — `defineSearchParams` builds its\n * own `urlKeys` from exactly this property.\n */\nfunction deriveUrlKeys(codecs: Record<string, SearchParamCodec<unknown>>): Record<string, string> {\n  const result: Record<string, string> = {};\n  for (const key of Object.keys(codecs)) {\n    const alias = codecs[key]?.urlKey;\n    if (alias) result[key] = alias;\n  }\n  return result;\n}\n\n/**\n * Bridge an entire codec map to nuqs-compatible parsers.\n */\nfunction bridgeCodecs<T extends Record<string, unknown>>(codecs: {\n  [K in keyof T]: SearchParamCodec<T[K]>;\n}) {\n  const result: Record<string, MultiParser<unknown> & { defaultValue: unknown }> = {};\n  for (const key of Object.keys(codecs)) {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    result[key] = bridgeCodec(codecs[key as keyof T]) as any;\n  }\n  return result as { [K in keyof T]: MultiParser<T[K]> & { defaultValue: T[K] } };\n}\n\n// ─── Hook ─────────────────────────────────────────────────────────\n\n/**\n * Read and write typed search params from/to the URL.\n *\n * Delegates to nuqs internally. The timber nuqs adapter (auto-injected in\n * browser-entry.ts) handles RSC navigation on non-shallow updates.\n *\n * Usage:\n * ```ts\n * // Via a SearchParamsDefinition imported from the route's params.ts\n * const [params, setParams] = definition.useQueryStates()\n *\n * // Standalone with inline codecs\n * const [params, setParams] = useQueryStates({\n *   page: fromSchema(z.coerce.number().int().min(1).default(1)),\n * })\n * ```\n *\n * There is deliberately no route-string form (`useQueryStates('/products')`).\n * Importing the definition from `params.ts` is the documented way to reach\n * another route's codecs — it needs no runtime registry lookup and so has no\n * \"not registered yet\" failure mode. See design/23-search-params.md\n * §\"Client Access\".\n */\nexport function useQueryStates<T extends Record<string, unknown>>(\n  codecs: { [K in keyof T]: SearchParamCodec<T[K]> },\n  _options?: QueryStatesOptions,\n  urlKeys?: Readonly<Record<string, string>>\n): [T, SetParams<T>] {\n  const bridged = bridgeCodecs(codecs);\n\n  // Forward hook-level options (shallow, scroll, history) to nuqs.\n  // These become the default for all setter calls from this hook instance.\n  // Per-call options in setParams(values, opts) override these defaults.\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const nuqsOptions: any = {};\n  if (_options?.shallow !== undefined) nuqsOptions.shallow = _options.shallow;\n  if (_options?.scroll !== undefined) nuqsOptions.scroll = _options.scroll;\n  if (_options?.history !== undefined) nuqsOptions.history = _options.history;\n  // `withUrlKey` attaches the alias to the codec itself — that is the design's\n  // \"URL keys travel with codecs\" principle — so the aliases are derivable\n  // here and must be, for the inline codec-map form: nobody passes `urlKeys`\n  // on that path, and without this an aliased bundle silently read and wrote\n  // the property name instead of the alias. `bindUseQueryStates` still passes\n  // the definition's precomputed map, which wins on conflict; it is built from\n  // these same codecs, so the two agree by construction rather than by luck.\n  const resolvedUrlKeys = { ...deriveUrlKeys(codecs), ...urlKeys };\n  if (Object.keys(resolvedUrlKeys).length > 0) {\n    nuqsOptions.urlKeys = resolvedUrlKeys;\n  }\n\n  let values: Record<string, unknown>;\n  let setValues: Function;\n  try {\n    [values, setValues] = nuqsUseQueryStates(bridged, nuqsOptions);\n  } catch (err) {\n    if (\n      err instanceof Error &&\n      /Invalid hook call|cannot be called|Cannot read properties of null/i.test(err.message)\n    ) {\n      throw new Error(\n        'useQueryStates is a client component hook and cannot be called outside a React component. ' +\n          'Use definition.parse(searchParams) in server components instead.'\n      );\n    }\n    throw err;\n  }\n\n  // Unwrap the null/undefined sentinels the bridge injected (see Codec\n  // Bridge above) so callers see exactly what server-side parse() returns.\n  // Copy-on-write preserves the identity of nuqs's memoized values object\n  // when nothing needs unwrapping.\n  let normalized = values;\n  for (const key of Object.keys(bridged)) {\n    const value = normalized[key];\n    if (value === NULL_SENTINEL || value === UNDEFINED_SENTINEL) {\n      if (normalized === values) normalized = { ...values };\n      normalized[key] = unwrapNuqsValue(value);\n    }\n  }\n\n  // Wrap the nuqs setter to match timber's SetParams<T> signature.\n  // nuqs's setter accepts Partial<Nullable<Values>> | UpdaterFn | null.\n  // timber's setter accepts Partial<T> with optional SetParamsOptions.\n  const setParams: SetParams<T> = (partial, setOptions?) => {\n    const nuqsSetOptions: Record<string, unknown> = {};\n    if (setOptions?.shallow !== undefined) nuqsSetOptions.shallow = setOptions.shallow;\n    if (setOptions?.scroll !== undefined) nuqsSetOptions.scroll = setOptions.scroll;\n    if (setOptions?.history !== undefined) nuqsSetOptions.history = setOptions.history;\n    // nuqs's update loop skips undefined entries and treats null as a\n    // key deletion before serialize runs. Timber semantics:\n    //   - setParams({ q: undefined }) must clear ?q= (absent = undefined),\n    //     so explicit undefined maps to a null deletion.\n    //   - setParams({ q: null }) clears the key only when the codec encodes\n    //     null as \"omit\" (serialize(null) === null). If the codec encodes\n    //     null as a real query value, forward the sentinel so the bridged\n    //     serialize writes it — matching definition.serialize({ q: null }).\n    let forwarded: Record<string, unknown> = partial;\n    for (const key of Object.keys(partial)) {\n      const value = partial[key as keyof T];\n      if (value === undefined) {\n        if (forwarded === partial) forwarded = { ...partial };\n        forwarded[key] = null;\n      } else if (value === null) {\n        let encoded: string | null = null;\n        try {\n          encoded = codecs[key as keyof T]?.serialize(null as T[keyof T]) ?? null;\n        } catch {\n          // Codec can't serialize null — treat as a deletion.\n        }\n        if (encoded !== null) {\n          if (forwarded === partial) forwarded = { ...partial };\n          forwarded[key] = NULL_SENTINEL;\n        }\n      }\n    }\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    void setValues(forwarded as any, nuqsSetOptions);\n  };\n\n  return [normalized as T, setParams];\n}\n\n// ─── Definition binding ───────────────────────────────────────────\n\n/**\n * Create a useQueryStates binding for a SearchParamsDefinition.\n * This is used internally by SearchParamsDefinition.useQueryStates().\n */\nexport function bindUseQueryStates<T extends Record<string, unknown>>(\n  definition: SearchParamsDefinition<T>\n): (options?: QueryStatesOptions) => [T, SetParams<T>] {\n  return (options?: QueryStatesOptions) => {\n    return useQueryStates<T>(definition.codecs, options, definition.urlKeys);\n  };\n}\n"],"mappings":"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"}