@timber-js/app 0.2.0-alpha.203 → 0.2.0-alpha.205

package/dist/_chunks/chains-CBNA0Ozj.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"chains-CBNA0Ozj.js","names":[],"sources":["../../src/analyze/classify.ts","../../src/analyze/chains.ts"],"sourcesContent":["/**\n * classify — environment-graph classification for project modules.\n *\n * The one classification module every frontend shares (design/47): the\n * `timber graph` CLI, the dev-server endpoint, the VS Code extension,\n * and the cold crawl must never disagree about a file's environment.\n * Classification intersects RSC/SSR module-graph membership with\n * first-directive detection to produce the decided taxonomy:\n *\n * - `server`          — RSC graph only\n * - `client-boundary` — has `'use client'`\n * - `client-internal` — reachable only behind a boundary, no directive\n * - `shared`          — instantiated in both environments; INFO, never a\n *                       warning — shared-by-design is a legitimate pattern\n * - `server-action`   — has `'use server'`\n * - `unreferenced`    — in no graph and no provisional signal; files with\n *                       a directive or filename convention get that\n *                       provisional kind instead, marked `pending`\n *\n * The browser (`client`) Vite graph stays empty until a real browser\n * requests modules, so membership is RSC × SSR — the SSR graph is a\n * faithful proxy for the client tree (design/47 §8, with the frontier\n * caveat below).\n *\n * Design docs: 47-module-environment-tooling.md (taxonomy, §8),\n * 43-analyze-cli.md (directive detection rules).\n */\n\nimport { basename, extname } from 'node:path';\nimport { parseAst, normalizePath } from 'vite';\nimport { hasDirective } from '../rsc-runtime/transforms.ts';\nimport { isRouteConventionFile } from '../routing/scanner.ts';\nimport {\n  isDynamicMetadataExtension,\n  isStaticMetadataExtension,\n} from '../server/metadata-routes.ts';\n\n/** The statement-list shape hasDirective consumes (estree Program body). */\ntype DirectiveBody = Parameters<typeof hasDirective>[0];\n\nexport type ModuleKind =\n  | 'server'\n  | 'client-boundary'\n  | 'client-internal'\n  | 'shared'\n  | 'server-action'\n  | 'unreferenced';\n\nexport type Directive = 'use client' | 'use server' | null;\n\n/**\n * What a frontend observed about one project module. Graph membership\n * comes from the live dev-server graphs or the cold crawl; the directive\n * comes from the module's original source (never the transformed output,\n * where the RSC plugin has already stripped or proxied it).\n */\nexport interface ModuleObservation {\n  /** Absolute path of the source file. */\n  file: string;\n  /** Present in the RSC environment's module graph. */\n  inRsc: boolean;\n  /** Present in the SSR environment's module graph. */\n  inSsr: boolean;\n  /**\n   * Present in the browser (`client`) environment's module graph. Only a\n   * live dev server with a real connected browser can confirm this — the\n   * client graph stays empty otherwise (design/47 §8) — so the cold\n   * crawl always observes false. Defaults to false.\n   */\n  inClient?: boolean;\n  /**\n   * False when the SSR graph has a node for this file but Vite never\n   * transformed it — the §8 signature of a module behind an unexecuted\n   * dynamic import (`transformResult == null`). Its own membership is\n   * trustworthy; its subtree is not. Defaults to true.\n   */\n  ssrTransformed?: boolean;\n  /** First directive of the original source, or null. */\n  directive: Directive;\n}\n\nexport interface ModuleClassification {\n  file: string;\n  kind: ModuleKind;\n  /**\n   * Raw per-environment graph membership, in doc 43's classification\n   * vocabulary (`{ client, ssr, rsc }`). `kind` is the interpreted\n   * answer; this is the evidence. `client` is confirmable only by a\n   * live browser graph — static scans always report false.\n   */\n  envs: { rsc: boolean; ssr: boolean; client: boolean };\n  /**\n   * True when no graph has confirmed this module — the kind is\n   * provisional, derived from directive + filename convention, and\n   * frontends must visibly mark it \"pending\" (design/47 §2).\n   */\n  pending: boolean;\n  /**\n   * §8 frontier: the module is reachable (it ships to the browser) but\n   * was never transformed, so modules behind it may be missing from the\n   * graphs entirely. Consumers should transform-on-demand or surface\n   * \"reachable, subtree unknown\".\n   */\n  subtreeUnknown: boolean;\n}\n\n/** File extensions eligible for directive detection. */\nconst PARSEABLE_EXTENSIONS = /\\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts)$/;\n\n/**\n * Parse language for a source file, from its extension. Never force\n * `tsx` onto plain `.ts`: JSX-ambiguous TypeScript such as\n * `const identity = <T>(value: T) => value` is valid TS but rejected\n * by a TSX parse, and the resulting parse failure would silently drop\n * the file's directive and poison signals. Plain JS parses as `jsx`\n * (JSX-in-.js is common in Vite projects and JS has no generic-arrow\n * ambiguity for the x-syntax to break).\n */\nexport function langForFile(file: string): 'ts' | 'tsx' | 'jsx' {\n  if (/\\.tsx$/.test(file)) return 'tsx';\n  if (/\\.[mc]?ts$/.test(file)) return 'ts';\n  return 'jsx';\n}\n\n/**\n * Detect the first directive of a module's original source.\n *\n * Never string-match or regex directives (design/43): `hasDirective`\n * from @vitejs/plugin-rsc scans the top-level statement list — the same\n * check the RSC plugin runs to decide boundaries, so classification\n * agrees with what the framework actually does with the file (a\n * directive after imports or statements still counts). Non-JS sources\n * (CSS, MDX, assets) and sources that fail to parse return null — no\n * directive is a safe default; classification then falls back to graph\n * membership.\n */\nexport function detectDirective(code: string, file: string): Directive {\n  if (!PARSEABLE_EXTENSIONS.test(file)) return null;\n  let body: DirectiveBody;\n  try {\n    // Vite's parseAst returns oxc-typed nodes; hasDirective expects the\n    // estree shapes. They are structurally identical for the top-level\n    // statement scan — the same bridge the rest of the codebase uses\n    // (plugin-context.ts parse memo, routing/export-detect.ts).\n    body = parseAst(code, { lang: langForFile(file) }).body as unknown as DirectiveBody;\n  } catch {\n    return null;\n  }\n  if (hasDirective(body, 'use client')) return 'use client';\n  if (hasDirective(body, 'use server')) return 'use server';\n  return null;\n}\n\n/** Optional context for classification. */\nexport interface ClassifyContext {\n  /**\n   * Absolute path of the app directory. When provided, convention-based\n   * provisional classification only applies to files inside it — a\n   * `lib/page.tsx` is not a route file, and the scanner would never\n   * recognize it there.\n   */\n  appDir?: string;\n  /**\n   * Configured pageExtensions, when the caller has resolved the app\n   * config. Omitted → scanner defaults.\n   */\n  pageExtensions?: readonly string[];\n}\n\n/**\n * Whether a file is a route-convention source the framework itself\n * imports (page/layout/route/… plus metadata routes). Conventions are\n * derived from the routing scanner and the metadata route table — never\n * a local duplicate list (drift lesson). Each family carries the\n * scanner's own extension rules.\n *\n * Shared by the provisional classifier below and by chains.ts, whose\n * RSC-side walks terminate at the first route-convention file\n * (design/47 §7) — the two must never disagree about what counts.\n *\n * `pageExtensions` mirrors the scanner's parameter: callers that have\n * resolved the app config pass the configured set (a `page.mdx` app);\n * callers without config access fall back to the defaults and tolerate\n * the mismatch.\n */\nexport function isConventionSourceFile(file: string, pageExtensions?: readonly string[]): boolean {\n  const ext = extname(file).slice(1);\n  const base = basename(file, `.${ext}`);\n  return (\n    isRouteConventionFile(base, ext, pageExtensions) ||\n    isStaticMetadataExtension(base, ext) ||\n    isDynamicMetadataExtension(base, ext)\n  );\n}\n\n/**\n * Provisional kind for a file no graph has confirmed (design/47 §2):\n * directive first, then filename convention, else `unreferenced`.\n */\nfunction provisionalKind(file: string, directive: Directive, ctx?: ClassifyContext): ModuleKind {\n  if (directive === 'use client') return 'client-boundary';\n  if (directive === 'use server') return 'server-action';\n  // Normalize both sides before the containment check: on Windows,\n  // `file` may arrive slash-normalized (Vite module-node paths are)\n  // while appDir comes from node:path with backslashes — comparing raw\n  // would misreport every provisional route file as unreferenced.\n  if (ctx?.appDir && !normalizePath(file).startsWith(normalizePath(ctx.appDir) + '/')) {\n    return 'unreferenced';\n  }\n  if (isConventionSourceFile(file, ctx?.pageExtensions)) return 'server';\n  return 'unreferenced';\n}\n\n/**\n * Classify one module from its observation. Pure — all frontends call\n * this with membership data from their own graph source.\n */\nexport function classifyModule(\n  obs: ModuleObservation,\n  ctx?: ClassifyContext\n): ModuleClassification {\n  const referenced = obs.inRsc || obs.inSsr || obs.inClient === true;\n  const subtreeUnknown = obs.inSsr && obs.ssrTransformed === false;\n  const envs = { rsc: obs.inRsc, ssr: obs.inSsr, client: obs.inClient === true };\n\n  if (!referenced) {\n    return {\n      file: obs.file,\n      kind: provisionalKind(obs.file, obs.directive, ctx),\n      envs,\n      pending: true,\n      subtreeUnknown: false,\n    };\n  }\n\n  // Directive wins over membership: a 'use client' file also has an RSC\n  // graph node (the client-reference proxy), and a 'use server' module\n  // appears in the SSR graph when referenced from client forms — the\n  // directive is what those memberships mean.\n  let kind: ModuleKind;\n  if (obs.directive === 'use client') kind = 'client-boundary';\n  else if (obs.directive === 'use server') kind = 'server-action';\n  else if (obs.inRsc && obs.inSsr) kind = 'shared';\n  else if (obs.inRsc) kind = 'server';\n  else kind = 'client-internal';\n\n  return { file: obs.file, kind, envs, pending: false, subtreeUnknown };\n}\n\n/** Classify a batch of observations, sorted by file for stable output. */\nexport function classifyModules(\n  observations: Iterable<ModuleObservation>,\n  ctx?: ClassifyContext\n): ModuleClassification[] {\n  return [...observations]\n    .map((obs) => classifyModule(obs, ctx))\n    .sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));\n}\n","/**\n * chains — boundary-aware import-chain stitching (the \"why\" answer).\n *\n * The human-meaningful import chain for a client-reachable module is a\n * JOIN of two graphs: RSC-graph importers ABOVE the `'use client'`\n * boundary and SSR-graph importers BELOW it. Walking `importers` naively\n * in one graph produces virtual-entry noise (`virtual:vite-rsc/css`)\n * instead of semantic importers — the design/47 §7 findings this module\n * bakes in:\n *\n * - RSC-side walks terminate at `virtual:timber-route-manifest` or the\n *   first route-convention file (page/layout/…), never the literal RSC\n *   entry — route files' importer is the manifest, whose importers are\n *   framework internals; the manifest is the semantic root.\n * - `\\0virtual:vite-rsc/*` importers are filtered so they can never\n *   surface in a chain.\n * - When multiple boundaries import the target, one chain is reported\n *   PER BOUNDARY — a single BFS shortest path would pick arbitrarily.\n *\n * The chain/hop shapes and text formatting are shared with doc 43's\n * `timber why` so both commands emit the same contract: hops carry\n * `{ id, directive, boundary }`, and one shortest chain is emitted per\n * (boundary, reaching route entry) pair — doc 43's \"one shortest path\n * per reaching entry\", crossed with §7's per-boundary rule.\n *\n * Design docs: 47-module-environment-tooling.md §7, 43-analyze-cli.md\n * §Output Formats.\n */\n\nimport { relative, isAbsolute } from 'node:path';\nimport { normalizePath } from 'vite';\nimport { isConventionSourceFile, type Directive } from './classify.ts';\n\n/**\n * Duck-typed view of a Vite environment module node — a supertype of\n * `EnvironmentModuleNode` for the members the walk reads, so live\n * dev-server graphs and crawl graphs both satisfy it structurally.\n */\nexport interface ChainModuleNode {\n  id: string | null;\n  url: string;\n  file: string | null;\n  importers: Set<ChainModuleNode>;\n}\n\n/** Duck-typed view of a Vite environment module graph. */\nexport interface ChainGraph {\n  getModulesByFile(file: string): Set<ChainModuleNode> | undefined;\n}\n\n/** Per-hop directive in doc 43's JSON vocabulary. */\nexport type HopDirective = 'client' | 'server' | null;\n\nexport interface ChainHop {\n  /** Absolute file path, or a virtual module id printed verbatim. */\n  id: string;\n  directive: HopDirective;\n  /** True only on the hop that crosses the server→client boundary. */\n  boundary: boolean;\n}\n\nexport interface ImportChain {\n  /**\n   * Semantic root: a route-convention file, or the route-manifest\n   * virtual id when the walk reached it without passing one. Null when\n   * the RSC-side walk dead-ended (no root found) — the chain then\n   * starts at its deepest known importer and consumers must present it\n   * as partial.\n   */\n  entry: string | null;\n  /**\n   * The `'use client'` file this chain crosses; null for a pure\n   * server-side chain.\n   */\n  boundary: string | null;\n  /** Hops in forward import order, entry → … → target. */\n  hops: ChainHop[];\n}\n\nexport interface ChainContext {\n  rsc: ChainGraph;\n  ssr: ChainGraph;\n  /** Absolute app directory — scopes route-convention root detection. */\n  appDir: string;\n  /**\n   * Configured pageExtensions, when the caller has resolved the app\n   * config — a `page.mdx` app's route files are only roots with it.\n   * Omitted → scanner defaults.\n   */\n  pageExtensions?: readonly string[];\n  /**\n   * First directive of a file's ORIGINAL source (design/43: never the\n   * transformed output, where directives are stripped/proxied).\n   */\n  getDirective(file: string): Directive;\n}\n\n/**\n * The route manifest appears under several ids depending on environment\n * and build phase: `virtual:timber-route-manifest`,\n * `\\0virtual:timber-route-manifest`, and a root-prefixed form\n * (plugins/routing.ts) — match by substring.\n */\nfunction isRouteManifest(key: string): boolean {\n  return key.includes('virtual:timber-route-manifest');\n}\n\n/** plugin-rsc internal virtuals (observed: virtual:vite-rsc/css). */\nfunction isViteRscInternal(key: string): boolean {\n  return key.includes('virtual:vite-rsc/');\n}\n\n/**\n * File-level vertex key for a node: the file path when Vite resolved\n * one, else the virtual id. Multiple nodes can exist per file (query\n * variants); collapsing to the file keeps chains at source granularity.\n */\nfunction vertexKey(node: ChainModuleNode): string | null {\n  return node.file ?? node.id ?? node.url ?? null;\n}\n\n/**\n * Separator for path signatures. Sorts below every printable character\n * so comparing joined signatures equals comparing key sequences.\n */\nconst SIG_SEP = '\\u0000';\n\n/**\n * Backwards level-order BFS over `importers` from `start`, collapsing\n * nodes to file-level vertices and filtering plugin-rsc internals.\n *\n * Shortest-path ties are broken GLOBALLY: each vertex's predecessor is\n * the candidate whose full path signature (the id sequence from the\n * target outward) is lexicographically smallest — per-frontier\n * candidate selection, not merely per-parent importer sorting, so\n * reconverging equal-length branches still yield the advertised\n * representative path (doc 43 §Tie-Breaking).\n *\n * `stopAt` marks terminal vertices. By default their importers are not\n * expanded (RSC walks must not proceed past a route root into\n * framework internals); with `continuePastTerminals` the traversal\n * records the terminal and keeps walking — the SSR walk needs this so\n * an outer boundary that imports an inner boundary is still\n * discovered (one chain per boundary).\n */\nfunction walkImporters(\n  graph: ChainGraph,\n  start: string,\n  stopAt: (key: string) => boolean,\n  continuePastTerminals = false\n): { predecessors: Map<string, string | null>; terminals: string[] } {\n  const startNodes = graph.getModulesByFile(start);\n  const predecessors = new Map<string, string | null>();\n  const terminals: string[] = [];\n  if (!startNodes || startNodes.size === 0) return { predecessors, terminals };\n\n  predecessors.set(start, null);\n  const signatures = new Map<string, string>([[start, start]]);\n  const nodesOf = new Map<string, ChainModuleNode[]>([[start, [...startNodes]]]);\n  let frontier = [start];\n\n  while (frontier.length > 0) {\n    interface Candidate {\n      sig: string;\n      parent: string;\n      observed: ChainModuleNode[];\n    }\n    const candidates = new Map<string, Candidate>();\n    for (const key of frontier) {\n      if (stopAt(key)) {\n        terminals.push(key);\n        if (!continuePastTerminals) continue;\n      }\n      for (const node of nodesOf.get(key) ?? []) {\n        for (const importer of node.importers) {\n          const importerKey = vertexKey(importer);\n          if (!importerKey || isViteRscInternal(importerKey)) continue;\n          if (predecessors.has(importerKey)) continue;\n          // Every frontier vertex has a signature (set when its level\n          // was fixed); the fallback only satisfies the type.\n          const sig = (signatures.get(key) ?? key) + SIG_SEP + importerKey;\n          const existing = candidates.get(importerKey);\n          if (!existing) {\n            candidates.set(importerKey, { sig, parent: key, observed: [importer] });\n          } else {\n            // Keep every observed node object (virtual ids have no file\n            // index to re-fetch from), but the smallest signature wins\n            // the predecessor slot.\n            existing.observed.push(importer);\n            if (sig < existing.sig) {\n              existing.sig = sig;\n              existing.parent = key;\n            }\n          }\n        }\n      }\n    }\n    // Fix the next level, ordered by signature so terminal discovery\n    // order — and therefore chain order — is deterministic.\n    const next = [...candidates.entries()].sort(([, a], [, b]) =>\n      a.sig < b.sig ? -1 : a.sig > b.sig ? 1 : 0\n    );\n    frontier = [];\n    for (const [importerKey, candidate] of next) {\n      predecessors.set(importerKey, candidate.parent);\n      signatures.set(importerKey, candidate.sig);\n      // Re-fetch the file's FULL node set from the graph: the importer\n      // edges seen so far may cover only one of several nodes per file\n      // (query variants — ?direct, ?v=…), and expanding a partial set\n      // would silently drop the sibling nodes' importers and dead-end\n      // the chain. Virtual ids have no file index; use observed nodes.\n      const fullNodes = graph.getModulesByFile(importerKey);\n      nodesOf.set(\n        importerKey,\n        fullNodes && fullNodes.size > 0 ? [...fullNodes] : candidate.observed\n      );\n      frontier.push(importerKey);\n    }\n  }\n  return { predecessors, terminals };\n}\n\n/** Follow predecessors from `from` back to the walk's start vertex. */\nfunction pathToStart(predecessors: Map<string, string | null>, from: string): string[] {\n  const path: string[] = [];\n  for (let key: string | null = from; key !== null; key = predecessors.get(key) ?? null) {\n    path.push(key);\n  }\n  return path;\n}\n\nfunction isRouteRoot(key: string, ctx: ChainContext): boolean {\n  // Manifest matching applies to virtual ids only — a real file whose\n  // path happens to contain the substring must not become a root.\n  if (!isAbsolute(key) && isRouteManifest(key)) return true;\n  if (!isAbsolute(key)) return false;\n  if (key !== ctx.appDir && !key.startsWith(ctx.appDir + '/')) return false;\n  return isConventionSourceFile(key, ctx.pageExtensions);\n}\n\n/**\n * RSC-side walk: importers of `file` in the RSC graph up to the\n * semantic roots. Returns one chain PER reaching route entry (doc 43:\n * \"one shortest path per reaching entry\"), each with hops in forward\n * order (root → … → file), in discovery order (shallowest first,\n * signature tie-break). When no root was reached, a single partial\n * result (entry: null) carrying the deepest known path.\n */\nfunction rscSideChains(\n  file: string,\n  ctx: ChainContext\n): Array<{ entry: string | null; files: string[] }> {\n  const { predecessors, terminals } = walkImporters(ctx.rsc, file, (key) => isRouteRoot(key, ctx));\n  if (terminals.length > 0) {\n    return terminals.map((root) => ({ entry: root, files: pathToStart(predecessors, root) }));\n  }\n  if (predecessors.size <= 1) {\n    // Nothing above the file at all (or file absent from the graph).\n    return [{ entry: null, files: [file] }];\n  }\n  // Dead end — no root found. Report from the deepest vertex on the\n  // last-discovered shortest path so the partial chain is still useful.\n  const keys = [...predecessors.keys()];\n  const deepest = keys[keys.length - 1];\n  return [{ entry: null, files: pathToStart(predecessors, deepest) }];\n}\n\n/** Map a source directive onto the doc-43 hop vocabulary. */\nfunction hopDirective(key: string, ctx: ChainContext): HopDirective {\n  if (!isAbsolute(key)) return null;\n  const directive = ctx.getDirective(key);\n  if (directive === 'use client') return 'client';\n  if (directive === 'use server') return 'server';\n  return null;\n}\n\nfunction toChain(\n  entry: string | null,\n  boundary: string | null,\n  files: string[],\n  ctx: ChainContext\n): ImportChain {\n  return {\n    entry,\n    boundary,\n    hops: files.map((key) => ({\n      id: key,\n      directive: hopDirective(key, ctx),\n      boundary: boundary !== null && key === boundary,\n    })),\n  };\n}\n\n/**\n * Stitch the import chain(s) for a target file.\n *\n * - Target in the SSR graph (client-side): walk SSR importers up to\n *   each `'use client'` boundary that the RSC graph knows (nested\n *   boundaries only reachable from other client components are walked\n *   THROUGH — they exist in no RSC graph, so the chain must continue\n *   to a boundary a server component actually references), then walk\n *   RSC importers from that boundary to the semantic root. One chain\n *   per boundary.\n * - Target in the RSC graph without `'use client'`: a pure server\n *   chain (boundary: null). Shared modules get both kinds.\n * - Target IS an RSC-known boundary: an RSC-side chain from the target\n *   itself, PLUS any outer-boundary chains the SSR walk finds — a\n *   boundary imported by another boundary is pulled in by both. A\n *   nested `'use client'` target the RSC graph does NOT know is\n *   handled like any client-internal file — the SSR walk continues to\n *   the boundary a server component references.\n */\nexport function stitchImportChains(rawTargetFile: string, rawCtx: ChainContext): ImportChain[] {\n  // Vite module-node `file` values are slash-normalized even on\n  // Windows, while node:path targets/appDir arrive backslashed there —\n  // normalize both once so graph lookups and containment checks agree\n  // (normalizePath only rewrites separators on Windows, so posix paths\n  // pass through untouched).\n  const targetFile = normalizePath(rawTargetFile);\n  const ctx: ChainContext = { ...rawCtx, appDir: normalizePath(rawCtx.appDir) };\n\n  const chains: ImportChain[] = [];\n  const targetDirective = ctx.getDirective(targetFile);\n  const targetInRsc = (ctx.rsc.getModulesByFile(targetFile)?.size ?? 0) > 0;\n\n  if (targetDirective === 'use client' && targetInRsc) {\n    for (const above of rscSideChains(targetFile, ctx)) {\n      chains.push(toChain(above.entry, targetFile, above.files, ctx));\n    }\n  }\n\n  // Client-side chains: one per RSC-known boundary above the target.\n  const isRscKnownBoundary = (key: string): boolean =>\n    isAbsolute(key) &&\n    ctx.getDirective(key) === 'use client' &&\n    (ctx.rsc.getModulesByFile(key)?.size ?? 0) > 0;\n\n  // continuePastTerminals: an outer boundary that imports an inner\n  // boundary must still be discovered — one chain per boundary.\n  const ssrWalk = walkImporters(ctx.ssr, targetFile, isRscKnownBoundary, true);\n  for (const boundary of [...ssrWalk.terminals].sort()) {\n    // A boundary target records itself as a terminal; its own chain is\n    // the RSC-side one already pushed above.\n    if (boundary === targetFile) continue;\n    const below = pathToStart(ssrWalk.predecessors, boundary);\n    for (const above of rscSideChains(boundary, ctx)) {\n      // Stitch, dropping the duplicated boundary vertex from the RSC side.\n      chains.push(toChain(above.entry, boundary, [...above.files.slice(0, -1), ...below], ctx));\n    }\n  }\n\n  // Pure server chains when the RSC graph reaches the target directly.\n  if (targetInRsc && targetDirective !== 'use client') {\n    for (const above of rscSideChains(targetFile, ctx)) {\n      chains.push(toChain(above.entry, null, above.files, ctx));\n    }\n  }\n\n  // SSR-side dead end with nothing else to show: mirror the RSC side's\n  // honesty and emit a partial chain from the deepest importer instead\n  // of returning [] as if the file were in no graph. A singleton walk\n  // (target in the SSR graph with no importers at all) still emits its\n  // one-hop partial — graph membership is information.\n  if (chains.length === 0 && ssrWalk.predecessors.size > 0) {\n    const keys = [...ssrWalk.predecessors.keys()];\n    const deepest = keys[keys.length - 1];\n    chains.push(toChain(null, null, pathToStart(ssrWalk.predecessors, deepest), ctx));\n  }\n\n  return chains;\n}\n\n/**\n * Render chains in doc 43's text shape — shared by `timber graph` and\n * `timber why` so both commands print identically:\n *\n * ```\n *   app/page.tsx\n *     → app/nav.tsx  ← 'use client' [boundary]\n *       → src/lib/icons/chevron.ts\n * ```\n *\n * Paths under `projectRoot` print relative; virtual ids print verbatim\n * (doc 43 §Relative-vs-Absolute Paths). A partial chain (entry: null)\n * is prefixed with an honest marker instead of silently posing as\n * complete.\n */\nexport function formatChains(chains: ImportChain[], projectRoot: string): string {\n  const root = normalizePath(projectRoot);\n  const lines: string[] = [];\n  for (const chain of chains) {\n    if (lines.length > 0) lines.push('');\n    if (chain.entry === null) {\n      lines.push('  (partial chain — no route root found)');\n    }\n    chain.hops.forEach((hop, index) => {\n      const display =\n        isAbsolute(hop.id) && hop.id.startsWith(root + '/') ? relative(root, hop.id) : hop.id;\n      const indent = '  '.repeat(index + 1);\n      const arrow = index === 0 ? '' : '→ ';\n      let annotation = '';\n      if (hop.directive === 'client') {\n        annotation = `  ← 'use client'${hop.boundary ? ' [boundary]' : ''}`;\n      } else if (hop.directive === 'server') {\n        annotation = `  ← 'use server'`;\n      }\n      lines.push(`${indent}${arrow}${display}${annotation}`);\n    });\n  }\n  return lines.join('\\n');\n}\n"],"mappings":"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"}

package/dist/_chunks/csp-nonce-hOGniaG4.js

@@ -1,227 +0,0 @@
-import { r as requestContextAls } from "./als-registry-C6kcfprT.js";
-import { R as getSetCookieHeaders, m as setLogger, q as getTraceId } from "./logger-DqJ2VoAY.js";
-import { r as isRscRequest } from "./rsc-media-type-DDc7duTD.js";
-//#region src/server/instrumentation.ts
-/**
-* Instrumentation — loads and runs the user's instrumentation.ts file.
-*
-* instrumentation.ts is a file convention at the project root that exports:
-* - register() — called once at server startup, before the first request
-* - onRequestError() — called for every unhandled server error
-* - logger — any object with info/warn/error/debug methods
-*
-* See design/17-logging.md §"instrumentation.ts — The Entry Point"
-*/
-var _initialized = false;
-var _onRequestError = null;
-/**
-* Load and initialize the user's instrumentation.ts module.
-*
-* - Awaits register() before returning (server blocks on this).
-* - Picks up the logger export and wires it into the framework logger.
-* - Stores onRequestError for later invocation.
-*
-* @param loader - Function that dynamically imports the user's instrumentation module.
-*                 Returns null if no instrumentation.ts exists.
-*/
-async function loadInstrumentation(loader) {
-	if (_initialized) return;
-	_initialized = true;
-	let mod;
-	try {
-		mod = await loader();
-	} catch (error) {
-		console.error("[timber] Failed to load instrumentation.ts:", error);
-		return;
-	}
-	if (!mod) return;
-	if (mod.logger && typeof mod.logger.info === "function") setLogger(mod.logger);
-	if (typeof mod.onRequestError === "function") _onRequestError = mod.onRequestError;
-	if (typeof mod.register === "function") try {
-		await mod.register();
-	} catch (error) {
-		console.error("[timber] instrumentation.ts register() threw:", error);
-		throw error;
-	}
-}
-/**
-* Call the user's onRequestError hook. Catches and logs any errors thrown
-* by the hook itself — it must not affect the response.
-*/
-async function callOnRequestError(error, request, context) {
-	if (!_onRequestError) return;
-	try {
-		await _onRequestError(error, request, context);
-	} catch (hookError) {
-		console.error("[timber] onRequestError hook threw:", hookError);
-	}
-}
-/**
-* Check if onRequestError is registered.
-*/
-function hasOnRequestError() {
-	return _onRequestError !== null;
-}
-//#endregion
-//#region src/server/pipeline-helpers.ts
-/**
-* Build a proxy resolver closure from the declared source. Called exactly
-* once at `createPipeline` setup time, so the hot path sees only the branch
-* that corresponds to this pipeline's configured variant.
-*
-* Returns `null` when the app has no proxy.ts — the hot path short-circuits
-* around `runProxyPhase` entirely in that case.
-*
-* Accepts the sugar form (a bare `ProxyExport` — function or function array)
-* and normalises it to the static variant. Functions and arrays are
-* structurally distinct from the tagged `{ kind: 'lazy', loader }` object,
-* so discrimination is unambiguous.
-*/
-function makeProxyResolver(proxy) {
-	if (proxy === void 0) return null;
-	if (typeof proxy === "function" || Array.isArray(proxy)) {
-		const exp = proxy;
-		return () => exp;
-	}
-	if (proxy.kind === "static") {
-		const exp = proxy.export;
-		return () => exp;
-	}
-	const loader = proxy.loader;
-	return async () => (await loader()).default;
-}
-/**
-* Apply all Set-Cookie headers from the cookie jar to a Headers object.
-* Each cookie gets its own Set-Cookie header per RFC 6265 §4.1.
-*/
-function applyCookieJar(headers) {
-	for (const value of getSetCookieHeaders()) headers.append("Set-Cookie", value);
-}
-/**
-* Merge framework-managed response headers onto a terminal response without
-* overwriting headers the terminal response already set itself.
-*/
-function mergeMissingHeaders(target, source) {
-	const existingKeys = new Set([...target.keys()].map((key) => key.toLowerCase()));
-	for (const [key, value] of source.entries()) if (!existingKeys.has(key.toLowerCase())) target.append(key, value);
-}
-/**
-* Clone a Response into a fresh one whose header bag is guaranteed mutable.
-*
-* `Response.redirect()` and some platform-level passthrough responses (notably
-* on Cloudflare Workers) return objects with frozen header bags. Calling
-* `.set()` or `.append()` on them throws `TypeError: immutable`, which the
-* pipeline can hit when it appends Set-Cookie or Server-Timing entries.
-*
-* The pipeline calls this at the producer sites where user-controlled
-* responses enter the framework — `outcomeToResponse` for all phase outcomes,
-* and `handleRequest` for metadata-route and auto-sitemap user handlers — so
-* downstream code can write headers without runtime feature-detection.
-*
-* The clone is unconditional. This is a deliberate trade: we avoid a
-* try/catch + thrown `TypeError` on every request (the previous probe-based
-* approach paid that cost on the hot path) and accept one cheap Response
-* rewrap at the framework boundary instead.
-*/
-function cloneWithMutableHeaders(response) {
-	return new Response(response.body, {
-		status: response.status,
-		statusText: response.statusText,
-		headers: new Headers(response.headers)
-	});
-}
-/**
-* Build a redirect Response from a RedirectSignal.
-*
-* For RSC payload requests (client navigation), returns 204 + X-Timber-Redirect
-* so the client router can perform a soft SPA redirect. A raw 302 would be
-* turned into an opaque redirect by fetch({redirect:'manual'}), crashing
-* createFromFetch. See design/19-client-navigation.md.
-*/
-function buildRedirectResponse(signal, req, headers) {
-	if (isRscRequest(req)) {
-		headers.set("X-Timber-Redirect", signal.location);
-		return new Response(null, {
-			status: 204,
-			headers
-		});
-	}
-	headers.set("Location", signal.location);
-	return new Response(null, {
-		status: signal.status,
-		headers
-	});
-}
-/**
-* Fire the user's onRequestError hook with request context.
-* Extracts request info from the Request object and calls the instrumentation hook.
-*/
-async function fireOnRequestError(error, req, phase) {
-	const url = new URL(req.url);
-	const headersObj = {};
-	req.headers.forEach((v, k) => {
-		headersObj[k] = v;
-	});
-	await callOnRequestError(error, {
-		method: req.method,
-		path: url.pathname,
-		headers: headersObj
-	}, {
-		phase,
-		routePath: url.pathname,
-		routeType: "page",
-		traceId: getTraceId()
-	});
-}
-//#endregion
-//#region src/server/csp-nonce.ts
-/**
-* CSP nonce — per-request, generated on demand.
-*
-* timber emits several inline `<script>` tags per HTML response — React's
-* bootstrap script and Fizz runtime, the Flight init/chunk scripts, the
-* segment-tree script, and the post-flush noindex script. Under a strict
-* `Content-Security-Policy` (`script-src 'nonce-…' 'strict-dynamic'`) every
-* one of them needs the request's nonce or the browser refuses to run it.
-*
-* The app opts in by reading `ctx.nonce` in `middleware.ts` and putting it
-* in the CSP header it sets through `ctx.headers`. The first read generates
-* the value and stores it on the request context; the render pipeline reads
-* it back with `getCspNonce()` and stamps it on every inline script. A
-* request whose middleware never reads `ctx.nonce` has no nonce, and its
-* markup is byte-identical to a render without this feature. timber does
-* not parse the CSP header — the app owns the policy, timber owns the
-* markup, and `ctx.nonce` is the one value both are built from.
-*
-* `proxy.ts` cannot participate: it only sees the finished response from
-* `next()`, after the markup exists.
-*
-* See design/13-security.md §"Content Security Policy" (TIM-1414).
-*/
-/**
-* Generate a CSP nonce: 128 random bits, base64. Matches CSP's
-* `base64-value` grammar, so it is valid in the header verbatim and safe
-* inside a double-quoted HTML attribute without escaping.
-*/
-function generateNonce() {
-	const bytes = crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(16));
-	let binary = "";
-	for (const b of bytes) binary += String.fromCharCode(b);
-	return btoa(binary);
-}
-/**
-* The request's CSP nonce, creating it on first call. Backs the
-* `ctx.nonce` getter on `MiddlewareContext`. Outside a request context
-* (tests, build-time rendering) a fresh value is returned but not
-* retained, since there is no request for it to belong to.
-*/
-function requestCspNonce() {
-	const store = requestContextAls.getStore();
-	if (!store) return generateNonce();
-	store.cspNonce ??= generateNonce();
-	return store.cspNonce;
-}
-//#endregion
-export { fireOnRequestError as a, callOnRequestError as c, cloneWithMutableHeaders as i, hasOnRequestError as l, applyCookieJar as n, makeProxyResolver as o, buildRedirectResponse as r, mergeMissingHeaders as s, requestCspNonce as t, loadInstrumentation as u };
-
-//# sourceMappingURL=csp-nonce-hOGniaG4.js.map

package/dist/_chunks/csp-nonce-hOGniaG4.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"csp-nonce-hOGniaG4.js","names":[],"sources":["../../src/server/instrumentation.ts","../../src/server/pipeline-helpers.ts","../../src/server/csp-nonce.ts"],"sourcesContent":["/**\n * Instrumentation — loads and runs the user's instrumentation.ts file.\n *\n * instrumentation.ts is a file convention at the project root that exports:\n * - register() — called once at server startup, before the first request\n * - onRequestError() — called for every unhandled server error\n * - logger — any object with info/warn/error/debug methods\n *\n * See design/17-logging.md §\"instrumentation.ts — The Entry Point\"\n */\n\nimport { setLogger, type TimberLogger } from './logger.ts';\n\n// ─── Instrumentation Types ────────────────────────────────────────────────\n\nexport type InstrumentationOnRequestError = (\n  error: unknown,\n  request: InstrumentationRequestInfo,\n  context: InstrumentationErrorContext\n) => void | Promise<void>;\n\nexport interface InstrumentationRequestInfo {\n  /** HTTP method: 'GET', 'POST', etc. */\n  method: string;\n  /** Request path: '/dashboard/projects/123' */\n  path: string;\n  /** Request headers as a plain object. */\n  headers: Record<string, string>;\n}\n\nexport interface InstrumentationErrorContext {\n  /** Which pipeline phase the error occurred in. */\n  phase: 'proxy' | 'handler' | 'render' | 'action' | 'route';\n  /** The route pattern: '/dashboard/projects/[id]' */\n  routePath: string;\n  /** Type of route that was matched. */\n  routeType: 'page' | 'route' | 'action';\n  /** Always set — OTEL trace ID or UUID fallback. */\n  traceId: string;\n}\n\n// ─── Instrumentation Module Shape ─────────────────────────────────────────\n\ninterface InstrumentationModule {\n  register?: () => void | Promise<void>;\n  onRequestError?: InstrumentationOnRequestError;\n  logger?: TimberLogger;\n}\n\n// ─── State ────────────────────────────────────────────────────────────────\n//\n// Intentional per-app singletons (not per-request). Instrumentation loads\n// once at server startup and persists for the lifetime of the process/isolate.\n// These must NOT be migrated to ALS — they are correctly scoped to the app.\n\nlet _initialized = false;\nlet _onRequestError: InstrumentationOnRequestError | null = null;\n\n/**\n * Load and initialize the user's instrumentation.ts module.\n *\n * - Awaits register() before returning (server blocks on this).\n * - Picks up the logger export and wires it into the framework logger.\n * - Stores onRequestError for later invocation.\n *\n * @param loader - Function that dynamically imports the user's instrumentation module.\n *                 Returns null if no instrumentation.ts exists.\n */\nexport async function loadInstrumentation(\n  loader: () => Promise<InstrumentationModule | null>\n): Promise<void> {\n  if (_initialized) return;\n  _initialized = true;\n\n  let mod: InstrumentationModule | null;\n  try {\n    mod = await loader();\n  } catch (error) {\n    console.error('[timber] Failed to load instrumentation.ts:', error);\n    return;\n  }\n\n  if (!mod) return;\n\n  // Wire up the logger export\n  if (mod.logger && typeof mod.logger.info === 'function') {\n    setLogger(mod.logger);\n  }\n\n  // Store onRequestError for later\n  if (typeof mod.onRequestError === 'function') {\n    _onRequestError = mod.onRequestError;\n  }\n\n  // Await register() — server does not accept requests until this resolves\n  if (typeof mod.register === 'function') {\n    try {\n      await mod.register();\n    } catch (error) {\n      console.error('[timber] instrumentation.ts register() threw:', error);\n      throw error;\n    }\n  }\n}\n\n/**\n * Call the user's onRequestError hook. Catches and logs any errors thrown\n * by the hook itself — it must not affect the response.\n */\nexport async function callOnRequestError(\n  error: unknown,\n  request: InstrumentationRequestInfo,\n  context: InstrumentationErrorContext\n): Promise<void> {\n  if (!_onRequestError) return;\n  try {\n    await _onRequestError(error, request, context);\n  } catch (hookError) {\n    console.error('[timber] onRequestError hook threw:', hookError);\n  }\n}\n\n/**\n * Check if onRequestError is registered.\n */\nexport function hasOnRequestError(): boolean {\n  return _onRequestError !== null;\n}\n\n/**\n * Reset instrumentation state. Test-only.\n */\nexport function resetInstrumentation(): void {\n  _initialized = false;\n  _onRequestError = null;\n}\n","/**\n * Pipeline helpers — small utility functions used by `pipeline.ts` and\n * `pipeline-phases.ts`. Lifted out of `pipeline.ts` to keep that file\n * focused on the request handler entry point.\n *\n * Each helper is intentionally a free function with no closure capture, so\n * it can be unit-tested in isolation.\n *\n * See design/07-routing.md §\"Request Lifecycle\".\n */\n\nimport type { ProxyExport } from './proxy.ts';\nimport { getSetCookieHeaders } from './cookie-context.ts';\nimport { callOnRequestError } from './instrumentation.ts';\nimport { getTraceId } from './tracing.ts';\nimport { RedirectSignal } from './primitives.ts';\nimport type { ProxyConfig } from './pipeline.ts';\nimport { isRscRequest } from '../shared/rsc-media-type.ts';\n\n// ─── Prototype-Pollution-Safe Sanitizer ────────────────────────────────────\n\n// ─── Proxy Resolver ────────────────────────────────────────────────────────\n\n/**\n * Resolver closure produced once at pipeline construction. The lazy variant\n * still calls `loader()` per-request (HMR relies on re-importing), but the\n * choice of which branch to take is made once, not on every request.\n */\nexport type ProxyResolver = () => ProxyExport | Promise<ProxyExport>;\n\n/**\n * Build a proxy resolver closure from the declared source. Called exactly\n * once at `createPipeline` setup time, so the hot path sees only the branch\n * that corresponds to this pipeline's configured variant.\n *\n * Returns `null` when the app has no proxy.ts — the hot path short-circuits\n * around `runProxyPhase` entirely in that case.\n *\n * Accepts the sugar form (a bare `ProxyExport` — function or function array)\n * and normalises it to the static variant. Functions and arrays are\n * structurally distinct from the tagged `{ kind: 'lazy', loader }` object,\n * so discrimination is unambiguous.\n */\nexport function makeProxyResolver(\n  proxy: ProxyConfig | ProxyExport | undefined\n): ProxyResolver | null {\n  if (proxy === undefined) return null;\n  // Sugar: a bare ProxyExport (function or function array) — treat as static.\n  if (typeof proxy === 'function' || Array.isArray(proxy)) {\n    const exp = proxy;\n    return () => exp;\n  }\n  if (proxy.kind === 'static') {\n    const exp = proxy.export;\n    return () => exp;\n  }\n  const loader = proxy.loader;\n  return async () => (await loader()).default;\n}\n\n// ─── Cookie / Header Helpers ───────────────────────────────────────────────\n\n/**\n * Apply all Set-Cookie headers from the cookie jar to a Headers object.\n * Each cookie gets its own Set-Cookie header per RFC 6265 §4.1.\n */\nexport function applyCookieJar(headers: Headers): void {\n  for (const value of getSetCookieHeaders()) {\n    headers.append('Set-Cookie', value);\n  }\n}\n\n/**\n * Merge framework-managed response headers onto a terminal response without\n * overwriting headers the terminal response already set itself.\n */\nexport function mergeMissingHeaders(target: Headers, source: Headers): void {\n  const existingKeys = new Set([...target.keys()].map((key) => key.toLowerCase()));\n  for (const [key, value] of source.entries()) {\n    if (!existingKeys.has(key.toLowerCase())) {\n      target.append(key, value);\n    }\n  }\n}\n\n// ─── Mutable Response Cloning ──────────────────────────────────────────────\n\n/**\n * Clone a Response into a fresh one whose header bag is guaranteed mutable.\n *\n * `Response.redirect()` and some platform-level passthrough responses (notably\n * on Cloudflare Workers) return objects with frozen header bags. Calling\n * `.set()` or `.append()` on them throws `TypeError: immutable`, which the\n * pipeline can hit when it appends Set-Cookie or Server-Timing entries.\n *\n * The pipeline calls this at the producer sites where user-controlled\n * responses enter the framework — `outcomeToResponse` for all phase outcomes,\n * and `handleRequest` for metadata-route and auto-sitemap user handlers — so\n * downstream code can write headers without runtime feature-detection.\n *\n * The clone is unconditional. This is a deliberate trade: we avoid a\n * try/catch + thrown `TypeError` on every request (the previous probe-based\n * approach paid that cost on the hot path) and accept one cheap Response\n * rewrap at the framework boundary instead.\n */\nexport function cloneWithMutableHeaders(response: Response): Response {\n  return new Response(response.body, {\n    status: response.status,\n    statusText: response.statusText,\n    headers: new Headers(response.headers),\n  });\n}\n\n// ─── Redirect Builder ──────────────────────────────────────────────────────\n\n/**\n * Build a redirect Response from a RedirectSignal.\n *\n * For RSC payload requests (client navigation), returns 204 + X-Timber-Redirect\n * so the client router can perform a soft SPA redirect. A raw 302 would be\n * turned into an opaque redirect by fetch({redirect:'manual'}), crashing\n * createFromFetch. See design/19-client-navigation.md.\n */\nexport function buildRedirectResponse(\n  signal: RedirectSignal,\n  req: Request,\n  headers: Headers\n): Response {\n  if (isRscRequest(req)) {\n    headers.set('X-Timber-Redirect', signal.location);\n    return new Response(null, { status: 204, headers });\n  }\n  headers.set('Location', signal.location);\n  return new Response(null, { status: signal.status, headers });\n}\n\n// ─── Instrumentation ───────────────────────────────────────────────────────\n\n/**\n * Fire the user's onRequestError hook with request context.\n * Extracts request info from the Request object and calls the instrumentation hook.\n */\nexport async function fireOnRequestError(\n  error: unknown,\n  req: Request,\n  phase: 'proxy' | 'handler' | 'render' | 'action' | 'route'\n): Promise<void> {\n  const url = new URL(req.url);\n  const headersObj: Record<string, string> = {};\n  req.headers.forEach((v, k) => {\n    headersObj[k] = v;\n  });\n\n  await callOnRequestError(\n    error,\n    { method: req.method, path: url.pathname, headers: headersObj },\n    { phase, routePath: url.pathname, routeType: 'page', traceId: getTraceId() }\n  );\n}\n","/**\n * CSP nonce — per-request, generated on demand.\n *\n * timber emits several inline `<script>` tags per HTML response — React's\n * bootstrap script and Fizz runtime, the Flight init/chunk scripts, the\n * segment-tree script, and the post-flush noindex script. Under a strict\n * `Content-Security-Policy` (`script-src 'nonce-…' 'strict-dynamic'`) every\n * one of them needs the request's nonce or the browser refuses to run it.\n *\n * The app opts in by reading `ctx.nonce` in `middleware.ts` and putting it\n * in the CSP header it sets through `ctx.headers`. The first read generates\n * the value and stores it on the request context; the render pipeline reads\n * it back with `getCspNonce()` and stamps it on every inline script. A\n * request whose middleware never reads `ctx.nonce` has no nonce, and its\n * markup is byte-identical to a render without this feature. timber does\n * not parse the CSP header — the app owns the policy, timber owns the\n * markup, and `ctx.nonce` is the one value both are built from.\n *\n * `proxy.ts` cannot participate: it only sees the finished response from\n * `next()`, after the markup exists.\n *\n * See design/13-security.md §\"Content Security Policy\" (TIM-1414).\n */\n\nimport { requestContextAls } from './als-registry.ts';\n\n/**\n * Generate a CSP nonce: 128 random bits, base64. Matches CSP's\n * `base64-value` grammar, so it is valid in the header verbatim and safe\n * inside a double-quoted HTML attribute without escaping.\n */\nfunction generateNonce(): string {\n  const bytes = crypto.getRandomValues(new Uint8Array(16));\n  let binary = '';\n  for (const b of bytes) binary += String.fromCharCode(b);\n  return btoa(binary);\n}\n\n/**\n * The request's CSP nonce, creating it on first call. Backs the\n * `ctx.nonce` getter on `MiddlewareContext`. Outside a request context\n * (tests, build-time rendering) a fresh value is returned but not\n * retained, since there is no request for it to belong to.\n */\nexport function requestCspNonce(): string {\n  const store = requestContextAls.getStore();\n  if (!store) return generateNonce();\n  store.cspNonce ??= generateNonce();\n  return store.cspNonce;\n}\n\n/**\n * The request's CSP nonce if middleware asked for one, else `undefined` —\n * in which case the pipeline emits bare `<script>` tags.\n */\nexport function getCspNonce(): string | undefined {\n  return requestContextAls.getStore()?.cspNonce;\n}\n\n/**\n * The ` nonce=\"…\"` attribute fragment for a timber-generated `<script>` tag,\n * or `''` when the request has no nonce. Callers interpolate it directly\n * after the tag name: `` `<script${nonceAttr(nonce)}>` ``.\n *\n * The value comes from `generateNonce` and is base64, so no attribute\n * escaping is required.\n */\nexport function nonceAttr(nonce: string | undefined): string {\n  return nonce ? ` nonce=\"${nonce}\"` : '';\n}\n"],"mappings":";;;;;;;;;;;;;;AAuDA,IAAI,eAAe;AACnB,IAAI,kBAAwD;;;;;;;;;;;AAY5D,eAAsB,oBACpB,QACe;CACf,IAAI,cAAc;CAClB,eAAe;CAEf,IAAI;CACJ,IAAI;EACF,MAAM,MAAM,OAAO;CACrB,SAAS,OAAO;EACd,QAAQ,MAAM,+CAA+C,KAAK;EAClE;CACF;CAEA,IAAI,CAAC,KAAK;CAGV,IAAI,IAAI,UAAU,OAAO,IAAI,OAAO,SAAS,YAC3C,UAAU,IAAI,MAAM;CAItB,IAAI,OAAO,IAAI,mBAAmB,YAChC,kBAAkB,IAAI;CAIxB,IAAI,OAAO,IAAI,aAAa,YAC1B,IAAI;EACF,MAAM,IAAI,SAAS;CACrB,SAAS,OAAO;EACd,QAAQ,MAAM,iDAAiD,KAAK;EACpE,MAAM;CACR;AAEJ;;;;;AAMA,eAAsB,mBACpB,OACA,SACA,SACe;CACf,IAAI,CAAC,iBAAiB;CACtB,IAAI;EACF,MAAM,gBAAgB,OAAO,SAAS,OAAO;CAC/C,SAAS,WAAW;EAClB,QAAQ,MAAM,uCAAuC,SAAS;CAChE;AACF;;;;AAKA,SAAgB,oBAA6B;CAC3C,OAAO,oBAAoB;AAC7B;;;;;;;;;;;;;;;;ACpFA,SAAgB,kBACd,OACsB;CACtB,IAAI,UAAU,KAAA,GAAW,OAAO;CAEhC,IAAI,OAAO,UAAU,cAAc,MAAM,QAAQ,KAAK,GAAG;EACvD,MAAM,MAAM;EACZ,aAAa;CACf;CACA,IAAI,MAAM,SAAS,UAAU;EAC3B,MAAM,MAAM,MAAM;EAClB,aAAa;CACf;CACA,MAAM,SAAS,MAAM;CACrB,OAAO,aAAa,MAAM,OAAO,EAAA,CAAG;AACtC;;;;;AAQA,SAAgB,eAAe,SAAwB;CACrD,KAAK,MAAM,SAAS,oBAAoB,GACtC,QAAQ,OAAO,cAAc,KAAK;AAEtC;;;;;AAMA,SAAgB,oBAAoB,QAAiB,QAAuB;CAC1E,MAAM,eAAe,IAAI,IAAI,CAAC,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,YAAY,CAAC,CAAC;CAC/E,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,GACxC,IAAI,CAAC,aAAa,IAAI,IAAI,YAAY,CAAC,GACrC,OAAO,OAAO,KAAK,KAAK;AAG9B;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,wBAAwB,UAA8B;CACpE,OAAO,IAAI,SAAS,SAAS,MAAM;EACjC,QAAQ,SAAS;EACjB,YAAY,SAAS;EACrB,SAAS,IAAI,QAAQ,SAAS,OAAO;CACvC,CAAC;AACH;;;;;;;;;AAYA,SAAgB,sBACd,QACA,KACA,SACU;CACV,IAAI,aAAa,GAAG,GAAG;EACrB,QAAQ,IAAI,qBAAqB,OAAO,QAAQ;EAChD,OAAO,IAAI,SAAS,MAAM;GAAE,QAAQ;GAAK;EAAQ,CAAC;CACpD;CACA,QAAQ,IAAI,YAAY,OAAO,QAAQ;CACvC,OAAO,IAAI,SAAS,MAAM;EAAE,QAAQ,OAAO;EAAQ;CAAQ,CAAC;AAC9D;;;;;AAQA,eAAsB,mBACpB,OACA,KACA,OACe;CACf,MAAM,MAAM,IAAI,IAAI,IAAI,GAAG;CAC3B,MAAM,aAAqC,CAAC;CAC5C,IAAI,QAAQ,SAAS,GAAG,MAAM;EAC5B,WAAW,KAAK;CAClB,CAAC;CAED,MAAM,mBACJ,OACA;EAAE,QAAQ,IAAI;EAAQ,MAAM,IAAI;EAAU,SAAS;CAAW,GAC9D;EAAE;EAAO,WAAW,IAAI;EAAU,WAAW;EAAQ,SAAS,WAAW;CAAE,CAC7E;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC/HA,SAAS,gBAAwB;CAC/B,MAAM,QAAQ,OAAO,gCAAgB,IAAI,WAAW,EAAE,CAAC;CACvD,IAAI,SAAS;CACb,KAAK,MAAM,KAAK,OAAO,UAAU,OAAO,aAAa,CAAC;CACtD,OAAO,KAAK,MAAM;AACpB;;;;;;;AAQA,SAAgB,kBAA0B;CACxC,MAAM,QAAQ,kBAAkB,SAAS;CACzC,IAAI,CAAC,OAAO,OAAO,cAAc;CACjC,MAAM,aAAa,cAAc;CACjC,OAAO,MAAM;AACf"}