@timber-js/app 0.2.0-alpha.157 → 0.2.0-alpha.159

package/dist/_chunks/walkers-D5jCGPum.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"walkers-D5jCGPum.js","names":[],"sources":["../../src/routing/codegen-shared.ts","../../src/routing/file-cache.ts","../../src/routing/link-codegen.ts","../../src/routing/codegen.ts","../../src/routing/schema-validation.ts","../../src/routing/interception.ts","../../src/routing/walkers.ts"],"sourcesContent":["/**\n * Shared codegen helpers — import-path computation, codec chain type\n * builder, and searchParams type formatter.\n *\n * Extracted from `codegen.ts` so `link-codegen.ts` can use the same\n * helpers without a cyclic import.\n */\n\nimport { relative, posix } from 'node:path';\nimport type { ParamEntry, RouteEntry } from './codegen-types.js';\n\n/**\n * Compute a relative import specifier for a codec/page file, stripping\n * the .ts/.tsx extension and resolving against the codegen output dir.\n */\nexport function codecImportPath(codecFilePath: string, importBase: string | undefined): string {\n  const absPath = codecFilePath.replace(/\\.(ts|tsx)$/, '');\n  if (importBase) {\n    return './' + relative(importBase, absPath).replace(/\\\\/g, '/');\n  }\n  return './' + posix.basename(absPath);\n}\n\n/** Name of the shared helper type emitted at the top of the .d.ts. */\nexport const RESOLVE_SEGMENT_FIELD_TYPE_NAME = '_TimberResolveSegmentField';\n\n/**\n * Helper type emitted once at the top of the generated `.d.ts` and\n * referenced by every codec-chain conditional. Without this shared\n * helper, the inline expansion would duplicate the fallback branch on\n * every step and grow O(2^N) in chain depth (a single deep nested route\n * could blow up the file size and TS performance). With the helper,\n * each step reuses the named type and growth is O(N).\n *\n * The helper is a 2-arg conditional: given a typeof import expression\n * (`Def`), a key (`K`), and a fallback (`F`), it returns `T[K]` if\n * `Def extends ParamsDefinition<T>` and `K extends keyof T`, otherwise\n * `F`. The codec chain composes calls to this helper.\n */\nexport function emitResolveSegmentFieldHelper(): string {\n  return [\n    `type ${RESOLVE_SEGMENT_FIELD_TYPE_NAME}<Def, K extends string, F> =`,\n    `  Def extends import('@timber-js/app/segment-params').ParamsDefinition<infer T>`,\n    `    ? K extends keyof T ? T[K] : F`,\n    `    : F;`,\n  ].join('\\n');\n}\n\n/**\n * Build a TypeScript type expression that resolves a single param's\n * codec by walking a chain of params.ts files in priority order.\n *\n * Each entry in the chain emits one application of the shared\n * `_TimberResolveSegmentField` helper type. Composing N applications\n * grows linearly with chain depth (O(N) characters), unlike an inline\n * conditional that would duplicate the fallback in each branch and\n * grow O(2^N).\n *\n * The closest match (position 0 in the chain) is checked first; if its\n * `segmentParams` definition declares the key, its inferred type wins.\n * Otherwise we fall through to the next entry, and finally to the\n * provided fallback. See TIM-834.\n */\nexport function buildCodecChainType(\n  p: ParamEntry,\n  importBase: string | undefined,\n  fallback: string\n): string {\n  const files = p.codecFilePaths;\n  if (!files || files.length === 0) return fallback;\n  const key = JSON.stringify(p.name);\n  // Compose helper applications inside-out so the closest entry\n  // (files[0]) ends up as the OUTERMOST application. Each application\n  // adds a constant-size wrapper around the running fallback.\n  let inner = fallback;\n  for (let i = files.length - 1; i >= 0; i--) {\n    const importPath = codecImportPath(files[i], importBase);\n    inner = `${RESOLVE_SEGMENT_FIELD_TYPE_NAME}<(typeof import('${importPath}'))['segmentParams'], ${key}, ${inner}>`;\n  }\n  return inner;\n}\n\n/**\n * Build a TypeScript type expression for a single param using the global\n * schema's InferCodecType. Falls back to the param's base type when\n * schema doesn't declare this param (schemas are opt-in per key).\n *\n * Uses `infer` to extract the codec value rather than direct indexing\n * because TypeScript doesn't narrow index validity inside a conditional\n * type's true branch — `typeof schema.segmentParams[K]` produces TS2538\n * even when the condition proves K is a valid key. In .d.ts files that\n * error is suppressed and the type silently becomes `any`.\n */\nexport function buildSchemaParamType(p: ParamEntry, fallback?: string): string {\n  const key = JSON.stringify(p.bracketName);\n  const fb = fallback ?? p.type;\n  return `typeof schema['segmentParams'] extends Record<${key}, infer V> ? InferCodecType<V> : ${fb}`;\n}\n\n/**\n * Format the searchParams type for a route entry.\n *\n * When a page.tsx (or params.ts) exports searchParams, we reference its\n * inferred type via an import type. The import path is relative to\n * `importBase` (the directory where the .d.ts will be written). When\n * importBase is undefined, falls back to a bare relative path.\n */\nexport function formatSearchParamsType(route: RouteEntry, importBase?: string): string {\n  if (route.hasSearchParams && route.searchParamsPagePath) {\n    const importPath = codecImportPath(route.searchParamsPagePath, importBase);\n    // Extract the type from the named 'searchParams' export of the page module.\n    return `(typeof import('${importPath}'))['searchParams'] extends import('@timber-js/app/search-params').SearchParamsDefinition<infer T> ? T : never`;\n  }\n  return '{}';\n}\n","import { readFileSync, statSync } from 'node:fs';\n\nconst cache = new Map<string, { mtimeMs: number; size: number; content: string }>();\n\n/**\n * Read a file's text content, returning a cached copy when the file\n * hasn't been modified since the last read (checked via mtime + size).\n *\n * Falls back to a fresh read on any stat/read error.\n */\nexport function readFileCached(filePath: string): string {\n  try {\n    const stat = statSync(filePath);\n    const entry = cache.get(filePath);\n    if (entry && entry.mtimeMs === stat.mtimeMs && entry.size === stat.size) return entry.content;\n    const content = readFileSync(filePath, 'utf-8');\n    cache.set(filePath, { mtimeMs: stat.mtimeMs, size: stat.size, content });\n    return content;\n  } catch {\n    cache.delete(filePath);\n    return readFileSync(filePath, 'utf-8');\n  }\n}\n","/**\n * Typed `<Link>` codegen — interface augmentation generation.\n *\n * Extracted from `codegen.ts` to keep that file under the project's\n * 500-line cap. This module owns everything that emits the\n * `interface LinkFunction { ... }` augmentation blocks in the generated\n * `.timber/timber-routes.d.ts`.\n *\n * Two augmentation blocks are emitted:\n *\n * 1. **Per-route discriminated union** (`formatTypedLinkOverloads`) —\n *    one call signature whose props is a union keyed on `href`. TS\n *    narrows by literal href and reports prop errors against the\n *    matched variant. See TIM-835 and `design/09-typescript.md`.\n *\n * 2. **Catch-all overloads** (`formatLinkCatchAllOverloads`) — external\n *    href literals (`http://`, `mailto:`, etc.) and a computed-string\n *    `<H extends string>` signature for runtime-computed paths.\n *\n * Block ordering is critical for error UX: per-route is emitted FIRST\n * so that, after TS's \"later overload set ordered first\" merge rule,\n * the discriminated union ends up LAST in resolution order — the\n * overload TS reports against on failure.\n */\n\nimport type { ParamEntry, RouteEntry } from './codegen-types.js';\nimport {\n  buildCodecChainType,\n  buildSchemaParamType,\n  formatSearchParamsType,\n} from './codegen-shared.js';\n\n/** Shared Link base-props type literal used in every emitted call signature. */\nexport const LINK_BASE_PROPS_TYPE =\n  \"Omit<import('react').AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & { prefetch?: boolean; scroll?: boolean; preserveSearchParams?: true | string[]; onNavigate?: import('./client/link.js').OnNavigateHandler; children?: import('react').ReactNode }\";\n\n/**\n * Build a TypeScript template literal pattern for a dynamic route.\n * e.g. '/products/[id]'        → '/products/${string}'\n *      '/blog/[...slug]'       → '/blog/${string}'\n *      '/docs/[[...path]]'     → '/docs/${string}' (also matches /docs)\n *      '/[org]/[repo]'         → '/${string}/${string}'\n */\nexport function buildResolvedPattern(route: RouteEntry): string | null {\n  const parts = route.urlPath.split('/');\n  const templateParts = parts.map((part) => {\n    if (part.startsWith('[[...') && part.endsWith(']]')) {\n      // eslint-disable-next-line no-template-curly-in-string -- codegen output\n      return '${string}';\n    }\n    if (part.startsWith('[...') && part.endsWith(']')) {\n      // eslint-disable-next-line no-template-curly-in-string -- codegen output\n      return '${string}';\n    }\n    if (part.startsWith('[') && part.endsWith(']')) {\n      // eslint-disable-next-line no-template-curly-in-string -- codegen output\n      return '${string}';\n    }\n    return part;\n  });\n  return templateParts.join('/');\n}\n\n/**\n * Format the segmentParams type for Link overloads.\n *\n * Link params accept `string | number` for single dynamic segments\n * (convenience — values are stringified at runtime). Catch-all and\n * optional catch-all remain `string[]` / `string[] | undefined`.\n *\n * When the segment's params chain (TIM-834) declares a typed codec, the\n * inferred type from the codec wins via a nested conditional.\n */\nexport function formatLinkParamsType(\n  params: ParamEntry[],\n  importBase?: string,\n  hasSchema?: boolean\n): string {\n  if (params.length === 0) {\n    return '{}';\n  }\n\n  const fields = params.map((p) => {\n    const fallback = p.type === 'string' ? 'string | number' : p.type;\n    const codecType = hasSchema\n      ? buildSchemaParamType(p, fallback)\n      : buildCodecChainType(p, importBase, fallback);\n    return `${p.name}: ${codecType}`;\n  });\n  return `{ ${fields.join('; ')} }`;\n}\n\n/**\n * Catch-all call signatures for `<Link>` — external hrefs and computed\n * `string` variables. Emitted from codegen in a SEPARATE\n * `declare module` block (declared AFTER the per-route block) so the TS\n * \"later overload set ordered first\" rule places these catch-all\n * signatures ahead of per-route in resolution order, leaving per-route\n * as the final overload whose error message is reported on failure.\n *\n * The conditional `string extends H ? ... : never` protection preserves\n * TIM-624's guarantee that unknown internal path literals don't match\n * the catch-all — typos like `<Link href=\"/typo\" />` still error.\n */\nexport function formatLinkCatchAllOverloads(): string[] {\n  const lines: string[] = [];\n  const baseProps = LINK_BASE_PROPS_TYPE;\n\n  // TIM-830: the catch-all signatures accept EITHER the legacy\n  // `{ definition, values }` wrapper OR a flat `Record<string, unknown>`\n  // values object. External/computed hrefs can't be looked up in the\n  // runtime registry, so the wrapped form is still the reliable path;\n  // the flat form is kept permissive for callers migrating from typed-\n  // route hrefs to computed strings. `resolveHref` discriminates at\n  // runtime via the presence of a `definition` key.\n  const catchAllSearchParams =\n    '{ definition: SearchParamsDefinition<Record<string, unknown>>; values: Record<string, unknown> } | Record<string, unknown>';\n\n  // ExternalHref inlined here rather than referenced as an exported\n  // alias so the generated .d.ts stands alone without source imports.\n  /* eslint-disable no-template-curly-in-string -- codegen output */\n  const externalHref =\n    '`http://${string}` | `https://${string}` | `mailto:${string}` | `tel:${string}` | `ftp://${string}` | `//${string}` | `#${string}` | `?${string}`';\n  /* eslint-enable no-template-curly-in-string */\n\n  lines.push('  // Typed Link overloads — catch-all (block 2 / emitted second)');\n  lines.push('  interface LinkFunction {');\n\n  // (1) External/literal-protocol hrefs.\n  //\n  // TIM-833: `segmentParams` is permissively typed as\n  // `Record<string, unknown>` (not `never`) so generic wrappers that\n  // forward a `LinkProps`-shaped object can compile when the wrapper\n  // happens to bottom out at an external href. There are no dynamic\n  // segments to interpolate for an external href, so this prop is\n  // ignored at runtime — accepting an open-shape object instead of\n  // forbidding it removes a footgun without changing behavior.\n  lines.push(`    (props: ${baseProps} & {`);\n  lines.push(`      href: ${externalHref}`);\n  lines.push(`      segmentParams?: Record<string, unknown>`);\n  lines.push(`      searchParams?: ${catchAllSearchParams}`);\n  lines.push(`    }): import('react').JSX.Element`);\n\n  // (2) Computed/variable href — non-literal `string` only.\n  //\n  // `string extends H` is true only when H is the wide `string` type,\n  // not a specific literal. For literal hrefs, this overload must NOT\n  // be selectable so the per-route discriminated union (block 1) is\n  // the resolution target.\n  //\n  // TIM-833 follow-up: the previous shape used `string extends H ? {...} : never`\n  // on the WHOLE props type. For literal H, that collapsed `props` to\n  // `never`, and JSX type inference then read `(never).children` as\n  // `never` — producing the misleading\n  // `'children' prop expects type 'never' which requires multiple\n  // children, but only a single child was provided` (TS2745) error,\n  // which buried the actual prop-mismatch message under a noise diagnostic.\n  //\n  // Fix: move the `: never` from the whole props onto just the `href`\n  // field. The overload remains uncallable for literal H (since `\"/x\"`\n  // is not assignable to `never`), but `children` retains its real\n  // `ReactNode` type so JSX inference no longer collapses to never.\n  // The diagnostic surface becomes: TS reports the per-route block's\n  // error chain (the helpful \"Type 'number' is not assignable to type\n  // 'string'\" message) WITHOUT a leading TS2745 noise line.\n  lines.push(`    <H extends string>(`);\n  lines.push(`      props: ${baseProps} & {`);\n  lines.push(`        href: string extends H ? H : never`);\n  lines.push(`        segmentParams?: Record<string, string | number | string[]>`);\n  lines.push(`        searchParams?: ${catchAllSearchParams}`);\n  lines.push(`      }`);\n  lines.push(`    ): import('react').JSX.Element`);\n\n  lines.push('  }');\n  return lines;\n}\n\n/**\n * Generate typed per-route Link call signatures via LinkFunction\n * interface merging.\n *\n * TIM-835: This emits a SINGLE call signature whose props is a\n * discriminated union keyed on `href`. TypeScript narrows the union by\n * the literal `href` at the call site, then checks the rest of the\n * props against the matched variant. When `segmentParams` or\n * `searchParams` is wrong, TS reports the error against the matched\n * variant — naming the user's actual `href` and the offending field.\n *\n * Before TIM-835, this function emitted N separate per-route overloads\n * (one per route, sometimes two for dynamic routes). When ALL overloads\n * failed, TS would pick an arbitrary failed overload (heuristically the\n * \"last tried\") to render the diagnostic, often pointing at a route\n * completely unrelated to the one the user wrote. The discriminated\n * union sidesteps overload-resolution heuristics entirely.\n *\n * Open property shapes (`Record<string, unknown>` instead of `never`)\n * for `segmentParams` on routes that don't declare them keep generic\n * `LinkProps`-spreading wrappers compiling. (Aligned with TIM-833.)\n *\n * TIM-832: this function still emits the per-route block FIRST and the\n * catch-all block follows, so per-route remains the LAST overload set in\n * resolution order — the one TS reports against on failure. With a\n * discriminated union there is only one call signature in this block,\n * so the resolved-template-vs-pattern ordering reduces to placing the\n * pattern variant before the resolved-template variant inside the union.\n */\nexport function formatTypedLinkOverloads(\n  routes: RouteEntry[],\n  importBase?: string,\n  hasSchema?: boolean\n): string[] {\n  const lines: string[] = [];\n  const baseProps = LINK_BASE_PROPS_TYPE;\n\n  // Build the union variants. Each route contributes one variant for the\n  // pattern href (e.g. '/products/[id]') and, for dynamic routes, an\n  // additional variant for the resolved-template href (e.g.\n  // `/products/${string}`).\n  //\n  // The PATTERN variant must be listed BEFORE the resolved-template\n  // variant for the same route so that when the user writes the literal\n  // pattern href (`<Link href=\"/products/[id]\" />`), TS narrows to the\n  // pattern variant (which carries the typed `segmentParams` shape)\n  // rather than the looser resolved-template variant. Without this\n  // ordering, TS would silently match the resolved-template variant\n  // first — swallowing typed-segmentParams type errors.\n  const variants: string[] = [];\n  for (const route of routes) {\n    const hasDynamicParams = route.params.length > 0;\n    // For routes with no dynamic params, accept an absent OR open-shape\n    // segmentParams. `Record<string, unknown>` keeps generic spreads\n    // compiling and gives a readable error if a non-object is passed.\n    const paramsProp = hasDynamicParams\n      ? `segmentParams: ${formatLinkParamsType(route.params, importBase, hasSchema)}`\n      : 'segmentParams?: Record<string, unknown>';\n\n    const searchParamsType = route.hasSearchParams\n      ? formatSearchParamsType(route, importBase)\n      : null;\n    // TIM-830: pattern href uses the FLAT `Partial<T>` shape — the\n    // runtime registry is keyed by the un-interpolated pattern.\n    //\n    // TIM-833: when the route has NO searchParams definition, use\n    // `Record<string, unknown>` (open shape) instead of\n    // `Record<string, never>` so generic `LinkProps`-spreading wrappers\n    // compile. The trade-off vs the original TIM-835 strict shape is\n    // that excess searchParams keys on a no-def route no longer raise\n    // a type error — but those keys are runtime no-ops anyway, and\n    // wrapper compatibility is the more common pain point. Routes WITH\n    // a searchParams definition still get strict `Partial<T>` typing.\n    const patternSearchParamsProp = searchParamsType\n      ? `searchParams?: Partial<${searchParamsType}>`\n      : 'searchParams?: Record<string, unknown>';\n\n    // Pattern variant FIRST (more specific).\n    variants.push(\n      `${baseProps} & { href: '${route.urlPath}'; ${paramsProp}; ${patternSearchParamsProp} }`\n    );\n\n    // Resolved-template variant SECOND (looser, matches interpolated hrefs).\n    if (hasDynamicParams) {\n      const templatePattern = buildResolvedPattern(route);\n      if (templatePattern) {\n        // TIM-830: resolved-template href keeps the WRAPPED\n        // `{ definition, values }` shape — the registry can't be looked\n        // up by an already-interpolated href.\n        //\n        // TIM-833: searchParams falls back to `Record<string, unknown>`\n        // (was `Record<string, never>`) when the route has no\n        // definition, mirroring the pattern-variant change above. The\n        // resolved-template `segmentParams` is intentionally KEPT as\n        // `Record<string, never>` below to preserve TIM-835's\n        // pattern-variant typo detection: loosening segmentParams here\n        // would let the resolved-template variant shadow the pattern\n        // variant on literal pattern hrefs and silently swallow keyed\n        // typos like `<Link href=\"/[id]\" segmentParams={{ idz: 1 }} />`.\n        const resolvedSearchParamsProp = searchParamsType\n          ? `searchParams?: { definition: SearchParamsDefinition<${searchParamsType}>; values: Partial<${searchParamsType}> }`\n          : 'searchParams?: Record<string, unknown>';\n        // TIM-835: `Record<string, never>` for segmentParams forbids ANY\n        // provided keys on the resolved-template variant. Without this,\n        // the resolved-template would shadow the pattern variant for\n        // literal pattern hrefs (`<Link href=\"/products/[id]\" segmentParams={...} />`)\n        // because both variants accept the literal `'/products/[id]'`\n        // and the looser variant would silently swallow segmentParams\n        // type errors.\n        variants.push(\n          `${baseProps} & { href: \\`${templatePattern}\\`; segmentParams?: Record<string, never>; ${resolvedSearchParamsProp} }`\n        );\n      }\n    }\n  }\n\n  lines.push('  interface LinkFunction {');\n  if (variants.length === 0) {\n    // No page routes — emit nothing. The catch-all block in the second\n    // augmentation still provides external/computed-string signatures.\n    lines.push('  }');\n    return lines;\n  }\n  lines.push('    (');\n  lines.push('      props:');\n  for (const variant of variants) {\n    lines.push(`        | (${variant})`);\n  }\n  lines.push(`    ): import('react').JSX.Element`);\n  lines.push('  }');\n\n  return lines;\n}\n","/**\n * Route map codegen.\n *\n * Walks the scanned RouteTree and generates a TypeScript declaration file\n * mapping every route to its params and searchParams shapes.\n *\n * This runs at build time and in dev (regenerated on file changes).\n * No runtime overhead — purely static type generation.\n */\n\nimport { existsSync } from 'node:fs';\nimport { join, relative } from 'node:path';\nimport type { RouteTree, SegmentNode } from './types.js';\nimport type { ParamEntry, RouteEntry } from './codegen-types.js';\nimport {\n  buildCodecChainType,\n  buildSchemaParamType,\n  emitResolveSegmentFieldHelper,\n  formatSearchParamsType,\n} from './codegen-shared.js';\nimport { readFileCached } from './file-cache.js';\nimport { formatLinkCatchAllOverloads, formatTypedLinkOverloads } from './link-codegen.js';\n\n/** Options for route map generation. */\nexport interface CodegenOptions {\n  /** Absolute path to the app/ directory. Required for page searchParams detection. */\n  appDir?: string;\n  /**\n   * Absolute path to the directory where the .d.ts file will be written.\n   * Used to compute correct relative import paths for page files.\n   * Defaults to appDir when not provided (preserves backward compat for tests).\n   */\n  outputDir?: string;\n  /**\n   * Whether a global schema (app/schema.ts) exists.\n   * Auto-detected from appDir when not explicitly set.\n   */\n  hasSchema?: boolean;\n}\n\n/**\n * Generate a TypeScript declaration file string from a scanned route tree.\n *\n * The output is a `declare module '@timber-js/app'` block containing the Routes\n * interface that maps every route path to its params and searchParams shape.\n */\nexport function generateRouteMap(tree: RouteTree, options: CodegenOptions = {}): string {\n  // Auto-detect schema from appDir when not explicitly set\n  const hasSchema = options.hasSchema ?? detectSchema(options.appDir);\n\n  const routes: RouteEntry[] = [];\n  collectRoutes(tree.root, [], [], '', routes, hasSchema, false);\n\n  // Sort routes alphabetically for deterministic output\n  routes.sort((a, b) => a.urlPath.localeCompare(b.urlPath));\n\n  // When outputDir differs from appDir, import paths must be relative to outputDir\n  const importBase = options.outputDir ?? options.appDir;\n\n  return formatDeclarationFile(routes, importBase, hasSchema, options.appDir);\n}\n\n/** Schema file extensions to check, in priority order. */\nconst SCHEMA_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];\n\n/**\n * Detect whether app/schema.{ts,tsx,js,jsx} exists.\n */\nfunction detectSchema(appDir: string | undefined): boolean {\n  if (!appDir) return false;\n  return SCHEMA_EXTENSIONS.some((ext) => existsSync(join(appDir, `schema${ext}`)));\n}\n\n/**\n * Recursively walk the segment tree and collect route entries.\n *\n * A route entry is created for any segment that has a `page` or `route` file.\n * Params accumulate from ancestor dynamic segments.\n */\nfunction collectRoutes(\n  node: SegmentNode,\n  ancestorParams: ParamEntry[],\n  ancestorParamsFiles: string[],\n  parentTreePath: string,\n  routes: RouteEntry[],\n  hasSchema: boolean,\n  insideSlot: boolean\n): void {\n  // Build the tree path (includes groups, slots — uniquely identifies this segment).\n  // Root node has empty segmentName, producing treePath = ''.\n  const treePath = node.segmentName ? `${parentTreePath}/${node.segmentName}` : parentTreePath;\n  // TIM-834: Identify this segment's own params.ts (if it has a\n  // segmentParams export). The full chain of params.ts files in the\n  // route ancestry is threaded down via `ancestorParamsFiles`; codec\n  // resolution for each ParamEntry is deferred until leaf time so that\n  // descendant params.ts files can override ancestor codecs (closest-\n  // to-leaf wins, matching the runtime semantics of\n  // coerceSegmentParams which walks segments top-down and overwrites\n  // earlier coercions).\n  const ownParamsFile =\n    node.params && fileHasExport(node.params.filePath, 'segmentParams')\n      ? node.params.filePath\n      : undefined;\n\n  // Accumulate params from this segment. We attach `codecFilePaths`\n  // later (at leaf time) using the FULL chain so descendant overrides\n  // are visible. The legacy layout/page fallback is recorded now\n  // because it is per-segment (and does not participate in inheritance).\n  const params = [...ancestorParams];\n  if (node.paramName) {\n    const legacyFallback = ownParamsFile ? undefined : findLegacyParamsExport(node);\n    params.push({\n      name: node.paramName,\n      bracketName: node.segmentName,\n      type: paramTypeForSegment(node.segmentType),\n      // Codec chain populated at leaf time. We carry the per-segment\n      // legacy fallback (if any) so leaf-time resolution can fall back\n      // to it when no params.ts in the chain declares this key.\n      legacyCodecFilePath: legacyFallback,\n    });\n  }\n\n  // Extend the chain for descendants of this segment.\n  const nextAncestorFiles = ownParamsFile\n    ? [...ancestorParamsFiles, ownParamsFile]\n    : ancestorParamsFiles;\n\n  // Check if this segment is a leaf route (has page or route file)\n  const isPage = !!node.page;\n  const isApiRoute = !!node.route;\n\n  if (isPage || isApiRoute) {\n    // TIM-834 P1 fix: at LEAF time, the full chain of params.ts files\n    // (root-to-leaf) is known. Resolve every ParamEntry's\n    // `codecFilePaths` to the chain in LEAF-FIRST order so the\n    // closest-to-leaf entry is checked first — matching runtime\n    // closest-wins semantics. The chain is shared by all params in the\n    // route, so we compute it once.\n    const leafFirstChain = nextAncestorFiles.length > 0 ? [...nextAncestorFiles].reverse() : [];\n    const resolvedParams: ParamEntry[] = params.map((p) => {\n      const codecFilePaths =\n        leafFirstChain.length > 0\n          ? leafFirstChain\n          : p.legacyCodecFilePath\n            ? [p.legacyCodecFilePath]\n            : undefined;\n      return {\n        name: p.name,\n        bracketName: p.bracketName,\n        type: p.type,\n        codecFilePaths,\n      };\n    });\n\n    const entry: RouteEntry = {\n      urlPath: node.urlPath,\n      segmentPath: treePath || '/',\n      params: resolvedParams,\n      hasSearchParams: false,\n      isApiRoute,\n      isSlotRoute: insideSlot,\n      hasSchema,\n    };\n\n    // Detect searchParams export from params.ts (primary) or page.tsx (fallback)\n    if (isPage) {\n      if (node.params && fileHasExport(node.params.filePath, 'searchParams')) {\n        entry.hasSearchParams = true;\n        entry.searchParamsPagePath = node.params.filePath;\n      } else if (node.page && fileHasExport(node.page.filePath, 'searchParams')) {\n        entry.hasSearchParams = true;\n        entry.searchParamsPagePath = node.page.filePath;\n      }\n    }\n\n    routes.push(entry);\n  }\n\n  // Recurse into children\n  for (const child of node.children) {\n    collectRoutes(child, params, nextAncestorFiles, treePath, routes, hasSchema, insideSlot);\n  }\n\n  // Recurse into slots (they share the parent's URL path, but may have their own pages)\n  for (const slot of Object.values(node.slots)) {\n    collectRoutes(slot, params, nextAncestorFiles, treePath, routes, hasSchema, true);\n  }\n}\n\n/**\n * Dedupe route entries by urlPath for urlPath-keyed emissions (the Routes\n * interface, useQueryStates overloads, and typed Link variants).\n *\n * Parallel-slot pages share their parent's urlPath; emitting one entry per\n * slot page produced duplicate interface keys (TS2300/TS2717 under\n * skipLibCheck:false) and duplicate overloads. The non-slot entry is the\n * canonical one; when only slot entries exist (parent has no page), the\n * lexicographically smallest segmentPath wins so output is independent of\n * slot scan order. A slot's searchParams definition is carried onto the\n * merged entry when the canonical entry has none — never silently dropped.\n *\n * segmentPath-keyed emissions (getSegmentParams, useSegmentParams,\n * TimberSegmentParams) must NOT use this — segmentPaths are already unique\n * and slot entries feed those APIs directly.\n */\nfunction dedupeRoutesByUrlPath(routes: RouteEntry[]): RouteEntry[] {\n  const byPath = new Map<string, RouteEntry>();\n  for (const route of routes) {\n    const existing = byPath.get(route.urlPath);\n    if (!existing) {\n      byPath.set(route.urlPath, route);\n      continue;\n    }\n\n    let winner = existing;\n    let loser = route;\n    const routeWins =\n      (existing.isSlotRoute && !route.isSlotRoute) ||\n      (!!existing.isSlotRoute === !!route.isSlotRoute &&\n        route.segmentPath.localeCompare(existing.segmentPath) < 0);\n    if (routeWins) {\n      winner = route;\n      loser = existing;\n    }\n\n    if (!winner.hasSearchParams && loser.hasSearchParams) {\n      winner = {\n        ...winner,\n        hasSearchParams: true,\n        searchParamsPagePath: loser.searchParamsPagePath,\n      };\n    }\n    byPath.set(route.urlPath, winner);\n  }\n  return [...byPath.values()];\n}\n\n/**\n * Determine the TypeScript type for a segment's param.\n */\nfunction paramTypeForSegment(segmentType: string): ParamEntry['type'] {\n  switch (segmentType) {\n    case 'catch-all':\n      return 'string[]';\n    case 'optional-catch-all':\n      return 'string[] | undefined';\n    default:\n      return 'string';\n  }\n}\n\n/**\n * Check if a file exports a specific named export.\n *\n * Uses a lightweight regex check — not full AST parsing. The actual type\n * extraction happens via the TypeScript compiler in the generated .d.ts.\n */\nfunction fileHasExport(filePath: string, exportName: string): boolean {\n  if (!existsSync(filePath)) return false;\n  try {\n    const content = readFileCached(filePath);\n    const e = exportName.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n    return (\n      new RegExp(`export\\\\s+(const|let|var)\\\\s+${e}\\\\b`).test(content) ||\n      new RegExp(`export\\\\s*\\\\{[^}]*\\\\b${e}\\\\b[^}]*\\\\}`).test(content)\n    );\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Find a legacy `segmentParams` export on layout.tsx or page.tsx.\n *\n * Backward-compat shim: TIM-508 made params.ts the canonical location\n * for `segmentParams`. Layout/page exports are still accepted for the\n * OWN segment only (not inherited by descendants — see TIM-834).\n */\nfunction findLegacyParamsExport(node: SegmentNode): string | undefined {\n  if (node.layout && fileHasExport(node.layout.filePath, 'segmentParams')) {\n    return node.layout.filePath;\n  }\n  if (node.page && fileHasExport(node.page.filePath, 'segmentParams')) {\n    return node.page.filePath;\n  }\n  return undefined;\n}\n\n/**\n * Emit the schema-based type exports: TimberSegmentParams, TimberRoute,\n * AllSegmentParams, RoutesWithParams.\n *\n * These types use InferCodecType references so they stay in sync with\n * the schema without hardcoding resolved types.\n *\n * Design doc: design/41-global-params.md §Codegen Output\n */\nfunction formatSchemaTypes(routes: RouteEntry[]): string[] {\n  const lines: string[] = [];\n\n  lines.push('/** Union of all valid route patterns. */');\n  lines.push('export type TimberRoute = keyof TimberSegmentParams;');\n  lines.push('');\n  lines.push('/** Maps each segment path to its accumulated segment params. */');\n  lines.push('export interface TimberSegmentParams {');\n\n  for (const route of routes) {\n    if (route.params.length === 0) {\n      lines.push(`  '${route.segmentPath}': {};`);\n    } else {\n      lines.push(`  '${route.segmentPath}': {`);\n      for (const p of route.params) {\n        lines.push(`    ${p.name}: ${buildSchemaParamType(p)};`);\n      }\n      lines.push('  };');\n    }\n  }\n\n  lines.push('}');\n  lines.push('');\n\n  // AllSegmentParams — flat union of all param types across all routes\n  lines.push('/** All segment params (union of all route params). */');\n  lines.push('export type AllSegmentParams = {');\n  lines.push(\n    '  [K in keyof TimberSegmentParams as TimberSegmentParams[K] extends Record<string, never>'\n  );\n  lines.push('    ? never');\n  lines.push('    : K]: TimberSegmentParams[K];');\n  lines.push('} extends infer U');\n  lines.push('  ? { [K in keyof U[keyof U]]: U[keyof U][K] }');\n  lines.push('  : never;');\n  lines.push('');\n\n  // RoutesWithParams — filter routes by required param keys\n  lines.push(\n    '/** Filters TimberRoute to routes whose accumulated params include all listed keys. */'\n  );\n  lines.push('export type RoutesWithParams<K extends keyof AllSegmentParams> = {');\n  lines.push('  [R in TimberRoute]: K extends keyof TimberSegmentParams[R] ? R : never;');\n  lines.push('}[TimberRoute];');\n\n  return lines;\n}\n\n/**\n * Format the collected routes into a TypeScript declaration file.\n */\nfunction formatDeclarationFile(\n  routes: RouteEntry[],\n  importBase?: string,\n  hasSchema?: boolean,\n  appDir?: string\n): string {\n  const lines: string[] = [];\n\n  lines.push('// This file is auto-generated by timber.js route map codegen.');\n  lines.push('// Do not edit manually. Regenerated on build and in dev mode.');\n  lines.push('');\n  // export {} makes this file a module, so all declare module blocks are\n  // augmentations rather than ambient replacements. Without this, the\n  // declare module blocks would replace the original module types entirely\n  // (removing exports like bindUseQueryStates that aren't listed here).\n  lines.push('export {};');\n  lines.push('');\n\n  if (hasSchema) {\n    // Schema-based codegen: import schema and InferCodecType\n    // Compute the schema import path relative to the output directory\n    const schemaImport =\n      appDir && importBase\n        ? './' + relative(importBase, join(appDir, 'schema')).replace(/\\\\/g, '/')\n        : '../app/schema';\n    lines.push(`import type schema from '${schemaImport}';`);\n    lines.push(\"import type { InferCodecType, SegmentParamCodec } from '@timber-js/app/params';\");\n    lines.push('');\n    // Collect all unique bracket keys from routes for key validation\n    const allBracketKeys = new Set<string>();\n    for (const route of routes) {\n      for (const p of route.params) {\n        allBracketKeys.add(p.bracketName);\n      }\n    }\n\n    // Augment the ValidDynamicSegmentKeysRegistry so defineSchema constrains keys\n    // to known filesystem segments. Unknown keys produce inline TS errors.\n    if (allBracketKeys.size > 0) {\n      lines.push(\"declare module '@timber-js/app/params' {\");\n      lines.push('  interface ValidDynamicSegmentKeysRegistry {');\n      for (const key of [...allBracketKeys].sort()) {\n        lines.push(`    ${JSON.stringify(key)}: true;`);\n      }\n      lines.push('  }');\n      lines.push('}');\n      lines.push('');\n    }\n    // Type-level validation: each schema value must be a Codec or Standard Schema.\n    // Running `pnpm run typecheck` will surface errors for invalid values.\n    lines.push('type _AssertSchemaValues = {');\n    lines.push(\n      \"  [K in keyof typeof schema['segmentParams']]: typeof schema['segmentParams'][K] extends SegmentParamCodec ? true : ['Error: value for', K, 'is not a valid Codec or Standard Schema'];\"\n    );\n    lines.push('};');\n    // Generic constraint enforces that all values are `true` — if any value is\n    // an error tuple, TS reports a real diagnostic instead of silently computing it.\n    lines.push(\n      'type _EnforceSchemaValues<_T extends Record<string, true> = _AssertSchemaValues> = true;'\n    );\n    lines.push('');\n  }\n\n  if (!hasSchema) {\n    // TIM-834 P2: emit the shared codec-resolution helper type ONCE so the\n    // per-param chain conditionals reference it instead of inlining the\n    // fallback in both branches (which grows O(2^N) in chain depth).\n    lines.push(emitResolveSegmentFieldHelper());\n    lines.push('');\n  }\n\n  // urlPath-keyed emissions use the deduped list (slot pages share their\n  // parent's urlPath); segmentPath-keyed emissions below keep all entries.\n  const uniqueByUrlPath = dedupeRoutesByUrlPath(routes);\n\n  lines.push(\"declare module '@timber-js/app' {\");\n  lines.push('  interface Routes {');\n\n  for (const route of uniqueByUrlPath) {\n    const paramsType = formatParamsType(route.params, importBase, hasSchema);\n    const searchParamsType = formatSearchParamsType(route, importBase);\n\n    lines.push(`    '${route.urlPath}': {`);\n    lines.push(`      segmentParams: ${paramsType}`);\n    lines.push(`      searchParams: ${searchParamsType}`);\n    lines.push(`    }`);\n  }\n\n  lines.push('  }');\n\n  // When a global schema exists, emit segment param types inside the\n  // @timber-js/app module augmentation so that declare module blocks\n  // for @timber-js/app/server and @timber-js/app/client can reference\n  // AllSegmentParams via `import type { AllSegmentParams } from '@timber-js/app'`.\n  if (hasSchema) {\n    lines.push('');\n    lines.push(...formatSchemaTypes(routes).map((l) => `  ${l}`));\n  }\n\n  lines.push('}');\n  lines.push('');\n\n  // useQueryStates + typed Link are urlPath-keyed → deduped list.\n  const pageRoutes = uniqueByUrlPath.filter((r) => !r.isApiRoute);\n  // getSegmentParams / useSegmentParams are segmentPath-keyed → full list,\n  // so slot segments keep their own typed overloads.\n  const dynamicRoutes = routes.filter((r) => r.params.length > 0);\n\n  // Generate @timber-js/app/server augmentation — typed getSegmentParams\n  if (dynamicRoutes.length > 0) {\n    lines.push(\"declare module '@timber-js/app/server' {\");\n    if (hasSchema) {\n      lines.push(\"  import type { AllSegmentParams } from '@timber-js/app'\");\n    }\n    for (const route of dynamicRoutes) {\n      const paramsType = formatParamsType(route.params, importBase, hasSchema);\n      lines.push(\n        `  export function getSegmentParams(segmentPath: '${route.segmentPath}'): ${paramsType}`\n      );\n    }\n    lines.push(\n      hasSchema\n        ? '  export function getSegmentParams(): Partial<AllSegmentParams>'\n        : '  export function getSegmentParams(): Record<string, string | string[]>'\n    );\n    lines.push('}');\n    lines.push('');\n  }\n\n  // Generate overloads for @timber-js/app/client\n\n  if (dynamicRoutes.length > 0 || pageRoutes.length > 0) {\n    lines.push(\"declare module '@timber-js/app/client' {\");\n    lines.push(\n      \"  import type { SearchParamsDefinition, SetParams, QueryStatesOptions, SearchParamCodec } from '@timber-js/app/search-params'\"\n    );\n    if (hasSchema) {\n      lines.push(\"  import type { AllSegmentParams } from '@timber-js/app'\");\n    }\n    lines.push('');\n\n    // useSegmentParams overloads\n    if (dynamicRoutes.length > 0) {\n      for (const route of dynamicRoutes) {\n        const paramsType = formatParamsType(route.params, importBase, hasSchema);\n        lines.push(\n          `  export function useSegmentParams(segmentPath: '${route.segmentPath}'): ${paramsType}`\n        );\n      }\n      lines.push(\n        hasSchema\n          ? '  export function useSegmentParams(): Partial<AllSegmentParams>'\n          : '  export function useSegmentParams(): Record<string, string | string[]>'\n      );\n      lines.push('');\n    }\n\n    // useQueryStates overloads\n    if (pageRoutes.length > 0) {\n      lines.push(...formatUseQueryStatesOverloads(pageRoutes, importBase));\n      lines.push('');\n    }\n\n    // Typed Link overloads — per-route with DIRECT types (no conditionals).\n    // Direct types preserve TypeScript's excess property checking.\n    //\n    // TIM-832: per-route and catch-all are emitted as TWO separate\n    // augmentation blocks. Per TS's merging rule \"later overload sets\n    // ordered first\", the catch-all block (declared SECOND in this file)\n    // ends up FIRST in the merged call-signature list at resolution time,\n    // which puts the per-route block LAST — so its error message is the\n    // one TypeScript reports when no overload matches. This gives users a\n    // clear prop-mismatch error (e.g. \"'string | undefined' is not\n    // assignable to 'string | number' on id\") instead of the old\n    // confusing \"Type 'string' is not assignable to type 'never'\" cascade.\n    if (pageRoutes.length > 0) {\n      lines.push('  // Typed Link overloads — per-route (block 1 / emitted first)');\n      lines.push(...formatTypedLinkOverloads(pageRoutes, importBase, hasSchema));\n      lines.push('');\n    }\n\n    lines.push('}');\n    lines.push('');\n  }\n\n  // TIM-832: catch-all block — emitted as a SEPARATE `declare module`\n  // augmentation so TS's \"later overload set first\" rule orders it ahead\n  // of the per-route block above at resolution time, leaving per-route as\n  // the \"last overload\" whose error TypeScript reports.\n  lines.push(\"declare module '@timber-js/app/client' {\");\n  lines.push(\"  import type { SearchParamsDefinition } from '@timber-js/app/search-params'\");\n  lines.push('');\n  lines.push(...formatLinkCatchAllOverloads());\n  lines.push('}');\n  lines.push('');\n\n  return lines.join('\\n');\n}\n\n/**\n * Format the params type for a route entry.\n */\nfunction formatParamsType(params: ParamEntry[], importBase?: string, hasSchema?: boolean): string {\n  if (params.length === 0) {\n    return '{}';\n  }\n\n  const fields = params.map((p) => {\n    const codecType = hasSchema\n      ? buildSchemaParamType(p)\n      : buildCodecChainType(p, importBase, p.type);\n    return `${p.name}: ${codecType}`;\n  });\n  return `{ ${fields.join('; ')} }`;\n}\n\n/**\n * Generate useQueryStates overloads.\n *\n * For each page route:\n * - Routes with search-params.ts get a typed overload returning the inferred T\n * - Routes without search-params.ts get an overload returning [{}, SetParams<{}>]\n *\n * A fallback overload for standalone codecs (existing API) is emitted last.\n */\nfunction formatUseQueryStatesOverloads(routes: RouteEntry[], importBase?: string): string[] {\n  const lines: string[] = [];\n\n  for (const route of routes) {\n    const searchParamsType = route.hasSearchParams\n      ? formatSearchParamsType(route, importBase)\n      : '{}';\n    lines.push(\n      `  export function useQueryStates<R extends '${route.urlPath}'>(route: R, options?: QueryStatesOptions): [${searchParamsType}, SetParams<${searchParamsType}>]`\n    );\n  }\n\n  // Fallback: standalone codecs (existing API)\n  lines.push(\n    '  export function useQueryStates<T extends Record<string, unknown>>(codecs: { [K in keyof T]: SearchParamCodec<T[K]> }, options?: QueryStatesOptions): [T, SetParams<T>]'\n  );\n\n  return lines;\n}\n\n// Link overload formatters and helpers (`formatTypedLinkOverloads`,\n// `formatLinkCatchAllOverloads`, `formatLinkParamsType`,\n// `buildResolvedPattern`, `LINK_BASE_PROPS_TYPE`) were extracted to\n// `./link-codegen.ts` (TIM-835) to keep this file under the 500-line\n// cap. They are imported at the top of this file.\n","/**\n * Schema key/value validation against the filesystem route tree.\n *\n * Runs at codegen time (build + dev) to catch mismatches between\n * app/schema.ts keys and the actual dynamic segments on disk.\n *\n * Design doc: design/41-global-params.md\n */\n\nimport { readFileCached } from './file-cache.js';\nimport type { RouteTree, SegmentNode } from './types.js';\nimport { findSchemaFile, parseExistingSchemaKeys } from '../cli-schema-sync.js';\nimport { classifyUrlSegment } from './segment-classify.js';\n\nexport interface SchemaWarning {\n  type: 'stale-key' | 'missing-key' | 'bracket-mismatch';\n  key: string;\n  message: string;\n  filesystemKey?: string;\n}\n\n/**\n * Collect all unique bracket-keyed dynamic segment names from a route tree.\n * Returns entries like '[artistSlug]', '[...slug]', '[[...topic]]'.\n */\nexport function collectDynamicSegmentsFromTree(tree: RouteTree): Set<string> {\n  const segments = new Set<string>();\n  walkTree(tree.root, segments);\n  return segments;\n}\n\nfunction walkTree(node: SegmentNode, segments: Set<string>): void {\n  if (node.paramName && node.segmentName) {\n    const classified = classifyUrlSegment(node.segmentName);\n    if (classified.kind !== 'static') {\n      segments.add(node.segmentName);\n    }\n  }\n  for (const child of node.children) {\n    walkTree(child, segments);\n  }\n  for (const slot of Object.values(node.slots)) {\n    walkTree(slot, segments);\n  }\n}\n\n/**\n * Extract the param name from a bracket key.\n * '[id]' → 'id', '[...slug]' → 'slug', '[[...topic]]' → 'topic'\n */\nfunction extractParamName(bracketKey: string): string | null {\n  const seg = classifyUrlSegment(bracketKey);\n  if (seg.kind === 'static') return null;\n  return seg.name;\n}\n\n/**\n * Validate schema keys against the filesystem route tree.\n *\n * Returns warnings for:\n * - Stale keys: schema keys that don't match any filesystem segment\n * - Bracket form mismatches: same param name, different bracket form\n * - Missing keys: filesystem segments not registered in schema (informational)\n */\nexport function validateSchemaAgainstRoutes(tree: RouteTree, appDir: string): SchemaWarning[] {\n  const schemaPath = findSchemaFile(appDir);\n  if (!schemaPath) return [];\n\n  const content = readFileCached(schemaPath);\n  const schemaKeys = parseExistingSchemaKeys(content);\n\n  if (schemaKeys.length === 0) return [];\n\n  const filesystemSegments = collectDynamicSegmentsFromTree(tree);\n\n  return validateKeys(schemaKeys, filesystemSegments);\n}\n\n/**\n * Core validation: compare schema keys against filesystem segments.\n * Exported separately for testing without filesystem dependencies.\n */\nexport function validateKeys(\n  schemaKeys: string[],\n  filesystemSegments: Set<string>\n): SchemaWarning[] {\n  const warnings: SchemaWarning[] = [];\n\n  // Build a map of param name → bracket form for filesystem segments\n  const fsParamToKey = new Map<string, string>();\n  for (const fsKey of filesystemSegments) {\n    const name = extractParamName(fsKey);\n    if (name) {\n      fsParamToKey.set(name, fsKey);\n    }\n  }\n\n  // Build a set of schema param names for the missing-key check\n  const schemaParamNames = new Set<string>();\n\n  for (const schemaKey of schemaKeys) {\n    const schemaParamName = extractParamName(schemaKey);\n    if (!schemaParamName) continue;\n\n    schemaParamNames.add(schemaParamName);\n\n    if (filesystemSegments.has(schemaKey)) {\n      // Exact match — no issue\n      continue;\n    }\n\n    // Check if the param name exists but with a different bracket form\n    const fsKey = fsParamToKey.get(schemaParamName);\n    if (fsKey) {\n      warnings.push({\n        type: 'bracket-mismatch',\n        key: schemaKey,\n        filesystemKey: fsKey,\n        message:\n          `Schema key '${schemaKey}' does not match filesystem bracket form '${fsKey}'. ` +\n          `Update the schema key to '${fsKey}'.`,\n      });\n    } else {\n      warnings.push({\n        type: 'stale-key',\n        key: schemaKey,\n        message:\n          `Schema key '${schemaKey}' does not match any dynamic segment in the filesystem. ` +\n          `Remove it from app/schema.ts or create the corresponding route segment.`,\n      });\n    }\n  }\n\n  // Check for filesystem segments not in schema (informational)\n  for (const fsKey of filesystemSegments) {\n    const name = extractParamName(fsKey);\n    if (name && !schemaParamNames.has(name)) {\n      warnings.push({\n        type: 'missing-key',\n        key: fsKey,\n        message:\n          `Dynamic segment '${fsKey}' has no codec in app/schema.ts (defaults to string). ` +\n          `Run: timber schema sync`,\n      });\n    }\n  }\n\n  return warnings;\n}\n","/**\n * Intercepting route utilities.\n *\n * Computes rewrite rules from the route tree that enable intercepting routes\n * to conditionally render when navigating via client-side (soft) navigation.\n *\n * The mechanism: at build time, each intercepting route directory generates a\n * conditional rewrite. On soft navigation, the client sends an `X-Timber-URL`\n * header with the current pathname. The server checks if any rewrite's source\n * (the intercepted URL) matches the target pathname AND the header matches\n * the intercepting route's parent URL. If both match, the intercepting route\n * renders instead of the normal route.\n *\n * On hard navigation (no header), no rewrite matches, and the normal route\n * renders.\n *\n * See design/07-routing.md §\"Intercepting Routes\"\n */\n\nimport type { SegmentNode, InterceptionMarker } from './types.js';\n\n/** A conditional rewrite rule generated from an intercepting route. */\nexport interface InterceptionRewrite {\n  /**\n   * The URL pattern that this rewrite intercepts (the target of navigation).\n   * E.g., \"/photo/[id]\" for a (.)photo/[id] interception.\n   */\n  interceptedPattern: string;\n  /**\n   * The URL prefix that the client must be navigating FROM for this rewrite\n   * to apply. Matched against the X-Timber-URL header.\n   * E.g., \"/feed\" for a (.)photo/[id] inside /feed/@modal/.\n   */\n  interceptingPrefix: string;\n}\n\n/**\n * Collect all interception rewrite rules from the route tree.\n *\n * Walks the tree recursively. For each intercepting segment, computes the\n * intercepted URL based on the marker and the segment's position.\n */\nexport function collectInterceptionRewrites(root: SegmentNode): InterceptionRewrite[] {\n  const rewrites: InterceptionRewrite[] = [];\n  walkForInterceptions(root, [root], rewrites);\n  return rewrites;\n}\n\n/**\n * Recursively walk the segment tree to find intercepting routes.\n */\nfunction walkForInterceptions(\n  node: SegmentNode,\n  ancestors: SegmentNode[],\n  rewrites: InterceptionRewrite[]\n): void {\n  // Check children\n  for (const child of node.children) {\n    if (child.segmentType === 'intercepting' && child.interceptionMarker) {\n      // Found an intercepting route — collect rewrites from its sub-tree\n      collectFromInterceptingNode(child, ancestors, rewrites);\n    } else {\n      walkForInterceptions(child, [...ancestors, child], rewrites);\n    }\n  }\n\n  // Check slots (intercepting routes are typically inside slots like @modal)\n  for (const slot of Object.values(node.slots)) {\n    walkForInterceptions(slot, ancestors, rewrites);\n  }\n}\n\n/**\n * For an intercepting segment, find all leaf pages in its sub-tree and\n * generate rewrite rules for each.\n */\nfunction collectFromInterceptingNode(\n  interceptingNode: SegmentNode,\n  ancestors: SegmentNode[],\n  rewrites: InterceptionRewrite[]\n): void {\n  const marker = interceptingNode.interceptionMarker!;\n  const segmentName = interceptingNode.interceptedSegmentName!;\n\n  // Compute the intercepted URL base based on the marker\n  const parentUrlPath = ancestors[ancestors.length - 1].urlPath;\n  const interceptedBase = computeInterceptedBase(parentUrlPath, marker);\n  const interceptedUrlBase =\n    interceptedBase === '/' ? `/${segmentName}` : `${interceptedBase}/${segmentName}`;\n\n  // Find all leaf pages in the intercepting sub-tree\n  collectLeavesWithRewrites(interceptingNode, interceptedUrlBase, parentUrlPath, rewrites);\n}\n\n/**\n * Recursively find leaf pages in an intercepting sub-tree and generate\n * rewrite rules for each.\n */\nfunction collectLeavesWithRewrites(\n  node: SegmentNode,\n  interceptedUrlPath: string,\n  interceptingPrefix: string,\n  rewrites: InterceptionRewrite[]\n): void {\n  if (node.page) {\n    rewrites.push({\n      interceptedPattern: interceptedUrlPath,\n      interceptingPrefix,\n    });\n  }\n\n  for (const child of node.children) {\n    const childUrl =\n      child.segmentType === 'group'\n        ? interceptedUrlPath\n        : `${interceptedUrlPath}/${child.segmentName}`;\n    collectLeavesWithRewrites(child, childUrl, interceptingPrefix, rewrites);\n  }\n}\n\n/**\n * Compute the base URL that an intercepting route intercepts, given the\n * parent's URL path and the interception marker.\n *\n * - (.)  — same level: parent's URL path\n * - (..) — one level up: parent's parent URL path\n * - (...) — root level: /\n * - (..)(..) — two levels up: parent's grandparent URL path\n *\n * Level counting operates on URL path segments, NOT filesystem directories.\n * Route groups and parallel slots are already excluded from urlPath (they\n * don't add URL depth), so (..) correctly climbs visible segments. This\n * avoids the Vinext bug where path.dirname() on filesystem paths would\n * waste climbs on invisible route groups.\n */\nfunction computeInterceptedBase(parentUrlPath: string, marker: InterceptionMarker): string {\n  switch (marker) {\n    case '(.)':\n      return parentUrlPath;\n    case '(..)': {\n      const parts = parentUrlPath.split('/').filter(Boolean);\n      parts.pop();\n      return parts.length === 0 ? '/' : `/${parts.join('/')}`;\n    }\n    case '(...)':\n      return '/';\n    case '(..)(..)': {\n      const parts = parentUrlPath.split('/').filter(Boolean);\n      parts.pop();\n      parts.pop();\n      return parts.length === 0 ? '/' : `/${parts.join('/')}`;\n    }\n  }\n}\n","/**\n * Shared route-tree walkers (TIM-848).\n *\n * Tiny helpers that walk a `SegmentNode<TFile>` tree generically. Both the\n * build-time tree (`SegmentNode<RouteFile>`) and the runtime manifest\n * tree (`SegmentNode<ManifestFile>`) flow through these helpers because\n * the walker only reads the structural fields shared by both shapes\n * (`children`, `slots`, `page`, `route`, `urlPath`).\n *\n * Before this module, three near-identical `collectRoutes` functions\n * lived in `plugins/dev-404-page.ts`, `plugins/build-report.ts`, and\n * `routing/codegen.ts`. The codegen one is special-purpose (it\n * accumulates `ParamEntry[]` and resolves codec chains) and stays\n * local; the other two now share `collectLeafRoutes` from this file.\n */\n\nimport type { SegmentNode } from './types.js';\n\n/** A leaf route discovered while walking the segment tree. */\nexport interface LeafRoute<TFile> {\n  /** URL path of the leaf (root is \"/\"). */\n  urlPath: string;\n  /** Segment chain from root to this leaf, inclusive. */\n  segments: SegmentNode<TFile>[];\n  /** The page file at this leaf, if any. */\n  page?: TFile;\n  /** The route handler file at this leaf, if any. */\n  route?: TFile;\n}\n\n/** Options for `collectLeafRoutes`. */\nexport interface CollectLeafRoutesOptions {\n  /**\n   * If true, recurse into parallel slots and emit slot leaves alongside\n   * the main route tree. Defaults to `false` because slots render\n   * alongside their parent at the same URL and are not separately\n   * URL-addressable. The build report excludes slots; route-listing\n   * UIs that want to show \"all leaves with a page handler\" can opt in.\n   */\n  includeSlots?: boolean;\n}\n\n/**\n * Walk a segment tree and collect every leaf with a `page` or `route`\n * handler. Generic over `TFile` so it works on both the build-time\n * scanner output and the runtime manifest tree.\n *\n * - Pages and route handlers at the same URL produce two distinct\n *   entries (the build report deduplicates by URL afterward).\n * - Parallel slots are skipped unless `includeSlots: true` (slots\n *   share their parent's URL and are not addressable on their own).\n * - Result is sorted by `urlPath` for deterministic output.\n */\nexport function collectLeafRoutes<TFile>(\n  root: SegmentNode<TFile>,\n  options: CollectLeafRoutesOptions = {}\n): LeafRoute<TFile>[] {\n  const { includeSlots = false } = options;\n  const result: LeafRoute<TFile>[] = [];\n  walk(root, [], result, includeSlots);\n  result.sort((a, b) => a.urlPath.localeCompare(b.urlPath));\n  return result;\n}\n\nfunction walk<TFile>(\n  node: SegmentNode<TFile>,\n  chain: SegmentNode<TFile>[],\n  result: LeafRoute<TFile>[],\n  includeSlots: boolean\n): void {\n  const currentChain = [...chain, node];\n  const path = node.urlPath || '/';\n\n  if (node.page) {\n    result.push({ urlPath: path, segments: currentChain, page: node.page });\n  }\n  if (node.route) {\n    result.push({ urlPath: path, segments: currentChain, route: node.route });\n  }\n\n  for (const child of node.children) {\n    walk(child, currentChain, result, includeSlots);\n  }\n\n  if (includeSlots) {\n    for (const slotNode of Object.values(node.slots)) {\n      walk(slotNode, currentChain, result, includeSlots);\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/cache/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/cache/sizeof.ts","../../src/cache/redis-handler.ts","../../src/cache/index.ts"],"sourcesContent":["/**\n * Lightweight byte-size estimation for cache entries.\n *\n * Estimates the in-memory byte cost of a JavaScript value using\n * JSON.stringify().length * 2 (UTF-16 char width). This is a rough\n * approximation — it doesn't account for V8 object overhead, Map\n * metadata, or non-serializable values — but it's fast and good\n * enough for cache budget enforcement.\n *\n * Values that fail JSON serialization (circular references, BigInt,\n * etc.) return 0, allowing the entry to be cached without counting\n * toward the byte budget. This is a conservative choice: it's better\n * to cache and undercount than to reject the entry.\n */\n\n/**\n * Estimate the byte size of a value.\n *\n * Uses `JSON.stringify(value).length * 2` to approximate UTF-16\n * in-memory size. Returns 0 if the value is not serializable.\n */\nexport function estimateByteSize(value: unknown): number {\n  try {\n    const json = JSON.stringify(value);\n    if (json === undefined) return 0;\n    // Each JS string character is 2 bytes (UTF-16)\n    return json.length * 2;\n  } catch (e) {\n    // Circular reference or non-serializable value\n    console.debug('[timber] sizeof estimation failed:', e instanceof Error ? e.message : e);\n    return 0;\n  }\n}\n","import type { CacheHandler } from './index';\n\n/**\n * Minimal Redis client contract for `RedisCacheHandler`.\n *\n * This is deliberately NOT the native shape of any client library. ioredis,\n * node-redis v4, and @upstash/redis all disagree on TTL argument shapes\n * (positional `'EX'` vs `{ EX }` vs `{ ex }`), method casing (`sadd` vs\n * `sAdd`), and array handling in `del` — a contract that pattern-matches one\n * client lets another silently drop the expiry (TIM-1030: node-redis ignored\n * the positional `'EX'` and wrote keys with no TTL). Instead, TTL semantics\n * are explicit in the signature and you adapt your client with a thin\n * wrapper, so a mismatch is a type error rather than silent unbounded\n * keyspace growth.\n *\n * @example ioredis\n * ```ts\n * import Redis from 'ioredis';\n * const redis = new Redis(process.env.REDIS_URL);\n * const client: RedisClient = {\n *   get: (k) => redis.get(k),\n *   set: (k, v, ttl) => redis.set(k, v, 'EX', ttl),\n *   expire: (k, s) => redis.expire(k, s),\n *   del: (k) => redis.del(k),\n *   sadd: (k, ...m) => redis.sadd(k, ...m),\n *   srem: (k, ...m) => redis.srem(k, ...m),\n *   smembers: (k) => redis.smembers(k),\n *   ttl: (k) => redis.ttl(k),\n * };\n * ```\n *\n * @example node-redis v4\n * ```ts\n * import { createClient } from 'redis';\n * const redis = createClient({ url: process.env.REDIS_URL });\n * await redis.connect();\n * const client: RedisClient = {\n *   get: (k) => redis.get(k),\n *   set: (k, v, ttl) => redis.set(k, v, { EX: ttl }),\n *   expire: (k, s) => redis.expire(k, s),\n *   del: (k) => redis.del(k),\n *   sadd: (k, ...m) => redis.sAdd(k, m),\n *   srem: (k, ...m) => redis.sRem(k, m),\n *   smembers: (k) => redis.sMembers(k),\n *   ttl: (k) => redis.ttl(k),\n * };\n * ```\n *\n * @example @upstash/redis\n * ```ts\n * import { Redis } from '@upstash/redis';\n * // automaticDeserialization must be off: the handler stores JSON strings\n * // and parses them itself — auto-parsing would hand back objects.\n * const redis = new Redis({ url, token, automaticDeserialization: false });\n * const client: RedisClient = {\n *   get: (k) => redis.get(k),\n *   set: (k, v, ttl) => redis.set(k, v, { ex: ttl }),\n *   expire: (k, s) => redis.expire(k, s),\n *   del: (k) => redis.del(k),\n *   sadd: (k, ...m) => redis.sadd(k, m[0], ...m.slice(1)),\n *   srem: (k, ...m) => redis.srem(k, m[0], ...m.slice(1)),\n *   smembers: (k) => redis.smembers(k),\n *   ttl: (k) => redis.ttl(k),\n * };\n * ```\n */\nexport interface RedisClient {\n  /** `GET key` — the stored string, or null when absent. */\n  get(key: string): Promise<string | null>;\n  /**\n   * `SET key value EX ttlSeconds` — store with an expiry. The TTL is a\n   * required positional argument so no adapter can forget it.\n   */\n  set(key: string, value: string, ttlSeconds: number): Promise<unknown>;\n  /** `EXPIRE key seconds` — set/refresh a key's TTL (used for tag sets). */\n  expire(key: string, seconds: number): Promise<unknown>;\n  /** `DEL key` — delete a single key. Multi-key deletes loop per key. */\n  del(key: string): Promise<unknown>;\n  /** `SADD key member [member ...]` — add members to a set. */\n  sadd(key: string, ...members: string[]): Promise<unknown>;\n  /** `SREM key member [member ...]` — remove members from a set. */\n  srem(key: string, ...members: string[]): Promise<unknown>;\n  /** `SMEMBERS key` — all members of a set. */\n  smembers(key: string): Promise<string[]>;\n  /**\n   * `TTL key` — remaining time-to-live in seconds. Returns -2 if the key does\n   * not exist, -1 if the key exists but has no expiry.\n   */\n  ttl(key: string): Promise<number>;\n}\n\nconst KEY_PREFIX = 'timber:cache:';\nconst TAG_PREFIX = 'timber:tag:';\n\n/**\n * Redis-backed CacheHandler for distributed caching.\n *\n * All instances sharing the same Redis see each other's cache entries and\n * invalidations. Tag-based invalidation uses Redis Sets to track which keys\n * belong to which tags.\n *\n * Bring your own Redis client wrapped to the {@link RedisClient} contract —\n * see the adapter examples on the interface for ioredis, node-redis v4, and\n * @upstash/redis.\n */\nexport class RedisCacheHandler implements CacheHandler {\n  private client: RedisClient;\n  private prefix: string;\n\n  constructor(client: RedisClient, opts?: { prefix?: string }) {\n    this.client = client;\n    this.prefix = opts?.prefix ?? '';\n  }\n\n  private cacheKey(key: string): string {\n    return `${this.prefix}${KEY_PREFIX}${key}`;\n  }\n\n  private tagKey(tag: string): string {\n    return `${this.prefix}${TAG_PREFIX}${tag}`;\n  }\n\n  async get(key: string): Promise<{ value: unknown; stale: boolean } | null> {\n    const raw = await this.client.get(this.cacheKey(key));\n    if (raw === null) return null;\n\n    const entry = JSON.parse(raw) as { value: unknown; expiresAt: number };\n    const stale = Date.now() > entry.expiresAt;\n    return { value: entry.value, stale };\n  }\n\n  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void> {\n    const ck = this.cacheKey(key);\n    const expiresAt = Date.now() + opts.ttl * 1000;\n    const payload = JSON.stringify({ value, expiresAt, tags: opts.tags });\n\n    // Redis TTL with generous margin beyond the logical TTL to allow SWR reads\n    // on stale entries. The logical staleness is determined by expiresAt.\n    // We use 2x TTL + 60s as the Redis expiry so stale entries remain\n    // available for SWR background refetches.\n    const redisTtlSeconds = Math.max(opts.ttl * 2 + 60, 120);\n    await this.client.set(ck, payload, redisTtlSeconds);\n\n    // Track key membership in each tag set, and expire the set so it doesn't\n    // outlive all its members. Only extend the TTL, never shorten — a short-TTL\n    // entry must not shrink a tag set that already contains long-TTL entries,\n    // otherwise invalidate({tag}) would miss the long-lived entries.\n    for (const tag of opts.tags) {\n      await this.client.sadd(this.tagKey(tag), key);\n      const currentTtl = await this.client.ttl(this.tagKey(tag));\n      // Only extend, never shorten. -2 = key doesn't exist (rare race after\n      // sadd), -1 = no expiry (new set or legacy — set initial TTL), positive\n      // but shorter = extend. A longer current TTL means a longer-lived entry\n      // set it first — don't shorten.\n      if (currentTtl < redisTtlSeconds) {\n        await this.client.expire(this.tagKey(tag), redisTtlSeconds);\n      }\n    }\n  }\n\n  async invalidate(opts: { key?: string; tag?: string }): Promise<void> {\n    if (opts.key) {\n      const raw = await this.client.get(this.cacheKey(opts.key));\n      if (raw !== null) {\n        const entry = JSON.parse(raw) as { tags?: string[] };\n        if (entry.tags) {\n          await Promise.all(entry.tags.map((tag) => this.client.srem(this.tagKey(tag), opts.key!)));\n        }\n      }\n      await this.client.del(this.cacheKey(opts.key));\n    }\n\n    if (opts.tag) {\n      const tk = this.tagKey(opts.tag);\n      const keys = await this.client.smembers(tk);\n\n      // One del per key: the only multi-key shape every client accepts.\n      // ioredis takes del(...keys), node-redis takes del(key | key[]), and\n      // @upstash/redis takes del(...keys) but breaks on an array argument.\n      await Promise.all(keys.map((k) => this.client.del(this.cacheKey(k))));\n\n      // Clean up the tag set itself\n      await this.client.del(tk);\n    }\n  }\n}\n","// @timber-js/app/cache — Caching primitives\n\nimport { estimateByteSize } from './sizeof.js';\n\nexport interface CacheHandler {\n  get(key: string): Promise<{ value: unknown; stale: boolean } | null>;\n  set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void>;\n  invalidate(opts: { key?: string; tag?: string }): Promise<void>;\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface CacheOptions<Fn extends (...args: any[]) => any> {\n  ttl: number;\n  key?: (...args: Parameters<Fn>) => string;\n  staleWhileRevalidate?: boolean;\n  tags?: string[] | ((...args: Parameters<Fn>) => string[]);\n  /** Timeout (ms) for singleflight-coalesced calls. Prevents hung fn() from\n   *  permanently blocking all future callers for the same cache key. See TIM-518. */\n  timeoutMs?: number;\n}\n\nexport interface MemoryCacheHandlerOptions {\n  /** Maximum number of entries. Oldest accessed entries are evicted first. Default: 1000. */\n  maxEntries?: number;\n  /**\n   * @deprecated Use `maxEntries` instead. Will be removed in a future release.\n   * Alias for `maxEntries` — maximum number of entries (not bytes).\n   */\n  maxSize?: number;\n  /** Maximum total byte budget for all cached values. Oldest entries are evicted when exceeded. Default: no limit. */\n  maxBytes?: number;\n  /** Maximum byte size for a single cache entry. Entries exceeding this are silently dropped. Default: no limit. */\n  maxEntryBytes?: number;\n}\n\nexport class MemoryCacheHandler implements CacheHandler {\n  private store = new Map<\n    string,\n    { value: unknown; expiresAt: number; tags: string[]; byteSize: number }\n  >();\n  private maxEntries: number;\n  private maxBytes: number | undefined;\n  private maxEntryBytes: number | undefined;\n  private currentBytes = 0;\n  private readonly _trackBytes: boolean;\n\n  constructor(opts?: MemoryCacheHandlerOptions) {\n    // maxEntries takes precedence over deprecated maxSize\n    this.maxEntries = opts?.maxEntries ?? opts?.maxSize ?? 1000;\n    this.maxBytes = opts?.maxBytes;\n    this.maxEntryBytes = opts?.maxEntryBytes;\n    this._trackBytes = this.maxBytes !== undefined || this.maxEntryBytes !== undefined;\n  }\n\n  async get(key: string) {\n    const entry = this.store.get(key);\n    if (!entry) return null;\n\n    // Move to end of Map (most recently used) for LRU ordering\n    this.store.delete(key);\n    this.store.set(key, entry);\n\n    const stale = Date.now() > entry.expiresAt;\n    return { value: entry.value, stale };\n  }\n\n  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }) {\n    const byteSize = this._trackBytes ? estimateByteSize(value) : 0;\n\n    // Reject entries exceeding per-entry byte limit\n    if (this.maxEntryBytes !== undefined && byteSize > this.maxEntryBytes) {\n      return;\n    }\n\n    // If key already exists, delete first to refresh insertion order and reclaim bytes\n    if (this.store.has(key)) {\n      const existing = this.store.get(key)!;\n      this.currentBytes -= existing.byteSize;\n      this.store.delete(key);\n    }\n\n    // Evict oldest entries (front of Map) if at entry count capacity\n    while (this.store.size >= this.maxEntries) {\n      this.evictOldest();\n    }\n\n    // Evict oldest entries if byte budget would be exceeded\n    if (this.maxBytes !== undefined) {\n      while (this.currentBytes + byteSize > this.maxBytes && this.store.size > 0) {\n        this.evictOldest();\n      }\n      // If the single entry exceeds the total byte budget, don't store it\n      if (this.currentBytes + byteSize > this.maxBytes) {\n        return;\n      }\n    }\n\n    this.store.set(key, {\n      value,\n      expiresAt: Date.now() + opts.ttl * 1000,\n      tags: opts.tags,\n      byteSize,\n    });\n    this.currentBytes += byteSize;\n  }\n\n  async invalidate(opts: { key?: string; tag?: string }) {\n    if (opts.key) {\n      const entry = this.store.get(opts.key);\n      if (entry) {\n        this.currentBytes -= entry.byteSize;\n        this.store.delete(opts.key);\n      }\n    }\n    if (opts.tag) {\n      for (const [key, entry] of this.store) {\n        if (entry.tags.includes(opts.tag)) {\n          this.currentBytes -= entry.byteSize;\n          this.store.delete(key);\n        }\n      }\n    }\n  }\n\n  /** Number of entries currently in the cache. */\n  get size(): number {\n    return this.store.size;\n  }\n\n  /** Estimated total byte size of all cached values. Only tracked when maxBytes or maxEntryBytes is configured; returns 0 otherwise. */\n  get bytes(): number {\n    return this.currentBytes;\n  }\n\n  /** Evict the oldest entry (front of Map). */\n  private evictOldest(): void {\n    const oldest = this.store.keys().next().value;\n    if (oldest !== undefined) {\n      const entry = this.store.get(oldest)!;\n      this.currentBytes -= entry.byteSize;\n      this.store.delete(oldest);\n    }\n  }\n}\n\nexport { RedisCacheHandler } from './redis-handler';\nexport type { RedisClient } from './redis-handler';\nexport { cache } from './cache-api';\nexport { setCacheHandler, getCacheHandler } from './handler-store';\nexport { setDefaultSingleflightTimeout } from './timber-cache';\n// NOTE: registerCachedFunction (runtime for 'use cache' directive) removed.\n// Future feature pending design doc. See design/06-caching.md.\nexport { estimateByteSize } from './sizeof';\n// stableStringify, createSingleflight, and SingleflightTimeoutError are\n// internal utilities used by the cache implementation. They are not\n// re-exported here — import directly from the source files if needed\n// within the package. See TIM-720.\n"],"mappings":"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"}

package/dist/client/head.d.ts

@@ -1,16 +0,0 @@
-/** A rendered head element descriptor (matches server-side HeadElement from metadata.ts). */
-export interface HeadElement {
-    tag: 'title' | 'meta' | 'link';
-    content?: string;
-    attrs?: Record<string, string>;
-}
-/**
- * Apply resolved head elements to the DOM.
- *
- * - Sets document.title for <title> elements
- * - Creates <meta> and <link> tags with a data-timber-head marker
- * - Removes previous timber-managed tags to prevent accumulation
- * - Replaces existing SSR-rendered tags with the same name/property
- */
-export declare function applyHeadElements(elements: HeadElement[]): void;
-//# sourceMappingURL=head.d.ts.map

package/dist/client/head.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"head.d.ts","sourceRoot":"","sources":["../../src/client/head.ts"],"names":[],"mappings":"AAaA,6FAA6F;AAC7F,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAID;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI,CA8B/D"}

package/dist/client/navigation-api-types.d.ts

@@ -1,90 +0,0 @@
-/**
- * Ambient type declarations for the Navigation API.
- *
- * The Navigation API is not yet in TypeScript's standard lib. These types
- * are used internally via type assertions — we never import Navigation API
- * types unconditionally. Progressive enhancement only: the API is feature-
- * detected at runtime.
- *
- * See https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API
- */
-export interface NavigationHistoryEntry {
-    readonly key: string;
-    readonly id: string;
-    readonly url: string | null;
-    readonly index: number;
-    readonly sameDocument: boolean;
-    getState(): unknown;
-    addEventListener(type: string, listener: EventListener): void;
-    removeEventListener(type: string, listener: EventListener): void;
-}
-export interface NavigationDestination {
-    readonly url: string;
-    readonly key: string | null;
-    readonly id: string | null;
-    readonly index: number;
-    readonly sameDocument: boolean;
-    getState(): unknown;
-}
-export interface NavigateEvent extends Event {
-    readonly navigationType: 'push' | 'replace' | 'reload' | 'traverse';
-    readonly destination: NavigationDestination;
-    readonly canIntercept: boolean;
-    readonly userInitiated: boolean;
-    readonly hashChange: boolean;
-    readonly signal: AbortSignal;
-    readonly formData: FormData | null;
-    readonly downloadRequest: string | null;
-    readonly info: unknown;
-    intercept(options?: NavigateInterceptOptions): void;
-    scroll(): void;
-}
-export interface NavigateInterceptOptions {
-    handler?: () => Promise<void>;
-    focusReset?: 'after-transition' | 'manual';
-    scroll?: 'after-transition' | 'manual';
-}
-export interface NavigationTransition {
-    readonly navigationType: 'push' | 'replace' | 'reload' | 'traverse';
-    readonly from: NavigationHistoryEntry;
-    readonly finished: Promise<void>;
-}
-export interface NavigationResult {
-    committed: Promise<NavigationHistoryEntry>;
-    finished: Promise<NavigationHistoryEntry>;
-}
-export interface NavigationApi {
-    readonly currentEntry: NavigationHistoryEntry | null;
-    readonly transition: NavigationTransition | null;
-    readonly canGoBack: boolean;
-    readonly canGoForward: boolean;
-    entries(): NavigationHistoryEntry[];
-    navigate(url: string, options?: NavigationNavigateOptions): NavigationResult;
-    reload(options?: NavigationReloadOptions): NavigationResult;
-    traverseTo(key: string, options?: NavigationOptions): NavigationResult;
-    back(options?: NavigationOptions): NavigationResult;
-    forward(options?: NavigationOptions): NavigationResult;
-    updateCurrentEntry(options: NavigationUpdateCurrentEntryOptions): void;
-    addEventListener(type: 'navigate', listener: (event: NavigateEvent) => void): void;
-    addEventListener(type: 'navigatesuccess', listener: (event: Event) => void): void;
-    addEventListener(type: 'navigateerror', listener: (event: Event) => void): void;
-    addEventListener(type: 'currententrychange', listener: (event: Event) => void): void;
-    addEventListener(type: string, listener: EventListener): void;
-    removeEventListener(type: string, listener: EventListener): void;
-}
-export interface NavigationNavigateOptions {
-    state?: unknown;
-    history?: 'auto' | 'push' | 'replace';
-    info?: unknown;
-}
-export interface NavigationReloadOptions {
-    state?: unknown;
-    info?: unknown;
-}
-export interface NavigationOptions {
-    info?: unknown;
-}
-export interface NavigationUpdateCurrentEntryOptions {
-    state: unknown;
-}
-//# sourceMappingURL=navigation-api-types.d.ts.map

package/dist/client/navigation-api-types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"navigation-api-types.d.ts","sourceRoot":"","sources":["../../src/client/navigation-api-types.ts"],"names":[],"mappings":"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"}

package/dist/server/client-module-map.d.ts

@@ -1,47 +0,0 @@
-/**
- * Client module map — maps client reference IDs to their SSR module loaders.
- *
- * When the RSC stream contains a client component reference (from a
- * "use client" module), the SSR environment needs to resolve it to the
- * actual component module so it can render the component to HTML.
- *
- * The @vitejs/plugin-rsc SSR runtime handles this internally via its
- * setRequireModule hook — it imports client reference modules from the
- * SSR environment's module graph. This module provides the configuration
- * bridge between timber's entry system and the RSC plugin's runtime.
- *
- * Design docs: 18-build-system.md §"Entry Files", 02-rendering-pipeline.md
- */
-/**
- * Client reference metadata used during SSR to resolve client components.
- *
- * The RSC plugin tracks these internally via `clientReferenceMetaMap`.
- * At SSR time, when `createFromReadableStream` encounters a client
- * reference in the RSC payload, it uses the module map to import the
- * actual component for server-side HTML rendering.
- */
-export interface ClientModuleEntry {
-    /** The module ID (Vite-resolved file path) */
-    id: string;
-    /** The export name (e.g., 'default', 'Counter') */
-    name: string;
-    /** Async module loader */
-    load: () => Promise<Record<string, unknown>>;
-}
-/**
- * Create a client module map for SSR resolution.
- *
- * In dev mode, the RSC plugin's SSR runtime (`@vitejs/plugin-rsc/ssr`)
- * handles client reference resolution automatically via its initialize()
- * function which sets up `setRequireModule` with dynamic imports through
- * Vite's dev server. No explicit module map is needed.
- *
- * In production builds, the RSC plugin generates a `virtual:vite-rsc/client-references`
- * module that maps client reference IDs to their chunk imports. The SSR
- * runtime reads this at startup.
- *
- * This function returns an empty map as a placeholder — the actual
- * resolution is handled by the RSC plugin's runtime internals.
- */
-export declare function createClientModuleMap(): Record<string, ClientModuleEntry>;
-//# sourceMappingURL=client-module-map.d.ts.map

package/dist/server/client-module-map.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"client-module-map.d.ts","sourceRoot":"","sources":["../../src/server/client-module-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC9C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAUzE"}

package/dist/shared/head-header.d.ts

@@ -1,54 +0,0 @@
-/**
- * Shared encode/decode for the X-Timber-Head response header.
- *
- * Head elements (title, meta, link) are forwarded to the client as a JSON
- * payload in a response header on both the navigation path (RSC payload
- * responses) and the action-revalidation path. HTTP header values must be
- * ByteStrings — any character above U+00FF (em dash, curly quotes, emoji,
- * CJK) makes `new Response(...)` throw. Percent-encoding via
- * encodeURIComponent keeps the value ASCII-safe.
- *
- * This module is the single source of truth for the wire format. Both
- * server emit sites (rsc-entry/rsc-payload.ts, action-handler.ts) and both
- * client parse sites (rsc-fetch.ts, browser-entry/action-dispatch.ts) MUST
- * use it — changing one side alone breaks the other. See TIM-1058.
- *
- * Isomorphic: no server or client imports allowed here.
- *
- * See design/16-metadata.md and design/08-forms-and-actions.md.
- */
-/** Header name for resolved head elements. */
-export declare const HEAD_HEADER = "X-Timber-Head";
-/**
- * Maximum encoded payload size in characters (ASCII after encoding, so
- * characters === bytes). Headers aren't meant for unbounded payloads;
- * oversized head metadata is skipped rather than truncated — the client
- * keeps its current head, which degrades gracefully.
- */
-export declare const HEAD_HEADER_MAX_LENGTH = 4096;
-/**
- * A rendered head element descriptor — the structural shape on the wire.
- * Matches the server's `HeadElement` (route-element-builder.ts); the client
- * narrows `tag` to 'title' | 'meta' | 'link' when applying to the DOM.
- */
-export interface HeadElementPayload {
-    tag: string;
-    content?: string;
-    attrs?: Record<string, string | null>;
-}
-/**
- * Encode head elements for the X-Timber-Head header.
- *
- * Returns the percent-encoded JSON string, or null when the encoded
- * payload exceeds HEAD_HEADER_MAX_LENGTH (caller skips the header).
- */
-export declare function encodeHeadHeader(headElements: HeadElementPayload[]): string | null;
-/**
- * Decode an X-Timber-Head header value back into head elements.
- *
- * Returns null when the value is missing or malformed (corrupted
- * percent-encoding or invalid JSON) — callers treat null as "no head
- * update" rather than failing the navigation or action.
- */
-export declare function decodeHeadHeader(header: string | null): HeadElementPayload[] | null;
-//# sourceMappingURL=head-header.d.ts.map

package/dist/shared/head-header.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"head-header.d.ts","sourceRoot":"","sources":["../../src/shared/head-header.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,8CAA8C;AAC9C,eAAO,MAAM,WAAW,kBAAkB,CAAC;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAE3C;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CACvC;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,kBAAkB,EAAE,GAAG,MAAM,GAAG,IAAI,CAGlF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,kBAAkB,EAAE,GAAG,IAAI,CAQnF"}

package/src/client/head.ts

@@ -1,61 +0,0 @@
-// Client-side head element updates for SPA navigation.
-//
-// On RSC payload responses, the server sends resolved HeadElement[] via the
-// X-Timber-Head response header. This module applies those elements to the
-// DOM so document.title and <meta> tags stay current after navigation.
-//
-// See design/16-metadata.md
-
-// ─── Types ───────────────────────────────────────────────────────
-
-/** Marker attribute for timber-managed head elements (cleanup on next navigation). */
-const TIMBER_ATTR = 'data-timber-head';
-
-/** A rendered head element descriptor (matches server-side HeadElement from metadata.ts). */
-export interface HeadElement {
-  tag: 'title' | 'meta' | 'link';
-  content?: string;
-  attrs?: Record<string, string>;
-}
-
-// ─── Apply Head Elements ─────────────────────────────────────────
-
-/**
- * Apply resolved head elements to the DOM.
- *
- * - Sets document.title for <title> elements
- * - Creates <meta> and <link> tags with a data-timber-head marker
- * - Removes previous timber-managed tags to prevent accumulation
- * - Replaces existing SSR-rendered tags with the same name/property
- */
-export function applyHeadElements(elements: HeadElement[]): void {
-  // Remove previous timber-managed meta/link tags
-  document.head.querySelectorAll(`[${TIMBER_ATTR}]`).forEach((el) => el.remove());
-
-  for (const el of elements) {
-    if (el.tag === 'title' && el.content !== undefined) {
-      document.title = el.content;
-      continue;
-    }
-
-    if (!el.attrs) continue;
-
-    // For meta: remove existing tag with same name/property to avoid duplicates from SSR
-    if (el.tag === 'meta') {
-      const key = el.attrs.name || el.attrs.property;
-      if (key) {
-        const existing = document.head.querySelector(
-          `meta[name="${key}"], meta[property="${key}"]`
-        );
-        if (existing) existing.remove();
-      }
-    }
-
-    const node = document.createElement(el.tag);
-    node.setAttribute(TIMBER_ATTR, '');
-    for (const [k, v] of Object.entries(el.attrs)) {
-      node.setAttribute(k, v);
-    }
-    document.head.appendChild(node);
-  }
-}

package/src/client/navigation-api-types.ts

@@ -1,112 +0,0 @@
-/**
- * Ambient type declarations for the Navigation API.
- *
- * The Navigation API is not yet in TypeScript's standard lib. These types
- * are used internally via type assertions — we never import Navigation API
- * types unconditionally. Progressive enhancement only: the API is feature-
- * detected at runtime.
- *
- * See https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API
- */
-
-// ─── Navigation Entry ────────────────────────────────────────────
-
-export interface NavigationHistoryEntry {
-  readonly key: string;
-  readonly id: string;
-  readonly url: string | null;
-  readonly index: number;
-  readonly sameDocument: boolean;
-  getState(): unknown;
-  addEventListener(type: string, listener: EventListener): void;
-  removeEventListener(type: string, listener: EventListener): void;
-}
-
-// ─── Navigation Destination ──────────────────────────────────────
-
-export interface NavigationDestination {
-  readonly url: string;
-  readonly key: string | null;
-  readonly id: string | null;
-  readonly index: number;
-  readonly sameDocument: boolean;
-  getState(): unknown;
-}
-
-// ─── Navigate Event ──────────────────────────────────────────────
-
-export interface NavigateEvent extends Event {
-  readonly navigationType: 'push' | 'replace' | 'reload' | 'traverse';
-  readonly destination: NavigationDestination;
-  readonly canIntercept: boolean;
-  readonly userInitiated: boolean;
-  readonly hashChange: boolean;
-  readonly signal: AbortSignal;
-  readonly formData: FormData | null;
-  readonly downloadRequest: string | null;
-  readonly info: unknown;
-  intercept(options?: NavigateInterceptOptions): void;
-  scroll(): void;
-}
-
-export interface NavigateInterceptOptions {
-  handler?: () => Promise<void>;
-  focusReset?: 'after-transition' | 'manual';
-  scroll?: 'after-transition' | 'manual';
-}
-
-// ─── Navigation Transition ───────────────────────────────────────
-
-export interface NavigationTransition {
-  readonly navigationType: 'push' | 'replace' | 'reload' | 'traverse';
-  readonly from: NavigationHistoryEntry;
-  readonly finished: Promise<void>;
-}
-
-// ─── Navigation Result ───────────────────────────────────────────
-
-export interface NavigationResult {
-  committed: Promise<NavigationHistoryEntry>;
-  finished: Promise<NavigationHistoryEntry>;
-}
-
-// ─── Navigation Interface ────────────────────────────────────────
-
-export interface NavigationApi {
-  readonly currentEntry: NavigationHistoryEntry | null;
-  readonly transition: NavigationTransition | null;
-  readonly canGoBack: boolean;
-  readonly canGoForward: boolean;
-  entries(): NavigationHistoryEntry[];
-  navigate(url: string, options?: NavigationNavigateOptions): NavigationResult;
-  reload(options?: NavigationReloadOptions): NavigationResult;
-  traverseTo(key: string, options?: NavigationOptions): NavigationResult;
-  back(options?: NavigationOptions): NavigationResult;
-  forward(options?: NavigationOptions): NavigationResult;
-  updateCurrentEntry(options: NavigationUpdateCurrentEntryOptions): void;
-  addEventListener(type: 'navigate', listener: (event: NavigateEvent) => void): void;
-  addEventListener(type: 'navigatesuccess', listener: (event: Event) => void): void;
-  addEventListener(type: 'navigateerror', listener: (event: Event) => void): void;
-  addEventListener(type: 'currententrychange', listener: (event: Event) => void): void;
-  addEventListener(type: string, listener: EventListener): void;
-  removeEventListener(type: string, listener: EventListener): void;
-}
-
-export interface NavigationNavigateOptions {
-  state?: unknown;
-  history?: 'auto' | 'push' | 'replace';
-  info?: unknown;
-}
-
-export interface NavigationReloadOptions {
-  state?: unknown;
-  info?: unknown;
-}
-
-export interface NavigationOptions {
-  info?: unknown;
-}
-
-export interface NavigationUpdateCurrentEntryOptions {
-  state: unknown;
-}