@rangojs/router 0.5.0 → 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/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/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>;
         }
     >,

package/src/static-handler.ts

@@ -46,9 +46,24 @@ export interface StaticHandlerOptions {
   passthrough?: boolean;
 }
 
+declare const STATIC_HANDLER_REF: unique symbol;
+
+/**
+ * Opaque identity used by DSL type seams that accept Static() values.
+ *
+ * The brand is required, never optional: an optional brand makes this a weak
+ * type, and weak-type checking lets `{}` through — `parallel({ "@x": {} })`
+ * would typecheck and then die at render as an invalid React child. The
+ * symbol never exists at runtime; Static() casts its return instead.
+ */
+export interface StaticHandlerRef {
+  /** @internal Type-only brand; see interface doc. */
+  readonly [STATIC_HANDLER_REF]: true;
+}
+
 export interface StaticHandlerDefinition<
   TParams extends Record<string, any> = any,
-> {
+> extends StaticHandlerRef {
   readonly __brand: "staticHandler";
   /** Auto-generated unique ID (injected by Vite plugin). */
   $$id: string;
@@ -103,12 +118,13 @@ export function Static<TParams extends Record<string, any>>(
     id = `__rango_runtime_static_${runtimeStaticIdCounter++}`;
   }
 
+  // Cast: STATIC_HANDLER_REF is a type-only brand with no runtime field.
   return {
     __brand: "staticHandler" as const,
     $$id: id,
     handler: handler as Handler<TParams>,
     ...(options ? { options } : {}),
-  };
+  } as StaticHandlerDefinition<TParams>;
 }
 
 export function isStaticHandler(

package/src/urls/path-helper-types.ts

@@ -40,7 +40,10 @@ import type {
   PrerenderHandlerDefinition,
   PassthroughHandlerDefinition,
 } from "../prerender.js";
-import type { StaticHandlerDefinition } from "../static-handler.js";
+import type {
+  StaticHandlerDefinition,
+  StaticHandlerRef,
+} from "../static-handler.js";
 import type {
   ResponseHandler,
   ResponseHandlerContext,
@@ -271,22 +274,18 @@ export type PathHelpers<TEnv> = {
    *
    * Not generic over the slots record: an inferred type parameter makes the
    * object literal an inference site, which suppresses contextual typing of
-   * arrow slot handlers (`(ctx) => ...` was implicit any). Bare handlers infer
-   * now; a descriptor's `handler:` arrow still needs an explicit ctx annotation
-   * because StaticHandlerDefinition's own `.handler` joins the contextual union
-   * (two callables — see parallel-slot-handler-types.test.ts).
+   * arrow slot handlers (`(ctx) => ...` was implicit any). Static() values use
+   * an opaque handler-less reference here so their own `.handler` cannot
+   * contribute a second call signature or expose internal fields in completion.
    */
   parallel: (
     slots: Record<
       `@${string}`,
       | Handler<any, any, TEnv>
       | ReactNode
-      | StaticHandlerDefinition
+      | StaticHandlerRef
       | {
-          handler:
-            | Handler<any, any, TEnv>
-            | ReactNode
-            | StaticHandlerDefinition;
+          handler: Handler<any, any, TEnv> | ReactNode | StaticHandlerRef;
           use?: () => ParallelUseItem[];
         }
     >,