@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/dist/_chunks/scan-BoP17W3w.js

@@ -0,0 +1,140 @@
+import { join } from "node:path";
+import { readdir } from "node:fs/promises";
+//#region src/analyze/scan.ts
+/**
+* scan — project source-file disk scan shared by the crawl and the
+* graph cache.
+*
+* One walker, one rule set: the crawl uses it to find files no graph
+* reached (the provisional/pending set) and to bound graph membership,
+* and the mtime-keyed graph cache fingerprints exactly the same file
+* set — the three can never disagree about what "the project" is (a
+* file the crawl classifies but the fingerprint ignores would make the
+* cache silently stale).
+*
+* Skip rules are deliberately shallow: timber's router excludes only
+* `_`-prefixed directories, so `app/.well-known/page.tsx` and
+* `app/dist/page.tsx` are REAL routes — a rule that skipped `dist` or
+* dot-directories at any depth would hide legitimate route files from
+* the scan while the module graph still reached them (codex review,
+* PR #1056). Therefore:
+*
+* - `node_modules` is skipped at ANY depth (never project source, and
+*   graph membership excludes it identically)
+* - dot-prefixed and build-output directories (`dist`, `coverage`, …)
+*   are skipped only as the FIRST path segment under the root — that
+*   is where `.git`, `.timber`, `.wrangler`, and real build outputs
+*   live; deeper occurrences are walked
+*
+* Deliberately vite-free: the cache-hit path of `timber graph` reads
+* this module without booting (or even importing) Vite.
+*
+* Design docs: 47-module-environment-tooling.md §2, §Cold-path policy.
+*/
+/**
+* Slash-normalize a Windows path — Vite's `normalizePath` for the
+* vite-free callers (the graph cache-hit path must not import Vite).
+* Same platform guard as Vite's: posix paths pass through untouched,
+* so a filename containing a literal backslash is never corrupted.
+*/
+var normalizeSlashes = process.platform === "win32" ? (path) => path.replace(/\\/g, "/") : (path) => path;
+/**
+* Directories never scanned when they are the first path segment under
+* the root. `node_modules` is additionally skipped at any depth.
+*/
+var SCAN_IGNORED_DIRS = /* @__PURE__ */ new Set([
+	"node_modules",
+	"dist",
+	"test-results",
+	"coverage"
+]);
+/**
+* Single source of truth for builtin source extensions. Includes mdx —
+* timber supports page.mdx via pageExtensions, so an unreferenced MDX
+* page must not vanish from --all output.
+*/
+var BUILTIN_EXTENSIONS = [
+	"ts",
+	"tsx",
+	"js",
+	"jsx",
+	"mjs",
+	"cjs",
+	"mts",
+	"cts",
+	"mdx"
+];
+/** Regex form of BUILTIN_EXTENSIONS for file-basename matching. */
+var SOURCE_EXTENSIONS = new RegExp(`\\.(?:${BUILTIN_EXTENSIONS.join("|")})$`);
+/** Set form for O(1) membership checks. */
+var BUILTIN_EXTENSION_SET = new Set(BUILTIN_EXTENSIONS);
+/**
+* Build a regex that matches SOURCE_EXTENSIONS plus any extra
+* extensions from the user's pageExtensions config. Returns the
+* builtin regex unchanged when nothing new is added.
+*/
+function buildSourceExtensions(pageExtensions) {
+	if (!pageExtensions) return SOURCE_EXTENSIONS;
+	const extras = pageExtensions.filter((ext) => !BUILTIN_EXTENSION_SET.has(ext));
+	if (extras.length === 0) return SOURCE_EXTENSIONS;
+	const escaped = extras.map((ext) => ext.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+	return new RegExp(`\\.(?:${BUILTIN_EXTENSIONS.join("|")}|${escaped.join("|")})$`);
+}
+/** Whether a directory SEGMENT is skipped at the given depth (0 = root child). */
+function isSkippedDirSegment(segment, depth) {
+	if (segment === "node_modules") return true;
+	if (depth === 0 && (segment.startsWith(".") || SCAN_IGNORED_DIRS.has(segment))) return true;
+	return false;
+}
+/** Whether a file basename is admitted as project source. */
+function isSourceBasename(base, depth, extensions) {
+	if (depth === 0 && base.startsWith(".")) return false;
+	if (!(extensions ?? SOURCE_EXTENSIONS).test(base)) return false;
+	if (/\.d\.[mc]?ts$/.test(base)) return false;
+	return true;
+}
+/**
+* Whether an absolute, slash-normalized path is one the scanner WOULD
+* admit — the same segment rules the walker applies, so a
+* directly-addressed path (`package.json`, `<root>/dist/generated.js`,
+* `types.d.ts`, a nested node_modules file) is answered exactly the
+* way the scan-based sweep would answer it: by exclusion. Existence
+* and is-a-file checks remain the caller's (this is pure path logic).
+*/
+function isScannableSourceFile(file, root, extensions) {
+	if (!file.startsWith(root + "/")) return false;
+	const segments = file.slice(root.length + 1).split("/");
+	const base = segments[segments.length - 1];
+	for (let depth = 0; depth < segments.length - 1; depth++) if (isSkippedDirSegment(segments[depth], depth)) return false;
+	return isSourceBasename(base, segments.length - 1, extensions);
+}
+/**
+* Recursively list project source files on disk.
+*
+* Unreadable directories are reported through `onFailure`, not thrown
+* and not swallowed — this walker exists to keep files from silently
+* vanishing, so a directory it cannot see must be visible too.
+*/
+async function scanProjectSourceFiles(dir, out, onFailure, depth = 0, extensions) {
+	let entries;
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch (error) {
+		onFailure({
+			dir,
+			message: `directory scan failed: ${error instanceof Error ? error.message : String(error)}`
+		});
+		return;
+	}
+	for (const entry of entries) {
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			if (isSkippedDirSegment(entry.name, depth)) continue;
+			await scanProjectSourceFiles(full, out, onFailure, depth + 1, extensions);
+		} else if (entry.isFile() && isSourceBasename(entry.name, depth, extensions)) out.push(full);
+	}
+}
+//#endregion
+export { scanProjectSourceFiles as i, isScannableSourceFile as n, normalizeSlashes as r, buildSourceExtensions as t };
+
+//# sourceMappingURL=scan-BoP17W3w.js.map

package/dist/_chunks/scan-BoP17W3w.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-BoP17W3w.js","names":[],"sources":["../../src/analyze/scan.ts"],"sourcesContent":["/**\n * scan — project source-file disk scan shared by the crawl and the\n * graph cache.\n *\n * One walker, one rule set: the crawl uses it to find files no graph\n * reached (the provisional/pending set) and to bound graph membership,\n * and the mtime-keyed graph cache fingerprints exactly the same file\n * set — the three can never disagree about what \"the project\" is (a\n * file the crawl classifies but the fingerprint ignores would make the\n * cache silently stale).\n *\n * Skip rules are deliberately shallow: timber's router excludes only\n * `_`-prefixed directories, so `app/.well-known/page.tsx` and\n * `app/dist/page.tsx` are REAL routes — a rule that skipped `dist` or\n * dot-directories at any depth would hide legitimate route files from\n * the scan while the module graph still reached them (codex review,\n * PR #1056). Therefore:\n *\n * - `node_modules` is skipped at ANY depth (never project source, and\n *   graph membership excludes it identically)\n * - dot-prefixed and build-output directories (`dist`, `coverage`, …)\n *   are skipped only as the FIRST path segment under the root — that\n *   is where `.git`, `.timber`, `.wrangler`, and real build outputs\n *   live; deeper occurrences are walked\n *\n * Deliberately vite-free: the cache-hit path of `timber graph` reads\n * this module without booting (or even importing) Vite.\n *\n * Design docs: 47-module-environment-tooling.md §2, §Cold-path policy.\n */\n\nimport { readdir } from 'node:fs/promises';\nimport { join } from 'node:path';\n\n/**\n * Slash-normalize a Windows path — Vite's `normalizePath` for the\n * vite-free callers (the graph cache-hit path must not import Vite).\n * Same platform guard as Vite's: posix paths pass through untouched,\n * so a filename containing a literal backslash is never corrupted.\n */\nexport const normalizeSlashes: (path: string) => string =\n  process.platform === 'win32' ? (path) => path.replace(/\\\\/g, '/') : (path) => path;\n\n/** A scan failure the caller records instead of swallowing. */\nexport interface ScanFailure {\n  dir: string;\n  message: string;\n}\n\n/**\n * Directories never scanned when they are the first path segment under\n * the root. `node_modules` is additionally skipped at any depth.\n */\nexport const SCAN_IGNORED_DIRS = new Set(['node_modules', 'dist', 'test-results', 'coverage']);\n\n/**\n * Single source of truth for builtin source extensions. Includes mdx —\n * timber supports page.mdx via pageExtensions, so an unreferenced MDX\n * page must not vanish from --all output.\n */\nconst BUILTIN_EXTENSIONS = ['ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs', 'mts', 'cts', 'mdx'] as const;\n\n/** Regex form of BUILTIN_EXTENSIONS for file-basename matching. */\nexport const SOURCE_EXTENSIONS = new RegExp(`\\\\.(?:${BUILTIN_EXTENSIONS.join('|')})$`);\n\n/** Set form for O(1) membership checks. */\nconst BUILTIN_EXTENSION_SET = new Set<string>(BUILTIN_EXTENSIONS);\n\n/**\n * Build a regex that matches SOURCE_EXTENSIONS plus any extra\n * extensions from the user's pageExtensions config. Returns the\n * builtin regex unchanged when nothing new is added.\n */\nexport function buildSourceExtensions(pageExtensions?: readonly string[]): RegExp {\n  if (!pageExtensions) return SOURCE_EXTENSIONS;\n  const extras = pageExtensions.filter((ext) => !BUILTIN_EXTENSION_SET.has(ext));\n  if (extras.length === 0) return SOURCE_EXTENSIONS;\n  const escaped = extras.map((ext) => ext.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&'));\n  return new RegExp(`\\\\.(?:${BUILTIN_EXTENSIONS.join('|')}|${escaped.join('|')})$`);\n}\n\n/** Whether a directory SEGMENT is skipped at the given depth (0 = root child). */\nfunction isSkippedDirSegment(segment: string, depth: number): boolean {\n  if (segment === 'node_modules') return true;\n  if (depth === 0 && (segment.startsWith('.') || SCAN_IGNORED_DIRS.has(segment))) return true;\n  return false;\n}\n\n/** Whether a file basename is admitted as project source. */\nfunction isSourceBasename(base: string, depth: number, extensions?: RegExp): boolean {\n  if (depth === 0 && base.startsWith('.')) return false;\n  if (!(extensions ?? SOURCE_EXTENSIONS).test(base)) return false;\n  // Declaration files are types-only — they never run in any environment.\n  if (/\\.d\\.[mc]?ts$/.test(base)) return false;\n  return true;\n}\n\n/**\n * Whether an absolute, slash-normalized path is one the scanner WOULD\n * admit — the same segment rules the walker applies, so a\n * directly-addressed path (`package.json`, `<root>/dist/generated.js`,\n * `types.d.ts`, a nested node_modules file) is answered exactly the\n * way the scan-based sweep would answer it: by exclusion. Existence\n * and is-a-file checks remain the caller's (this is pure path logic).\n */\nexport function isScannableSourceFile(file: string, root: string, extensions?: RegExp): boolean {\n  if (!file.startsWith(root + '/')) return false;\n  const segments = file.slice(root.length + 1).split('/');\n  const base = segments[segments.length - 1];\n  for (let depth = 0; depth < segments.length - 1; depth++) {\n    if (isSkippedDirSegment(segments[depth], depth)) return false;\n  }\n  return isSourceBasename(base, segments.length - 1, extensions);\n}\n\n/**\n * Recursively list project source files on disk.\n *\n * Unreadable directories are reported through `onFailure`, not thrown\n * and not swallowed — this walker exists to keep files from silently\n * vanishing, so a directory it cannot see must be visible too.\n */\nexport async function scanProjectSourceFiles(\n  dir: string,\n  out: string[],\n  onFailure: (failure: ScanFailure) => void,\n  depth = 0,\n  extensions?: RegExp\n): Promise<void> {\n  let entries;\n  try {\n    entries = await readdir(dir, { withFileTypes: true });\n  } catch (error) {\n    onFailure({\n      dir,\n      message: `directory scan failed: ${error instanceof Error ? error.message : String(error)}`,\n    });\n    return;\n  }\n  for (const entry of entries) {\n    const full = join(dir, entry.name);\n    if (entry.isDirectory()) {\n      if (isSkippedDirSegment(entry.name, depth)) continue;\n      await scanProjectSourceFiles(full, out, onFailure, depth + 1, extensions);\n    } else if (entry.isFile() && isSourceBasename(entry.name, depth, extensions)) {\n      out.push(full);\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,IAAa,mBACX,QAAQ,aAAa,WAAW,SAAS,KAAK,QAAQ,OAAO,GAAG,KAAK,SAAS;;;;;AAYhF,IAAa,oCAAoB,IAAI,IAAI;CAAC;CAAgB;CAAQ;CAAgB;AAAU,CAAC;;;;;;AAO7F,IAAM,qBAAqB;CAAC;CAAM;CAAO;CAAM;CAAO;CAAO;CAAO;CAAO;CAAO;AAAK;;AAGvF,IAAa,oBAAoB,IAAI,OAAO,SAAS,mBAAmB,KAAK,GAAG,EAAE,GAAG;;AAGrF,IAAM,wBAAwB,IAAI,IAAY,kBAAkB;;;;;;AAOhE,SAAgB,sBAAsB,gBAA4C;CAChF,IAAI,CAAC,gBAAgB,OAAO;CAC5B,MAAM,SAAS,eAAe,QAAQ,QAAQ,CAAC,sBAAsB,IAAI,GAAG,CAAC;CAC7E,IAAI,OAAO,WAAW,GAAG,OAAO;CAChC,MAAM,UAAU,OAAO,KAAK,QAAQ,IAAI,QAAQ,uBAAuB,MAAM,CAAC;CAC9E,OAAO,IAAI,OAAO,SAAS,mBAAmB,KAAK,GAAG,EAAE,GAAG,QAAQ,KAAK,GAAG,EAAE,GAAG;AAClF;;AAGA,SAAS,oBAAoB,SAAiB,OAAwB;CACpE,IAAI,YAAY,gBAAgB,OAAO;CACvC,IAAI,UAAU,MAAM,QAAQ,WAAW,GAAG,KAAK,kBAAkB,IAAI,OAAO,IAAI,OAAO;CACvF,OAAO;AACT;;AAGA,SAAS,iBAAiB,MAAc,OAAe,YAA8B;CACnF,IAAI,UAAU,KAAK,KAAK,WAAW,GAAG,GAAG,OAAO;CAChD,IAAI,EAAE,cAAc,kBAAA,CAAmB,KAAK,IAAI,GAAG,OAAO;CAE1D,IAAI,gBAAgB,KAAK,IAAI,GAAG,OAAO;CACvC,OAAO;AACT;;;;;;;;;AAUA,SAAgB,sBAAsB,MAAc,MAAc,YAA8B;CAC9F,IAAI,CAAC,KAAK,WAAW,OAAO,GAAG,GAAG,OAAO;CACzC,MAAM,WAAW,KAAK,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,GAAG;CACtD,MAAM,OAAO,SAAS,SAAS,SAAS;CACxC,KAAK,IAAI,QAAQ,GAAG,QAAQ,SAAS,SAAS,GAAG,SAC/C,IAAI,oBAAoB,SAAS,QAAQ,KAAK,GAAG,OAAO;CAE1D,OAAO,iBAAiB,MAAM,SAAS,SAAS,GAAG,UAAU;AAC/D;;;;;;;;AASA,eAAsB,uBACpB,KACA,KACA,WACA,QAAQ,GACR,YACe;CACf,IAAI;CACJ,IAAI;EACF,UAAU,MAAM,QAAQ,KAAK,EAAE,eAAe,KAAK,CAAC;CACtD,SAAS,OAAO;EACd,UAAU;GACR;GACA,SAAS,0BAA0B,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;EAC1F,CAAC;EACD;CACF;CACA,KAAK,MAAM,SAAS,SAAS;EAC3B,MAAM,OAAO,KAAK,KAAK,MAAM,IAAI;EACjC,IAAI,MAAM,YAAY,GAAG;GACvB,IAAI,oBAAoB,MAAM,MAAM,KAAK,GAAG;GAC5C,MAAM,uBAAuB,MAAM,KAAK,WAAW,QAAQ,GAAG,UAAU;EAC1E,OAAO,IAAI,MAAM,OAAO,KAAK,iBAAiB,MAAM,MAAM,OAAO,UAAU,GACzE,IAAI,KAAK,IAAI;CAEjB;AACF"}