@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/dist/_chunks/poison-rules-DoEhbqaY.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"poison-rules-DoEhbqaY.js","names":[],"sources":["../../src/analyze/poison-rules.ts"],"sourcesContent":["/**\n * poison-rules — single source of truth for server-only / client-only\n * module rules.\n *\n * Two tiers with different enforcement policies (design/47 §3):\n *\n * 1. **Explicit markers** (`server-only`, `client-only`) — evaluation-time\n *    poison pills. `plugins/shims.ts` resolves them to virtual modules\n *    whose body is a top-level `throw` in the wrong environment and a\n *    silent no-op in the right one. The error fires when the module is\n *    evaluated, not at resolve time.\n *\n * 2. **Inferred rules** (`node:*` imports, timber's ALS modules, browser\n *    globals) — report-only. They have legitimate false positives\n *    (`import.meta.env.SSR`-guarded `node:*` use, conditionally-imported\n *    packages), so erroring the build on them would refuse working apps.\n *    The `timber graph` reporter surfaces them as hints.\n *\n * Both shims.ts and the reporter consume this module so the two surfaces\n * can never disagree. Promoting inferred rules to build errors is a\n * policy flip on this list, never a new rule set.\n *\n * Design doc: 47-module-environment-tooling.md §3.\n */\n\nimport { isBuiltin } from 'node:module';\n\n/** Vite environment names the dev server / build run. */\nexport type EnvironmentName = 'rsc' | 'ssr' | 'client';\n\n// ─── Tier 1: explicit markers (evaluation-time poison pills) ──────────────\n\nexport interface ExplicitMarker {\n  /** The bare specifier user code imports (`server-only` / `client-only`). */\n  readonly specifier: string;\n  /** Virtual module ID the specifier resolves to in shims.ts. */\n  readonly virtualId: string;\n  /**\n   * True when evaluating the marker in `env` is a violation (the virtual\n   * module body must throw). `undefined` means \"no environment context\"\n   * (e.g. a non-environment-aware build) and is treated as a server\n   * environment — matching the historical shims.ts behavior.\n   */\n  readonly violatesIn: (env: EnvironmentName | string | undefined) => boolean;\n  /** Exact runtime error message thrown in the wrong environment. */\n  readonly errorMessage: string;\n  readonly enforcement: 'poison-pill';\n}\n\nexport const EXPLICIT_MARKERS: readonly ExplicitMarker[] = [\n  {\n    specifier: 'server-only',\n    virtualId: '\\0timber:server-only',\n    violatesIn: (env) => env === 'client',\n    errorMessage:\n      'This module cannot be imported from a Client Component module. ' +\n      'It should only be used from a Server Component.',\n    enforcement: 'poison-pill',\n  },\n  {\n    specifier: 'client-only',\n    virtualId: '\\0timber:client-only',\n    violatesIn: (env) => env !== 'client',\n    errorMessage:\n      'This module cannot be imported from a Server Component module. ' +\n      'It should only be used from a Client Component.',\n    enforcement: 'poison-pill',\n  },\n];\n\n/**\n * Look up an explicit marker by its import specifier. Throws on an\n * unknown specifier — callers reference rules that must exist, and a\n * silent undefined would just defer the failure.\n */\nexport function markerFor(specifier: string): ExplicitMarker {\n  const marker = EXPLICIT_MARKERS.find((m) => m.specifier === specifier);\n  if (!marker) throw new Error(`[timber] unknown poison marker: ${specifier}`);\n  return marker;\n}\n\n/**\n * Generate the virtual module body for an explicit marker in `env`:\n * a top-level throw in the wrong environment, a no-op otherwise.\n */\nexport function poisonPillSource(\n  marker: ExplicitMarker,\n  env: EnvironmentName | string | undefined\n): string {\n  if (marker.violatesIn(env)) {\n    return `throw new Error(${JSON.stringify(marker.errorMessage)});`;\n  }\n  return 'export {};';\n}\n\n// ─── Tier 2: inferred rules (report-only) ─────────────────────────────────\n\nexport interface InferredRule {\n  readonly id: string;\n  /** Which exclusivity the signal implies for the containing module. */\n  readonly implies: 'server-only' | 'client-only';\n  readonly enforcement: 'report-only';\n  /** Human-readable description for reporter output. */\n  readonly description: string;\n  /** Import-specifier signal — matches static import sources. */\n  readonly matchesImport?: (specifier: string) => boolean;\n  /**\n   * Identifier signal — global names whose use implies the exclusivity.\n   * Consumers must apply shadow-safe matching (an allowlisted-position\n   * AST check, not a text search).\n   */\n  readonly identifiers?: readonly string[];\n}\n\n/**\n * Timber modules that hold per-request AsyncLocalStorage state. Importing\n * one from client-reachable code is a strong server-only signal — cf. the\n * no-server-imports-in-isomorphic-define-modules rule.\n */\nconst ALS_MODULE_SPECIFIERS = new Set([\n  '@timber-js/app/server',\n  '@timber-js/app/server/internal',\n  '#server-internal',\n]);\n\n/**\n * The ALS registry module itself, as it appears in import sources.\n * Framework code imports it ESM-style with a `.js` specifier — both\n * `../server/als-registry.js` and sibling `./als-registry.js` forms\n * exist throughout src/server — while resolved module ids carry `.ts`.\n * Matching any path ending in the basename is deliberate: the rule is\n * report-only, and a user file coincidentally named als-registry is a\n * far rarer event than a missed hint on the real one.\n */\nconst ALS_REGISTRY_SUFFIX = /(?:^|\\/)als-registry\\.(?:ts|js)$/;\n\nexport const INFERRED_RULES: readonly InferredRule[] = [\n  {\n    id: 'node-builtin-import',\n    implies: 'server-only',\n    enforcement: 'report-only',\n    description: 'imports a node:* built-in module',\n    // Deliberately node:-prefixed only, matching design/47 §3's scope.\n    // Bare builtin names (`buffer`, `events`, `process`, `util`, …) are\n    // also real npm packages that browser code legitimately imports (the\n    // classic polyfill set) — matching them would report working client\n    // code, so they are intentionally NOT a signal.\n    matchesImport: (specifier) => specifier.startsWith('node:') && isBuiltin(specifier),\n  },\n  {\n    id: 'timber-als-module',\n    implies: 'server-only',\n    enforcement: 'report-only',\n    description: \"imports timber's per-request AsyncLocalStorage modules\",\n    matchesImport: (specifier) =>\n      ALS_MODULE_SPECIFIERS.has(specifier) || ALS_REGISTRY_SUFFIX.test(specifier),\n  },\n  {\n    id: 'browser-global',\n    implies: 'client-only',\n    enforcement: 'report-only',\n    description: 'references a browser-only global',\n    identifiers: ['window', 'document', 'navigator', 'localStorage', 'sessionStorage'],\n  },\n];\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAiDA,IAAa,mBAA8C,CACzD;CACE,WAAW;CACX,WAAW;CACX,aAAa,QAAQ,QAAQ;CAC7B,cACE;CAEF,aAAa;AACf,GACA;CACE,WAAW;CACX,WAAW;CACX,aAAa,QAAQ,QAAQ;CAC7B,cACE;CAEF,aAAa;AACf,CACF;;;;;;AAOA,SAAgB,UAAU,WAAmC;CAC3D,MAAM,SAAS,iBAAiB,MAAM,MAAM,EAAE,cAAc,SAAS;CACrE,IAAI,CAAC,QAAQ,MAAM,IAAI,MAAM,mCAAmC,WAAW;CAC3E,OAAO;AACT;;;;;AAMA,SAAgB,iBACd,QACA,KACQ;CACR,IAAI,OAAO,WAAW,GAAG,GACvB,OAAO,mBAAmB,KAAK,UAAU,OAAO,YAAY,EAAE;CAEhE,OAAO;AACT;;;;;;AA0BA,IAAM,wCAAwB,IAAI,IAAI;CACpC;CACA;CACA;AACF,CAAC;;;;;;;;;;AAWD,IAAM,sBAAsB;AAE5B,IAAa,iBAA0C;CACrD;EACE,IAAI;EACJ,SAAS;EACT,aAAa;EACb,aAAa;EAMb,gBAAgB,cAAc,UAAU,WAAW,OAAO,KAAK,UAAU,SAAS;CACpF;CACA;EACE,IAAI;EACJ,SAAS;EACT,aAAa;EACb,aAAa;EACb,gBAAgB,cACd,sBAAsB,IAAI,SAAS,KAAK,oBAAoB,KAAK,SAAS;CAC9E;CACA;EACE,IAAI;EACJ,SAAS;EACT,aAAa;EACb,aAAa;EACb,aAAa;GAAC;GAAU;GAAY;GAAa;GAAgB;EAAgB;CACnF;AACF"}

package/dist/_chunks/poison-scan-Bm9Yyqk9.js

@@ -0,0 +1,101 @@
+import { n as INFERRED_RULES, t as EXPLICIT_MARKERS } from "./poison-rules-DoEhbqaY.js";
+import { o as langForFile } from "./chains-Bpb0W4ax.js";
+import { parseAst } from "vite";
+//#region src/analyze/poison-scan.ts
+/**
+* poison-scan — report-only poisoning detection for `timber graph`.
+*
+* Matches a module's static import specifiers against the shared rule
+* lists in poison-rules.ts (the single source of truth — design/47 §3)
+* and reports a poisoning only when the implied exclusivity CONFLICTS
+* with where the module actually runs: a server-only signal in a
+* client-reachable module, or a client-only signal in a server-reachable
+* one. A `node:fs` import in a file only the RSC environment loads is
+* working code, not a finding.
+*
+* Scope: import-specifier signals only (explicit markers + the inferred
+* rules' `matchesImport`). The inferred browser-global identifier rules
+* need shadow-safe allowlisted-position AST matching and are a separate
+* ticket — reporting them from a text scan would flag legitimate code.
+*
+* Design docs: 47-module-environment-tooling.md §3.
+*/
+/** File extensions the specifier scan can parse. */
+var PARSEABLE_EXTENSIONS = /\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts)$/;
+/**
+* A NON-EMPTY specifier list where every entry is type-only. Empty or
+* absent lists return false — a bare `import 'pkg'` is a side-effect
+* import and very much runs.
+*/
+function isAllSpecifiersTypeOnly(specifiers) {
+	if (!specifiers || specifiers.length === 0) return false;
+	return specifiers.every((s) => s.importKind === "type" || s.exportKind === "type");
+}
+/**
+* Collect every static import/export source and string-literal dynamic
+* import from a module's original source. Sources that fail to parse
+* (or are not JS/TS at all) return [] — no specifiers is a safe
+* default for a report-only scan.
+*/
+function collectImportSpecifiers(code, file) {
+	if (!PARSEABLE_EXTENSIONS.test(file)) return [];
+	let program;
+	try {
+		program = parseAst(code, { lang: langForFile(file) });
+	} catch {
+		return [];
+	}
+	const specifiers = [];
+	const visit = (node) => {
+		if (Array.isArray(node)) {
+			for (const child of node) visit(child);
+			return;
+		}
+		if (typeof node !== "object" || node === null) return;
+		const record = node;
+		if ((record.type === "ImportDeclaration" || record.type === "ExportNamedDeclaration" || record.type === "ExportAllDeclaration") && record.importKind !== "type" && record.exportKind !== "type" && !isAllSpecifiersTypeOnly(record.specifiers) && typeof record.source?.value === "string") specifiers.push(record.source.value);
+		else if (record.type === "ImportExpression" && record.source?.type === "Literal" && typeof record.source.value === "string") specifiers.push(record.source.value);
+		for (const key of Object.keys(record)) {
+			if (key === "type") continue;
+			visit(record[key]);
+		}
+	};
+	visit(program.body);
+	return specifiers;
+}
+/** Exclusivity signals a module's import specifiers carry. */
+function importSignals(specifiers) {
+	const signals = [];
+	for (const specifier of specifiers) {
+		for (const marker of EXPLICIT_MARKERS) if (specifier === marker.specifier) signals.push({
+			rule: marker.specifier,
+			specifier,
+			implies: marker.specifier === "server-only" ? "server-only" : "client-only",
+			description: `imports the ${marker.specifier} poison-pill marker`
+		});
+		for (const rule of INFERRED_RULES) if (rule.matchesImport?.(specifier)) signals.push({
+			rule: rule.id,
+			specifier,
+			implies: rule.implies,
+			description: rule.description
+		});
+	}
+	return signals;
+}
+/**
+* Filter a module's signals down to actual conflicts with its
+* classification. Environment reach follows the taxonomy: boundary /
+* client-internal / shared modules run client-side; server / shared /
+* server-action modules run server-side. Pending (provisional) modules
+* run nowhere confirmed, so nothing conflicts yet.
+*/
+function poisoningsFor(kind, pending, signals) {
+	if (pending || signals.length === 0) return [];
+	const clientReachable = kind === "client-boundary" || kind === "client-internal" || kind === "shared";
+	const serverReachable = kind === "server" || kind === "shared" || kind === "server-action";
+	return signals.filter((signal) => signal.implies === "server-only" && clientReachable || signal.implies === "client-only" && serverReachable);
+}
+//#endregion
+export { importSignals as n, poisoningsFor as r, collectImportSpecifiers as t };
+
+//# sourceMappingURL=poison-scan-Bm9Yyqk9.js.map

package/dist/_chunks/poison-scan-Bm9Yyqk9.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"poison-scan-Bm9Yyqk9.js","names":[],"sources":["../../src/analyze/poison-scan.ts"],"sourcesContent":["/**\n * poison-scan — report-only poisoning detection for `timber graph`.\n *\n * Matches a module's static import specifiers against the shared rule\n * lists in poison-rules.ts (the single source of truth — design/47 §3)\n * and reports a poisoning only when the implied exclusivity CONFLICTS\n * with where the module actually runs: a server-only signal in a\n * client-reachable module, or a client-only signal in a server-reachable\n * one. A `node:fs` import in a file only the RSC environment loads is\n * working code, not a finding.\n *\n * Scope: import-specifier signals only (explicit markers + the inferred\n * rules' `matchesImport`). The inferred browser-global identifier rules\n * need shadow-safe allowlisted-position AST matching and are a separate\n * ticket — reporting them from a text scan would flag legitimate code.\n *\n * Design docs: 47-module-environment-tooling.md §3.\n */\n\nimport { parseAst } from 'vite';\nimport { EXPLICIT_MARKERS, INFERRED_RULES } from './poison-rules.ts';\nimport { langForFile, type ModuleKind } from './classify.ts';\n\n/** One poisoning finding on a module, in the JSON-contract shape. */\nexport interface Poisoning {\n  /** Rule id — an inferred rule's id, or the explicit marker specifier. */\n  rule: string;\n  /** The import specifier that matched. */\n  specifier: string;\n  /** Which exclusivity the signal implies for the containing module. */\n  implies: 'server-only' | 'client-only';\n  /** Human-readable description for reporter output. */\n  description: string;\n}\n\n/** File extensions the specifier scan can parse. */\nconst PARSEABLE_EXTENSIONS = /\\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts)$/;\n\n/**\n * A NON-EMPTY specifier list where every entry is type-only. Empty or\n * absent lists return false — a bare `import 'pkg'` is a side-effect\n * import and very much runs.\n */\nfunction isAllSpecifiersTypeOnly(\n  specifiers: Array<{ importKind?: string; exportKind?: string }> | undefined\n): boolean {\n  if (!specifiers || specifiers.length === 0) return false;\n  return specifiers.every((s) => s.importKind === 'type' || s.exportKind === 'type');\n}\n\n/**\n * Collect every static import/export source and string-literal dynamic\n * import from a module's original source. Sources that fail to parse\n * (or are not JS/TS at all) return [] — no specifiers is a safe\n * default for a report-only scan.\n */\nexport function collectImportSpecifiers(code: string, file: string): string[] {\n  if (!PARSEABLE_EXTENSIONS.test(file)) return [];\n  let program;\n  try {\n    // Language from the extension, never forced tsx — see langForFile.\n    program = parseAst(code, { lang: langForFile(file) });\n  } catch {\n    return [];\n  }\n  const specifiers: string[] = [];\n  const visit = (node: unknown): void => {\n    if (Array.isArray(node)) {\n      for (const child of node) visit(child);\n      return;\n    }\n    if (typeof node !== 'object' || node === null) return;\n    const record = node as Record<string, unknown> & {\n      type?: string;\n      importKind?: string;\n      exportKind?: string;\n      specifiers?: Array<{ importKind?: string; exportKind?: string }>;\n    };\n    if (\n      (record.type === 'ImportDeclaration' ||\n        record.type === 'ExportNamedDeclaration' ||\n        record.type === 'ExportAllDeclaration') &&\n      // Type-only imports/exports are erased at runtime — `import type\n      // { Stats } from 'node:fs'` in client code is working code, and\n      // flagging it would be a false positive in a report-only scan.\n      // Covers both the declaration-level form (`import type {…}`,\n      // importKind on the declaration) and the inline form\n      // (`import { type Stats }`, where the declaration stays 'value'\n      // and each SPECIFIER carries the kind) — a declaration whose\n      // specifiers are all type-only is erased just the same.\n      record.importKind !== 'type' &&\n      record.exportKind !== 'type' &&\n      !isAllSpecifiersTypeOnly(record.specifiers) &&\n      typeof (record.source as { value?: unknown } | null)?.value === 'string'\n    ) {\n      specifiers.push((record.source as { value: string }).value);\n    } else if (\n      record.type === 'ImportExpression' &&\n      (record.source as { type?: string; value?: unknown })?.type === 'Literal' &&\n      typeof (record.source as { value?: unknown }).value === 'string'\n    ) {\n      specifiers.push((record.source as { value: string }).value);\n    }\n    for (const key of Object.keys(record)) {\n      if (key === 'type') continue;\n      visit(record[key]);\n    }\n  };\n  visit(program.body);\n  return specifiers;\n}\n\n/** Exclusivity signals a module's import specifiers carry. */\nexport function importSignals(specifiers: string[]): Poisoning[] {\n  const signals: Poisoning[] = [];\n  for (const specifier of specifiers) {\n    for (const marker of EXPLICIT_MARKERS) {\n      if (specifier === marker.specifier) {\n        signals.push({\n          rule: marker.specifier,\n          specifier,\n          implies: marker.specifier === 'server-only' ? 'server-only' : 'client-only',\n          description: `imports the ${marker.specifier} poison-pill marker`,\n        });\n      }\n    }\n    for (const rule of INFERRED_RULES) {\n      if (rule.matchesImport?.(specifier)) {\n        signals.push({\n          rule: rule.id,\n          specifier,\n          implies: rule.implies,\n          description: rule.description,\n        });\n      }\n    }\n  }\n  return signals;\n}\n\n/**\n * Filter a module's signals down to actual conflicts with its\n * classification. Environment reach follows the taxonomy: boundary /\n * client-internal / shared modules run client-side; server / shared /\n * server-action modules run server-side. Pending (provisional) modules\n * run nowhere confirmed, so nothing conflicts yet.\n */\nexport function poisoningsFor(\n  kind: ModuleKind,\n  pending: boolean,\n  signals: Poisoning[]\n): Poisoning[] {\n  if (pending || signals.length === 0) return [];\n  const clientReachable =\n    kind === 'client-boundary' || kind === 'client-internal' || kind === 'shared';\n  const serverReachable = kind === 'server' || kind === 'shared' || kind === 'server-action';\n  return signals.filter(\n    (signal) =>\n      (signal.implies === 'server-only' && clientReachable) ||\n      (signal.implies === 'client-only' && serverReachable)\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAoCA,IAAM,uBAAuB;;;;;;AAO7B,SAAS,wBACP,YACS;CACT,IAAI,CAAC,cAAc,WAAW,WAAW,GAAG,OAAO;CACnD,OAAO,WAAW,OAAO,MAAM,EAAE,eAAe,UAAU,EAAE,eAAe,MAAM;AACnF;;;;;;;AAQA,SAAgB,wBAAwB,MAAc,MAAwB;CAC5E,IAAI,CAAC,qBAAqB,KAAK,IAAI,GAAG,OAAO,CAAC;CAC9C,IAAI;CACJ,IAAI;EAEF,UAAU,SAAS,MAAM,EAAE,MAAM,YAAY,IAAI,EAAE,CAAC;CACtD,QAAQ;EACN,OAAO,CAAC;CACV;CACA,MAAM,aAAuB,CAAC;CAC9B,MAAM,SAAS,SAAwB;EACrC,IAAI,MAAM,QAAQ,IAAI,GAAG;GACvB,KAAK,MAAM,SAAS,MAAM,MAAM,KAAK;GACrC;EACF;EACA,IAAI,OAAO,SAAS,YAAY,SAAS,MAAM;EAC/C,MAAM,SAAS;EAMf,KACG,OAAO,SAAS,uBACf,OAAO,SAAS,4BAChB,OAAO,SAAS,2BASlB,OAAO,eAAe,UACtB,OAAO,eAAe,UACtB,CAAC,wBAAwB,OAAO,UAAU,KAC1C,OAAQ,OAAO,QAAuC,UAAU,UAEhE,WAAW,KAAM,OAAO,OAA6B,KAAK;OACrD,IACL,OAAO,SAAS,sBACf,OAAO,QAA+C,SAAS,aAChE,OAAQ,OAAO,OAA+B,UAAU,UAExD,WAAW,KAAM,OAAO,OAA6B,KAAK;EAE5D,KAAK,MAAM,OAAO,OAAO,KAAK,MAAM,GAAG;GACrC,IAAI,QAAQ,QAAQ;GACpB,MAAM,OAAO,IAAI;EACnB;CACF;CACA,MAAM,QAAQ,IAAI;CAClB,OAAO;AACT;;AAGA,SAAgB,cAAc,YAAmC;CAC/D,MAAM,UAAuB,CAAC;CAC9B,KAAK,MAAM,aAAa,YAAY;EAClC,KAAK,MAAM,UAAU,kBACnB,IAAI,cAAc,OAAO,WACvB,QAAQ,KAAK;GACX,MAAM,OAAO;GACb;GACA,SAAS,OAAO,cAAc,gBAAgB,gBAAgB;GAC9D,aAAa,eAAe,OAAO,UAAU;EAC/C,CAAC;EAGL,KAAK,MAAM,QAAQ,gBACjB,IAAI,KAAK,gBAAgB,SAAS,GAChC,QAAQ,KAAK;GACX,MAAM,KAAK;GACX;GACA,SAAS,KAAK;GACd,aAAa,KAAK;EACpB,CAAC;CAGP;CACA,OAAO;AACT;;;;;;;;AASA,SAAgB,cACd,MACA,SACA,SACa;CACb,IAAI,WAAW,QAAQ,WAAW,GAAG,OAAO,CAAC;CAC7C,MAAM,kBACJ,SAAS,qBAAqB,SAAS,qBAAqB,SAAS;CACvE,MAAM,kBAAkB,SAAS,YAAY,SAAS,YAAY,SAAS;CAC3E,OAAO,QAAQ,QACZ,WACE,OAAO,YAAY,iBAAiB,mBACpC,OAAO,YAAY,iBAAiB,eACzC;AACF"}

package/dist/_chunks/purge-store-Byr8XOjU.js

@@ -0,0 +1,14 @@
+//#region src/cdn/purge-store.ts
+var handler;
+/** Install a CDN purge handler. Called by the framework at boot from timber.config.ts. */
+function setCdnPurgeHandler(h) {
+	handler = h;
+}
+/** Get the current CDN purge handler, if configured. */
+function getCdnPurgeHandler() {
+	return handler;
+}
+//#endregion
+export { setCdnPurgeHandler as n, getCdnPurgeHandler as t };
+
+//# sourceMappingURL=purge-store-Byr8XOjU.js.map

package/dist/_chunks/purge-store-Byr8XOjU.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"purge-store-Byr8XOjU.js","names":[],"sources":["../../src/cdn/purge-store.ts"],"sourcesContent":["/**\n * CDN purge handler singleton — same pattern as cache/handler-store.ts.\n *\n * Set via timber.config.ts or setCdnPurgeHandler() at boot. When set,\n * cache.invalidate({ tag }) also triggers CDN purge for the invalidated\n * tags, so revalidateTag() composes with CDN caching out of the box.\n *\n * See design/25-production-deployments.md §Layer 2.\n */\n\nexport interface CdnPurgeHandler {\n  /**\n   * Purge the given cache tags from the CDN.\n   * Called by cache.invalidate when a tag is invalidated.\n   */\n  purgeTags(tags: string[]): Promise<void>;\n}\n\nlet handler: CdnPurgeHandler | undefined;\n\n/** Install a CDN purge handler. Called by the framework at boot from timber.config.ts. */\nexport function setCdnPurgeHandler(h: CdnPurgeHandler): void {\n  handler = h;\n}\n\n/** Get the current CDN purge handler, if configured. */\nexport function getCdnPurgeHandler(): CdnPurgeHandler | undefined {\n  return handler;\n}\n\n/** @internal — reset for tests only. */\nexport function _resetCdnPurgeHandler(): void {\n  handler = undefined;\n}\n"],"mappings":";AAkBA,IAAI;;AAGJ,SAAgB,mBAAmB,GAA0B;CAC3D,UAAU;AACZ;;AAGA,SAAgB,qBAAkD;CAChE,OAAO;AACT"}

package/dist/_chunks/resolve-schema-CBR6Lm4i.js

@@ -0,0 +1,50 @@
+import { a as resolveCodecOrSchema, r as isCodec } from "./schema-bridge-C83xa9lT.js";
+//#region src/params/resolve-schema.ts
+/**
+* Reconstruct the bracket key for a segment from its type and param name.
+* Used by the coercion layer to look up codecs in the bracket-keyed map.
+*
+* 'dynamic'          + 'id'   → '[id]'
+* 'catch-all'        + 'slug' → '[...slug]'
+* 'optional-catch-all' + 'slug' → '[[...slug]]'
+*/
+function toBracketKey(segmentType, paramName) {
+	switch (segmentType) {
+		case "catch-all": return `[...${paramName}]`;
+		case "optional-catch-all": return `[[...${paramName}]]`;
+		default: return `[${paramName}]`;
+	}
+}
+var CATCH_ALL_RE = /^\[\.\.\..+\]$/;
+var OPTIONAL_CATCH_ALL_RE = /^\[\[\.\.\..+\]\]$/;
+function isCatchAllKey(key) {
+	return CATCH_ALL_RE.test(key) || OPTIONAL_CATCH_ALL_RE.test(key);
+}
+function isOptionalCatchAllKey(key) {
+	return OPTIONAL_CATCH_ALL_RE.test(key);
+}
+/**
+* Resolve the global schema's segmentParams into a map of bracket-keyed
+* param name → resolved Codec.
+*
+* Keys are preserved exactly as written in `app/schema.ts` so that
+* `[id]`, `[...id]`, and `[[...id]]` remain distinct entries.
+* The coercion layer in `param-coercion.ts` reconstructs bracket keys
+* from matched segment metadata to look up the correct codec.
+*
+* Input:  { '[id]': z.coerce.number(), '[...slug]': codec.string }
+* Output: { '[id]': Codec<number>, '[...slug]': Codec<string> }
+*/
+function resolveSchemaCodecs(segmentParams) {
+	const resolved = Object.create(null);
+	for (const [bracketName, value] of Object.entries(segmentParams)) {
+		if (isCatchAllKey(bracketName) && isCodec(value) && !("__catchAll" in value)) throw new Error(`[timber] Schema error: '${bracketName}' is a catch-all segment and requires an array codec (e.g. codec.catchAll(codec.string)). Got a scalar codec.`);
+		if (isOptionalCatchAllKey(bracketName) && isCodec(value) && "__catchAll" in value && !("__optional" in value)) throw new Error(`[timber] Schema error: '${bracketName}' is an optional catch-all segment and requires codec.optionalCatchAll() (e.g. codec.optionalCatchAll(codec.string)). Got a non-optional catch-all codec.`);
+		resolved[bracketName] = resolveCodecOrSchema(bracketName, value, "param");
+	}
+	return resolved;
+}
+//#endregion
+export { toBracketKey as n, resolveSchemaCodecs as t };
+
+//# sourceMappingURL=resolve-schema-CBR6Lm4i.js.map

package/dist/_chunks/resolve-schema-CBR6Lm4i.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-schema-CBR6Lm4i.js","names":[],"sources":["../../src/params/resolve-schema.ts"],"sourcesContent":["/**\n * Schema resolution — resolves the global schema's segmentParams into\n * a runtime-ready codec map keyed by bracket name (e.g. '[id]').\n *\n * Bracket keys are preserved so that `[id]`, `[...id]`, and `[[...id]]`\n * remain distinct entries. The coercion layer reconstructs bracket keys\n * from matched segment metadata to look up the correct codec.\n *\n * Design doc: design/41-global-params.md §Pipeline Integration\n */\n\nimport type { Codec } from '../codec.ts';\nimport { isCodec, resolveCodecOrSchema } from '../schema-bridge.ts';\n\n/**\n * Reconstruct the bracket key for a segment from its type and param name.\n * Used by the coercion layer to look up codecs in the bracket-keyed map.\n *\n * 'dynamic'          + 'id'   → '[id]'\n * 'catch-all'        + 'slug' → '[...slug]'\n * 'optional-catch-all' + 'slug' → '[[...slug]]'\n */\nexport function toBracketKey(segmentType: string, paramName: string): string {\n  switch (segmentType) {\n    case 'catch-all':\n      return `[...${paramName}]`;\n    case 'optional-catch-all':\n      return `[[...${paramName}]]`;\n    default:\n      return `[${paramName}]`;\n  }\n}\n\nconst CATCH_ALL_RE = /^\\[\\.\\.\\..+\\]$/;\nconst OPTIONAL_CATCH_ALL_RE = /^\\[\\[\\.\\.\\..+\\]\\]$/;\n\nfunction isCatchAllKey(key: string): boolean {\n  return CATCH_ALL_RE.test(key) || OPTIONAL_CATCH_ALL_RE.test(key);\n}\n\nfunction isOptionalCatchAllKey(key: string): boolean {\n  return OPTIONAL_CATCH_ALL_RE.test(key);\n}\n\n/**\n * Resolve the global schema's segmentParams into a map of bracket-keyed\n * param name → resolved Codec.\n *\n * Keys are preserved exactly as written in `app/schema.ts` so that\n * `[id]`, `[...id]`, and `[[...id]]` remain distinct entries.\n * The coercion layer in `param-coercion.ts` reconstructs bracket keys\n * from matched segment metadata to look up the correct codec.\n *\n * Input:  { '[id]': z.coerce.number(), '[...slug]': codec.string }\n * Output: { '[id]': Codec<number>, '[...slug]': Codec<string> }\n */\nexport function resolveSchemaCodecs(\n  segmentParams: Record<string, unknown>\n): Record<string, Codec<unknown>> {\n  const resolved: Record<string, Codec<unknown>> = Object.create(null);\n\n  for (const [bracketName, value] of Object.entries(segmentParams)) {\n    if (isCatchAllKey(bracketName) && isCodec(value) && !('__catchAll' in value)) {\n      throw new Error(\n        `[timber] Schema error: '${bracketName}' is a catch-all segment and requires an array codec ` +\n          `(e.g. codec.catchAll(codec.string)). Got a scalar codec.`\n      );\n    }\n    if (\n      isOptionalCatchAllKey(bracketName) &&\n      isCodec(value) &&\n      '__catchAll' in value &&\n      !('__optional' in value)\n    ) {\n      throw new Error(\n        `[timber] Schema error: '${bracketName}' is an optional catch-all segment and requires codec.optionalCatchAll() ` +\n          `(e.g. codec.optionalCatchAll(codec.string)). Got a non-optional catch-all codec.`\n      );\n    }\n    resolved[bracketName] = resolveCodecOrSchema(bracketName, value, 'param');\n  }\n\n  return resolved;\n}\n"],"mappings":";;;;;;;;;;AAsBA,SAAgB,aAAa,aAAqB,WAA2B;CAC3E,QAAQ,aAAR;EACE,KAAK,aACH,OAAO,OAAO,UAAU;EAC1B,KAAK,sBACH,OAAO,QAAQ,UAAU;EAC3B,SACE,OAAO,IAAI,UAAU;CACzB;AACF;AAEA,IAAM,eAAe;AACrB,IAAM,wBAAwB;AAE9B,SAAS,cAAc,KAAsB;CAC3C,OAAO,aAAa,KAAK,GAAG,KAAK,sBAAsB,KAAK,GAAG;AACjE;AAEA,SAAS,sBAAsB,KAAsB;CACnD,OAAO,sBAAsB,KAAK,GAAG;AACvC;;;;;;;;;;;;;AAcA,SAAgB,oBACd,eACgC;CAChC,MAAM,WAA2C,OAAO,OAAO,IAAI;CAEnE,KAAK,MAAM,CAAC,aAAa,UAAU,OAAO,QAAQ,aAAa,GAAG;EAChE,IAAI,cAAc,WAAW,KAAK,QAAQ,KAAK,KAAK,EAAE,gBAAgB,QACpE,MAAM,IAAI,MACR,2BAA2B,YAAY,8GAEzC;EAEF,IACE,sBAAsB,WAAW,KACjC,QAAQ,KAAK,KACb,gBAAgB,SAChB,EAAE,gBAAgB,QAElB,MAAM,IAAI,MACR,2BAA2B,YAAY,0JAEzC;EAEF,SAAS,eAAe,qBAAqB,aAAa,OAAO,OAAO;CAC1E;CAEA,OAAO;AACT"}

package/dist/_chunks/rolldown-runtime-D7D4PA-g.js

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll as t };

package/dist/_chunks/rsc-cache-key-ClUiXQnK.js

@@ -0,0 +1,243 @@
+//#region src/shared/rsc-cache-key.ts
+/**
+* The `_rsc` payload cache key — derived identically on both sides.
+*
+* The client puts this in the payload URL so the document and its Flight
+* payload occupy different cache keys (TIM-1268). The server recomputes it
+* from the received headers so a request cannot claim one client's key while
+* sending another client's headers — see `server/rsc-cache-key-guard.ts`.
+* Both sides must agree exactly, which is why the derivation lives here and
+* not in either one.
+*
+* Isomorphic: no server or client imports. The browser bundle audit
+* (`tests/client-bundle-audit.test.ts`) enforces the client half of that.
+*
+* See design/19-client-navigation.md §"The `_rsc` cache key".
+*/
+/**
+* Digest length in hex characters. 128 bits: the origin guard compares a
+* caller-supplied key against a recomputed one, so the relevant bound is a
+* birthday attack (an attacker who can influence a victim's `X-Timber-URL`
+* gets to search both sides), not second preimage. 64 bits would fall to
+* ~2^32 work; 128 puts it at 2^64.
+*/
+var KEY_HEX_LENGTH = 32;
+/**
+* Marks a value as a framework-issued key, and versions the derivation.
+*
+* Without it, an application value that happened to be 32 lowercase hex — an
+* MD5, a token — is indistinguishable from a forged claim: both are "the
+* right shape, the wrong digest", and no information in the value separates
+* them. So the exemption cannot key on shape alone.
+*
+* The prefix resolves that because it is anchored to the address the
+* victim's own client uses. A payload lives at `?_rsc=1.<digest>`, so
+* anything aimed at that cache entry must carry the prefix and therefore
+* gets validated; anything without it cannot be addressing a payload URL at
+* all, and is exempt as application data. An attacker cannot both hit the
+* victim's cache key and dodge the check.
+*
+* The version component also gives the derivation a migration path: the
+* client and the origin must agree byte for byte, so a future change to the
+* canonical form can be rolled out by bumping this instead of a flag day.
+*/
+var KEY_PREFIX = "1.";
+/**
+* The request headers that vary an RSC payload response, in canonical
+* casing — this list is also emitted verbatim as the response's `Vary`
+* tokens (`server/pipeline.ts`), since "what varies the response" is one
+* question with one answer, not two lists that happen to agree.
+*
+* This list is the contract, and it is enforced rather than trusted:
+* `tests/rsc-cache-key.test.ts` asserts that the header names
+* `buildRscHeaders()` can emit are exactly this set. A header added to the
+* request without being added here fails that test, because a varying input
+* outside the key is precisely the cache-poisoning hazard the key exists to
+* close.
+*
+* **No credentials, session identifiers, or user-supplied content may be
+* added.** Every value here is hashed into a URL, and URLs are logged by
+* proxies, CDNs, and origin access logs. `fnv1aHash` is a cache-key hash,
+* not a KDF — a low-entropy secret would be recoverable by brute force.
+* Authentication travels on cookies, which never enter the key.
+*/
+var RSC_KEY_HEADERS = [
+	"Accept",
+	"X-Timber-State-Tree",
+	"X-Timber-URL",
+	"X-Timber-Deployment-Id"
+];
+/**
+* Whether a value could be a key this module produced.
+*
+* `_rsc` is not a reserved parameter name — an application may already use
+* it for its own search state, including for a value that happens to look
+* like a digest. Anything without the `KEY_PREFIX` is therefore application
+* data, not a claim on a payload cache key, and the origin guard leaves it
+* alone rather than penalizing the response.
+*
+* Derived from `KEY_PREFIX` and `KEY_HEX_LENGTH` rather than spelled again,
+* so the shape cannot drift from the digest that has to satisfy it.
+*
+* Ignoring a malformed value costs no protection: clients only ever send
+* well-formed keys, so a URL bearing a malformed one is an address no
+* legitimate request will ever ask for, and nothing can be poisoned at an
+* address nobody reads.
+*/
+function isRscCacheKeyShape(value) {
+	if (!value.startsWith(KEY_PREFIX)) return false;
+	const digest = value.slice(2);
+	return digest.length === KEY_HEX_LENGTH && /^[0-9a-f]+$/.test(digest);
+}
+/**
+* The query parameter carrying the payload cache key.
+*
+* Spelled here rather than at each of the four places that read or write it
+* — the client that appends it, the origin guard that validates it, and the
+* strip below — because it is a wire contract between two independent
+* implementations, exactly like the digest itself.
+*/
+var RSC_KEY_PARAM = "_rsc";
+/**
+* Decode one raw `name` or `value` the way `URLSearchParams` does:
+* `application/x-www-form-urlencoded`, so `+` is a space.
+*
+* Malformed percent-escapes throw in `decodeURIComponent`. `URLSearchParams`
+* leaves those bytes as-is rather than throwing, and so do we — a pair we
+* cannot decode is by definition not the framework's, so it is kept.
+*/
+function formDecode(raw) {
+	try {
+		return decodeURIComponent(raw.replace(/\+/g, " "));
+	} catch {
+		return raw;
+	}
+}
+/**
+* Remove framework-issued `_rsc` values from a raw query string.
+*
+* Only values matching `isRscCacheKeyShape` are removed. `_rsc` is not a
+* reserved name (see that function), so `/search?_rsc=foo` is application
+* state and survives — the same exemption the origin guard applies, derived
+* from the same predicate so the two cannot disagree about what "ours"
+* means.
+*
+* Operates on the raw string rather than round-tripping through
+* `URLSearchParams`, so every surviving pair keeps its original bytes.
+* Re-serializing would rewrite `?b` as `?b=` and `?a=%7E` as `?a=~` on RSC
+* navigations only, which is the same class of inconsistency this function
+* exists to remove.
+*
+* Matching decodes the name, because `?%5Frsc=<key>` is a `_rsc` parameter
+* as far as `URLSearchParams` is concerned — the same reasoning as the
+* guard's fast path.
+*
+* @param search - `url.search`, with or without the leading `?`.
+* @returns The query string including a leading `?`, or `''` if empty.
+*/
+function stripRscCacheKey(search) {
+	const query = search.startsWith("?") ? search.slice(1) : search;
+	if (query === "") return "";
+	const result = query.split("&").filter((pair) => {
+		const eq = pair.indexOf("=");
+		if (formDecode(eq === -1 ? pair : pair.slice(0, eq)) !== "_rsc") return true;
+		return !isRscCacheKeyShape(eq === -1 ? "" : formDecode(pair.slice(eq + 1)));
+	}).join("&");
+	return result === "" ? "" : `?${result}`;
+}
+/**
+* The search state application code sees, for any request URL.
+*
+* The `_rsc` key rides on the payload URL of every RSC navigation and on no
+* other request, so reading search params straight off `req.url` makes the
+* same page observe different search state depending on whether it was
+* reached by a full load or a client navigation — and lets the cache key
+* leak into whatever the page builds from it: a canonical URL, a pagination
+* link, an analytics payload (TIM-1272).
+*
+* Every application-facing derivation of search state goes through here.
+* `params` and `search` are returned together, from one strip, because they
+* are two views of one answer and were previously two expressions that had
+* to agree.
+*
+* The raw request URL is deliberately untouched: `server/rsc-cache-key-guard.ts`
+* still reads the parameter from `req.url` to bind the key to the request.
+*/
+function appVisibleSearch(url) {
+	const search = stripRscCacheKey(url.search);
+	return {
+		params: new URLSearchParams(search),
+		search
+	};
+}
+/**
+* Compute the `_rsc` cache key for a request.
+*
+* Absent headers are omitted rather than sent as empty, so "header missing"
+* and "header present but empty" produce different keys.
+*
+* Values are length-prefixed rather than delimiter-separated. Any delimiter
+* can be forged by a value that contains it: with a `\0` separator, an
+* `accept` of `a\nx-timber-url\0b` serializes identically to an `accept` of
+* `a` alongside an `x-timber-url` of `b`, which would let one header claim
+* another's key. HTTP forbids control characters in header values and both
+* `fetch()` and the server runtime reject them, so this is defense in depth
+* — but a length prefix is unambiguous for *any* content, which is a
+* property worth having in a function whose whole job is to be agreed on by
+* two independent implementations.
+*
+* SHA-256, truncated to 128 bits. A fast non-cryptographic hash is the
+* obvious choice for a cache key and is the wrong one here: the origin
+* *compares* this value against a recomputed one, which makes it a check.
+* FNV-1a — used for timber's other cache keys — is a multiply-xor over a
+* fixed field, so an attacker controlling a few bytes of any input (their
+* own `X-Timber-URL`, say) can solve for a chosen digest rather than search
+* for one, and forge a key belonging to somebody else.
+*
+* Returns `null` when no digest is available — `crypto.subtle` is absent in
+* non-secure browsing contexts (plain `http://` on a LAN address). Callers
+* must treat that as "no key", never as "key matches": the client omits the
+* parameter and the server refuses to share-cache. That returns those
+* clients to the pre-TIM-1268 posture, where `Vary` alone separates HTML
+* from Flight — acceptable, because a non-secure origin has no shared-CDN
+* caching story to protect in the first place.
+*/
+async function rscCacheKey(lookup) {
+	const subtle = globalThis.crypto?.subtle;
+	if (!subtle) return null;
+	let canonical = "";
+	for (const name of RSC_KEY_HEADERS) {
+		const value = lookup(name);
+		if (value == null) continue;
+		canonical += `${name.toLowerCase()}:${value.length}:${value}`;
+	}
+	const digest = await subtle.digest("SHA-256", new TextEncoder().encode(canonical));
+	let hex = "";
+	for (const byte of new Uint8Array(digest, 0, KEY_HEX_LENGTH / 2)) hex += byte.toString(16).padStart(2, "0");
+	return KEY_PREFIX + hex;
+}
+/**
+* An unverifiable stand-in key, for the one case where the digest cannot be
+* computed: `crypto.subtle` is absent in non-secure browsing contexts.
+* `crypto.getRandomValues` is not gated that way, so it is available exactly
+* where the digest is not.
+*
+* Carries `KEY_PREFIX` like any other key, so the origin reads it as a claim
+* it cannot verify — and refuses to share-cache the response — rather than
+* exempting it as application data. Lives here so the prefix has one home.
+*/
+function randomRscCacheKey() {
+	const bytes = new Uint8Array(KEY_HEX_LENGTH / 2);
+	globalThis.crypto.getRandomValues(bytes);
+	return KEY_PREFIX + [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** Build a case-insensitive lookup over a plain header record. */
+function recordLookup(headers) {
+	const lowered = {};
+	for (const name of Object.keys(headers)) lowered[name.toLowerCase()] = headers[name];
+	return (name) => lowered[name.toLowerCase()];
+}
+//#endregion
+export { randomRscCacheKey as a, stripRscCacheKey as c, isRscCacheKeyShape as i, RSC_KEY_PARAM as n, recordLookup as o, appVisibleSearch as r, rscCacheKey as s, RSC_KEY_HEADERS as t };
+
+//# sourceMappingURL=rsc-cache-key-ClUiXQnK.js.map

package/dist/_chunks/rsc-cache-key-ClUiXQnK.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsc-cache-key-ClUiXQnK.js","names":[],"sources":["../../src/shared/rsc-cache-key.ts"],"sourcesContent":["/**\n * The `_rsc` payload cache key — derived identically on both sides.\n *\n * The client puts this in the payload URL so the document and its Flight\n * payload occupy different cache keys (TIM-1268). The server recomputes it\n * from the received headers so a request cannot claim one client's key while\n * sending another client's headers — see `server/rsc-cache-key-guard.ts`.\n * Both sides must agree exactly, which is why the derivation lives here and\n * not in either one.\n *\n * Isomorphic: no server or client imports. The browser bundle audit\n * (`tests/client-bundle-audit.test.ts`) enforces the client half of that.\n *\n * See design/19-client-navigation.md §\"The `_rsc` cache key\".\n */\n\n/**\n * Digest length in hex characters. 128 bits: the origin guard compares a\n * caller-supplied key against a recomputed one, so the relevant bound is a\n * birthday attack (an attacker who can influence a victim's `X-Timber-URL`\n * gets to search both sides), not second preimage. 64 bits would fall to\n * ~2^32 work; 128 puts it at 2^64.\n */\nconst KEY_HEX_LENGTH = 32;\n\n/**\n * Marks a value as a framework-issued key, and versions the derivation.\n *\n * Without it, an application value that happened to be 32 lowercase hex — an\n * MD5, a token — is indistinguishable from a forged claim: both are \"the\n * right shape, the wrong digest\", and no information in the value separates\n * them. So the exemption cannot key on shape alone.\n *\n * The prefix resolves that because it is anchored to the address the\n * victim's own client uses. A payload lives at `?_rsc=1.<digest>`, so\n * anything aimed at that cache entry must carry the prefix and therefore\n * gets validated; anything without it cannot be addressing a payload URL at\n * all, and is exempt as application data. An attacker cannot both hit the\n * victim's cache key and dodge the check.\n *\n * The version component also gives the derivation a migration path: the\n * client and the origin must agree byte for byte, so a future change to the\n * canonical form can be rolled out by bumping this instead of a flag day.\n */\nconst KEY_PREFIX = '1.';\n\n/**\n * The request headers that vary an RSC payload response, in canonical\n * casing — this list is also emitted verbatim as the response's `Vary`\n * tokens (`server/pipeline.ts`), since \"what varies the response\" is one\n * question with one answer, not two lists that happen to agree.\n *\n * This list is the contract, and it is enforced rather than trusted:\n * `tests/rsc-cache-key.test.ts` asserts that the header names\n * `buildRscHeaders()` can emit are exactly this set. A header added to the\n * request without being added here fails that test, because a varying input\n * outside the key is precisely the cache-poisoning hazard the key exists to\n * close.\n *\n * **No credentials, session identifiers, or user-supplied content may be\n * added.** Every value here is hashed into a URL, and URLs are logged by\n * proxies, CDNs, and origin access logs. `fnv1aHash` is a cache-key hash,\n * not a KDF — a low-entropy secret would be recoverable by brute force.\n * Authentication travels on cookies, which never enter the key.\n */\nexport const RSC_KEY_HEADERS = [\n  'Accept',\n  'X-Timber-State-Tree',\n  'X-Timber-URL',\n  'X-Timber-Deployment-Id',\n] as const;\n\n/**\n * Whether a value could be a key this module produced.\n *\n * `_rsc` is not a reserved parameter name — an application may already use\n * it for its own search state, including for a value that happens to look\n * like a digest. Anything without the `KEY_PREFIX` is therefore application\n * data, not a claim on a payload cache key, and the origin guard leaves it\n * alone rather than penalizing the response.\n *\n * Derived from `KEY_PREFIX` and `KEY_HEX_LENGTH` rather than spelled again,\n * so the shape cannot drift from the digest that has to satisfy it.\n *\n * Ignoring a malformed value costs no protection: clients only ever send\n * well-formed keys, so a URL bearing a malformed one is an address no\n * legitimate request will ever ask for, and nothing can be poisoned at an\n * address nobody reads.\n */\nexport function isRscCacheKeyShape(value: string): boolean {\n  if (!value.startsWith(KEY_PREFIX)) return false;\n  const digest = value.slice(KEY_PREFIX.length);\n  return digest.length === KEY_HEX_LENGTH && /^[0-9a-f]+$/.test(digest);\n}\n\n/**\n * The query parameter carrying the payload cache key.\n *\n * Spelled here rather than at each of the four places that read or write it\n * — the client that appends it, the origin guard that validates it, and the\n * strip below — because it is a wire contract between two independent\n * implementations, exactly like the digest itself.\n */\nexport const RSC_KEY_PARAM = '_rsc';\n\n// ─── Keeping the key out of application state ────────────────────────────\n\n/**\n * Decode one raw `name` or `value` the way `URLSearchParams` does:\n * `application/x-www-form-urlencoded`, so `+` is a space.\n *\n * Malformed percent-escapes throw in `decodeURIComponent`. `URLSearchParams`\n * leaves those bytes as-is rather than throwing, and so do we — a pair we\n * cannot decode is by definition not the framework's, so it is kept.\n */\nfunction formDecode(raw: string): string {\n  try {\n    return decodeURIComponent(raw.replace(/\\+/g, ' '));\n  } catch {\n    return raw;\n  }\n}\n\n/**\n * Remove framework-issued `_rsc` values from a raw query string.\n *\n * Only values matching `isRscCacheKeyShape` are removed. `_rsc` is not a\n * reserved name (see that function), so `/search?_rsc=foo` is application\n * state and survives — the same exemption the origin guard applies, derived\n * from the same predicate so the two cannot disagree about what \"ours\"\n * means.\n *\n * Operates on the raw string rather than round-tripping through\n * `URLSearchParams`, so every surviving pair keeps its original bytes.\n * Re-serializing would rewrite `?b` as `?b=` and `?a=%7E` as `?a=~` on RSC\n * navigations only, which is the same class of inconsistency this function\n * exists to remove.\n *\n * Matching decodes the name, because `?%5Frsc=<key>` is a `_rsc` parameter\n * as far as `URLSearchParams` is concerned — the same reasoning as the\n * guard's fast path.\n *\n * @param search - `url.search`, with or without the leading `?`.\n * @returns The query string including a leading `?`, or `''` if empty.\n */\nexport function stripRscCacheKey(search: string): string {\n  const query = search.startsWith('?') ? search.slice(1) : search;\n  if (query === '') return '';\n  const kept = query.split('&').filter((pair) => {\n    const eq = pair.indexOf('=');\n    if (formDecode(eq === -1 ? pair : pair.slice(0, eq)) !== RSC_KEY_PARAM) return true;\n    return !isRscCacheKeyShape(eq === -1 ? '' : formDecode(pair.slice(eq + 1)));\n  });\n  const result = kept.join('&');\n  return result === '' ? '' : `?${result}`;\n}\n\n/** A request's search state as application code should see it. */\nexport interface AppVisibleSearch {\n  /** Parsed params, with the framework's cache key removed. */\n  params: URLSearchParams;\n  /** The matching raw query string — `''` or `?…`. */\n  search: string;\n}\n\n/**\n * The search state application code sees, for any request URL.\n *\n * The `_rsc` key rides on the payload URL of every RSC navigation and on no\n * other request, so reading search params straight off `req.url` makes the\n * same page observe different search state depending on whether it was\n * reached by a full load or a client navigation — and lets the cache key\n * leak into whatever the page builds from it: a canonical URL, a pagination\n * link, an analytics payload (TIM-1272).\n *\n * Every application-facing derivation of search state goes through here.\n * `params` and `search` are returned together, from one strip, because they\n * are two views of one answer and were previously two expressions that had\n * to agree.\n *\n * The raw request URL is deliberately untouched: `server/rsc-cache-key-guard.ts`\n * still reads the parameter from `req.url` to bind the key to the request.\n */\nexport function appVisibleSearch(url: URL): AppVisibleSearch {\n  const search = stripRscCacheKey(url.search);\n  return { params: new URLSearchParams(search), search };\n}\n\n/**\n * Reads a header value by name. Must be case-insensitive — `Headers.get()`\n * already is, and `recordLookup` below makes a plain record so.\n */\nexport type HeaderLookup = (name: string) => string | null | undefined;\n\n/**\n * Compute the `_rsc` cache key for a request.\n *\n * Absent headers are omitted rather than sent as empty, so \"header missing\"\n * and \"header present but empty\" produce different keys.\n *\n * Values are length-prefixed rather than delimiter-separated. Any delimiter\n * can be forged by a value that contains it: with a `\\0` separator, an\n * `accept` of `a\\nx-timber-url\\0b` serializes identically to an `accept` of\n * `a` alongside an `x-timber-url` of `b`, which would let one header claim\n * another's key. HTTP forbids control characters in header values and both\n * `fetch()` and the server runtime reject them, so this is defense in depth\n * — but a length prefix is unambiguous for *any* content, which is a\n * property worth having in a function whose whole job is to be agreed on by\n * two independent implementations.\n *\n * SHA-256, truncated to 128 bits. A fast non-cryptographic hash is the\n * obvious choice for a cache key and is the wrong one here: the origin\n * *compares* this value against a recomputed one, which makes it a check.\n * FNV-1a — used for timber's other cache keys — is a multiply-xor over a\n * fixed field, so an attacker controlling a few bytes of any input (their\n * own `X-Timber-URL`, say) can solve for a chosen digest rather than search\n * for one, and forge a key belonging to somebody else.\n *\n * Returns `null` when no digest is available — `crypto.subtle` is absent in\n * non-secure browsing contexts (plain `http://` on a LAN address). Callers\n * must treat that as \"no key\", never as \"key matches\": the client omits the\n * parameter and the server refuses to share-cache. That returns those\n * clients to the pre-TIM-1268 posture, where `Vary` alone separates HTML\n * from Flight — acceptable, because a non-secure origin has no shared-CDN\n * caching story to protect in the first place.\n */\nexport async function rscCacheKey(lookup: HeaderLookup): Promise<string | null> {\n  const subtle = globalThis.crypto?.subtle;\n  if (!subtle) return null;\n  let canonical = '';\n  for (const name of RSC_KEY_HEADERS) {\n    const value = lookup(name);\n    if (value == null) continue;\n    // Lowercased in the canonical form so the two implementations cannot\n    // disagree over the casing of the constant they share.\n    canonical += `${name.toLowerCase()}:${value.length}:${value}`;\n  }\n  const digest = await subtle.digest('SHA-256', new TextEncoder().encode(canonical));\n  let hex = '';\n  for (const byte of new Uint8Array(digest, 0, KEY_HEX_LENGTH / 2)) {\n    hex += byte.toString(16).padStart(2, '0');\n  }\n  return KEY_PREFIX + hex;\n}\n\n/**\n * An unverifiable stand-in key, for the one case where the digest cannot be\n * computed: `crypto.subtle` is absent in non-secure browsing contexts.\n * `crypto.getRandomValues` is not gated that way, so it is available exactly\n * where the digest is not.\n *\n * Carries `KEY_PREFIX` like any other key, so the origin reads it as a claim\n * it cannot verify — and refuses to share-cache the response — rather than\n * exempting it as application data. Lives here so the prefix has one home.\n */\nexport function randomRscCacheKey(): string {\n  const bytes = new Uint8Array(KEY_HEX_LENGTH / 2);\n  globalThis.crypto.getRandomValues(bytes);\n  return KEY_PREFIX + [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('');\n}\n\n/** Build a case-insensitive lookup over a plain header record. */\nexport function recordLookup(headers: Record<string, string>): HeaderLookup {\n  const lowered: Record<string, string> = {};\n  for (const name of Object.keys(headers)) {\n    lowered[name.toLowerCase()] = headers[name];\n  }\n  return (name) => lowered[name.toLowerCase()];\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAuBA,IAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;AAqBvB,IAAM,aAAa;;;;;;;;;;;;;;;;;;;;AAqBnB,IAAa,kBAAkB;CAC7B;CACA;CACA;CACA;AACF;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,mBAAmB,OAAwB;CACzD,IAAI,CAAC,MAAM,WAAW,UAAU,GAAG,OAAO;CAC1C,MAAM,SAAS,MAAM,MAAM,CAAiB;CAC5C,OAAO,OAAO,WAAW,kBAAkB,cAAc,KAAK,MAAM;AACtE;;;;;;;;;AAUA,IAAa,gBAAgB;;;;;;;;;AAY7B,SAAS,WAAW,KAAqB;CACvC,IAAI;EACF,OAAO,mBAAmB,IAAI,QAAQ,OAAO,GAAG,CAAC;CACnD,QAAQ;EACN,OAAO;CACT;AACF;;;;;;;;;;;;;;;;;;;;;;;AAwBA,SAAgB,iBAAiB,QAAwB;CACvD,MAAM,QAAQ,OAAO,WAAW,GAAG,IAAI,OAAO,MAAM,CAAC,IAAI;CACzD,IAAI,UAAU,IAAI,OAAO;CAMzB,MAAM,SALO,MAAM,MAAM,GAAG,CAAC,CAAC,QAAQ,SAAS;EAC7C,MAAM,KAAK,KAAK,QAAQ,GAAG;EAC3B,IAAI,WAAW,OAAO,KAAK,OAAO,KAAK,MAAM,GAAG,EAAE,CAAC,MAAA,QAAqB,OAAO;EAC/E,OAAO,CAAC,mBAAmB,OAAO,KAAK,KAAK,WAAW,KAAK,MAAM,KAAK,CAAC,CAAC,CAAC;CAC5E,CACe,CAAA,CAAK,KAAK,GAAG;CAC5B,OAAO,WAAW,KAAK,KAAK,IAAI;AAClC;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,iBAAiB,KAA4B;CAC3D,MAAM,SAAS,iBAAiB,IAAI,MAAM;CAC1C,OAAO;EAAE,QAAQ,IAAI,gBAAgB,MAAM;EAAG;CAAO;AACvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,eAAsB,YAAY,QAA8C;CAC9E,MAAM,SAAS,WAAW,QAAQ;CAClC,IAAI,CAAC,QAAQ,OAAO;CACpB,IAAI,YAAY;CAChB,KAAK,MAAM,QAAQ,iBAAiB;EAClC,MAAM,QAAQ,OAAO,IAAI;EACzB,IAAI,SAAS,MAAM;EAGnB,aAAa,GAAG,KAAK,YAAY,EAAE,GAAG,MAAM,OAAO,GAAG;CACxD;CACA,MAAM,SAAS,MAAM,OAAO,OAAO,WAAW,IAAI,YAAY,CAAC,CAAC,OAAO,SAAS,CAAC;CACjF,IAAI,MAAM;CACV,KAAK,MAAM,QAAQ,IAAI,WAAW,QAAQ,GAAG,iBAAiB,CAAC,GAC7D,OAAO,KAAK,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG;CAE1C,OAAO,aAAa;AACtB;;;;;;;;;;;AAYA,SAAgB,oBAA4B;CAC1C,MAAM,QAAQ,IAAI,WAAW,iBAAiB,CAAC;CAC/C,WAAW,OAAO,gBAAgB,KAAK;CACvC,OAAO,aAAa,CAAC,GAAG,KAAK,CAAC,CAAC,KAAK,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE;AACpF;;AAGA,SAAgB,aAAa,SAA+C;CAC1E,MAAM,UAAkC,CAAC;CACzC,KAAK,MAAM,QAAQ,OAAO,KAAK,OAAO,GACpC,QAAQ,KAAK,YAAY,KAAK,QAAQ;CAExC,QAAQ,SAAS,QAAQ,KAAK,YAAY;AAC5C"}

package/dist/_chunks/rsc-media-type-DDc7duTD.js

@@ -0,0 +1,61 @@
+//#region src/shared/rsc-media-type.ts
+/**
+* The RSC Flight media type, and the request predicate over it.
+*
+* One module owns the string because two independently-written spellings of
+* "is this an RSC request?" must agree, and the consequence of them
+* disagreeing is cache poisoning rather than a visible bug. The Cloudflare
+* adapter's `isRsc` decides what may enter the edge cache; the origin's
+* pipeline decides which headers may vary the response. TIM-1269 made the
+* adapter's `VARY_HONORED` allowlist exempt `Accept` *because* `isRsc`
+* excludes Flight responses from the cache, and exempt the `X-Timber-*`
+* headers *because* the origin reads them only behind its own RSC check. If
+* one predicate is ever tightened (a real media-type parse, a
+* parameter-aware match) and the other is not, the adapter can classify a
+* request as a document while the origin treats it as RSC, and store a
+* Flight payload under the document's key — the class
+* `design/48-payload-addressing.md` exists to prevent.
+*
+* `tests/rsc-media-type-single-source.test.ts` fails if the literal reappears
+* in executable source outside this file.
+*
+* Isomorphic: zero imports, so `adapters/cloudflare.ts` — which Node's native
+* ESM loader evaluates before Vite's resolver exists — can load it and
+* interpolate the value into the generated worker. Same precedent as
+* `shared/rsc-cache-key.ts`.
+*
+* See design/19-client-navigation.md, design/25-production-deployments.md
+* §"`Vary` and the Workers Cache API".
+*/
+/** Media type of a React Flight payload. */
+var RSC_CONTENT_TYPE = "text/x-component";
+/**
+* Is this request asking for an RSC payload rather than a full document?
+*
+* Substring containment, deliberately: `Accept` is a list, and a client may
+* send `text/x-component;charset=utf-8` or list it alongside other types.
+* Tightening this to a real media-type parse is a behaviour change that has
+* to move the adapter's generated `isRsc` in the same commit — see above.
+*/
+function isRscRequest(req) {
+	return (req.headers.get("Accept") ?? "").includes(RSC_CONTENT_TYPE);
+}
+/**
+* Does this Content-Type header value designate an RSC Flight payload?
+*
+* Case-insensitive exact media-type match per RFC 9110 §8.3.1 — media types
+* are case-insensitive. Parameters (`;charset=utf-8`) are stripped before
+* comparison.
+*
+* Contrast with `isRscRequest`, which uses substring containment because
+* `Accept` is a list of types. A `Content-Type` header names exactly one
+* type, so substring would over-match (e.g. `text/x-component-v2`).
+*/
+function isRscContentType(contentType) {
+	if (!contentType) return false;
+	return contentType.split(";")[0].trim().toLowerCase() === RSC_CONTENT_TYPE;
+}
+//#endregion
+export { isRscContentType as n, isRscRequest as r, RSC_CONTENT_TYPE as t };
+
+//# sourceMappingURL=rsc-media-type-DDc7duTD.js.map

package/dist/_chunks/rsc-media-type-DDc7duTD.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsc-media-type-DDc7duTD.js","names":[],"sources":["../../src/shared/rsc-media-type.ts"],"sourcesContent":["/**\n * The RSC Flight media type, and the request predicate over it.\n *\n * One module owns the string because two independently-written spellings of\n * \"is this an RSC request?\" must agree, and the consequence of them\n * disagreeing is cache poisoning rather than a visible bug. The Cloudflare\n * adapter's `isRsc` decides what may enter the edge cache; the origin's\n * pipeline decides which headers may vary the response. TIM-1269 made the\n * adapter's `VARY_HONORED` allowlist exempt `Accept` *because* `isRsc`\n * excludes Flight responses from the cache, and exempt the `X-Timber-*`\n * headers *because* the origin reads them only behind its own RSC check. If\n * one predicate is ever tightened (a real media-type parse, a\n * parameter-aware match) and the other is not, the adapter can classify a\n * request as a document while the origin treats it as RSC, and store a\n * Flight payload under the document's key — the class\n * `design/48-payload-addressing.md` exists to prevent.\n *\n * `tests/rsc-media-type-single-source.test.ts` fails if the literal reappears\n * in executable source outside this file.\n *\n * Isomorphic: zero imports, so `adapters/cloudflare.ts` — which Node's native\n * ESM loader evaluates before Vite's resolver exists — can load it and\n * interpolate the value into the generated worker. Same precedent as\n * `shared/rsc-cache-key.ts`.\n *\n * See design/19-client-navigation.md, design/25-production-deployments.md\n * §\"`Vary` and the Workers Cache API\".\n */\n\n/** Media type of a React Flight payload. */\nexport const RSC_CONTENT_TYPE = 'text/x-component';\n\n/**\n * Is this request asking for an RSC payload rather than a full document?\n *\n * Substring containment, deliberately: `Accept` is a list, and a client may\n * send `text/x-component;charset=utf-8` or list it alongside other types.\n * Tightening this to a real media-type parse is a behaviour change that has\n * to move the adapter's generated `isRsc` in the same commit — see above.\n */\nexport function isRscRequest(req: Request): boolean {\n  return (req.headers.get('Accept') ?? '').includes(RSC_CONTENT_TYPE);\n}\n\n/**\n * Does this Content-Type header value designate an RSC Flight payload?\n *\n * Case-insensitive exact media-type match per RFC 9110 §8.3.1 — media types\n * are case-insensitive. Parameters (`;charset=utf-8`) are stripped before\n * comparison.\n *\n * Contrast with `isRscRequest`, which uses substring containment because\n * `Accept` is a list of types. A `Content-Type` header names exactly one\n * type, so substring would over-match (e.g. `text/x-component-v2`).\n */\nexport function isRscContentType(contentType: string | null): boolean {\n  if (!contentType) return false;\n  return contentType.split(';')[0].trim().toLowerCase() === RSC_CONTENT_TYPE;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,IAAa,mBAAmB;;;;;;;;;AAUhC,SAAgB,aAAa,KAAuB;CAClD,QAAQ,IAAI,QAAQ,IAAI,QAAQ,KAAK,GAAA,CAAI,SAAS,gBAAgB;AACpE;;;;;;;;;;;;AAaA,SAAgB,iBAAiB,aAAqC;CACpE,IAAI,CAAC,aAAa,OAAO;CACzB,OAAO,YAAY,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,YAAY,MAAM;AAC5D"}

package/dist/_chunks/rsc-payload-path-B_LBodc2.js

@@ -0,0 +1,48 @@
+//#region src/shared/rsc-payload-path.ts
+/**
+* Where a route's Flight payload lives in `output: 'static'`.
+*
+* The static build writes these files and the client fetches them, so the two
+* halves must agree byte for byte. They used to state the naming rule
+* separately — `plugins/static-build.ts` for the write and
+* `client/rsc-fetch.ts` for the read — which is a duplicate representation with
+* nothing checking it. One function now, called by both.
+*
+* ## The shape
+*
+* The payload path mirrors the HTML path: every route gets a directory and the
+* artifact is the `index` inside it.
+*
+*   /           → /_rsc/index.rsc          (cf. index.html)
+*   /about      → /_rsc/about/index.rsc    (cf. about/index.html)
+*   /blog/hello → /_rsc/blog/hello/index.rsc
+*
+* That shape is **injective**, which the previous one (`/about` →
+* `/_rsc/about.rsc`, root → `/_rsc/index.rsc`) was not: a site with both `/`
+* and `/index` produced two payloads at `_rsc/index.rsc`, and the second write
+* won silently — a client navigation to one route was served the other route's
+* payload, same content type and same shape, undetectable downstream
+* (TIM-1266).
+*
+* Injectivity holds because two distinct non-root routes give distinct
+* directories, and the root's `/_rsc/index.rsc` has no directory component for
+* a non-root route to occupy — reaching it would need an empty route path,
+* which is not a route.
+*
+* Isomorphic: no server, client, or build-time imports.
+*/
+/**
+* The route-space path of a route's static Flight payload.
+*
+* @param routePath A route-space pathname: leading slash, no deployment base,
+*   no query or fragment, no trailing slash (except the root `/`). Callers
+*   normalize; this function does not, because the two callers normalize from
+*   different sources (a browser URL, a build-time route entry).
+*/
+function rscPayloadPath(routePath) {
+	return `/_rsc${routePath === "/" ? "" : routePath}/index.rsc`;
+}
+//#endregion
+export { rscPayloadPath as t };
+
+//# sourceMappingURL=rsc-payload-path-B_LBodc2.js.map

package/dist/_chunks/rsc-payload-path-B_LBodc2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsc-payload-path-B_LBodc2.js","names":[],"sources":["../../src/shared/rsc-payload-path.ts"],"sourcesContent":["/**\n * Where a route's Flight payload lives in `output: 'static'`.\n *\n * The static build writes these files and the client fetches them, so the two\n * halves must agree byte for byte. They used to state the naming rule\n * separately — `plugins/static-build.ts` for the write and\n * `client/rsc-fetch.ts` for the read — which is a duplicate representation with\n * nothing checking it. One function now, called by both.\n *\n * ## The shape\n *\n * The payload path mirrors the HTML path: every route gets a directory and the\n * artifact is the `index` inside it.\n *\n *   /           → /_rsc/index.rsc          (cf. index.html)\n *   /about      → /_rsc/about/index.rsc    (cf. about/index.html)\n *   /blog/hello → /_rsc/blog/hello/index.rsc\n *\n * That shape is **injective**, which the previous one (`/about` →\n * `/_rsc/about.rsc`, root → `/_rsc/index.rsc`) was not: a site with both `/`\n * and `/index` produced two payloads at `_rsc/index.rsc`, and the second write\n * won silently — a client navigation to one route was served the other route's\n * payload, same content type and same shape, undetectable downstream\n * (TIM-1266).\n *\n * Injectivity holds because two distinct non-root routes give distinct\n * directories, and the root's `/_rsc/index.rsc` has no directory component for\n * a non-root route to occupy — reaching it would need an empty route path,\n * which is not a route.\n *\n * Isomorphic: no server, client, or build-time imports.\n */\n\n/**\n * The route-space path of a route's static Flight payload.\n *\n * @param routePath A route-space pathname: leading slash, no deployment base,\n *   no query or fragment, no trailing slash (except the root `/`). Callers\n *   normalize; this function does not, because the two callers normalize from\n *   different sources (a browser URL, a build-time route entry).\n */\nexport function rscPayloadPath(routePath: string): string {\n  const prefix = routePath === '/' ? '' : routePath;\n  return `/_rsc${prefix}/index.rsc`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,SAAgB,eAAe,WAA2B;CAExD,OAAO,QADQ,cAAc,MAAM,KAAK,UAClB;AACxB"}