@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

package/src/index.rsc.ts

@@ -65,6 +65,12 @@ export type {
   ErrorPhase,
   OnErrorContext,
   OnErrorCallback,
+  // View transition types (also exported from the default entry; route
+  // definitions resolve to this react-server entry, so they must be here too)
+  TransitionConfig,
+  TransitionWhenFn,
+  TransitionWhenContext,
+  ViewTransitionClass,
 } from "./types.js";
 
 // Router options type (server-only, so import directly)
@@ -75,6 +81,13 @@ export type {
   ResolveStreamingContext,
 } from "./router.js";
 
+// Origin-check callback types (referenced by the RangoOptions.originCheck JSDoc)
+export type {
+  OriginCheckConfig,
+  OriginCheckContext,
+  OriginCheckPhase,
+} from "./rsc/origin-guard.js";
+
 // Server-side createLoader and redirect
 export {
   createLoader,
@@ -90,7 +103,6 @@ export {
   loading,
   parallel,
   intercept,
-  when,
   errorBoundary,
   notFoundBoundary,
   transition,
@@ -107,6 +119,12 @@ export type {
 
 // Handle API
 export { createHandle, isHandle, type Handle } from "./handle.js";
+export {
+  DEFAULT_DEFER_TIMEOUT_MS,
+  type DeferOptions,
+  type HandlePush,
+  type HandlePushFn,
+} from "./defer.js";
 
 // Context variable API (typed ctx.set/ctx.get tokens)
 export { createVar, type ContextVar } from "./context-var.js";
@@ -124,22 +142,27 @@ export {
   type BuildContext,
   type StaticBuildContext,
   type GetParamsContext,
+  type PrerenderPassthroughResult,
 } from "./prerender.js";
 
 // Static handler API
-export { Static, type StaticHandlerDefinition } from "./static-handler.js";
+export {
+  Static,
+  type StaticHandlerDefinition,
+  type StaticHandlerOptions,
+} from "./static-handler.js";
 
 // Django-style URL patterns (RSC/server context)
 export {
   urls,
   type PathHelpers,
   type PathOptions,
+  type PartialPrerenderProps,
   type UrlPatterns,
   type IncludeOptions,
   type IncludeItem,
   type RouteResponse,
-  type ResponseError,
-  type ResponseEnvelope,
+  type ProblemDetails,
   type ResponseHandler,
   type ResponseHandlerContext,
   type JsonResponseHandler,
@@ -163,6 +186,11 @@ export type { HandlerCacheConfig } from "./rsc/types.js";
 
 // Built-in handles (server-side)
 export { Meta } from "./handles/meta.js";
+export {
+  Script,
+  type ScriptConfig,
+  type ScriptAttributes,
+} from "./handles/script.js";
 export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
 
 // Request context (for accessing request data in server actions/components).
@@ -185,16 +213,31 @@ export const getRequestContext: <
 export {
   cookies,
   headers,
+  invalidateClientCache,
+  keepClientCache,
   type CookieStore,
   type Cookie,
   type ReadonlyHeaders,
 } from "./server/cookie-store.js";
 
+// Cache tag APIs (server-only)
+// cacheTag: tag the current "use cache" entry at runtime.
+// updateTag: read-your-own-writes invalidation (awaitable, for Server Actions).
+// revalidateTag: background hard-purge invalidation (not awaited, for route handlers / webhooks).
+export { cacheTag } from "./cache/cache-tag.js";
+export { updateTag, revalidateTag } from "./cache/tag-invalidation.js";
+
 // Meta types
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
 
 // Middleware context types
-export type { MiddlewareContext, CookieOptions } from "./router/middleware.js";
+export type {
+  MiddlewareContext,
+  CookieOptions,
+  // The function type of a middleware. Public so the documented "extract the
+  // middleware and unit-test it with runMiddleware" pattern has a nameable type.
+  MiddlewareFn,
+} from "./router/middleware.js";
 
 // Reverse type utilities for type-safe URL generation (Django-style URL reversal)
 export type {
@@ -225,11 +268,48 @@ export {
 // Path and response types are ambient on the `Rango` namespace (`Rango.Path`,
 // `Rango.PathResponse`, declared in href-client.ts) — no import needed.
 
-// Telemetry sink
+// Telemetry sink (event-shaped facts)
 export { createConsoleSink } from "./router/telemetry.js";
 export { createOTelSink } from "./router/telemetry-otel.js";
-export type { OTelTracer, OTelSpan } from "./router/telemetry-otel.js";
-export type { TelemetrySink, TelemetryEvent } from "./router/telemetry.js";
+// OTel phase-span adapter for the `tracing` slot (the canonical span layer).
+export { createOTelTracing } from "./router/telemetry-otel.js";
+export type {
+  OTelTracer,
+  OTelActiveSpanTracer,
+  OTelSpan,
+  OTelTracingOptions,
+} from "./router/telemetry-otel.js";
+// The full TelemetryEvent union PLUS its member types, so a consumer writing a
+// TelemetrySink can annotate a per-`type` handler (or construct an event literal
+// in a test) instead of only narrowing the opaque union.
+export type {
+  TelemetrySink,
+  TelemetryEvent,
+  RequestStartEvent,
+  RequestEndEvent,
+  RequestErrorEvent,
+  LoaderStartEvent,
+  LoaderEndEvent,
+  LoaderErrorEvent,
+  HandlerErrorEvent,
+  CacheSegmentStatus,
+  CacheSegmentSignal,
+  CacheDecisionEvent,
+  RevalidationDecisionEvent,
+  RequestTimeoutEvent,
+  OriginCheckRejectedEvent,
+} from "./router/telemetry.js";
+
+// Span tracing config types a consumer annotates. SpanRunner/TraceSpan are the
+// internal runner contract (consumers go through createOTelTracing /
+// createCloudflareTracing, which return a ready RouterTracingConfig) and are not
+// exported.
+export type {
+  RouterTracingConfig,
+  TracePhase,
+  TracePhaseToggles,
+  TracingToggleOptions,
+} from "./router/tracing.js";
 
 // Timeout types and error class
 export { RouterTimeoutError } from "./router/timeout.js";

package/src/index.ts

@@ -82,7 +82,12 @@ export { createLoader } from "./loader.js";
 
 // Route definition types (safe to import anywhere)
 export type { RouteHelpers, RouteHandlers } from "./route-definition.js";
-export type { TransitionConfig, ViewTransitionClass } from "./types.js";
+export type {
+  TransitionConfig,
+  TransitionWhenFn,
+  TransitionWhenContext,
+  ViewTransitionClass,
+} from "./types.js";
 
 // Composition types for reusable callback factories
 export type {
@@ -104,8 +109,8 @@ export type {
   JsonResponsePathFn,
   TextResponsePathFn,
   RouteResponse,
-  ResponseError,
-  ResponseEnvelope,
+  ProblemDetails,
+  PartialPrerenderProps,
 } from "./urls.js";
 
 // Middleware context types
@@ -141,6 +146,12 @@ export function redirect(): never {
 
 // Handle API (universal - works on both server and client)
 export { createHandle, isHandle, type Handle } from "./handle.js";
+export {
+  DEFAULT_DEFER_TIMEOUT_MS,
+  type DeferOptions,
+  type HandlePush,
+  type HandlePushFn,
+} from "./defer.js";
 
 // Context variable API (typed ctx.set/ctx.get tokens)
 export { createVar, type ContextVar } from "./context-var.js";
@@ -218,6 +229,17 @@ export function headers(): never {
   throw serverOnlyStubError("headers");
 }
 
+/**
+ * Client implementation of `invalidateClientCache()`. Unlike the server-only
+ * stubs above this is a REAL function under the `default` condition (it marks
+ * the client's caches stale); the `react-server` condition (index.rsc.ts)
+ * selects the server implementation that writes a rotated `Set-Cookie`.
+ */
+export {
+  invalidateClientCache,
+  keepClientCache,
+} from "./browser/invalidate-client-cache.js";
+
 /**
  * Error-throwing stub for server-only `createReverse` function.
  */
@@ -238,6 +260,18 @@ export function middleware(): never {
 export function revalidate(): never {
   throw serverOnlyStubError("revalidate");
 }
+// Cache tag APIs are server-only (real implementations in index.rsc.ts). These
+// stubs keep the named-export shape identical under the default/non-react-server
+// condition so SSR/client/default bundles that encounter the import link cleanly.
+export function cacheTag(): never {
+  throw serverOnlyStubError("cacheTag");
+}
+export function updateTag(): never {
+  throw serverOnlyStubError("updateTag");
+}
+export function revalidateTag(): never {
+  throw serverOnlyStubError("revalidateTag");
+}
 export function loader(): never {
   throw serverOnlyStubError("loader");
 }
@@ -250,9 +284,6 @@ export function parallel(): never {
 export function intercept(): never {
   throw serverOnlyStubError("intercept");
 }
-export function when(): never {
-  throw serverOnlyStubError("when");
-}
 export function errorBoundary(): never {
   throw serverOnlyStubError("errorBoundary");
 }
@@ -278,6 +309,11 @@ export type {
 
 // Built-in handles (universal — work on both server and client)
 export { Meta } from "./handles/meta.js";
+export {
+  Script,
+  type ScriptConfig,
+  type ScriptAttributes,
+} from "./handles/script.js";
 export { Breadcrumbs } from "./handles/breadcrumbs.js";
 
 // Meta types
@@ -307,16 +343,54 @@ export {
 // Path and response types are ambient on the `Rango` namespace (`Rango.Path`,
 // `Rango.PathResponse`, declared in href-client.ts) — no import needed.
 
-// Telemetry types only — the createConsoleSink/createOTelSink values are
-// server-only and live in index.rsc.ts (the `react-server` condition of the
-// bare `@rangojs/router` import). Re-exporting them as values from this
-// (default/client) entry would pull telemetry.ts and telemetry-otel.ts into
-// the client module graph; both tree-shake to zero bytes but still appear in
-// bundle analysis output and slow build-time module resolution. Consumers
-// who need the values in non-RSC contexts can import from
-// `@rangojs/router/server`.
-export type { OTelTracer, OTelSpan } from "./router/telemetry-otel.js";
-export type { TelemetrySink, TelemetryEvent } from "./router/telemetry.js";
+// Telemetry types only — the createConsoleSink / createOTelSink /
+// createOTelTracing VALUES are server-only and live in index.rsc.ts (the
+// `react-server` condition of the bare `@rangojs/router` import). Re-exporting
+// them as values from this (default/client) entry would pull telemetry.ts and
+// telemetry-otel.ts into the client module graph; both tree-shake to zero bytes
+// but still appear in bundle analysis output and slow build-time module
+// resolution. The factory values are NOT re-exported from `@rangojs/router/server`
+// either — that subpath is internal, not user-facing (see server.ts header).
+// Non-RSC server code imports these TYPES from the root and obtains the factory
+// VALUES from its own router definition module, which resolves to index.rsc.ts
+// under the `react-server` condition.
+export type {
+  OTelTracer,
+  OTelActiveSpanTracer,
+  OTelSpan,
+  OTelTracingOptions,
+} from "./router/telemetry-otel.js";
+// The full TelemetryEvent union PLUS its member types, so a consumer writing a
+// TelemetrySink can annotate a per-`type` handler (or construct an event literal
+// in a test) instead of only narrowing the opaque union.
+export type {
+  TelemetrySink,
+  TelemetryEvent,
+  RequestStartEvent,
+  RequestEndEvent,
+  RequestErrorEvent,
+  LoaderStartEvent,
+  LoaderEndEvent,
+  LoaderErrorEvent,
+  HandlerErrorEvent,
+  CacheSegmentStatus,
+  CacheSegmentSignal,
+  CacheDecisionEvent,
+  RevalidationDecisionEvent,
+  RequestTimeoutEvent,
+  OriginCheckRejectedEvent,
+} from "./router/telemetry.js";
+
+// Span tracing config types a consumer annotates. SpanRunner/TraceSpan are the
+// internal runner contract (consumers go through createOTelTracing /
+// createCloudflareTracing, which return a ready RouterTracingConfig) and are not
+// exported.
+export type {
+  RouterTracingConfig,
+  TracePhase,
+  TracePhaseToggles,
+  TracingToggleOptions,
+} from "./router/tracing.js";
 
 // Timeout types and error class
 export { RouterTimeoutError } from "./router/timeout.js";

package/src/internal-debug.ts

@@ -1,11 +1,12 @@
-// Internal debug gate. Enable with INTERNAL_RANGO_DEBUG=1 in the environment.
-// Uses a Vite define (__RANGO_DEBUG__) for compile-time injection so it works
-// in all runtimes including Cloudflare Workers where process.env is unavailable.
-// Falls back to process.env for non-Vite contexts (tests, direct Node usage).
+// Runtime fallback for non-Vite contexts (Node, tests, raw imports). In the Vite
+// pipeline -- dev and build, every environment -- the router discovery plugin's
+// transform replaces this module with the build-time-resolved flag (see
+// vite/inject-client-debug.ts), so the CLIENT debug flag no longer depends on a
+// `__RANGO_DEBUG__` define being delivered to the browser (which dev did only as
+// an injected global whose presence varied across consumer setups).
+//
+// Keep this module to the single INTERNAL_RANGO_DEBUG export: the transform
+// replaces the whole file, so a second export would be dropped from the bundle.
 export const INTERNAL_RANGO_DEBUG: boolean =
-  typeof __RANGO_DEBUG__ !== "undefined"
-    ? __RANGO_DEBUG__
-    : typeof process !== "undefined" &&
-      Boolean((process as any).env?.INTERNAL_RANGO_DEBUG);
-
-declare const __RANGO_DEBUG__: boolean;
+  typeof process !== "undefined" &&
+  Boolean((process as any).env?.INTERNAL_RANGO_DEBUG);

package/src/loader.rsc.ts

@@ -22,9 +22,13 @@ import {
   getFetchableLoader,
 } from "./server/fetchable-loader-store.js";
 import { missingInjectedIdError } from "./missing-id-error.js";
+import { isUnderTestRunner } from "./runtime-env.js";
 
 export { getFetchableLoader };
 
+// Runtime-fallback counter for bare unit tests (no Vite plugin); process-stable.
+let runtimeLoaderIdCounter = 0;
+
 // Overload 1: With function only (not fetchable)
 export function createLoader<T>(
   fn: LoaderFn<T, Record<string, string | undefined>, any>,
@@ -49,12 +53,21 @@ export function createLoader<T>(
   // Hidden parameter injected by Vite exposeInternalIds plugin
   __injectedId?: string,
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>> {
-  // The $$id will be set on the returned object by Vite plugin
-  // For fetchable loaders, __injectedId is also passed as a parameter
-  const loaderId = __injectedId || "";
+  let loaderId = __injectedId || "";
 
-  if (!loaderId && process.env.NODE_ENV === "development") {
-    throw missingInjectedIdError("Loader", "createLoader");
+  // Under test runner, fall back to synthetic id (recovers fn from registry by $$id).
+  // Otherwise (dev or prod), missing id means unsupported shape — fail loud.
+  if (!loaderId) {
+    if (isUnderTestRunner()) {
+      loaderId = `__rango_runtime_loader_${runtimeLoaderIdCounter++}`;
+    } else if (process.env.NODE_ENV !== "production") {
+      throw missingInjectedIdError("Loader", "createLoader");
+    } else {
+      throw new Error(
+        "[rango] Loader is missing $$id — the build plugin did not inject one. " +
+          "Export it as `export const X = createLoader(...)`.",
+      );
+    }
   }
 
   // If not fetchable, store fn in registry (for SSR ctx.use() resolution)
@@ -69,12 +82,9 @@ export function createLoader<T>(
     };
   }
 
-  // Fetchable loader - store fn in registry and return a serializable object
+  // Fetchable loader - store fn in registry and return a serializable object.
   const middleware: MiddlewareFn[] =
     fetchable === true ? [] : fetchable?.middleware || [];
-
-  // Register the function in the internal registry by $$id (server-side only)
-  // The loader fetch handler looks it up by $$id when load() is called from the client.
   if (fn && loaderId) {
     registerFetchableLoader(loaderId, fn, middleware, true);
   }

package/src/loader.ts

@@ -19,6 +19,7 @@ import type {
   LoaderFn,
 } from "./types.js";
 import { missingInjectedIdError } from "./missing-id-error.js";
+import { isUnderTestRunner } from "./runtime-env.js";
 
 // Overload 1: With function only (not fetchable)
 export function createLoader<T>(
@@ -37,8 +38,7 @@ export function createLoader<T>(
   options: FetchableLoaderOptions,
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
 
-// Implementation - client stub that just returns the loader definition
-// The $$id parameter is injected by Vite plugin, not user-provided
+// Implementation - client stub ($$id injected by Vite plugin, not user-provided)
 export function createLoader<T>(
   _fn: LoaderFn<T, Record<string, string | undefined>, any>,
   _fetchable?: true | FetchableLoaderOptions,
@@ -46,8 +46,16 @@ export function createLoader<T>(
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>> {
   const loaderId = __injectedId || "";
 
-  if (!loaderId && process.env.NODE_ENV === "development") {
-    throw missingInjectedIdError("Loader", "createLoader");
+  // Under test runner, no id needed (loaderId stays ""; loader.rsc.ts provides fallback).
+  // Otherwise, missing id means unsupported shape — fail loud to avoid wrong key.
+  if (!loaderId && !isUnderTestRunner()) {
+    if (process.env.NODE_ENV !== "production") {
+      throw missingInjectedIdError("Loader", "createLoader");
+    }
+    throw new Error(
+      "[rango] Loader is missing $$id — the build plugin did not inject one. " +
+        "Export it as `export const X = createLoader(...)`.",
+    );
   }
 
   return {

package/src/outlet-provider.tsx

@@ -5,11 +5,7 @@ import { OutletContext, type OutletContextValue } from "./outlet-context.js";
 import type { ResolvedSegment } from "./types.js";
 
 /**
- * Provider for outlet content - used internally by renderSegments
- *
- * Stores a reference to parent context so useLoader can walk up the chain
- * to find loader data from parent layouts. If this segment defines a loading
- * component, Outlet will wrap content with Suspense using that as fallback.
+ * Outlet content provider — stores parent context for useLoader chain walking.
  */
 export function OutletProvider({
   content,

package/src/prerender/param-hash.ts

@@ -1,32 +1,32 @@
 /**
  * Deterministic param hashing for prerender storage keys.
- *
- * Used at build time (child process) to generate filenames and at
- * runtime (worker) to look up pre-rendered data. Both environments
- * must produce identical hashes for the same params.
- *
- * Uses a simple DJB2-based hash that works in all JS environments
- * (Node.js, Cloudflare Workers, browsers) without crypto imports.
+ * Used at build time and runtime; both must produce identical hashes.
+ * DJB2-based; works in all JS environments without crypto imports.
  */
 
-/**
- * Compute a deterministic hash string from route params.
- * For static routes (no params), returns "_".
- */
+import { encodeKV } from "../encode-kv.js";
+
+// For static routes (no params), returns "_".
 export function hashParams(params: Record<string, string>): string {
   const entries = Object.entries(params);
   if (entries.length === 0) return "_";
 
-  const sorted = entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-  const str = sorted
-    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
-    .join("&");
-  return djb2Hex(str);
+  // Byte-order sort + encodeURIComponent join (see encodeKV); output is
+  // byte-identical to the prior inline implementation, so build-time and
+  // runtime hashes stay stable.
+  return djb2Hex(encodeKV(entries, { sort: true }));
 }
 
 /**
  * DJB2 hash returning an 8-char hex string.
  * Deterministic across all JS runtimes.
+ *
+ * 32-bit output: per-route collision probability hits ~50% near ~77k distinct
+ * param sets (birthday bound). The production store keys solely on
+ * routeName/paramHash and does not verify the canonical param string, so a
+ * collision serves the surviving entry for both param sets. Benign for typical
+ * catalogs; revisit (wider hash or stored-param verification) before
+ * pre-rendering hundreds of thousands of pages per route.
  */
 function djb2Hex(str: string): string {
   let hash = 5381;

package/src/prerender/store.ts

@@ -1,21 +1,17 @@
 /**
- * Prerender Store
- *
- * Reads pre-rendered segment data from the worker bundle at build time.
- * The manifest module is lazily loaded via globalThis.__loadPrerenderManifestModule,
- * a function injected into the RSC entry that returns the manifest module
- * containing a key-to-specifier map and a `loadPrerenderAsset` function
- * that anchors import() resolution relative to the manifest file.
+ * Prerender Store — reads pre-rendered segment data from the worker bundle.
+ * Manifest module (injected via globalThis.__loadPrerenderManifestModule)
+ * contains key-to-specifier map and loadPrerenderAsset for import() resolution.
  */
 
-import type {
-  SerializedSegmentData,
-  SegmentHandleData,
-} from "../cache/types.js";
+import type { SerializedSegmentData } from "../cache/types.js";
 
 export interface PrerenderEntry {
   segments: SerializedSegmentData[];
-  handles: Record<string, SegmentHandleData>;
+  /** RSC-encoded handle map (see handle-snapshot.ts encodeHandles); "" when the
+   *  route pushed no handles. Encoded so Promise/ReactNode handle values survive
+   *  the JSON-serialized build artifact / dev wire, identical to the runtime cache. */
+  handles: string;
 }
 
 export interface PrerenderStore {
@@ -28,7 +24,9 @@ export interface PrerenderStore {
 
 export interface StaticEntry {
   encoded: string;
-  handles: Record<string, unknown[]>;
+  /** RSC-encoded single-segment handle data (see encodeHandleValue); "" when the
+   *  Static handler pushed no handles. */
+  handles: string;
 }
 
 export interface StaticStore {
@@ -99,13 +97,20 @@ export function createPrerenderStore(): PrerenderStore | null {
   if (!globalThis.__loadPrerenderManifestModule) return null;
 
   const cache = new Map<string, Promise<PrerenderEntry | null>>();
-  let manifestModulePromise: Promise<PrerenderManifestModule | null> | null =
-    null;
+  let manifestModulePromise: Promise<PrerenderManifestModule> | null = null;
 
-  function loadManifestModule(): Promise<PrerenderManifestModule | null> {
+  function loadManifestModule(): Promise<PrerenderManifestModule> {
     if (!manifestModulePromise) {
+      // Do not cache a failed manifest-module load: clear the memoized promise
+      // on rejection so the next get() retries, and let the error propagate
+      // (consistent with the per-asset load policy below) instead of caching a
+      // null for the isolate lifetime, which would silently degrade every
+      // prerendered route to a miss after one transient failure.
       manifestModulePromise = globalThis.__loadPrerenderManifestModule!().catch(
-        () => null,
+        (err) => {
+          manifestModulePromise = null;
+          throw err;
+        },
       );
     }
     return manifestModulePromise;
@@ -118,7 +123,6 @@ export function createPrerenderStore(): PrerenderStore | null {
       if (cached) return cached;
 
       const promise = loadManifestModule().then((mod) => {
-        if (!mod) return null;
         const specifier = mod.default[key];
         if (!specifier) return null;
         // Let asset load errors propagate — a missing/corrupted artifact
@@ -127,29 +131,20 @@ export function createPrerenderStore(): PrerenderStore | null {
         // (which the handler stub would misreport as a 404).
         return mod.loadPrerenderAsset(specifier).then((asset) => asset.default);
       });
-      cache.set(key, promise);
+      // Only memoize once the manifest module resolved: a manifest-load
+      // rejection must not poison the per-key cache, or the retry above is moot.
+      cache.set(
+        key,
+        promise.catch((err) => {
+          cache.delete(key);
+          throw err;
+        }),
+      );
       return promise;
     },
   };
 }
 
-/**
- * Load the prerender manifest index for test introspection.
- * Returns the key→specifier map or null if unavailable.
- */
-export async function loadPrerenderManifestIndex(): Promise<Record<
-  string,
-  string
-> | null> {
-  if (!globalThis.__loadPrerenderManifestModule) return null;
-  try {
-    const mod = await globalThis.__loadPrerenderManifestModule();
-    return mod.default;
-  } catch {
-    return null;
-  }
-}
-
 /**
  * Create a static segment store.
  * Production only: backed by globalThis.__STATIC_MANIFEST injected at build time.
@@ -174,7 +169,7 @@ export function createStaticStore(): StaticStore | null {
           const val = mod.default;
           // Normalize: string-only (no handles) or { encoded, handles }
           if (typeof val === "string") {
-            return { encoded: val, handles: {} } as StaticEntry;
+            return { encoded: val, handles: "" } as StaticEntry;
           }
           return val as StaticEntry;
         })