@rangojs/router 0.4.3 → 0.5.1

package/skills/parallel/SKILL.md

@@ -273,7 +273,7 @@ parallel(
 
 Per-slot merge order is **handler.use → shared use → slot-local use**. Slot-local is the narrowest scope, so it wins for last-write-wins items. See [skills/handler-use § `loading()` is a single-assignment item — scope it correctly](../handler-use/SKILL.md#loading-is-a-single-assignment-item--scope-it-correctly) for the full reasoning.
 
-Typing note: a BARE arrow slot handler infers its ctx (`"@cart": (ctx) => ...`), but an arrow inside a DESCRIPTOR needs an explicit annotation — `handler: (ctx: HandlerContext) => ...` — because `StaticHandlerDefinition` in the slot union contributes a second callable to the contextual type and TS declines to pick a signature.
+Both a bare arrow slot handler (`"@cart": (ctx) => ...`) and an arrow inside a descriptor (`handler: (ctx) => ...`) infer their `ctx`; no explicit annotation is needed.
 
 ## Slot Override Semantics
 

package/skills/ppr/SKILL.md

@@ -358,14 +358,27 @@ curl -s -D - -o /dev/null https://app.example.com/products/1 | grep -i x-rango-s
   falls through to KV on a miss, and promotes the KV hit back into that colo.
   WITHOUT a KV namespace its shell family remains inert: every ppr route stays
   `MISS` forever. The store warns once per isolate — bind KV
-  (`new CFCacheStore({ ctx, kv: env.CACHE_KV })`) or use another store.
+  (`new CFCacheStore({ ctx, kv: env.CACHE_KV })`) or use another store. An
+  inert store also stops captures at the gate: the store declares
+  `shellFamilyInert` and the scheduler skips the background render entirely
+  (`skip-inert-store` on the debug event) instead of burning a full capture per
+  MISS whose write could only no-op.
 - Structured capture diagnostics: `createRouter({ debugShellCapture: true })`
   logs one line per capture attempt/skip (outcome, durations, prelude and
   snapshot bytes, backoff state); pass a function to receive each
   `ShellCaptureDebugEvent` instead. `skip-capacity` means the isolate already
   has 32 queued/running captures; the dropped best-effort capture can retry on a
-  later request. In dev, with `debugPerformance` on, the
-  last capture outcome for a key also rides the next document GET's
+  later request. `skip-queue-timeout` means this capture waited 15s behind the
+  active or same-priority work and was dropped before rendering; document-shell
+  captures outrank queued navigation-only snapshots, but never interrupt the
+  active capture — the skip event and the `rango.background` span carry
+  `queuePriority`/`queueAhead` (class and backlog at enqueue) so a parked
+  capture diagnoses itself. A stored attempt reports `bakeWaitMs`: how long the
+  slowest bake source (a top-level pushed handle promise or a bake-lane loader
+  container) held the capture gate — in dev, past 2s, the source is also named
+  once per key in a console warning with the remedies (nest the promise /
+  `cache()` the work / add `loading()`). In dev, with `debugPerformance` on,
+  the last capture outcome for a key also rides the next document GET's
   `Server-Timing` as `ppr-capture;desc="…"`.
 - For deployed Cloudflare tier diagnostics, build with
   `INTERNAL_RANGO_DEBUG=1` and run `wrangler tail`. `[CFCacheStore][shell]`
@@ -621,6 +634,34 @@ capture with identity reads permitted, and the value bakes as a shared
 capture-time copy — mirroring `cache()` semantics (the consumption-lane
 rule; semantic-matrix row PPR3).
 
+### Designing routes for cheap captures (the cost model)
+
+The hole doctrine has a cost corollary that bites silently: **everything that
+bakes is awaited at capture, and that wait recurs on EVERY capture of the
+route**. A top-level pushed handle promise that takes 5s and a Meta promise
+chained 2s further make every capture occupy the per-isolate serialized queue
+for ~7s — while the served response still reads 13ms TTFB, because captures are
+detached. You will not see this cost in any request timing; you see it as slow
+MISS→HIT flips, `skip-queue-timeout` under prefetch pressure, and (in dev, past
+2s) the bake-cost warning naming the source.
+
+Three levers, in preference order:
+
+1. **Nest it** (`{ data: promise }` instead of the promise): the value becomes
+   a hole — per-request, streamed under the consumer's `<Suspense>`, zero
+   capture cost. Choose this whenever the value may be dynamic anyway.
+2. **`cache()` the work inside it**: the value stays baked (shell material,
+   tag-invalidatable), but the capture replays the cached value instead of
+   re-executing the expensive body (mixed-chain). Choose this for shared,
+   expensive-to-compute shell content.
+3. **`loading()` on the entry** (loaders only): moves the loader to the live
+   lane — masked at capture, fresh per serve — at the cost of a fallback in
+   the shell.
+
+Head material (Meta) generally cannot be a hole — the head is shell — so its
+promises bake by design; make them cheap with lever 2. `bakeWaitMs` on the
+capture debug event tells you what each capture actually paid.
+
 ## Execution matrix
 
 | Phase            | MISS (foreground)      | Background capture                                                 | HIT (foreground)                                            |

package/src/browser/prefetch/cache.ts

@@ -72,8 +72,31 @@ export interface DecodedPrefetch {
    * tell a FULLY warmed prefetch (payload commits without suspending → safe to
    * commit in a startTransition, no fallback flash) from a partially-warmed one
    * (still streaming → stream its fallbacks like a cold load). Starts false.
+   *
+   * On a respawned entry (see `respawn`) this starts true: the buffered bytes
+   * are a complete stream by construction.
    */
   complete: boolean;
+  /**
+   * Re-create this entry from its buffered raw Flight bytes. Attached (by
+   * `executePrefetchFetch`) only after the stream ended cleanly AND the eager
+   * decode succeeded — a truncated or failed prefetch must stay one-shot.
+   *
+   * Why bytes and not the decoded payload: the revived payload is a live graph
+   * with one-shot stream edges (the handle stream is an async generator drained
+   * during commit; userland payloads may embed serialized ReadableStreams).
+   * Re-decoding from the wire bytes manufactures fresh instances of every
+   * stream, which no amount of cloning the revived graph can do. Each call tees
+   * the reserve branch, so the replacement entry carries its own `respawn` —
+   * one prefetch serves unlimited adoptions within TTL/state validity.
+   */
+  respawn?: () => DecodedPrefetch;
+  /**
+   * Release the buffered reserve bytes. Called when the entry is evicted
+   * without being consumed (expiry, FIFO, sweep, cache clear) so the tee
+   * buffer is dropped promptly instead of waiting for GC.
+   */
+  dispose?: () => void;
 }
 
 let cacheTTL = 300_000;
@@ -208,6 +231,7 @@ export function hasPrefetch(key: string): boolean {
   const entry = cache.get(key);
   if (!entry) return false;
   if (Date.now() - entry.timestamp > cacheTTL) {
+    entry.entry.dispose?.();
     cache.delete(key);
     return false;
   }
@@ -216,22 +240,34 @@ export function hasPrefetch(key: string): boolean {
 
 /**
  * Consume a cached, eagerly-decoded prefetch. Returns null if not found or
- * expired. One-time consumption: the entry is deleted after retrieval.
- * Returns null when caching is disabled (TTL <= 0).
+ * expired. Returns null when caching is disabled (TTL <= 0).
+ *
+ * A decoded payload is single-render (its handle stream is drained during the
+ * commit), so the returned entry is never served twice. When the entry carries
+ * `respawn` (clean-EOF prefetch with buffered bytes), the slot is re-armed in
+ * place with a fresh decode of those bytes — the ORIGINAL timestamp is kept so
+ * TTL bounds the age of the data, not of the latest adoption. Without
+ * `respawn` the entry is deleted (legacy one-shot behavior).
  *
  * Does NOT check in-flight prefetches — use consumeInflightPrefetch()
  * for that (returns a Promise instead of a resolved entry).
  */
 export function consumePrefetch(key: string): DecodedPrefetch | null {
   if (cacheTTL <= 0) return null;
-  const entry = cache.get(key);
-  if (!entry) return null;
-  if (Date.now() - entry.timestamp > cacheTTL) {
+  const cached = cache.get(key);
+  if (!cached) return null;
+  if (Date.now() - cached.timestamp > cacheTTL) {
+    cached.entry.dispose?.();
     cache.delete(key);
     return null;
   }
-  cache.delete(key);
-  return entry.entry;
+  const entry = cached.entry;
+  if (entry.respawn) {
+    cached.entry = entry.respawn();
+  } else {
+    cache.delete(key);
+  }
+  return entry;
 }
 
 /**
@@ -301,6 +337,7 @@ export function storePrefetch(
     let min = Infinity;
     for (const [k, cached] of cache) {
       if (now - cached.timestamp > cacheTTL) {
+        cached.entry.dispose?.();
         cache.delete(k);
       } else if (cached.timestamp < min) {
         min = cached.timestamp;
@@ -312,7 +349,10 @@ export function storePrefetch(
   // FIFO eviction if at capacity
   if (cache.size >= maxPrefetchCacheSize) {
     const oldest = cache.keys().next().value;
-    if (oldest) cache.delete(oldest);
+    if (oldest) {
+      cache.get(oldest)?.entry.dispose?.();
+      cache.delete(oldest);
+    }
   }
 
   cache.set(key, { entry, timestamp: now });
@@ -335,7 +375,10 @@ export function storePrefetch(
  * entry.
  */
 export function removePrefetch(key: string, entry: DecodedPrefetch): void {
-  if (cache.get(key)?.entry === entry) cache.delete(key);
+  if (cache.get(key)?.entry === entry) {
+    entry.dispose?.();
+    cache.delete(key);
+  }
 }
 
 /**
@@ -405,6 +448,7 @@ export function clearPrefetchCache(rotateRangoState = true): void {
   inflightPromises.clear();
   inflightAliases.clear();
   adoptedKeys.clear();
+  for (const cached of cache.values()) cached.entry.dispose?.();
   cache.clear();
   earliestTimestamp = Infinity;
   abortAllPrefetches();

package/src/browser/prefetch/fetch.ts

@@ -70,6 +70,49 @@ export function setPrefetchDecoder(fn: PrefetchDecoder): void {
   decoder = fn;
 }
 
+/**
+ * Build the respawn closure for a cleanly-completed prefetch entry. Each call
+ * tees the reserve byte branch: one side feeds a fresh decode — a fresh handle
+ * stream and fresh serialized-stream instances, which no cloning of the
+ * revived payload graph could produce — and the other becomes the next
+ * reserve, so the replacement entry can respawn again. `streamComplete`
+ * resolves immediately and `complete` starts true: the buffered bytes are a
+ * finished stream by construction. The chunk imports the decode triggers are
+ * already in the module cache from the original eager decode, so a respawn
+ * costs ~ms with no network.
+ */
+function makeRespawn(
+  storageKey: string,
+  reserve: ReadableStream<Uint8Array>,
+  scope: "source" | "wildcard",
+): () => DecodedPrefetch {
+  return () => {
+    const [body, nextReserve] = reserve.tee();
+    // decoder is non-null here: respawn is only armed after a successful
+    // eager decode, which requires the decoder to have been set.
+    const payload = decoder!(Promise.resolve(new Response(body)));
+    payload.catch(() => {});
+    const entry: DecodedPrefetch = {
+      payload,
+      streamComplete: Promise.resolve(),
+      scope,
+      complete: true,
+      dispose: () => {
+        // Rejects (caught) instead of throwing if the branch is already
+        // locked by a later respawn — cache eviction never races adoption on
+        // the same entry object, so this is belt-and-braces.
+        nextReserve.cancel().catch(() => {});
+      },
+    };
+    entry.respawn = makeRespawn(storageKey, nextReserve, scope);
+    // Parity with the original path: a rejected decode must not stay
+    // consumable. Clean bytes should never fail to decode, but if they do,
+    // evict (identity-guarded) so navigation refetches instead.
+    payload.catch(() => removePrefetch(storageKey, entry));
+    return entry;
+  };
+}
+
 /**
  * Check if a URL resolves to the current page (same pathname + search).
  * Used to prevent same-page prefetching, which produces a trivial diff
@@ -271,9 +314,23 @@ function executePrefetchFetch(
         true,
       );
 
+      // Split the decode branch: one side feeds the eager decoder (unchanged —
+      // client chunks still import at prefetch time), the other stays unread as
+      // a reserve of the raw Flight bytes. A decoded payload is single-render
+      // (its handle stream drains during commit), so adoption would otherwise
+      // spend the entry; the reserve lets a cleanly-completed entry respawn a
+      // fresh decode per adoption instead (see makeRespawn).
+      let decodeSource: Response = tracked;
+      let reserve: ReadableStream<Uint8Array> | undefined;
+      if (tracked.body) {
+        const [decodeBody, reserveBody] = tracked.body.tee();
+        decodeSource = new Response(decodeBody, { headers: tracked.headers });
+        reserve = reserveBody;
+      }
+
       // Eager decode: parsing the Flight stream imports the route's client
       // chunks now, not on click.
-      const payload = decoder(Promise.resolve(tracked));
+      const payload = decoder(Promise.resolve(decodeSource));
       // Mark handled so an unconsumed prefetch decode error stays quiet; the
       // error is still surfaced to navigation if it consumes the entry.
       payload.catch(() => {});
@@ -283,6 +340,11 @@ function executePrefetchFetch(
         streamComplete,
         scope,
         complete: false,
+        ...(reserve && {
+          dispose: () => {
+            reserve.cancel().catch(() => {});
+          },
+        }),
       };
       storePrefetch(storageKey, entry, gen);
       // The stall timeout now owns the body stream: arm eviction (publishedKey)
@@ -301,10 +363,29 @@ function executePrefetchFetch(
       streamComplete.then(() => {
         if (!endedCleanly) removePrefetch(storageKey, entry);
       });
-      // Mark complete ONLY on a fully-healthy prefetch (decode resolved AND clean EOF).
+      // Mark complete ONLY on a fully-healthy prefetch (decode resolved AND
+      // clean EOF) — and only then arm respawn: a truncated or failed stream's
+      // reserve would replay broken bytes, so it stays one-shot (and its
+      // buffered reserve is released via the removePrefetch dispose above).
       Promise.allSettled([payload, streamComplete]).then(([decode]) => {
         if (decode.status === "fulfilled" && endedCleanly) {
           entry.complete = true;
+          if (reserve) {
+            entry.respawn = makeRespawn(storageKey, reserve, scope);
+            // Refill after an early adoption. A click that lands before this
+            // point adopts the entry with respawn unarmed and leaves the slot
+            // empty — via either path: pre-headers inflight adoption makes
+            // storePrefetch skip publication (adoptedKeys), and a mid-stream
+            // cache adoption deletes the incomplete entry. Now that the bytes
+            // proved themselves complete, publish a respawned sibling so the
+            // revisit is warm. Guards: hasPrefetch skips when the slot is
+            // live again (our own un-adopted entry, a fresh entry, or a new
+            // in-flight prefetch), and storePrefetch's generation check drops
+            // the sibling if the cache was invalidated since the fetch began.
+            if (!hasPrefetch(storageKey)) {
+              storePrefetch(storageKey, entry.respawn(), gen);
+            }
+          }
         }
         clearTimeout(timeoutId);
       });

package/src/cache/cf/cf-cache-store.ts

@@ -267,10 +267,13 @@ interface KVItemEnvelope {
  * @internal
  */
 interface CFShellEnvelope {
-  /** base64-encoded prelude bytes */
-  p: string;
-  /** postponed state JSON, or null (DATA variant — no holes) */
-  po: string | null;
+  /**
+   * base64-encoded prelude bytes. Absent iff `no` (navigationOnly entries
+   * store no document half — ShellCacheEntry.prelude).
+   */
+  p?: string;
+  /** postponed state JSON, or null (DATA variant — no holes). Absent iff `no`. */
+  po?: string | null;
   /** React.version captured at prerender time */
   rv: string;
   /** Build version captured at prerender time (ShellCacheEntry.buildVersion) */
@@ -347,8 +350,14 @@ function isShellEnvelope(value: unknown): value is CFShellEnvelope {
   if (value == null || typeof value !== "object") return false;
   const envelope = value as Partial<CFShellEnvelope>;
   return (
-    typeof envelope.p === "string" &&
-    (envelope.po === null || typeof envelope.po === "string") &&
+    // Document half: required unless the envelope is navigationOnly (`no`),
+    // which stores neither field. Tolerate a legacy navigationOnly envelope
+    // that still carries them.
+    (typeof envelope.p === "string" ||
+      (envelope.p === undefined && envelope.no === true)) &&
+    (envelope.po === null ||
+      typeof envelope.po === "string" ||
+      (envelope.po === undefined && envelope.no === true)) &&
     typeof envelope.rv === "string" &&
     (envelope.bv === undefined || typeof envelope.bv === "string") &&
     typeof envelope.c === "number" &&
@@ -400,6 +409,8 @@ interface KVResponseEnvelope {
 
 export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   readonly supportsPassiveShellReads: true = true;
+  /** True when constructed without KV: the shell family no-ops (see ctor). */
+  readonly shellFamilyInert?: boolean;
   readonly defaults?: CacheDefaults;
   readonly keyGenerator?: (
     ctx: RequestContext<TEnv>,
@@ -471,6 +482,11 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     this.keyGenerator = options.keyGenerator;
     this.waitUntil = (fn) => options.ctx.waitUntil(fn());
     this.kv = options.kv;
+    // The shell family requires KV (getShell/putShell no-op without it — see
+    // warnShellFamilyInertOnce). Declaring it lets scheduleShellCapture skip
+    // captures whose write could only no-op instead of burning a background
+    // render per MISS that still occupies the serialized capture queue.
+    this.shellFamilyInert = options.kv ? undefined : true;
     this.onRevalidateTag = options.onRevalidateTag;
     // tagPurge accepts a ready purge function or a credentials object; the
     // object form is normalized through the built-in zone purge client, which
@@ -2083,8 +2099,11 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         }
 
         const envelope: CFShellEnvelope = {
-          p: entry.prelude,
-          po: entry.postponed,
+          // Presence-keyed: a navigationOnly entry has no document half, and an
+          // omitted key (vs an explicit undefined) also keeps it out of the
+          // serialized JSON.
+          ...(entry.prelude !== undefined ? { p: entry.prelude } : {}),
+          ...(entry.postponed !== undefined ? { po: entry.postponed } : {}),
           rv: entry.reactVersion,
           bv: entry.buildVersion,
           c: entry.createdAt,

package/src/cache/types.ts

@@ -198,6 +198,16 @@ export interface SegmentCacheStore<TEnv = unknown> {
     tags?: string[],
   ): Promise<"stored" | "invalidated" | void>;
 
+  /**
+   * Declares the shell family present-but-inert: getShell/putShell exist but
+   * no-op (CFCacheStore without a KV namespace). scheduleShellCapture skips
+   * captures whose only write target is inert — the background render would be
+   * dead work that still occupies the per-isolate serialized capture queue
+   * (a promise-heavy route bakes for seconds per MISS with nothing stored).
+   * Absent/false means the family, when present, actually stores.
+   */
+  shellFamilyInert?: boolean;
+
   /**
    * Get a cached function result by key.
    * Returns the serialized value, optional handle data, and staleness flag.
@@ -264,8 +274,8 @@ export interface CacheItemResult {
 /**
  * A cached PPR (Partial Pre-rendering) shell entry.
  *
- * One entry carries BOTH artifacts a resume needs — the rendered HTML prelude
- * and React's postponed state — because the pair is version- and
+ * A DOCUMENT entry carries BOTH artifacts a resume needs — the rendered HTML
+ * prelude and React's postponed state — because the pair is version- and
  * generation-coupled and must never be mixed across a React upgrade or a build
  * change. The reactVersion and buildVersion fields are the read-time gates that
  * enforce both halves: isValidShellHit (rsc/shell-serve.ts) treats an entry
@@ -274,15 +284,28 @@ export interface CacheItemResult {
  * positions against one exact tree; resuming it against a different React or a
  * different app build tree-mismatches inside resume(), AFTER the 200 + prelude
  * are committed — an unrecoverable broken serve).
+ *
+ * A `navigationOnly` entry stores NEITHER half: nothing ever serves its HTML
+ * (document serving skips navigationOnly entries at the read gate, and partial
+ * replay consumes only `snapshot`/`docKey`), so the prelude would ride every
+ * store write and read as dead weight at KV-value scale. The capture still runs
+ * the full fizz prerender — it is the completeness arbiter and sanity gate —
+ * but its output is dropped before putShell. hasIntactShellPayload is the
+ * document-half gate; navigationOnly entries never satisfy it.
  */
 export interface ShellCacheEntry {
-  /** Rendered HTML prelude bytes, base64-encoded (stores are JSON-serializing). */
-  prelude: string;
+  /**
+   * Rendered HTML prelude bytes, base64-encoded (stores are JSON-serializing).
+   * Absent on `navigationOnly` entries (no document half is stored — see the
+   * interface doc); present on every document-servable entry.
+   */
+  prelude?: string;
   /**
    * JSON.stringify of React's postponed state, or null when the shell settled
-   * with no holes (the DATA variant — served without a fizz resume).
+   * with no holes (the DATA variant — served without a fizz resume). Absent
+   * exactly when `prelude` is (navigationOnly entries).
    */
-  postponed: string | null;
+  postponed?: string | null;
   /** React.version captured at prerender time; the read-time invalidation gate. */
   reactVersion: string;
   /**
@@ -366,6 +389,18 @@ export interface ShellCacheEntry {
   createdAt: number;
 }
 
+/**
+ * A shell entry whose document half is present — what the document HIT path
+ * (serveShellHit / lookupBuildShell) consumes. hasIntactShellPayload
+ * (rsc/shell-serve.ts) is the runtime gate AND the type narrowing to this
+ * shape; navigationOnly entries never pass it (their document half is not
+ * stored).
+ */
+export type DocumentShellCacheEntry = ShellCacheEntry & {
+  prelude: string;
+  postponed: string | null;
+};
+
 /**
  * The families a shell snapshot pins. The item/segment/response families are
  * cache-store reads/writes (recorded by RecordingShellStore); the loader family

package/src/cache/vercel/vercel-cache-store.ts

@@ -184,10 +184,13 @@ interface VercelResponseEnvelope {
 
 /** Stored envelope for a PPR shell entry (getShell/putShell). */
 interface VercelShellEnvelope {
-  /** base64-encoded prelude bytes. */
-  p: string;
-  /** postponed state JSON, or null (DATA variant). */
-  po: string | null;
+  /**
+   * base64-encoded prelude bytes. Absent iff `no` (navigationOnly entries
+   * store no document half — ShellCacheEntry.prelude).
+   */
+  p?: string;
+  /** postponed state JSON, or null (DATA variant). Absent iff `no`. */
+  po?: string | null;
   /** React.version at capture. */
   rv: string;
   /** Build version at capture (ShellCacheEntry.buildVersion). */
@@ -868,8 +871,11 @@ export class VercelCacheStore<
           ? Math.min(totalTtl, TAG_MARKER_TTL_SECONDS)
           : totalTtl;
       const env: VercelShellEnvelope = {
-        p: entry.prelude,
-        po: entry.postponed,
+        // Presence-keyed: a navigationOnly entry has no document half, and an
+        // omitted key (vs an explicit undefined) also keeps it out of the
+        // serialized JSON.
+        ...(entry.prelude !== undefined ? { p: entry.prelude } : {}),
+        ...(entry.postponed !== undefined ? { po: entry.postponed } : {}),
         rv: entry.reactVersion,
         bv: entry.buildVersion,
         c: entry.createdAt,
@@ -1210,13 +1216,21 @@ export class VercelCacheStore<
   private asShellEnvelope(raw: unknown): VercelShellEnvelope | null {
     if (!isRecord(raw)) return null;
     const { p, po, rv, bv, c, s, e, t, i, sn, dk, lh, tw, no } = raw;
-    if (typeof p !== "string" || typeof rv !== "string") return null;
-    if (po !== null && typeof po !== "string") return null;
+    if (typeof rv !== "string") return null;
+    // Document half: required unless navigationOnly (`no`), which stores
+    // neither field. Tolerate a legacy navigationOnly envelope that still
+    // carries them.
+    if (p === undefined ? no !== true : typeof p !== "string") return null;
+    if (
+      po === undefined ? no !== true : po !== null && typeof po !== "string"
+    ) {
+      return null;
+    }
     if (typeof c !== "number") return null;
     if (typeof s !== "number" || typeof e !== "number") return null;
     return {
-      p,
-      po: po as string | null,
+      ...(typeof p === "string" ? { p } : {}),
+      ...(po !== undefined ? { po: po as string | null } : {}),
       rv,
       bv: typeof bv === "string" ? bv : undefined,
       c,

package/src/route-definition/helpers-types.ts

@@ -33,6 +33,7 @@ import type {
   TransitionItem,
   UseItems,
 } from "../route-types.js";
+import type { StaticHandlerRef } from "../static-handler.js";
 
 // Re-export route item types for backward compatibility
 export type {
@@ -140,8 +141,8 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   },
    * })
    * ```
-   * @param slots - Object with slot names (prefixed with @) mapped to handlers
-   *                or `{ handler, use? }` slot descriptors.
+   * @param slots - Object with slot names (prefixed with @) mapped to handlers,
+   *                Static() definitions, or `{ handler, use? }` descriptors.
    * @param use - Optional callback for loaders, loading, revalidate, etc.
    *              Items here apply to every slot in the call (broadcast).
    *              For per-slot single-assignment items, use the slot descriptor's
@@ -157,8 +158,9 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
       `@${string}`,
       | Handler<any, any, TEnv>
       | ReactNode
+      | StaticHandlerRef
       | {
-          handler: Handler<any, any, TEnv> | ReactNode;
+          handler: Handler<any, any, TEnv> | ReactNode | StaticHandlerRef;
           use?: () => UseItems<ParallelUseItem>;
         }
     >,