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

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-media-type.ts

@@ -0,0 +1,43 @@
+/**
+ * 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. */
+export const 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.
+ */
+export function isRscRequest(req: Request): boolean {
+  return (req.headers.get('Accept') ?? '').includes(RSC_CONTENT_TYPE);
+}

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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"}