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

package/src/shared/rsc-error-envelope.ts

@@ -0,0 +1,31 @@
+/**
+ * The hard-navigate error envelope shared by the server and the client router.
+ *
+ * A client-navigation (RSC) request cannot carry an error *page* — the response
+ * body must be Flight data or the decoder crashes. Instead the server answers
+ * with this envelope: an `X-Timber-Error: 1` header and a minimal JSON body.
+ * The client treats it as "give up on SPA navigation and hard-navigate", and
+ * the resulting document request renders the real error page as HTML.
+ *
+ * The header name lives here so the four server producers and the single
+ * client consumer cannot drift apart. See design/10-error-handling.md
+ * §"Error Page Rendering for Client Navigation".
+ */
+
+/** Header the client checks to decide whether to hard-navigate. */
+export const TIMBER_ERROR_HEADER = 'X-Timber-Error';
+
+/**
+ * Build the hard-navigate envelope for a status code.
+ *
+ * `responseHeaders` carries anything middleware already set (cookies, cache
+ * directives); the content type and error header are overwritten because the
+ * body is always this envelope. The body deliberately carries no message —
+ * only the status already on the wire (design/13-security.md principle 4).
+ */
+export function rscErrorEnvelope(status: number, responseHeaders?: Headers): Response {
+  const headers = responseHeaders ?? new Headers();
+  headers.set(TIMBER_ERROR_HEADER, '1');
+  headers.set('content-type', 'application/json; charset=utf-8');
+  return new Response(JSON.stringify({ error: true, status }), { status, headers });
+}

package/src/shared/rsc-manifest.ts

@@ -0,0 +1,29 @@
+/**
+ * The RSC manifest — the shape the static build writes and the client reads.
+ *
+ * In `output: 'static'` there is no server at navigation time and a generated
+ * `.rsc` file carries no response headers, so anything a navigation would
+ * normally learn from headers has to be inlined here at build time.
+ *
+ * Route params used to be such a thing (TIM-1255, TIM-1285). They are not any
+ * more: they ride inside the payload, on its root row, so the
+ * `.rsc` file carries them the same way it carries the tree, and the static
+ * path stopped needing a special case (TIM-1294). What is left is the content
+ * hash, which genuinely cannot live inside the file it names.
+ *
+ * Declared once rather than in each half. The producer
+ * (`plugins/static-build.ts`) and the consumer (`client/rsc-fetch.ts`) each
+ * had their own copy, and the copies drifted the moment a field was added to
+ * one — a static SPA navigation then committed `null` for the field the
+ * producer was faithfully writing.
+ *
+ * Isomorphic: no server, client, or build-time imports.
+ */
+
+export interface RscManifestEntry {
+  /** The content-hashed URL the payload actually lives at, in route space. */
+  url: string;
+}
+
+/** Keyed by the unhashed `/_rsc/*.rsc` path. */
+export type RscManifest = Record<string, RscManifestEntry>;

package/src/shared/rsc-payload-path.ts

@@ -0,0 +1,45 @@
+/**
+ * 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).
+ */
+export function rscPayloadPath(routePath: string): string {
+  const prefix = routePath === '/' ? '' : routePath;
+  return `/_rsc${prefix}/index.rsc`;
+}

package/src/shared/segment-info.ts

@@ -0,0 +1,60 @@
+/**
+ * The segment metadata wire contract between server and client.
+ *
+ * One declaration, imported by both ends. The producer
+ * (`server/rsc-entry/helpers.ts` → `X-Timber-Segments` and the
+ * `self.__timber_segments` bootstrap script) and the consumers
+ * (`client/segment-cache.ts`, the history stack, the prefetch cache) used to
+ * declare this shape separately, which is how a field gets added to one side
+ * only.
+ *
+ * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+ * See design/07-routing.md §"Intercepting Routes"
+ */
+
+/**
+ * Metadata for one rendered segment or slot, sent via `X-Timber-Segments`.
+ */
+export interface SegmentInfo {
+  /** The segment's URL path (e.g. `/`, `/feed`), or the slot key for slots. */
+  path: string;
+  /** Outlet key — includes route group name when applicable (e.g. `/(marketing)`). */
+  segmentId?: string;
+  /**
+   * The segment's directory path in `app/`, groups included and slots elided
+   * (e.g. `app/(browse)/feed` → `/(browse)/feed`). Absent on slot entries.
+   *
+   * This is the identity interception scoping compares against, and it is the
+   * reason it travels: `path`/`segmentId` are URL-addressed and collapse
+   * `(browse)/feed` and `(landing)/feed` to the same key, while a scope has to
+   * tell those two directories apart. See `computeSegmentTreePaths`.
+   */
+  treePath?: string;
+  isRequestDependent: boolean;
+  /** True for parallel route slot entries, keyed by slot path (e.g. `/@sidebar`). */
+  slot?: boolean;
+  /** Parent segment path for slot entries — attaches the slot to its SegmentNode. */
+  parentSegment?: string;
+  /** True when the slot's access.ts denied on this render. Denied slots are excluded from the state tree. */
+  denied?: boolean;
+  /** True when the slot was skipped (cached content reused). Payloads with skipped slots are not replayable. */
+  skipped?: boolean;
+}
+
+/**
+ * The client's `X-Timber-State-Tree` request header.
+ *
+ * `segments` and `slots` are a caching optimization — they tell the server what
+ * the client can reuse. `treePaths` is not: it describes the *shape* of the
+ * tree currently on screen, so the server can answer "does the rendered route
+ * pass through the segment that owns this intercepting slot?" without
+ * re-deriving it from the address bar, which stops being the source route the
+ * moment a modal is open (TIM-1282).
+ *
+ * None of the three is a security input. Every `access.ts` runs regardless.
+ */
+export interface StateTree {
+  segments: string[];
+  slots?: string[];
+  treePaths?: string[];
+}

package/src/shared/slot-params.ts

@@ -0,0 +1,111 @@
+/**
+ * Per-slot segment params — the one definition both halves of the API read.
+ *
+ * A parallel slot matches the URL through its *own* sub-tree, so it can derive
+ * a param the main route never had, or derive the same name with a different
+ * type (`[...year]` → `string[]` where the main route's `[year]` gave
+ * `string`). The server answers `getSegmentParams(slotPath)` from a per-slot
+ * map; the client answers `useSegmentParams(slotPath)` from the same map,
+ * published on the RSC payload (TIM-1285).
+ *
+ * The merge lives here rather than in either half because the two must agree
+ * about what "the slot's params" are — a divergence is invisible until
+ * somebody reads a param of the wrong type, which is exactly the class of bug
+ * this module closes.
+ *
+ * Isomorphic: no server or client imports.
+ *
+ * See design/41-global-params.md §"Params in a parallel slot".
+ */
+
+/** Slot tree path → that slot's own coerced params. */
+export type SlotParamsRecord = Record<string, Record<string, string | string[]>>;
+
+/**
+ * The params a slot sees: the main route's as a base, the slot's own on top.
+ *
+ * Params from segments *above* the slot are not re-derived by the slot's own
+ * chain, so they have to come from the main route; params the slot does
+ * re-derive may have a different type than the main route gave them, so the
+ * slot's win.
+ *
+ * Null-prototype, like every other param record the framework hands out
+ * (`coerceSegmentParams` installs one unconditionally). A spread literal would
+ * inherit `Object.prototype`, so a lookup for a param the route does not
+ * define would resolve to an inherited member — `params.constructor` returning
+ * a function instead of `undefined` — in the one param record that was built
+ * by merging. See design/13-security.md #36c.
+ */
+export function mergeSlotParams(
+  mainParams: Record<string, string | string[]>,
+  slotParams: Record<string, string | string[]>
+): Record<string, string | string[]> {
+  return Object.assign(Object.create(null), mainParams, slotParams);
+}
+
+/**
+ * Resolve the params for a segment path against a published slot map.
+ *
+ * Returns the merge when `segmentPath` names a slot that published params,
+ * and the main route's record otherwise — an ordinary (non-slot) segment
+ * path, an unknown path, or a request with no slots at all. Mirrors the
+ * server's `getSegmentParams(segmentPath)` branch exactly.
+ *
+ * `Object.hasOwn` rather than `in` or a truthiness test: the map arrives from
+ * JSON, so a segment path of `constructor` or `toString` would otherwise
+ * resolve to an inherited member of `Object.prototype`.
+ */
+export function resolveSegmentParams(
+  mainParams: Record<string, string | string[]>,
+  slotParams: SlotParamsRecord | null | undefined,
+  segmentPath: string | undefined
+): Record<string, string | string[]> {
+  if (!segmentPath || !slotParams || !Object.hasOwn(slotParams, segmentPath)) return mainParams;
+  return cachedMerge(mainParams, slotParams, segmentPath);
+}
+
+/**
+ * The merged record for one (main record, slot map, path) triple, reused until
+ * one of the three changes.
+ *
+ * `useSegmentParams(slotPath)` calls this on every render. Returning a fresh
+ * object each time makes the hook's result change by reference on renders where
+ * nothing navigated, so a component using it as a `useEffect` dependency
+ * re-runs the effect — and re-renders in a loop if that effect sets state —
+ * while memoized children below it lose their memoization.
+ *
+ * Keyed on the *identities* of the two records, not their contents: both are
+ * replaced rather than mutated on every navigation (`setCurrentParams`,
+ * `setCurrentSlotParams`, and the server's per-request store), so identity is
+ * the correct equality here and a deep comparison would be slower and no more
+ * accurate.
+ *
+ * A `WeakMap` chain rather than a `Map`, so a superseded navigation's records
+ * and their merges become collectable as soon as nothing else holds them.
+ */
+const mergeCache = new WeakMap<
+  object,
+  WeakMap<object, Map<string, Record<string, string | string[]>>>
+>();
+
+function cachedMerge(
+  mainParams: Record<string, string | string[]>,
+  slotParams: SlotParamsRecord,
+  segmentPath: string
+): Record<string, string | string[]> {
+  let bySlotMap = mergeCache.get(mainParams);
+  if (!bySlotMap) {
+    bySlotMap = new WeakMap();
+    mergeCache.set(mainParams, bySlotMap);
+  }
+  let byPath = bySlotMap.get(slotParams);
+  if (!byPath) {
+    byPath = new Map();
+    bySlotMap.set(slotParams, byPath);
+  }
+  const cached = byPath.get(segmentPath);
+  if (cached) return cached;
+  const merged = mergeSlotParams(mainParams, slotParams[segmentPath]);
+  byPath.set(segmentPath, merged);
+  return merged;
+}

package/src/shared/static-platform-files.ts

@@ -0,0 +1,75 @@
+/**
+ * Platform files the static build is allowed to overwrite in the output.
+ *
+ * The build merges two trees into the deployed directory — the client bundle
+ * (which carries everything the user put in `public/`) and the pre-rendered
+ * site. That merge otherwise refuses overlaps, because a silent overwrite
+ * leaves one of two artifacts deployed with nothing recording which
+ * (TIM-1266).
+ *
+ * These names are the exception, and only because the pre-rendered copy is
+ * *derived from* the one it replaces rather than competing with it:
+ * `plugins/static-build.ts` reads `public/_redirects` and writes the
+ * generated rules plus the user's, so the winner is a superset of the loser.
+ *
+ * That holds only for a file the current pass produced, which is why
+ * `cleanConditionalArtifacts` deletes a previous build's `_redirects` before
+ * generation: written only when a pass finds redirects, it would otherwise
+ * survive into a pass that produced nothing and claim an exemption it no
+ * longer earns.
+ *
+ * `_headers` is NOT here. It is not written into the pre-rendered tree at
+ * all — adapters generate it directly into the output, folding in the
+ * user's copy as they go (TIM-1326).
+ *
+ * Declared once so the code that performs the merge and the code that
+ * produces the merged file cannot disagree about which names are exempt.
+ *
+ * Isomorphic: no server, client, or build-time imports.
+ */
+
+/** Platform redirect rules (Cloudflare Pages, Netlify). See TIM-1245/TIM-1249. */
+export const REDIRECTS_FILE = '_redirects';
+
+/** Platform header rules (Cloudflare Pages, Netlify). See TIM-1241/TIM-1326. */
+export const HEADERS_FILE = '_headers';
+
+/**
+ * Where a user authors platform files. Stated once because two modules read
+ * from here — `plugins/static-build.ts` for `_redirects`, adapters for
+ * `_headers` — and they must look in the same place.
+ *
+ * Both read the **project source**, never the build output. The generated
+ * file lands under the same name in the output directory, so a reader aimed
+ * there would fold the previous build's generated rules back in and compound
+ * them on every rebuild.
+ */
+export const USER_PLATFORM_DIR = 'public';
+
+/** Output-relative paths whose pre-rendered copy subsumes the `public/` one. */
+export const USER_MERGED_PLATFORM_FILES: readonly string[] = [REDIRECTS_FILE];
+
+/**
+ * Output paths the framework writes itself, which no route may claim.
+ *
+ * These are written outside the per-entry writer — `_redirects` after
+ * generation, `_headers` by the adapter after the copy — so the collision
+ * tracker never sees them and a route rendering to one of these paths is
+ * overwritten with nothing recording it.
+ *
+ * Reserved rather than tracked, because there is no version of "serve a route
+ * at `/_headers`" that works: Cloudflare Pages and Netlify read these two
+ * files themselves and never serve them, so the route is unservable however
+ * the conflict is resolved.
+ *
+ * That justification is per-file, not per-mechanism. `.nojekyll` is written
+ * the same way and is deliberately NOT here: only the `github-pages` target
+ * writes it, and everywhere else `/.nojekyll` is an ordinary servable path,
+ * so reserving it globally would refuse a valid Cloudflare site. Its write
+ * site skips the write when a file is already there instead — GitHub Pages
+ * only cares that the file exists.
+ *
+ * Same reasoning as the synthetic 404 entry using an internal urlPath so a
+ * real `/404` route cannot collide with `404.html`.
+ */
+export const RESERVED_OUTPUT_PATHS: readonly string[] = [REDIRECTS_FILE, HEADERS_FILE];

package/dist/_chunks/build-output-helper-DOGYFb_X.js

@@ -1,196 +0,0 @@
-import { basename, join, relative } from "node:path";
-import { cp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
-//#region src/adapters/shared.ts
-/** Cache-Control value for hashed (immutable) assets. */
-var IMMUTABLE_CACHE = "public, max-age=31536000, immutable";
-/** Cache-Control value for unhashed static assets. */
-var STATIC_CACHE = "public, max-age=3600, must-revalidate";
-/**
-* Generate a `_headers` file for static asset cache control.
-*
-* The `_headers` file is a platform convention supported by Cloudflare Workers
-* Static Assets, Cloudflare Pages, and Netlify. It maps URL patterns to
-* HTTP response headers.
-*
-* Only hashed (immutable) asset paths are listed here by default. When
-* `unhashedPaths` is provided, per-file rules are appended for unhashed
-* static assets (favicon.ico, robots.txt, etc.) so they get Cache-Control
-* on platforms like Cloudflare Workers Static Assets where the server
-* handler never sees static file requests.
-*
-* A `/*` catch-all is NOT used — it would be additive on Cloudflare,
-* producing duplicate Cache-Control directives on hashed assets
-* (invalid per RFC 9111).
-*/
-var MAX_PER_FILE_RULES = 97;
-function generateHeadersFile(unhashedPaths, contentTypes) {
-	let content = `# Auto-generated by @timber-js/app — static asset cache headers.
-# See design/25-production-deployments.md §"CDN / Edge Cache"
-
-/assets/*
-  Cache-Control: ${IMMUTABLE_CACHE}
-
-/_timber/fonts/*
-  Cache-Control: ${IMMUTABLE_CACHE}
-
-/_rsc/*
-  Cache-Control: ${IMMUTABLE_CACHE}
-`;
-	const allCtEntries = contentTypes ? Object.entries(contentTypes).sort(([a], [b]) => a.localeCompare(b)) : [];
-	const ctEntries = allCtEntries.slice(0, MAX_PER_FILE_RULES);
-	if (allCtEntries.length > MAX_PER_FILE_RULES) console.warn(`[timber] _headers: ${allCtEntries.length} content-type rules exceed Cloudflare's 100-rule limit. Only the first ${MAX_PER_FILE_RULES} extensionless API routes will get Content-Type headers.`);
-	const remainingBudget = MAX_PER_FILE_RULES - ctEntries.length;
-	if (unhashedPaths && unhashedPaths.length > 0) {
-		const capped = unhashedPaths.slice(0, Math.max(0, remainingBudget));
-		if (unhashedPaths.length > remainingBudget) console.warn(`[timber] _headers: ${unhashedPaths.length} unhashed static files + ${ctEntries.length} content-type rules found, but Cloudflare limits _headers to 100 rules. Only the first ${capped.length} unhashed files will get Cache-Control headers.`);
-		if (capped.length > 0) {
-			content += `\n# Unhashed static assets — short-lived cache with revalidation\n`;
-			for (const p of capped) content += `\n${p}\n  Cache-Control: ${STATIC_CACHE}\n`;
-		}
-	}
-	if (ctEntries.length > 0) {
-		content += `\n# Content-Type for extensionless API routes\n`;
-		for (const [urlPath, ct] of ctEntries) content += `\n${urlPath}\n  Content-Type: ${ct}\n`;
-	}
-	return content;
-}
-//#endregion
-//#region src/adapters/build-output-helper.ts
-/**
-* Run the platform-agnostic build output steps shared by all adapters:
-*
-* 1. Create the output directory
-* 2. Copy client assets to the public/static directory
-* 3. Write the `_headers` file for static asset cache control
-* 4. Copy RSC and SSR server bundles into the output directory
-* 5. Write the manifest-init module if present
-*
-* Returns the resolved public directory path for further adapter-specific use.
-*/
-async function runSharedBuildSteps(opts) {
-	const { config, buildDir, outDir, publicDirName } = opts;
-	await mkdir(outDir, { recursive: true });
-	const clientDir = join(buildDir, "client");
-	const publicDir = join(outDir, publicDirName);
-	await mkdir(publicDir, { recursive: true });
-	const referencedWasm = await findReferencedWasm(clientDir);
-	await cp(clientDir, publicDir, {
-		recursive: true,
-		filter: (src) => {
-			if (src.endsWith(".wasm") && !referencedWasm.has(basename(src))) return false;
-			if (config.clientJavascriptDisabled && src.endsWith(".js")) return false;
-			return true;
-		}
-	}).catch((e) => {
-		if (e.code !== "ENOENT") throw e;
-	});
-	const unhashedPaths = await findUnhashedStaticFiles(publicDir);
-	await writeFile(join(publicDir, "_headers"), generateHeadersFile(unhashedPaths));
-	await cp(join(buildDir, "rsc"), join(outDir, "rsc"), { recursive: true });
-	await cp(join(buildDir, "ssr"), join(outDir, "ssr"), { recursive: true }).catch((e) => {
-		if (e.code !== "ENOENT") throw e;
-	});
-	await cp(join(buildDir, "prebuilt"), join(outDir, "prebuilt"), { recursive: true }).catch((e) => {
-		if (e.code !== "ENOENT") throw e;
-	});
-	if (config.manifestInit) await writeFile(join(outDir, "_timber-manifest-init.js"), config.manifestInit);
-	return publicDir;
-}
-/**
-* Find unhashed static files in the public directory that need per-file
-* Cache-Control rules in the `_headers` file.
-*
-* Excludes:
-* - Files under `assets/` and `_timber/` (covered by wildcard rules)
-* - Underscore-prefixed files (`_headers`, `_worker.js`, etc.)
-*
-* @internal Exported for testing.
-*/
-var PRIORITY_FILES = /* @__PURE__ */ new Set([
-	"/favicon.ico",
-	"/robots.txt",
-	"/sitemap.xml",
-	"/manifest.json",
-	"/manifest.webmanifest",
-	"/apple-touch-icon.png"
-]);
-async function findUnhashedStaticFiles(publicDir) {
-	let files;
-	try {
-		files = await collectFiles(publicDir);
-	} catch {
-		return [];
-	}
-	const priority = [];
-	const rest = [];
-	for (const file of files) {
-		const rel = relative(publicDir, file).replace(/\\/g, "/");
-		if (rel.startsWith("assets/") || rel.startsWith("_timber/")) continue;
-		if (rel.startsWith("rsc/") || rel.startsWith("ssr/") || rel.startsWith("_rsc/")) continue;
-		if (basename(rel).startsWith("_")) continue;
-		const urlPath = "/" + rel;
-		if (PRIORITY_FILES.has(urlPath)) priority.push(urlPath);
-		else rest.push(urlPath);
-	}
-	return [...priority.sort(), ...rest.sort()];
-}
-/**
-* Scan client JS files for references to .wasm filenames.
-* Returns the set of WASM basenames that are actually imported/referenced
-* by client code and must be preserved in the static output.
-*/
-async function findReferencedWasm(clientDir) {
-	const referenced = /* @__PURE__ */ new Set();
-	let files;
-	try {
-		files = await collectFiles(clientDir);
-	} catch {
-		return referenced;
-	}
-	const jsFiles = files.filter((f) => f.endsWith(".js"));
-	const wasmFiles = files.filter((f) => f.endsWith(".wasm")).map((f) => basename(f));
-	if (wasmFiles.length === 0) return referenced;
-	for (const jsFile of jsFiles) {
-		const content = await readFile(jsFile, "utf-8");
-		for (const wasmName of wasmFiles) if (content.includes(wasmName)) referenced.add(wasmName);
-	}
-	return referenced;
-}
-/**
-* Build a static-only output directory (no server entry). Copies client
-* assets and pre-rendered HTML/RSC/API files into `outDir/publicDirName`.
-* Used by both Cloudflare and Nitro adapters in `output: 'static'` mode.
-*/
-async function buildStaticDirectoryOutput(config, buildDir, outDir, publicDirName) {
-	await rm(outDir, {
-		recursive: true,
-		force: true
-	}).catch(() => {});
-	await mkdir(outDir, { recursive: true });
-	const publicDir = join(outDir, publicDirName);
-	await mkdir(publicDir, { recursive: true });
-	await cp(join(buildDir, "client"), publicDir, {
-		recursive: true,
-		filter: (src) => {
-			if (config.clientJavascriptDisabled && src.endsWith(".js")) return false;
-			return true;
-		}
-	}).catch((e) => {
-		if (e.code !== "ENOENT") throw e;
-	});
-	if (config.staticPagesDir) await cp(config.staticPagesDir, publicDir, { recursive: true });
-}
-async function collectFiles(dir) {
-	const result = [];
-	const entries = await readdir(dir, { withFileTypes: true });
-	for (const entry of entries) {
-		const fullPath = join(dir, entry.name);
-		if (entry.isDirectory()) result.push(...await collectFiles(fullPath));
-		else result.push(fullPath);
-	}
-	return result;
-}
-//#endregion
-export { generateHeadersFile as a, IMMUTABLE_CACHE as i, findUnhashedStaticFiles as n, runSharedBuildSteps as r, buildStaticDirectoryOutput as t };
-
-//# sourceMappingURL=build-output-helper-DOGYFb_X.js.map

package/dist/_chunks/build-output-helper-DOGYFb_X.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"build-output-helper-DOGYFb_X.js","names":[],"sources":["../../src/adapters/shared.ts","../../src/adapters/build-output-helper.ts"],"sourcesContent":["// Shared adapter utilities — leaf module with zero deps on server/, client/,\n// or any Vite-dependent code.\n//\n// Adapters are loaded by Node at Vite startup time, before Vite's module\n// resolver is available. This module uses only Node built-ins and can be\n// imported by both adapters via a relative path.\n//\n// IMPORTANT: Do NOT add imports from ../server/, ../client/, ../plugins/,\n// or any module that transitively depends on Vite. A test in\n// tests/adapters/shared-no-forbidden-imports.test.ts enforces this.\n\n// ─── Static asset cache headers ──────────────────────────────────────────\n\n/** Cache-Control value for hashed (immutable) assets. */\nexport const IMMUTABLE_CACHE = 'public, max-age=31536000, immutable';\n\n/** Cache-Control value for unhashed static assets. */\nexport const STATIC_CACHE = 'public, max-age=3600, must-revalidate';\n\n/**\n * Generate a `_headers` file for static asset cache control.\n *\n * The `_headers` file is a platform convention supported by Cloudflare Workers\n * Static Assets, Cloudflare Pages, and Netlify. It maps URL patterns to\n * HTTP response headers.\n *\n * Only hashed (immutable) asset paths are listed here by default. When\n * `unhashedPaths` is provided, per-file rules are appended for unhashed\n * static assets (favicon.ico, robots.txt, etc.) so they get Cache-Control\n * on platforms like Cloudflare Workers Static Assets where the server\n * handler never sees static file requests.\n *\n * A `/*` catch-all is NOT used — it would be additive on Cloudflare,\n * producing duplicate Cache-Control directives on hashed assets\n * (invalid per RFC 9111).\n */\n// Cloudflare Workers Static Assets caps _headers at 100 rules.\n// Reserve 3 for the wildcard hashed-asset rules (/assets/*, /_timber/fonts/*, /_rsc/*).\nconst MAX_PER_FILE_RULES = 97;\n\nexport function generateHeadersFile(\n  unhashedPaths?: string[],\n  contentTypes?: Record<string, string>\n): string {\n  let content = `# Auto-generated by @timber-js/app — static asset cache headers.\n# See design/25-production-deployments.md §\"CDN / Edge Cache\"\n\n/assets/*\n  Cache-Control: ${IMMUTABLE_CACHE}\n\n/_timber/fonts/*\n  Cache-Control: ${IMMUTABLE_CACHE}\n\n/_rsc/*\n  Cache-Control: ${IMMUTABLE_CACHE}\n`;\n\n  // Content-Type rules are higher priority than cache headers for\n  // extensionless files — without them the file is unreadable.\n  const allCtEntries = contentTypes\n    ? Object.entries(contentTypes).sort(([a], [b]) => a.localeCompare(b))\n    : [];\n  const ctEntries = allCtEntries.slice(0, MAX_PER_FILE_RULES);\n  if (allCtEntries.length > MAX_PER_FILE_RULES) {\n    console.warn(\n      `[timber] _headers: ${allCtEntries.length} content-type rules exceed ` +\n        `Cloudflare's 100-rule limit. Only the first ${MAX_PER_FILE_RULES} ` +\n        `extensionless API routes will get Content-Type headers.`\n    );\n  }\n  const remainingBudget = MAX_PER_FILE_RULES - ctEntries.length;\n\n  if (unhashedPaths && unhashedPaths.length > 0) {\n    const capped = unhashedPaths.slice(0, Math.max(0, remainingBudget));\n    if (unhashedPaths.length > remainingBudget) {\n      console.warn(\n        `[timber] _headers: ${unhashedPaths.length} unhashed static files + ` +\n          `${ctEntries.length} content-type rules found, but Cloudflare limits ` +\n          `_headers to 100 rules. Only the first ${capped.length} unhashed ` +\n          `files will get Cache-Control headers.`\n      );\n    }\n    if (capped.length > 0) {\n      content += `\\n# Unhashed static assets — short-lived cache with revalidation\\n`;\n      for (const p of capped) {\n        content += `\\n${p}\\n  Cache-Control: ${STATIC_CACHE}\\n`;\n      }\n    }\n  }\n\n  if (ctEntries.length > 0) {\n    content += `\\n# Content-Type for extensionless API routes\\n`;\n    for (const [urlPath, ct] of ctEntries) {\n      content += `\\n${urlPath}\\n  Content-Type: ${ct}\\n`;\n    }\n  }\n\n  return content;\n}\n","// Shared build-output helper for adapter buildOutput() methods.\n//\n// Steps 1–5 of every adapter's buildOutput are platform-agnostic:\n//   1. Copy client assets to the public/static directory\n//   2. Write _headers file for static asset cache control\n//   3. Copy RSC + SSR server bundles\n//   4. Write manifest-init module (if present)\n//\n// Only the final steps (entry codegen, platform config) vary per adapter.\n//\n// IMPORTANT: This module must remain a leaf — no imports from ../server/,\n// ../client/, or Vite-dependent code. See adapters/shared.ts header.\n\nimport { writeFile, mkdir, cp, rm, readdir, readFile } from 'node:fs/promises';\nimport { join, basename, relative } from 'node:path';\nimport { generateHeadersFile } from './shared.js';\nimport type { TimberConfig } from './types';\n\n/** Options for the shared build output steps. */\nexport interface BuildOutputBaseOptions {\n  /** Resolved timber config. */\n  config: TimberConfig;\n  /** Root build directory (e.g. `.timber/build`). */\n  buildDir: string;\n  /** Adapter-specific output directory (e.g. `.timber/build/nitro`). */\n  outDir: string;\n  /**\n   * Name of the public/static directory within outDir.\n   * Nitro uses 'public', Cloudflare uses 'static'.\n   */\n  publicDirName: string;\n}\n\n/**\n * Run the platform-agnostic build output steps shared by all adapters:\n *\n * 1. Create the output directory\n * 2. Copy client assets to the public/static directory\n * 3. Write the `_headers` file for static asset cache control\n * 4. Copy RSC and SSR server bundles into the output directory\n * 5. Write the manifest-init module if present\n *\n * Returns the resolved public directory path for further adapter-specific use.\n */\nexport async function runSharedBuildSteps(opts: BuildOutputBaseOptions): Promise<string> {\n  const { config, buildDir, outDir, publicDirName } = opts;\n\n  // 1. Create the output directory.\n  await mkdir(outDir, { recursive: true });\n\n  // 2. Copy client assets to public/static directory.\n  // When client JavaScript is disabled, skip .js files — only CSS,\n  // fonts, images, and other static assets are needed.\n  const clientDir = join(buildDir, 'client');\n  const publicDir = join(outDir, publicDirName);\n  await mkdir(publicDir, { recursive: true });\n  // Find WASM files that are referenced by client JS (legitimate client WASM)\n  // vs orphaned server-only WASM (e.g. @takumi-rs for OG image generation).\n  // Only strip orphaned WASM to avoid breaking client-side WASM usage.\n  const referencedWasm = await findReferencedWasm(clientDir);\n\n  await cp(clientDir, publicDir, {\n    recursive: true,\n    filter: (src: string) => {\n      if (src.endsWith('.wasm') && !referencedWasm.has(basename(src))) {\n        return false;\n      }\n      if (config.clientJavascriptDisabled && src.endsWith('.js')) return false;\n      return true;\n    },\n  }).catch((e: NodeJS.ErrnoException) => {\n    // Client dir may not exist when client JavaScript is disabled\n    if (e.code !== 'ENOENT') throw e;\n  });\n\n  // 3. Write _headers file for static asset cache control.\n  // Scan for unhashed files so they get per-file Cache-Control rules in the\n  // _headers file. On platforms like Cloudflare Workers Static Assets, the\n  // worker never sees static file requests — _headers is the only mechanism.\n  const unhashedPaths = await findUnhashedStaticFiles(publicDir);\n  await writeFile(join(publicDir, '_headers'), generateHeadersFile(unhashedPaths));\n\n  // 4. Copy RSC + SSR server bundles into the output directory.\n  await cp(join(buildDir, 'rsc'), join(outDir, 'rsc'), { recursive: true });\n  await cp(join(buildDir, 'ssr'), join(outDir, 'ssr'), { recursive: true }).catch(\n    (e: NodeJS.ErrnoException) => {\n      // SSR dir may not exist for static-only builds\n      if (e.code !== 'ENOENT') throw e;\n    }\n  );\n\n  // 4b. Copy prebuilt/ flight payloads if present (cache.component artifacts).\n  // These are produced by the post-build capture pass (design/44) and read\n  // at request time via the adapter's PrebuiltPayloadSource.\n  await cp(join(buildDir, 'prebuilt'), join(outDir, 'prebuilt'), { recursive: true }).catch(\n    (e: NodeJS.ErrnoException) => {\n      // No prebuilt dir when the app has no cache.component calls\n      if (e.code !== 'ENOENT') throw e;\n    }\n  );\n\n  // 5. Write manifest-init module if present.\n  if (config.manifestInit) {\n    await writeFile(join(outDir, '_timber-manifest-init.js'), config.manifestInit);\n  }\n\n  return publicDir;\n}\n\n/**\n * Find unhashed static files in the public directory that need per-file\n * Cache-Control rules in the `_headers` file.\n *\n * Excludes:\n * - Files under `assets/` and `_timber/` (covered by wildcard rules)\n * - Underscore-prefixed files (`_headers`, `_worker.js`, etc.)\n *\n * @internal Exported for testing.\n */\n// Well-known metadata files that should be prioritized when capping\n// _headers rules, so they're never dropped in favor of less important files.\nconst PRIORITY_FILES = new Set([\n  '/favicon.ico',\n  '/robots.txt',\n  '/sitemap.xml',\n  '/manifest.json',\n  '/manifest.webmanifest',\n  '/apple-touch-icon.png',\n]);\n\nexport async function findUnhashedStaticFiles(publicDir: string): Promise<string[]> {\n  let files: string[];\n  try {\n    files = await collectFiles(publicDir);\n  } catch {\n    return [];\n  }\n\n  const priority: string[] = [];\n  const rest: string[] = [];\n  for (const file of files) {\n    const rel = relative(publicDir, file).replace(/\\\\/g, '/');\n    if (rel.startsWith('assets/') || rel.startsWith('_timber/')) continue;\n    if (rel.startsWith('rsc/') || rel.startsWith('ssr/') || rel.startsWith('_rsc/')) continue;\n    if (basename(rel).startsWith('_')) continue;\n    const urlPath = '/' + rel;\n    if (PRIORITY_FILES.has(urlPath)) {\n      priority.push(urlPath);\n    } else {\n      rest.push(urlPath);\n    }\n  }\n\n  return [...priority.sort(), ...rest.sort()];\n}\n\n/**\n * Scan client JS files for references to .wasm filenames.\n * Returns the set of WASM basenames that are actually imported/referenced\n * by client code and must be preserved in the static output.\n */\nasync function findReferencedWasm(clientDir: string): Promise<Set<string>> {\n  const referenced = new Set<string>();\n\n  let files: string[];\n  try {\n    files = await collectFiles(clientDir);\n  } catch {\n    return referenced;\n  }\n\n  const jsFiles = files.filter((f) => f.endsWith('.js'));\n  const wasmFiles = files.filter((f) => f.endsWith('.wasm')).map((f) => basename(f));\n  if (wasmFiles.length === 0) return referenced;\n\n  for (const jsFile of jsFiles) {\n    const content = await readFile(jsFile, 'utf-8');\n    for (const wasmName of wasmFiles) {\n      if (content.includes(wasmName)) {\n        referenced.add(wasmName);\n      }\n    }\n  }\n\n  return referenced;\n}\n\n/**\n * Build a static-only output directory (no server entry). Copies client\n * assets and pre-rendered HTML/RSC/API files into `outDir/publicDirName`.\n * Used by both Cloudflare and Nitro adapters in `output: 'static'` mode.\n */\nexport async function buildStaticDirectoryOutput(\n  config: TimberConfig,\n  buildDir: string,\n  outDir: string,\n  publicDirName: string\n): Promise<void> {\n  // Clean stale artifacts from prior builds (e.g. server-mode builds that\n  // left rsc/, ssr/, _worker.js in the outDir). Without this, a static\n  // build after a server build inherits 140+ unused server chunks.\n  await rm(outDir, { recursive: true, force: true }).catch(() => {});\n  await mkdir(outDir, { recursive: true });\n\n  const publicDir = join(outDir, publicDirName);\n  await mkdir(publicDir, { recursive: true });\n\n  // Copy client assets (JS, CSS, fonts, images).\n  const clientDir = join(buildDir, 'client');\n  await cp(clientDir, publicDir, {\n    recursive: true,\n    filter: (src: string) => {\n      if (config.clientJavascriptDisabled && src.endsWith('.js')) return false;\n      return true;\n    },\n  }).catch((e: NodeJS.ErrnoException) => {\n    if (e.code !== 'ENOENT') throw e;\n  });\n\n  // Copy pre-rendered static pages (HTML + RSC flight + API routes).\n  if (config.staticPagesDir) {\n    await cp(config.staticPagesDir, publicDir, { recursive: true });\n  }\n}\n\nasync function collectFiles(dir: string): Promise<string[]> {\n  const result: string[] = [];\n  const entries = await readdir(dir, { withFileTypes: true });\n  for (const entry of entries) {\n    const fullPath = join(dir, entry.name);\n    if (entry.isDirectory()) {\n      result.push(...(await collectFiles(fullPath)));\n    } else {\n      result.push(fullPath);\n    }\n  }\n  return result;\n}\n"],"mappings":"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"}

package/dist/_chunks/canonicalize-DQHyFClh.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"canonicalize-DQHyFClh.js","names":[],"sources":["../../src/server/metadata-routes.ts","../../src/server/canonicalize.ts"],"sourcesContent":["/**\n * Metadata route classification for timber.js.\n *\n * Metadata routes are file-based endpoints that generate well-known URLs for\n * crawlers and browsers (sitemap.xml, robots.txt, OG images, etc.).\n *\n * These routes run through proxy.ts but NOT through middleware.ts or access.ts —\n * they are public endpoints by nature.\n *\n * See design/16-metadata.md §\"Metadata Routes\"\n */\n\nimport { randomUUID } from 'node:crypto';\nimport type { HeadElement } from './metadata.js';\nimport type { Metadata } from './types.js';\nimport type { ManifestSegmentNode } from './route-matcher.js';\n\n// ─── Types ───────────────────────────────────────────────────────────────────\n\n/** Classification of a metadata route file. */\nexport interface MetadataRouteInfo {\n  /** The metadata route type. */\n  type: MetadataRouteType;\n  /** The content type to serve this route with. */\n  contentType: string;\n  /** Whether this route can appear in nested segments (not just app root). */\n  nestable: boolean;\n}\n\nexport type MetadataRouteType =\n  | 'sitemap'\n  | 'robots'\n  | 'manifest'\n  | 'favicon'\n  | 'icon'\n  | 'opengraph-image'\n  | 'apple-icon';\n\n// ─── Convention Table ────────────────────────────────────────────────────────\n\n/**\n * All recognized metadata route file conventions.\n *\n * Each entry maps a base file name (without extension) to its route info.\n * The extensions determine whether the file is static or dynamic.\n *\n * Static extensions: .xml, .txt, .json, .png, .jpg, .ico, .svg\n * Dynamic extensions: .ts, .tsx\n */\nexport const METADATA_ROUTE_CONVENTIONS: Record<\n  string,\n  {\n    type: MetadataRouteType;\n    contentType: string;\n    nestable: boolean;\n    staticExtensions: string[];\n    dynamicExtensions: string[];\n    /**\n     * The URL path basename this file serves at (relative to segment).\n     * For image routes, the full serve path includes an extension via\n     * `resolveServePathForFile()`.\n     */\n    servePath: string;\n    /**\n     * When set, image routes append `.{serveExtension}` to the serve path.\n     * Dynamic handlers (`.ts`/`.tsx`) use this as the default. Static files\n     * use their own extension instead. Non-image routes leave this undefined.\n     */\n    serveExtension?: string;\n  }\n> = {\n  'sitemap': {\n    type: 'sitemap',\n    contentType: 'application/xml',\n    nestable: true,\n    staticExtensions: ['xml'],\n    dynamicExtensions: ['ts'],\n    servePath: 'sitemap.xml',\n  },\n  'robots': {\n    type: 'robots',\n    contentType: 'text/plain',\n    nestable: false,\n    staticExtensions: ['txt'],\n    dynamicExtensions: ['ts'],\n    servePath: 'robots.txt',\n  },\n  'manifest': {\n    type: 'manifest',\n    contentType: 'application/manifest+json',\n    nestable: false,\n    staticExtensions: ['json'],\n    dynamicExtensions: ['ts'],\n    servePath: 'manifest.webmanifest',\n  },\n  'favicon': {\n    type: 'favicon',\n    contentType: 'image/x-icon',\n    nestable: false,\n    staticExtensions: ['ico'],\n    dynamicExtensions: ['ts', 'tsx'],\n    servePath: 'favicon.ico',\n  },\n  'icon': {\n    type: 'icon',\n    contentType: 'image/*',\n    nestable: true,\n    staticExtensions: ['png', 'jpg', 'svg'],\n    dynamicExtensions: ['ts', 'tsx'],\n    servePath: 'icon',\n    serveExtension: 'png',\n  },\n  'opengraph-image': {\n    type: 'opengraph-image',\n    contentType: 'image/*',\n    nestable: true,\n    staticExtensions: ['png', 'jpg'],\n    dynamicExtensions: ['ts', 'tsx'],\n    servePath: 'opengraph-image',\n    serveExtension: 'png',\n  },\n\n  'apple-icon': {\n    type: 'apple-icon',\n    contentType: 'image/*',\n    nestable: true,\n    staticExtensions: ['png'],\n    dynamicExtensions: ['ts', 'tsx'],\n    servePath: 'apple-icon',\n    serveExtension: 'png',\n  },\n};\n\n// ─── MIME Type Resolution ─────────────────────────────────────────────────────\n\n/**\n * Map of file extensions to MIME types for static metadata route files.\n * Used to resolve the generic `image/*` content type for static image files.\n */\nconst EXTENSION_MIME_TYPES: Record<string, string> = {\n  xml: 'application/xml',\n  txt: 'text/plain',\n  json: 'application/json',\n  ico: 'image/x-icon',\n  png: 'image/png',\n  jpg: 'image/jpeg',\n  jpeg: 'image/jpeg',\n  svg: 'image/svg+xml',\n  webp: 'image/webp',\n};\n\n/**\n * Resolve the concrete MIME type for a static metadata route file.\n *\n * For generic content types like `image/*`, this resolves to the actual\n * MIME type based on the file extension (e.g. `image/png` for `.png`).\n *\n * @param conventionContentType - The content type from the convention table (may be generic like `image/*`)\n * @param extension - The file extension without leading dot (e.g. \"png\", \"xml\")\n * @returns The resolved MIME type\n */\nexport function resolveStaticContentType(conventionContentType: string, extension: string): string {\n  if (conventionContentType.includes('*')) {\n    return EXTENSION_MIME_TYPES[extension] ?? 'application/octet-stream';\n  }\n  return conventionContentType;\n}\n\n/**\n * Check if a file extension represents a static (non-code) metadata route file.\n *\n * @param baseName - The base file name without extension (e.g. \"sitemap\", \"icon\")\n * @param extension - The file extension without leading dot (e.g. \"xml\", \"png\", \"ts\")\n * @returns true if this is a static file, false if dynamic or unrecognized\n */\nexport function isStaticMetadataExtension(baseName: string, extension: string): boolean {\n  const convention = METADATA_ROUTE_CONVENTIONS[baseName];\n  if (!convention) return false;\n  return convention.staticExtensions.includes(extension);\n}\n\n/**\n * Check if a file extension represents a dynamic (code) metadata route file.\n *\n * @param baseName - The base file name without extension (e.g. \"sitemap\", \"icon\")\n * @param extension - The file extension without leading dot (e.g. \"ts\", \"tsx\")\n * @returns true if this is a dynamic file, false if static or unrecognized\n */\nexport function isDynamicMetadataExtension(baseName: string, extension: string): boolean {\n  const convention = METADATA_ROUTE_CONVENTIONS[baseName];\n  if (!convention) return false;\n  return convention.dynamicExtensions.includes(extension);\n}\n\n// ─── Classification ──────────────────────────────────────────────────────────\n\n/**\n * Classify a file name as a metadata route, or return null if it's not one.\n *\n * @param fileName - The full file name including extension (e.g. \"sitemap.xml\", \"icon.tsx\")\n * @returns Classification info, or null if not a metadata route\n */\nexport function classifyMetadataRoute(fileName: string): MetadataRouteInfo | null {\n  const dotIndex = fileName.lastIndexOf('.');\n  if (dotIndex === -1) return null;\n\n  const baseName = fileName.slice(0, dotIndex);\n  const ext = fileName.slice(dotIndex + 1);\n\n  const convention = METADATA_ROUTE_CONVENTIONS[baseName];\n  if (!convention) return null;\n\n  const isStatic = convention.staticExtensions.includes(ext);\n  const isDynamic = convention.dynamicExtensions.includes(ext);\n\n  if (!isStatic && !isDynamic) return null;\n\n  return {\n    type: convention.type,\n    contentType: convention.contentType,\n    nestable: convention.nestable,\n  };\n}\n\n/**\n * Resolve the serve path for a metadata route file.\n *\n * For image routes (icon, opengraph-image, apple-icon), the serve path includes\n * a file extension so CDNs cache correctly:\n * - Dynamic handlers (.ts/.tsx) use the convention's `serveExtension` (default: .png)\n * - Static files use their own extension (e.g., icon.svg → icon.svg)\n *\n * Non-image routes return the convention's `servePath` as-is (already includes\n * extension: sitemap.xml, robots.txt, etc.).\n */\nexport function resolveServePathForFile(baseName: string, filePath: string): string {\n  const convention = METADATA_ROUTE_CONVENTIONS[baseName];\n  if (!convention) return baseName;\n\n  if (!convention.serveExtension) return convention.servePath;\n\n  const ext = filePath.slice(filePath.lastIndexOf('.') + 1);\n  if (convention.staticExtensions.includes(ext)) {\n    return `${convention.servePath}.${ext}`;\n  }\n  return `${convention.servePath}.${convention.serveExtension}`;\n}\n\n/**\n * Get the default serve path for a metadata route type (using default extension\n * for image routes). Used for auto-link generation when only the type is known.\n */\nexport function getMetadataRouteServePath(type: MetadataRouteType): string {\n  for (const convention of Object.values(METADATA_ROUTE_CONVENTIONS)) {\n    if (convention.type === type) {\n      if (convention.serveExtension) {\n        return `${convention.servePath}.${convention.serveExtension}`;\n      }\n      return convention.servePath;\n    }\n  }\n  throw new Error(`[timber] Unknown metadata route type: ${type}`);\n}\n\n/**\n * All possible serve path segments for metadata routes (includes extension\n * variants for image routes).\n */\nconst METADATA_SERVE_PATHS = new Set<string>();\nfor (const convention of Object.values(METADATA_ROUTE_CONVENTIONS)) {\n  if (convention.serveExtension) {\n    for (const ext of [...convention.staticExtensions, convention.serveExtension]) {\n      METADATA_SERVE_PATHS.add(`${convention.servePath}.${ext}`);\n    }\n  } else {\n    METADATA_SERVE_PATHS.add(convention.servePath);\n  }\n}\n\nexport function isMetadataRouteServePath(pathname: string): boolean {\n  let lastSegment = pathname.slice(pathname.lastIndexOf('/') + 1);\n  const qIdx = lastSegment.indexOf('?');\n  let query = '';\n  if (qIdx !== -1) {\n    query = lastSegment.slice(qIdx + 1);\n    lastSegment = lastSegment.slice(0, qIdx);\n  }\n  if (!METADATA_SERVE_PATHS.has(lastSegment)) return false;\n  // Vite module requests (e.g., /src/icon.svg?import) use special query params.\n  // These are source assets, not metadata routes.\n  if (/(?:^|&)(?:import|url|raw|worker|inline)(?:&|$)/.test(query)) return false;\n  return true;\n}\n\n/** A <link> auto-link tag. */\nexport interface AutoLinkLink {\n  tag: 'link';\n  rel: string;\n  href: string;\n  type?: string;\n}\n\n/** A <meta> auto-link tag. */\nexport interface AutoLinkMeta {\n  tag: 'meta';\n  property?: string;\n  name?: string;\n  content: string;\n}\n\nexport type AutoLinkTag = AutoLinkLink | AutoLinkMeta;\n\n/**\n * Get the auto-link tags to inject into <head> for metadata route files\n * discovered in a segment.\n *\n * Returns link tags for icon/apple-icon/manifest, and meta tags for\n * opengraph-image (emits both og:image and twitter:image). Returns null\n * for types that don't auto-link (favicon, sitemap, robots).\n *\n * @param type - The metadata route type\n * @param href - The resolved URL path to the metadata route\n * @returns Tag descriptor(s) for the <head>, or null if no auto-link\n */\nexport function getMetadataRouteAutoLink(type: MetadataRouteType, href: string): AutoLinkTag[] {\n  switch (type) {\n    case 'icon':\n      return [{ tag: 'link', rel: 'icon', href }];\n    case 'apple-icon':\n      return [{ tag: 'link', rel: 'apple-touch-icon', href }];\n    case 'manifest':\n      return [{ tag: 'link', rel: 'manifest', href }];\n    case 'opengraph-image':\n      return [\n        { tag: 'meta', property: 'og:image', content: href },\n        { tag: 'meta', name: 'twitter:image', content: href },\n      ];\n    default:\n      return [];\n  }\n}\n\n// ─── Auto-Linking ──────────────────────────────────────────────────────────\n\n// In dev mode, use a per-startup nonce for metadata route cache busting\n// instead of per-file content hashes (avoids rehashing on every request).\nlet _devNonce: string | undefined;\nfunction getDevNonce(): string {\n  _devNonce ??= randomUUID().slice(0, 8);\n  return _devNonce;\n}\n\n/**\n * Collect auto-linked head elements from metadata route files in the segment chain.\n *\n * Walks each segment's metadataRoutes, resolves serve paths and URLs, and\n * emits HeadElement descriptors for <link> and <meta> tags that React Float\n * hoists into <head>.\n *\n * See design/16-metadata.md §\"Auto-Linking\"\n */\nexport function collectMetadataRouteHeadElements(\n  segments: ManifestSegmentNode[],\n  firstDeniedIndex: number,\n  resolvedMetadata: Metadata,\n  requestUrl: URL,\n  metadataRouteHashes?: Record<string, string>\n): HeadElement[] {\n  const elements: HeadElement[] = [];\n  const hasUserOgImage = Boolean(resolvedMetadata.openGraph?.images);\n  const hasUserTwitterImage = Boolean(resolvedMetadata.twitter?.images);\n  const requestPathname = requestUrl.pathname;\n  // In dev mode, use the request origin so OG URLs resolve to localhost.\n  // In production, use metadataBase (the canonical domain).\n  const ogBase =\n    process.env.NODE_ENV !== 'production'\n      ? new URL(requestUrl.origin)\n      : resolvedMetadata.metadataBase;\n\n  for (let si = 0; si < segments.length; si++) {\n    const segment = segments[si];\n    if (!segment.metadataRoutes) continue;\n    if (si >= firstDeniedIndex) continue;\n    for (const baseName of Object.keys(segment.metadataRoutes)) {\n      const convention = METADATA_ROUTE_CONVENTIONS[baseName];\n      if (!convention) continue;\n      if (!convention.nestable && segment.urlPath !== '/') continue;\n      if (convention.type === 'opengraph-image' && hasUserOgImage) continue;\n      const resolvedPrefix = convention.nestable\n        ? requestPathname === '/'\n          ? ''\n          : requestPathname\n        : '';\n      const metaFile = segment.metadataRoutes[baseName];\n      const fileServePath = metaFile?.filePath\n        ? resolveServePathForFile(baseName, metaFile.filePath)\n        : convention.serveExtension\n          ? `${convention.servePath}.${convention.serveExtension}`\n          : convention.servePath;\n      let href = `${resolvedPrefix}/${fileServePath}`;\n      if (convention.type === 'opengraph-image') {\n        const fileHash = metaFile?.filePath ? metadataRouteHashes?.[metaFile.filePath] : undefined;\n        const cacheBust = fileHash ?? getDevNonce();\n        href = `${href}?${cacheBust}`;\n      }\n      if (ogBase && convention.type === 'opengraph-image') {\n        href = new URL(href, ogBase).toString();\n      }\n      for (const autoLink of getMetadataRouteAutoLink(convention.type, href)) {\n        if (\n          hasUserTwitterImage &&\n          autoLink.tag === 'meta' &&\n          'name' in autoLink &&\n          autoLink.name === 'twitter:image'\n        )\n          continue;\n        if (autoLink.tag === 'link') {\n          const attrs: Record<string, string> = { rel: autoLink.rel, href: autoLink.href };\n          if (autoLink.type) attrs.type = autoLink.type;\n          elements.push({ tag: 'link', attrs });\n        } else {\n          const attrs: Record<string, string> = { content: autoLink.content };\n          if (autoLink.property) attrs.property = autoLink.property;\n          if (autoLink.name) attrs.name = autoLink.name;\n          elements.push({ tag: 'meta', attrs });\n        }\n      }\n    }\n  }\n  return elements;\n}\n","/**\n * URL canonicalization — runs once at the request boundary.\n *\n * Every layer (proxy.ts, middleware.ts, access.ts, components) sees the same\n * canonical path. No re-decoding occurs at any later stage.\n *\n * See design/07-routing.md §\"URL Canonicalization & Security\"\n */\n\n/** Result of canonicalization — either a clean path or a rejection. */\nexport type CanonicalizeResult = { ok: true; pathname: string } | { ok: false; status: 400 };\n\n/**\n * Encoded separators that produce a 400 rejection.\n * %2f (/) and %5c (\\) cause path-confusion attacks.\n *\n * Shared between the runtime canonicalizer and the build-time route scanner\n * to ensure both enforce identical security rules. See design/13-security.md.\n */\nexport const ENCODED_SEPARATOR_RE = /%2f|%5c/i;\n\n/** Null byte — rejected. Shared with the route scanner. */\nexport const NULL_BYTE_RE = /%00/i;\n\n/**\n * Canonicalize a URL pathname.\n *\n * 1. Reject encoded separators (%2f, %5c) and null bytes (%00)\n * 2. Single percent-decode\n * 3. Collapse // → /\n * 4. Resolve .. segments (reject if escaping root)\n * 5. Strip trailing slash (except root \"/\")\n *\n * @param rawPathname - The raw pathname from the request URL (percent-encoded)\n * @param stripTrailingSlash - Whether to strip trailing slashes. Default: true.\n */\nexport function canonicalize(rawPathname: string, stripTrailingSlash = true): CanonicalizeResult {\n  // Step 1: Reject dangerous encoded sequences BEFORE decoding.\n  // This must happen on the raw input so %252f doesn't bypass after a single decode.\n  if (ENCODED_SEPARATOR_RE.test(rawPathname)) {\n    return { ok: false, status: 400 };\n  }\n  if (NULL_BYTE_RE.test(rawPathname)) {\n    return { ok: false, status: 400 };\n  }\n\n  // Step 2: Single percent-decode.\n  // Double-encoded input (%2561 → %61) stays as %61 — not decoded again.\n  let decoded: string;\n  try {\n    decoded = decodeURIComponent(rawPathname);\n  } catch {\n    // Malformed percent-encoding → 400\n    return { ok: false, status: 400 };\n  }\n\n  // Reject null bytes that appeared after decoding (from valid %00-like sequences\n  // that weren't caught above — belt and suspenders).\n  if (decoded.includes('\\0')) {\n    return { ok: false, status: 400 };\n  }\n\n  // Backslash is NOT a path separator — keep as literal character.\n  // But reject if it would create // after normalization (e.g., /\\evil.com).\n  // We do NOT convert \\ to / — it stays as a literal.\n\n  // Step 3: Collapse consecutive slashes.\n  let pathname = decoded.replace(/\\/\\/+/g, '/');\n\n  // Step 4: Resolve .. and . segments.\n  const segments = pathname.split('/');\n  const resolved: string[] = [];\n  for (const seg of segments) {\n    if (seg === '..') {\n      if (resolved.length <= 1) {\n        // Trying to escape root — 400\n        return { ok: false, status: 400 };\n      }\n      resolved.pop();\n    } else if (seg !== '.') {\n      resolved.push(seg);\n    }\n  }\n\n  pathname = resolved.join('/') || '/';\n\n  // Step 5: Strip trailing slash (except root \"/\").\n  if (stripTrailingSlash && pathname.length > 1 && pathname.endsWith('/')) {\n    pathname = pathname.slice(0, -1);\n  }\n\n  return { ok: true, pathname };\n}\n"],"mappings":"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"}