@rangojs/router 0.0.0-experimental.136 → 0.0.0-experimental.137

package/dist/vite/index.js

@@ -2297,7 +2297,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.136",
+  version: "0.0.0-experimental.137",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.136",
+  "version": "0.0.0-experimental.137",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/breadcrumbs/SKILL.md

@@ -90,7 +90,9 @@ a deep async component, not the handler — call `.defer()` on the push function
 slot synchronously and returns a **resolver that is push-equal** — you call it
 later, anywhere in the render, with the same argument you'd have passed to the
 push (a value, a `Promise`, or a thunk). The only added behavior is a timeout, so a
-forgotten resolve can't hold the Flight stream (and the HTTP response) open forever.
+forgotten resolve can't hang the render (and the HTTP response): resolve-by-default
+awaits the reserved slot before any consumer reads it, and the timeout guarantees it
+settles to `else` instead of blocking forever.
 
 Reserve the slot in the handler, then resolve it from a nested async component
 that closes over the resolver — no extra wiring (the resolver is a plain closure,
@@ -131,15 +133,17 @@ hung request. `timeoutMs: 0` or `Infinity` disable the timeout intentionally; an
 other non-finite or negative value falls back to the default rather than silently
 disabling the safety net.
 
-**Consumer note:** because `.defer()` reserves the slot for the WHOLE item, a
-client reading the handle (`useHandle(Breadcrumbs)`) sees that entry as a
-`Promise` until it resolves. Type such reads with the exported
-`DeferredHandleEntry<BreadcrumbItem>` (from `@rangojs/router/client`); a
-deferred-aware consumer should `use()` thenable entries inside `<Suspense>`, while
-a simple one can skip them (`typeof entry.then === "function"`). Use `.defer()`
-only when even `label`/`href` are unknown at handler time — if you know them and
-only the `content` is async, push a concrete item with a `Promise` `content` field
-instead (no `.defer()` needed).
+**Consumer note (resolve-by-default):** a deferred crumb is RESOLVED before any
+consumer sees it — `useHandle(Breadcrumbs)` returns the resolved item, never a
+`Promise`, so you read it like any sync crumb (no `use()`, no thenable narrowing).
+On a full/SSR load the value is resolved server-side; on a soft navigation the
+breadcrumbs HOLD the previous resolved value until the deferred value lands, then
+swap in — no blank, no pending entry. If the slot times out to `else: null`/
+undefined, the entry is simply dropped. Use `.defer()` only when even
+`label`/`href` are unknown at handler time — if you know them and only the
+`content` is async, push a concrete item with a `Promise` `content` field instead
+(the `content` field is a nested promise you resolve with `use()` in your
+component; no `.defer()` needed).
 
 ## Consuming Breadcrumbs (Client)
 
@@ -274,15 +278,28 @@ Create your own handle with `createHandle()`:
 ```typescript
 import { createHandle } from "@rangojs/router";
 
-// Default: flatten into array
+// Custom collect: last value wins.
 export const PageTitle = createHandle<string, string>(
   (segments) => segments.flat().at(-1) ?? "Default Title",
 );
 
-// No collect function: default flattens into T[]
+// No collect: the DEFAULT is the identity (lossless) — `collect` receives the
+// per-segment data (TData[][], one array per segment that pushed, in segment
+// order) and passes it through as-is. `useHandle(Warnings)` is `string[][]`, so a
+// consumer can tell which/how-many segments contributed.
 export const Warnings = createHandle<string>();
+
+// Want a single flat list instead? Opt in:
+export const FlatWarnings = createHandle<string, string[]>((segments) =>
+  segments.flat(),
+);
 ```
 
+A handle whose module is never imported (so `createHandle()` never ran to register
+its collect) falls back to this same identity default and **warns in dev** — a
+handle with a custom collect that failed to register would otherwise return the
+wrong shape silently, and the runtime can't tell it from one that wanted the default.
+
 The Vite `exposeInternalIds` plugin auto-injects a stable `$$id` based on
 file path and export name. No manual naming required for project-local code.
 

package/skills/testing/handles.md

@@ -13,7 +13,7 @@ A handle's `collect`/accumulator (the `createHandle(collect)` argument that maps
 | `handle`   | `Handle<TData, TAccumulated>`         | The handle whose registered collect to run.                                                                                                                                                                                                          |
 | `segments` | `ReadonlyArray<ReadonlyArray<TData>>` | Per-segment pushed values, one inner array per route segment, in **parent -> child** order. Empty inner arrays are filtered before the collect runs (matching production `collectHandleData` — a segment that pushed nothing is not passed through). |
 
-**Returns** `TAccumulated` — exactly what the handle's collect produces (a default-flatten array, or a custom accumulator's value). If the handle's module was never imported (collect unregistered), it warns and falls back to `segments.flat()`.
+**Returns** `TAccumulated` — exactly what the handle's collect produces (the default identity collect's per-segment `TData[][]`, or a custom accumulator's value). If the handle's module was never imported (collect unregistered), it falls back to that same identity default and **warns** — a handle with a custom collect that failed to register would otherwise return the wrong shape silently.
 
 ### runLoader option — `handles` — `src/testing/run-loader.ts`
 
@@ -40,7 +40,9 @@ import { describe, it, expect } from "vitest";
 import { collectHandle } from "@rangojs/router/testing";
 import { createHandle } from "@rangojs/router";
 
-const Breadcrumbs = createHandle<{ label: string; href: string }>(); // default flatten
+// Opt into a flat list; the default collect groups per segment (TData[][]).
+type Crumb = { label: string; href: string };
+const Breadcrumbs = createHandle<Crumb, Crumb[]>((segments) => segments.flat());
 
 it("flattens per-segment crumbs in parent->child order", () => {
   const home = { label: "Home", href: "/" };

package/src/browser/event-controller.ts

@@ -249,6 +249,14 @@ export interface EventController {
     resolvedIds?: string[],
   ): void;
   getHandleState(): HandleState;
+  /**
+   * Update ONLY `routeSegmentIds` (what `useSegments` reads) from `matched`,
+   * leaving `data` and `segmentOrder` (what `useHandle` collects over) untouched.
+   * Used while a deferred handle is resolving: the route has changed (so
+   * `useSegments` must reflect the new segment ids) but `useHandle` still holds
+   * its previous value until the deferred snapshot is applied.
+   */
+  setRouteSegmentIds(matched: string[]): void;
 
   // Params operations
   setParams(params: Record<string, string>): void;
@@ -860,6 +868,18 @@ export function createEventController(
     };
   }
 
+  function setRouteSegmentIds(matched: string[]): void {
+    const next = filterRouteSegmentIds(matched);
+    if (
+      next.length === routeSegmentIds.length &&
+      next.every((id, i) => id === routeSegmentIds[i])
+    ) {
+      return;
+    }
+    routeSegmentIds = next;
+    notifyHandles();
+  }
+
   // ========================================================================
   // Subscriptions
   // ========================================================================
@@ -928,6 +948,7 @@ export function createEventController(
     // Handles
     setHandleData,
     getHandleState,
+    setRouteSegmentIds,
 
     // Params
     setParams,

package/src/browser/react/NavigationProvider.tsx

@@ -32,56 +32,10 @@ import { createAppShellRef, type AppShellRef } from "../app-shell.js";
 import { startConnectionWarmup } from "../connection-warmup.js";
 import { debugLog } from "../logging.js";
 import { cloneHandleData } from "../navigation-store.js";
-import { collectHandleData } from "../../handle.js";
-import { Meta } from "../../handles/meta.js";
-import type { MetaDescriptor } from "../../router/types.js";
 import {
-  HEAD_RESOLVE_HANDLE_NAMES,
-  hasDeferredHandleValue,
+  deferredHandleNames,
   resolveDeferredHandleValues,
-} from "./deferred-handle-resolution.js";
-
-/** Meta handle-name key. Meta is the only head-placed handle whose consumer
- *  use()s a deferred value above the route <Suspense>, so it must be resolved in
- *  the store before apply; every other handle keeps the promise contract. */
-const META = "__rsc_router_meta__";
-
-/**
- * Carry the previous page's COLLECTED Meta forward so the title is kept (no
- * blank) while a deferred Meta resolves on a soft navigation.
- *
- * Why a carry-forward and not just preserving the previous Meta data: handle
- * collection (useHandle/MetaTags) is driven by the event controller's
- * `segmentOrder`, which becomes the NEW route's order so the synchronous
- * breadcrumbs render immediately. The previous route's title lives under a
- * segment that is NOT in the new order, so it would stop being collected — the
- * title would fall back to the layout default. Re-keying the previous COLLECTED
- * descriptors under a segment that IS in the new order keeps them visible.
- *
- * Title descriptors are wrapped as `{ title: { absolute } }` so re-collection
- * under a (possibly template-bearing) new layout does not re-apply a title
- * template to an already-final title. Promise and default (charSet/viewport)
- * descriptors are dropped: Promise ones would suspend MetaTags, and the defaults
- * are re-added by collectMeta.
- */
-function carriedPreviousMeta(prev: MetaDescriptor[]): MetaDescriptor[] {
-  const out: MetaDescriptor[] = [];
-  for (const d of prev) {
-    if (d && typeof (d as { then?: unknown }).then === "function") continue;
-    const base = d as Exclude<MetaDescriptor, Promise<unknown>>;
-    if ("charSet" in base) continue;
-    if ("name" in base && (base as { name?: unknown }).name === "viewport") {
-      continue;
-    }
-    if ("title" in base) {
-      const t = (base as { title: unknown }).title;
-      out.push({ title: { absolute: typeof t === "string" ? t : String(t) } });
-      continue;
-    }
-    out.push(base);
-  }
-  return out;
-}
+} from "../../handles/deferred-resolution.js";
 
 /**
  * Process handles from an async generator, updating the event controller
@@ -144,131 +98,88 @@ async function processHandles(
 
     yieldCount++;
 
-    // Resolve ONLY Meta in the store before applying. Meta is the sole
-    // head-placed handle whose consumer use()s a deferred value above the route
-    // <Suspense>; an uncontained suspension there would revert the just-committed
-    // route and hide its loading fallback. Every other handle (Breadcrumbs,
-    // custom handles) keeps the DeferredHandleEntry contract: its deferred values
-    // reach the consumer AS A PROMISE and are narrowed via isThenable(). So sync
-    // handles AND non-Meta deferred promises apply/stream through immediately —
-    // only Meta is held back and swapped in once resolved.
-    const metaDeferred = hasDeferredHandleValue(
-      handleData,
-      HEAD_RESOLVE_HANDLE_NAMES,
-    );
+    // Resolve-by-default: hold the previous resolved value until this yield's
+    // deferred (Promise) handle values settle, then apply the fully-resolved
+    // snapshot. The hold needs NO extra state — we simply do not touch the store
+    // until the values resolve, so useHandle keeps reading (and showing) the
+    // previous data. A yield with no deferred value applies synchronously.
+    const hasDeferred = deferredHandleNames(handleData).size > 0;
 
-    // Apply now. The non-deferred-Meta case applies the whole snapshot in one
-    // call (Meta included). When Meta IS deferred, replace the deferred Meta with
-    // the previous page's COLLECTED Meta (stale-while-revalidate — never a blank
-    // title) keyed under one of the NEW route's Meta segments, so it stays
-    // collected under the new segment order while the synchronous and non-Meta
-    // deferred handles update with normal cleanup. The resolved Meta is swapped
-    // in by the partial merge below.
-    if (metaDeferred) {
-      const immediate: HandleData = { ...handleData };
-      const metaSegments = handleData[META] ?? {};
-      // Anchor: the last new Meta segment in matched order (collected after the
-      // shared layout, so its carried title wins). Falls back to any new Meta
-      // segment if matched ordering does not surface one.
-      const metaSegmentIds = Object.keys(metaSegments);
-      const ordered = (matched ?? []).filter((id) =>
-        metaSegmentIds.includes(id),
-      );
-      const anchor = ordered.at(-1) ?? metaSegmentIds.at(-1);
-
-      const prevState = eventController.getHandleState();
-      const prevCollected = collectHandleData(
-        Meta,
-        prevState.data,
-        prevState.segmentOrder,
-      ) as MetaDescriptor[];
-      const carried = carriedPreviousMeta(prevCollected);
-
-      if (anchor && carried.length > 0) {
-        immediate[META] = { [anchor]: carried };
-      } else {
-        // No previous Meta to carry and/or no anchor: leave Meta unset until it
-        // resolves (the documented no-previous-Meta behavior).
-        delete immediate[META];
-      }
-      eventController.setHandleData(immediate, matched, isPartial, resolvedIds);
-    } else {
+    if (!hasDeferred) {
       eventController.setHandleData(
         handleData,
         matched,
         isPartial,
         resolvedIds,
       );
-    }
-
-    // Snapshot of the nav's full applied handle state (sync handles, non-Meta
-    // deferred promises, and — when Meta is deferred — the carried previous Meta).
-    // Captured AFTER applying so it reflects what is actually on screen now.
-    const baseSnapshot = cloneHandleData(eventController.getHandleState().data);
-
-    if (!metaDeferred) {
-      // Non-deferred: the applied snapshot is final. Keep the cache in sync and
-      // fresh. The token guard stops a stale same-URL nav writing a newer entry.
+      // Keep the cache fresh. The token guard stops a stale same-URL nav writing
+      // a newer entry.
       if (store.getCacheEntryInstance(historyKey) === myInstance) {
-        store.updateCacheHandleData(historyKey, baseSnapshot, false);
+        store.updateCacheHandleData(
+          historyKey,
+          eventController.getHandleState().data,
+          false,
+        );
       }
       continue;
     }
 
-    // Meta is deferred-pending. The applied snapshot carries the PREVIOUS page's
-    // Meta (or none), not this route's final title, so the cache entry must NOT
-    // be served as fresh on a popstate return. Mark it STALE and handlesPending
-    // (token-guarded). This is the P1 fix: the deferred Meta is a SERVER-side
-    // promise streamed via Flight, so a navigate-away ABORTS the stream and the
-    // client's deferred-Meta promise never resolves — the .then below never
-    // fires. stale makes a popstate return revalidate; handlesPending makes that
+    // The PREVIOUS (held) snapshot — captured before the await so the cache and
+    // the navigate-away merge below reflect what useHandle is still showing.
+    const previousSnapshot = cloneHandleData(
+      eventController.getHandleState().data,
+    );
+
+    // The route HAS changed even though the handle data is held, so update
+    // `routeSegmentIds` (what useSegments reads) now. This leaves `data` /
+    // `segmentOrder` (what useHandle collects over) untouched, so useHandle keeps
+    // holding its previous value while useSegments reflects the new route.
+    eventController.setRouteSegmentIds(matched ?? []);
+
+    // Deferred-pending: the new values are not applied yet (the previous value is
+    // held), so the cache entry must NOT be served as fresh on a popstate return.
+    // Mark it STALE + handlesPending (token-guarded), storing the PREVIOUS (held)
+    // snapshot. P1 fix: a deferred value is a SERVER-side promise streamed via
+    // Flight, so a navigate-away ABORTS the stream and the resolve below never
+    // settles. stale makes a popstate return revalidate; handlesPending makes that
     // revalidation a FULL re-render (no client segment IDs) so the server
-    // re-streams the handles. A diff-only revalidation would omit the unchanged
-    // segments' handles and the deferred Meta would never land — see the
-    // segmentIds branch in navigation-bridge.ts.
+    // re-streams the handles — a diff-only revalidation would omit the unchanged
+    // segments' handles and the deferred value would never land (see the
+    // segmentIds branch in navigation-bridge.ts).
     if (store.getCacheEntryInstance(historyKey) === myInstance) {
-      store.updateCacheHandleData(historyKey, baseSnapshot, true, true);
+      store.updateCacheHandleData(historyKey, previousSnapshot, true, true);
     }
 
-    // Resolve Meta late, then swap it in. The swap is a PARTIAL merge with
-    // resolvedIds=undefined so the stale-clear loop (which scans all handle
-    // names under resolvedIds) cannot wipe the non-Meta buckets we already
-    // applied. When the deferred Meta DOES resolve while this nav still owns the
-    // entry (no navigate-away abort), write the resolved handle data and clear
-    // stale + handlesPending — the entry is now complete, so a popstate return
-    // serves it without revalidating.
-    //
-    // Order-safety: each stream yield is a full cumulative snapshot and a
-    // segment's handle array is atomic, so concurrent Meta resolutions of
-    // different yields write identical per-segment arrays or touch disjoint
-    // segments — neither can clobber the other.
-    void resolveDeferredHandleValues(
-      handleData,
-      HEAD_RESOLVE_HANDLE_NAMES,
-    ).then((resolved) => {
-      const cacheValue = { ...baseSnapshot, [META]: resolved[META] };
-      if (stillLive()) {
-        // Still on the live page: swap Meta in and refresh the cache as fresh.
-        eventController.setHandleData(
-          { [META]: resolved[META] },
-          matched,
-          true,
-          undefined,
-        );
-        store.updateCacheHandleData(
-          historyKey,
-          eventController.getHandleState().data,
-          false,
-          false,
-        );
-      } else if (store.getCacheEntryInstance(historyKey) === myInstance) {
-        // Navigated away, but THIS nav still owns the target cache entry: write
-        // the resolved data and clear stale + handlesPending so a popstate return
-        // is fresh.
-        store.updateCacheHandleData(historyKey, cacheValue, false, false);
-      }
-      // else: a newer nav to the same URL superseded us — do nothing.
-    });
+    // Resolve every deferred value (allSettled; rejected + nullish dropped, sync
+    // values pass through). Each stream yield is a full cumulative snapshot.
+    const resolved = await resolveDeferredHandleValues(handleData);
+
+    if (!stillLive()) {
+      // Navigated away (or a same-URL nav superseded us) while resolving. We do
+      // NOT write `resolved` into the entry. It is THIS yield's snapshot only (on a
+      // partial nav, just the re-resolved segments' buckets), and a correct write
+      // needs setHandleData's nested per-segment merge + matched/resolvedIds
+      // cleanup: HandleData is handleName -> segmentId -> entries[], so a
+      // handle-name-level spread would drop a shared layout bucket (e.g. a
+      // Breadcrumbs layout crumb under L0 when the route pushed under R0) and would
+      // mark stale previous-route buckets fresh. We cannot run that merge here
+      // without touching the now-different live page. Instead leave the entry as it
+      // was marked before the await — stale + handlesPending — so a popstate return
+      // revalidates with a full re-render and re-streams the handles. A newer nav
+      // owning the entry has already overwritten it; nothing to do either way.
+      continue;
+    }
+
+    // Still live: apply the fully-resolved snapshot and refresh the cache fresh.
+    eventController.setHandleData(resolved, matched, isPartial, resolvedIds);
+    if (store.getCacheEntryInstance(historyKey) === myInstance) {
+      store.updateCacheHandleData(
+        historyKey,
+        eventController.getHandleState().data,
+        false,
+        false,
+      );
+    }
   }
 
   // Check again before final updates

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

@@ -558,18 +558,15 @@ export function createServerActionBridge(
           return undefined;
         }
 
-        // Update UI with error boundary
-        startTransition(() => {
-          onUpdate({ root: errorTree, metadata: metadata! });
-        });
-
         // Update segment tracking to exclude error segment IDs
         const errorSegmentIds = new Set(diff);
         const segmentIdsAfterError = segmentState.currentSegmentIds.filter(
           (id) => !errorSegmentIds.has(id),
         );
 
-        // Update store state
+        // Cache (and bump the nav instance) BEFORE the UI update so a deferred
+        // handle pushed by the error-boundary render still applies — see the
+        // "normal" case below for why caching after onUpdate dropped it.
         store.setSegmentIds(segmentIdsAfterError);
         const currentHandleData = eventController.getHandleState().data;
         store.cacheSegmentsForHistory(
@@ -578,6 +575,11 @@ export function createServerActionBridge(
           currentHandleData,
         );
 
+        // Update UI with error boundary
+        startTransition(() => {
+          onUpdate({ root: errorTree, metadata: metadata! });
+        });
+
         // Throw the error so the action promise rejects
         if (returnValue && !returnValue.ok) {
           throw returnValue.data;
@@ -779,10 +781,16 @@ export function createServerActionBridge(
             break;
           }
 
-          startTransition(() => {
-            onUpdate({ root: newTree, metadata: metadata! });
-          });
-
+          // Cache (and bump the nav instance) BEFORE the UI update, matching the
+          // navigation commit order (navigation-transaction.ts:157). processHandles
+          // is spawned by onUpdate and captures the current nav instance up front;
+          // a deferred handle value resolves asynchronously and is only applied
+          // while stillLive() (its captured instance still owns the page). Caching
+          // AFTER onUpdate bumped the instance out from under that in-flight
+          // resolve, so stillLive() turned false and the resolved handle snapshot
+          // was dropped on the action-revalidation path (sync siblings sharing the
+          // yield are held atomically, so they were dropped too).
+          //
           // Location state already applied above (pre-switch). Update store.
           store.setSegmentIds(matched);
           const currentHandleData = eventController.getHandleState().data;
@@ -791,6 +799,10 @@ export function createServerActionBridge(
             fullSegments,
             currentHandleData,
           );
+
+          startTransition(() => {
+            onUpdate({ root: newTree, metadata: metadata! });
+          });
           // Invalidation deferred to finalizeAction() (runs after this caches
           // the fresh segments), suppressed when the action called
           // keepClientCache().

package/src/client.rsc.tsx

@@ -101,8 +101,5 @@ export { useHref } from "./browser/react/use-href.js";
 export { useReverse } from "./browser/react/use-reverse.js";
 
 export { useHandle } from "./browser/react/use-handle.js";
-// Type a deferred-aware consumer narrows: an accumulated entry may be a Promise
-// (a `ctx.use(Handle).defer()` slot) until it resolves.
-export type { DeferredHandleEntry } from "./defer.js";
 
 export { useLocationState } from "./browser/react/location-state.js";

package/src/client.tsx

@@ -389,9 +389,6 @@ export {
 
 export { type Handle } from "./handle.js";
 export { useHandle } from "./browser/react/use-handle.js";
-// Type a deferred-aware consumer narrows: an accumulated entry may be a Promise
-// (a `ctx.use(Handle).defer()` slot) until it resolves.
-export type { DeferredHandleEntry } from "./defer.js";
 
 export { Meta } from "./handles/meta.js";
 export { MetaTags } from "./handles/MetaTags.js";

package/src/defer.ts

@@ -14,14 +14,14 @@
  *   // deep async component, far from ctx:
  *   resolve({ label, href, content });          // identical call, just deferred
  *
- * Under the hood the reserved slot is a Promise the renderer `use()`s; RSC Flight
- * streams it as a late row, so a deferred-aware consumer reading the handle
- * (`useHandle`) sees that entry as a `Promise` until it resolves (see
- * {@link DeferredHandleEntry}). The hazard that guards against bugs: a deferred
- * slot whose resolver is never called would keep the Flight stream — and the HTTP
- * response — open forever. So a deferred auto-resolves to `else` after `timeoutMs`
- * (default {@link DEFAULT_DEFER_TIMEOUT_MS}) if the resolver is never called,
- * degrading gracefully (and warning in dev) instead of hanging the request.
+ * Under the hood the reserved slot is a Promise. Handle values are resolved
+ * before any consumer sees them (resolve-by-default: the full render resolves
+ * server-side, navigation resolves client-side before apply), so `useHandle`
+ * receives the resolved value, never the Promise. The hazard that guards against
+ * bugs: a deferred slot whose resolver is never called would keep the render —
+ * and the HTTP response — waiting forever. So a deferred auto-resolves to `else`
+ * after `timeoutMs` (default {@link DEFAULT_DEFER_TIMEOUT_MS}) if the resolver is
+ * never called, degrading gracefully (and warning in dev) instead of hanging.
  */
 
 /** Default auto-resolve window. Long enough for genuine deep async work, short
@@ -74,24 +74,13 @@ export type HandlePush<TData> = HandlePushFn<TData> & {
    * re-enter the deadlock-guard push-callback scope a direct push thunk gets,
    * because a deferred resolver fires after the handler phase has closed.
    *
-   * The reserved slot appears in the accumulated handle data as a pending
-   * `Promise` until it resolves (see {@link DeferredHandleEntry}); a
-   * deferred-aware consumer narrows thenable entries (`use()`/`await` + null
-   * check) before dereferencing.
+   * The reserved slot is resolved before any consumer reads it
+   * (resolve-by-default), so `useHandle` receives the resolved value (or the
+   * `else` fallback on timeout), never a Promise.
    */
   defer(options?: DeferOptions<TData>): HandlePushFn<TData>;
 };
 
-/**
- * A handle entry a deferred-aware consumer may read from `useHandle`: either a
- * resolved value, or a pending `Promise` that resolves to the value, to `else`,
- * or (when no `else` was given) `undefined` on timeout. Reading code should treat
- * thenable entries as such and narrow before dereferencing.
- */
-export type DeferredHandleEntry<TData> =
-  | TData
-  | Promise<TData | null | undefined>;
-
 // Internal: a timeout-bounded { promise, resolve }. Not part of the public API
 // (the public surface is `ctx.use(Handle).defer()`); exported for `withDefer`
 // and unit tests only. Resolves to `T`, the `else` fallback, or `undefined`.