@rangojs/router 0.0.0-experimental.132 → 0.0.0-experimental.133

package/src/browser/server-action-bridge.ts

@@ -12,7 +12,7 @@ import {
   reconcileErrorSegments,
 } from "./segment-reconciler.js";
 import { startTransition } from "react";
-import type { EventController } from "./event-controller.js";
+import type { EventController, ActionHandle } from "./event-controller.js";
 import {
   toNetworkError,
   emitNetworkError,
@@ -58,6 +58,27 @@ export interface ServerActionBridgeConfigWithController extends ServerActionBrid
   ) => Promise<void>;
 }
 
+/**
+ * Merge an action's location-state payload into history.state, restricted to
+ * the keys this action is entitled to write. claimLocationState enforces
+ * last-initiated-wins for same-key concurrent writes (a later-initiated sibling
+ * keeps its value even if this action's response settles afterward); distinct
+ * keys from every concurrent action survive. Arbitration is scoped to the
+ * action's cohort (captured at startAction), so a newer action on another entry
+ * cannot suppress this one. No-op when nothing was set or all keys were already
+ * claimed by a later-initiated sibling in the cohort.
+ */
+function applyActionLocationState(
+  handle: ActionHandle,
+  locationState: Record<string, unknown> | undefined,
+): void {
+  if (!locationState) return;
+  const winning = handle.claimLocationState(locationState);
+  if (Object.keys(winning).length > 0) {
+    mergeLocationState(winning);
+  }
+}
+
 /**
  * Create a server action bridge for handling RSC server actions
  *
@@ -165,8 +186,11 @@ export function createServerActionBridge(
     const locationKey = window.history.state?.key;
     log("action start", { id, argsCount: args.length });
 
-    // Start action in event controller - handles lifecycle tracking
-    const handle = eventController.startAction(id, args);
+    // Start action in event controller - handles lifecycle tracking. The
+    // current history key is the action's cohort: location-state arbitration is
+    // scoped to it so a later action on a different entry cannot suppress this
+    // one (and vice versa).
+    const handle = eventController.startAction(id, args, locationKey);
     // Whether the action's response carried the keepClientCache() directive.
     // Set when the response arrives; gates the deferred invalidation below.
     let keepCache = false;
@@ -627,6 +651,20 @@ export function createServerActionBridge(
         currentInterceptSource: store.getInterceptSourceUrl(),
       });
 
+      // Apply server-set location state exhaustively here, as a successful-
+      // response effect — the terminal switch below decides rendering/refetch,
+      // not whether this metadata survives (every refetch path is storeOnly and
+      // never writes history.state). Gated on NOT navigated-away: the classifier
+      // treats either a pathname OR history-key change as diversion, so this
+      // both honors the "diverted state is dropped" contract AND prevents a
+      // cross-entry write (mergeLocationState writes the CURRENT entry, which a
+      // navigated-away action no longer owns). Done before the switch (and
+      // before the normal branch's async renderSegments) so a slow render racing
+      // a navigation cannot drop it.
+      if (scenario.type !== "navigated-away") {
+        applyActionLocationState(handle, metadata?.locationState);
+      }
+
       switch (scenario.type) {
         case "navigated-away": {
           log("user navigated away during action", {
@@ -679,7 +717,8 @@ export function createServerActionBridge(
           log("consolidation fetch needed", {
             segmentIds: scenario.segmentIds,
           });
-          // Calculate segments to send (exclude the ones we want fresh)
+          // Location state already applied above (pre-switch). Calculate
+          // segments to send (exclude the ones we want fresh).
           const currentSegmentIds = store.getSegmentState().currentSegmentIds;
           const segmentsToSend = currentSegmentIds.filter(
             (sid) => !scenario.segmentIds.includes(sid),
@@ -703,6 +742,8 @@ export function createServerActionBridge(
           // Only update store if history key hasn't changed (user didn't navigate away)
           const currentKeyNow = store.getHistoryKey();
           if (currentKeyNow === currentKey) {
+            // Location state already applied above (pre-switch); this action's
+            // UI render is skipped because a later sibling consolidates.
             store.setSegmentIds(matched);
             const currentHandleData = eventController.getHandleState().data;
             store.cacheSegmentsForHistory(
@@ -742,13 +783,7 @@ export function createServerActionBridge(
             onUpdate({ root: newTree, metadata: metadata! });
           });
 
-          // Apply server-set location state to history.state (non-redirect flow)
-          const actionLocationState = metadata?.locationState;
-          if (actionLocationState) {
-            mergeLocationState(actionLocationState);
-          }
-
-          // Update store state
+          // Location state already applied above (pre-switch). Update store.
           store.setSegmentIds(matched);
           const currentHandleData = eventController.getHandleState().data;
           store.cacheSegmentsForHistory(

package/src/browser/types.ts

@@ -90,6 +90,12 @@ export interface RscMetadata {
   basename?: string;
   /** Whether connection warmup is enabled */
   warmupEnabled?: boolean;
+  /**
+   * Whether the client should hydrate inside React.StrictMode. Carried on the
+   * initial full-render payload only; the browser entry reads it once at
+   * hydration. Defaults to true on the client when omitted.
+   */
+  strictMode?: boolean;
   /**
    * Server-side redirect with optional state (for partial requests).
    * `external: true` (from redirect(url, { external: true })) tells the client

package/src/build/generate-route-types.ts

@@ -24,7 +24,6 @@ export {
   extractIncludesWithDiagnostics,
 } from "./route-types/include-resolution.js";
 export {
-  extractUrlsVariableFromRouter,
   extractUrlsFromRouter,
   extractBasenameFromRouter,
   type UrlsExtractionResult,

package/src/build/route-trie.ts

@@ -15,6 +15,19 @@ import type { FullManifest } from "./generate-manifest.js";
 
 // -- Trie data structures (compact keys for JSON serialization) --
 
+/**
+ * A response-type variant folded into a primary leaf's negotiate list. `pa` is
+ * the variant's own positional param-name array, carried so the runtime can
+ * re-key the matched params under the variant's names when it wins negotiation
+ * (the trie match extracts params under the PRIMARY leaf's pa). Omitted when the
+ * variant has no params; absent/identical pa means no re-key is needed.
+ */
+export interface NegotiateVariant {
+  routeKey: string;
+  responseType: string;
+  pa?: string[];
+}
+
 export interface TrieLeaf {
   /** Route name (e.g., "site.l1_500") */
   n: string;
@@ -35,7 +48,7 @@ export interface TrieLeaf {
   /** Response type for non-RSC routes (json, text, image, any) */
   rt?: string;
   /** Negotiate variants: response-type routes sharing this path */
-  nv?: Array<{ routeKey: string; responseType: string }>;
+  nv?: NegotiateVariant[];
   /** RSC-first: RSC route was defined before response-type variants */
   rf?: true;
 }
@@ -124,6 +137,9 @@ function sortSuffixParams(node: TrieNode): void {
       sorted[suffix] = node.xp[suffix];
     }
     node.xp = sorted;
+    for (const child of Object.values(node.xp)) {
+      sortSuffixParams(child.c);
+    }
   }
   if (node.s) {
     for (const child of Object.values(node.s)) {
@@ -133,11 +149,6 @@ function sortSuffixParams(node: TrieNode): void {
   if (node.p) {
     sortSuffixParams(node.p.c);
   }
-  if (node.xp) {
-    for (const child of Object.values(node.xp)) {
-      sortSuffixParams(child.c);
-    }
-  }
 }
 
 /**
@@ -259,6 +270,19 @@ export function extractAncestryFromTrie(
  * appended to the nv (negotiate variants) array.
  * Multiple response types on the same path are supported (json + text + xml).
  */
+/**
+ * Build a negotiate-variant entry from a leaf being folded into another leaf's
+ * nv list. Carries the variant's positional param names (`pa`) so the runtime
+ * can re-key matched params under the variant's names; omitted when the variant
+ * has none (the common case where primary and variant share the same names is a
+ * no-op re-key regardless).
+ */
+function toVariant(leaf: TrieLeaf, responseType: string): NegotiateVariant {
+  return leaf.pa
+    ? { routeKey: leaf.n, responseType, pa: leaf.pa }
+    : { routeKey: leaf.n, responseType };
+}
+
 function mergeLeaves(existing: TrieLeaf | undefined, leaf: TrieLeaf): TrieLeaf {
   if (!existing) return leaf;
 
@@ -266,7 +290,7 @@ function mergeLeaves(existing: TrieLeaf | undefined, leaf: TrieLeaf): TrieLeaf {
     // Both are response-type: preserve old as variant
     const merged = leaf;
     merged.nv = existing.nv || [];
-    merged.nv.push({ routeKey: existing.n, responseType: existing.rt });
+    merged.nv.push(toVariant(existing, existing.rt));
     return merged;
   }
   if (leaf.rt && !existing.rt) {
@@ -276,7 +300,7 @@ function mergeLeaves(existing: TrieLeaf | undefined, leaf: TrieLeaf): TrieLeaf {
       existing.nv = [];
       existing.rf = true;
     }
-    existing.nv.push({ routeKey: leaf.n, responseType: leaf.rt });
+    existing.nv.push(toVariant(leaf, leaf.rt));
     return existing;
   }
   if (!leaf.rt && existing.rt) {
@@ -284,7 +308,7 @@ function mergeLeaves(existing: TrieLeaf | undefined, leaf: TrieLeaf): TrieLeaf {
     // RSC was defined second (response-type was already the existing leaf)
     if (!leaf.nv) leaf.nv = [];
     if (existing.nv) leaf.nv.push(...existing.nv);
-    leaf.nv.push({ routeKey: existing.n, responseType: existing.rt });
+    leaf.nv.push(toVariant(existing, existing.rt));
     // rf intentionally not set — RSC came after response-type variants
     return leaf;
   }

package/src/build/route-types/include-resolution.ts

@@ -201,7 +201,13 @@ export function resolveImportedVariable(
   code: string,
   localName: string,
 ): { specifier: string; exportedName: string } | null {
-  const importRegex = /import\s*\{([^}]+)\}\s*from\s*["']([^"']+)["']/g;
+  // Allow an optional leading default binding before the named-import brace so
+  // a combined `import Foo, { bar } from "..."` is matched (the named members
+  // are the only part we resolve; the default binding is skipped). Without the
+  // optional `(?:[\w$]+\s*,\s*)?` segment, the `Foo, ` prefix breaks the match
+  // and a legitimate static named import surfaces as `unresolvable-import`.
+  const importRegex =
+    /import\s*(?:[\w$]+\s*,\s*)?\{([^}]+)\}\s*from\s*["']([^"']+)["']/g;
   let match;
 
   while ((match = importRegex.exec(code)) !== null) {

package/src/build/route-types/router-processing.ts

@@ -322,12 +322,6 @@ export function extractBasenameFromRouter(code: string): string | undefined {
   return result;
 }
 
-/** @deprecated Use extractUrlsFromRouter instead */
-export function extractUrlsVariableFromRouter(code: string): string | null {
-  const result = extractUrlsFromRouter(code);
-  return result?.kind === "variable" ? result.name : null;
-}
-
 /** Apply a basename prefix to all route patterns in a result set. */
 function applyBasenameToRoutes(
   result: {

package/src/build/route-types/source-scan.ts

@@ -13,12 +13,19 @@
 // Memory: O(1) for the boolean check; O(#matches) for the index list. No
 // stripped copy and no per-char array are ever materialized.
 //
-// Pragmatic scanner, not a full tokenizer: regex literals are not special-cased
-// (a target token inside one is implausible) and template interpolations are
-// treated as opaque string content. One intentional consequence: a token whose
-// match would only complete by treating an interleaved comment as whitespace
-// (e.g. `createRouter /* x */ (`) is not detected — real calls never interleave
-// a comment between the callee and its arguments.
+// Pragmatic scanner, not a full tokenizer: regex literals ARE coarsely skipped
+// (see below) and template interpolations are treated as opaque string content.
+// One intentional consequence: a token whose match would only complete by
+// treating an interleaved comment as whitespace (e.g. `createRouter /* x */ (`)
+// is not detected — real calls never interleave a comment between the callee
+// and its arguments.
+//
+// Regex literals are skipped because a literal containing a quote or comment
+// char (e.g. `const re = /it's a "x"/g;`) would otherwise open a phantom string
+// at the inner quote and swallow the following REAL code — dropping a router
+// file from discovery. We only treat a `/` as a regex start when it is in
+// "regex position" (the previous significant code char is not value-producing),
+// so genuine division (`a / b`) is left untouched.
 
 // JS line terminators end a `//` comment: LF, CR, LS (U+2028), PS (U+2029).
 function isLineTerminator(ch: string): boolean {
@@ -27,6 +34,56 @@ function isLineTerminator(ch: string): boolean {
   return c === 10 || c === 13 || c === 0x2028 || c === 0x2029;
 }
 
+// Identifier-position keywords after which a `/` begins a regex literal, not
+// division: the keyword cannot be the left operand of a division, so `return
+// /re/`, `typeof /re/`, `case /re/`, etc. are regexes. After any OTHER identifier
+// or number (a value), `/` is division.
+const REGEX_PRECEDING_KEYWORDS = new Set([
+  "return",
+  "typeof",
+  "instanceof",
+  "in",
+  "of",
+  "new",
+  "delete",
+  "void",
+  "do",
+  "else",
+  "yield",
+  "await",
+  "case",
+  "throw",
+]);
+
+// A `/` at `slashPos` is a regex-literal start (not division) when the previous
+// significant code char cannot end an expression. A closing `)`/`]`/`}` and an
+// identifier/digit/`$`/`_` are value-producing (division); everything else
+// (operators, `(`, `,`, `=`, `:`, `{`, `;`, `<`, `>`, ...) and the start-of-file
+// put `/` in regex position. The one subtlety: an identifier that is actually a
+// regex-preceding KEYWORD (`return /re/`) ends in a word char, so the
+// previous-char-only test misread it as division and then let the regex body's
+// inner quotes open a phantom string — dropping a later real `createRouter()`.
+// So when the previous char is a word char we walk back over any whitespace and
+// the identifier and treat `/` as a regex iff that identifier is such a keyword.
+// `}` stays value-producing to avoid swallowing an object/block followed by
+// division; the cost is only that a regex right after a block isn't skipped.
+function isRegexPositionAt(
+  code: string,
+  slashPos: number,
+  prevChar: string | undefined,
+): boolean {
+  if (prevChar === undefined) return true; // start of file
+  if (prevChar === ")" || prevChar === "]" || prevChar === "}") return false;
+  if (!/[\w$]/.test(prevChar)) return true; // operator / `(` / `,` / `=` / ...
+  // Previous char ends an identifier or number: regex only after a keyword that
+  // expects an expression. Walk back over whitespace + the identifier run.
+  let k = slashPos - 1;
+  while (k >= 0 && /\s/.test(code[k])) k--;
+  const wordEnd = k + 1;
+  while (k >= 0 && /[\w$]/.test(code[k])) k--;
+  return REGEX_PRECEDING_KEYWORDS.has(code.slice(k + 1, wordEnd));
+}
+
 /**
  * Build a classifier that answers "is offset `q` in code (not a comment or
  * string)?" for STRICTLY INCREASING `q`. The internal cursor only moves forward,
@@ -37,6 +94,9 @@ function makeCodeClassifier(code: string): (q: number) => boolean {
   let i = 0; // forward cursor: everything before `i` is already classified
   let skipStart = -1; // last detected comment/string region (cache)
   let skipEnd = -1;
+  // Last significant code char, used to disambiguate `/` (regex vs division).
+  // Comments are transparent (don't update it); strings/regex are value-producing.
+  let lastSig: string | undefined;
 
   return (q: number): boolean => {
     if (q >= skipStart && q < skipEnd) return false; // q in the cached region
@@ -44,14 +104,17 @@ function makeCodeClassifier(code: string): (q: number) => boolean {
       const c = code[i];
       const d = i + 1 < n ? code[i + 1] : "";
       let end = -1;
+      let transparent = false; // comment: skipped but does not set lastSig
       if (c === "/" && d === "/") {
         let j = i + 2;
         while (j < n && !isLineTerminator(code[j])) j++;
         end = j;
+        transparent = true;
       } else if (c === "/" && d === "*") {
         let j = i + 2;
         while (j < n && !(code[j] === "*" && code[j + 1] === "/")) j++;
         end = Math.min(n, j + 2);
+        transparent = true;
       } else if (c === '"' || c === "'" || c === "`") {
         let j = i + 1;
         while (j < n) {
@@ -66,16 +129,51 @@ function makeCodeClassifier(code: string): (q: number) => boolean {
           j++;
         }
         end = j;
+      } else if (
+        c === "/" &&
+        d !== "/" &&
+        d !== "*" &&
+        isRegexPositionAt(code, i, lastSig)
+      ) {
+        // Coarse regex-literal skip. A regex literal cannot span a raw newline;
+        // `/` inside a `[...]` character class is literal (not a terminator).
+        // Bail (treat the `/` as a normal char) if no closing `/` on the line
+        // so a stray division-looking `/` never swallows the rest of the line.
+        let j = i + 1;
+        let inClass = false;
+        let closed = false;
+        while (j < n && !isLineTerminator(code[j])) {
+          const r = code[j];
+          if (r === "\\") {
+            j += 2;
+            continue;
+          }
+          if (r === "[") inClass = true;
+          else if (r === "]") inClass = false;
+          else if (r === "/" && !inClass) {
+            j++;
+            closed = true;
+            break;
+          }
+          j++;
+        }
+        if (closed) {
+          while (j < n && /[a-z]/.test(code[j])) j++; // flags
+          end = j;
+        }
       }
       if (end >= 0) {
-        // Comment/string region [i, end). `q >= i` here (loop condition).
+        // Comment/string/regex region [i, end). `q >= i` here (loop condition).
         if (q < end) {
           skipStart = i;
           skipEnd = end;
           return false;
         }
         i = end;
+        // Strings and regex literals are value-producing; comments are not.
+        if (!transparent) lastSig = "x";
       } else {
+        if (!/\s/.test(c)) lastSig = c;
         i++;
       }
     }

package/src/cache/cache-policy.ts

@@ -10,6 +10,7 @@ import type { CacheDefaults, SegmentCacheStore } from "./types.js";
 import { _getRequestContext } from "../server/request-context.js";
 import type { RequestContext } from "../server/request-context.js";
 import { normalizeTags } from "./cache-tag.js";
+import { reportCacheError } from "./cache-error.js";
 
 /**
  * Default TTL for route-level cache() DSL and loader cache.
@@ -23,31 +24,62 @@ export const DEFAULT_ROUTE_TTL = 60;
  */
 export const DEFAULT_FUNCTION_TTL = 900;
 
+/**
+ * A finite, non-negative seconds value? A NaN/Infinity ttl/swr (from a bad
+ * cache() option or store defaults) flows into computeExpiration ->
+ * staleAt/expiresAt = NaN, where every `now > NaN` is false so the entry never
+ * evicts and is served fresh forever; a negative value makes every read a miss.
+ * Shared with cache-scope.ts (the segment getters) so every cache path validates
+ * the same way. profile-registry.ts uses the same predicate but fails fast at
+ * config time; the resolvers here degrade because they run on the live path.
+ */
+export function isFiniteNonNegativeSeconds(value: number): boolean {
+  return Number.isFinite(value) && value >= 0;
+}
+
+function warnInvalidSeconds(label: string, value: number): void {
+  if (process.env.NODE_ENV !== "production") {
+    console.warn(`[cache] Invalid ${label} ${value}; falling back to default`);
+  }
+}
+
 /**
  * Resolve effective TTL from the 3-tier cascade:
- * explicit → store defaults → fallback.
+ * explicit → store defaults → fallback. A non-finite/negative resolved value
+ * degrades to the fallback (loader cache and "use cache" setItem both resolve
+ * ttl here, so this is where those paths are guarded; the segment cache is
+ * guarded in cache-scope.ts).
  */
 export function resolveTtl(
   explicit: number | undefined,
   defaults: CacheDefaults | undefined,
   fallback: number,
 ): number {
-  if (explicit !== undefined) return explicit;
-  if (defaults?.ttl !== undefined) return defaults.ttl;
+  let value: number;
+  if (explicit !== undefined) value = explicit;
+  else if (defaults?.ttl !== undefined) value = defaults.ttl;
+  else return fallback;
+  if (isFiniteNonNegativeSeconds(value)) return value;
+  warnInvalidSeconds("ttl", value);
   return fallback;
 }
 
 /**
  * Resolve effective SWR window from the 2-tier cascade:
  * explicit → store defaults.
- * Returns 0 when unset (no SWR window).
+ * Returns 0 when unset (no SWR window) or when the resolved value is
+ * non-finite/negative (degrade rather than feed bad math into expiry).
  */
 export function resolveSwrWindow(
   explicit: number | undefined,
   defaults: CacheDefaults | undefined,
 ): number {
-  if (explicit !== undefined) return explicit;
-  if (defaults?.swr !== undefined) return defaults.swr;
+  let value: number;
+  if (explicit !== undefined) value = explicit;
+  else if (defaults?.swr !== undefined) value = defaults.swr;
+  else return 0;
+  if (isFiniteNonNegativeSeconds(value)) return value;
+  warnInvalidSeconds("swr", value);
   return 0;
 }
 
@@ -105,9 +137,11 @@ export function resolveTagsOption<TEnv>(
     try {
       return normalizeTagList(tags(ctx));
     } catch (error) {
-      console.error(
-        `[${label}] Tags function failed, caching without tags:`,
+      reportCacheError(
         error,
+        "cache-write",
+        `[${label}] Tags function failed, caching without tags`,
+        ctx,
       );
       return undefined;
     }

package/src/cache/cache-runtime.ts

@@ -40,6 +40,7 @@ import {
 } from "./handle-snapshot.js";
 import { startHandleCapture, type HandleCapture } from "./handle-capture.js";
 import { sortedSearchString } from "./cache-key-utils.js";
+import { encodeKV } from "../encode-kv.js";
 import { runBackground } from "./background-task.js";
 import {
   normalizeTags,
@@ -49,15 +50,74 @@ import {
 import { reportCacheError } from "./cache-error.js";
 import type { CacheItemResult } from "./types.js";
 
+/**
+ * DJB2 hash returning an 8-char hex string. Deterministic across runtimes
+ * (no crypto import — cache-runtime runs on the edge). Mirrors prerender's
+ * param-hash djb2Hex so binary key parts hash consistently.
+ */
+function djb2HexBytes(bytes: Uint8Array): string {
+  let hash = 5381;
+  for (let i = 0; i < bytes.length; i++) {
+    hash = ((hash << 5) + hash + bytes[i]!) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+
 /**
  * Convert encodeReply result to a stable string key.
- * encodeReply may return string or FormData — normalize to string.
+ *
+ * encodeReply may return a string or FormData. A plain string is already
+ * deterministic for a given arg set, so return it verbatim. FormData (emitted
+ * whenever a key arg is a typed array / Blob / File / a large object React
+ * lazily chunks) carries a per-call RANDOM multipart boundary
+ * (`formdata-undici-<random>`); stringifying the whole body via
+ * `new Response(formData).text()` would therefore produce a DIFFERENT key on
+ * every call, so the cached function would always miss and the store would
+ * accumulate one duplicate entry per call (unbounded growth).
+ *
+ * Instead derive the key from the entries themselves, independent of the
+ * boundary: iterate in sorted-key order and, for each value, emit a
+ * boundary-free token — `s:<value>` for strings, `b:<size>:<type>:<name>:<hash>`
+ * for Blob/File (bytes folded via djb2 so distinct payloads of equal
+ * size/type/name still differ). Strings carry an `s:` type tag so a string whose
+ * value happens to equal a blob token (e.g. the literal `b:4::a:b:<hash>`) cannot
+ * collide with an actual Blob/File entry under the same FormData key. The
+ * user-controlled `type`/`name` are percent-encoded before joining so an embedded
+ * `:` cannot shift the field boundaries and collide two distinct files (e.g.
+ * {name:"a:b",type:""} vs {name:"b",type:":a"}). The result is stable across
+ * identical arg sets.
  */
-async function replyToCacheKey(encoded: string | FormData): Promise<string> {
+export async function replyToCacheKey(
+  encoded: string | FormData,
+): Promise<string> {
   if (typeof encoded === "string") return encoded;
-  // FormData: convert to Response body, then to string for deterministic key
-  const text = await new Response(encoded).text();
-  return text;
+
+  // Snapshot entries synchronously (forEach avoids relying on FormData's
+  // iterator typings), then fold any Blob/File bytes asynchronously.
+  const raw: [string, FormDataEntryValue][] = [];
+  encoded.forEach((value, key) => {
+    raw.push([key, value]);
+  });
+  const pairs: [string, string][] = [];
+  for (const [key, value] of raw) {
+    if (typeof value === "string") {
+      // Type-tag strings with `s:` so a string equal to a blob token (e.g.
+      // `b:4::a:b:<hash>`) cannot collide with a Blob/File entry under the same
+      // key (which carries the `b:` tag below).
+      pairs.push([key, "s:" + value]);
+    } else {
+      // Blob/File: fold the bytes into a deterministic, boundary-free token.
+      // Percent-encode the user-controlled type/name so an embedded `:` cannot
+      // shift the `:`-delimited field boundaries and collide distinct files.
+      const buf = await value.arrayBuffer();
+      const hash = djb2HexBytes(new Uint8Array(buf));
+      const name = "name" in value ? value.name : "";
+      const encType = encodeURIComponent(value.type);
+      const encName = encodeURIComponent(name);
+      pairs.push([key, `b:${value.size}:${encType}:${encName}:${hash}`]);
+    }
+  }
+  return encodeKV(pairs, { sort: true });
 }
 
 // Cached-fn ids already warned about running uncached under a test runner, so