@rangojs/router 0.0.0-experimental.e9c0b2f2 → 0.0.0-experimental.ea9f40f2

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/cloudflare/tracing.ts

@@ -39,7 +39,7 @@ import { _getRequestContext } from "../server/request-context.js";
 import {
   type RouterTracingConfig,
   type SpanRunner,
-  type TracePhaseToggles,
+  type TracingToggleOptions,
   NOOP_TRACE_SPAN,
 } from "../router/tracing.js";
 
@@ -57,13 +57,12 @@ interface CloudflareTracing {
   enterSpan<T>(name: string, callback: (span: CloudflareSpan) => T): T;
 }
 
-/** Options for createCloudflareTracing. */
-export interface CloudflareTracingOptions {
-  /** Master switch. Defaults to true. */
-  enabled?: boolean;
-  /** Per-phase span toggles. Omitted phases default to enabled. */
-  spans?: TracePhaseToggles;
-}
+/**
+ * Options for createCloudflareTracing. Alias of the shared
+ * {@link TracingToggleOptions} (`enabled` master switch + per-phase `spans`
+ * toggles); the name is public API.
+ */
+export type CloudflareTracingOptions = TracingToggleOptions;
 
 /**
  * Resolve the per-request Cloudflare tracer from the active execution context.

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`.

package/src/handle.ts

@@ -10,8 +10,11 @@ import { isUnderTestRunner } from "./runtime-env.js";
  *
  * @example
  * ```ts
- * // Define a handle (name auto-generated from file + export)
- * export const Breadcrumbs = createHandle<BreadcrumbItem>();
+ * // Define a handle (name auto-generated from file + export).
+ * // Default collect is the identity: one array per segment that pushed.
+ * export const Breadcrumbs = createHandle<BreadcrumbItem, BreadcrumbItem[]>(
+ *   (segments) => segments.flat(), // opt into a single flat list
+ * );
  *
  * // Use in handler
  * const push = ctx.use(Breadcrumbs);
@@ -21,7 +24,7 @@ import { isUnderTestRunner } from "./runtime-env.js";
  * const crumbs = useHandle(Breadcrumbs);
  * ```
  */
-export interface Handle<TData, TAccumulated = TData[]> {
+export interface Handle<TData, TAccumulated = TData[][]> {
   /**
    * Brand to distinguish handles from loaders in ctx.use()
    */
@@ -35,10 +38,13 @@ export interface Handle<TData, TAccumulated = TData[]> {
 }
 
 /**
- * Default collect function that flattens segment arrays into a single array.
+ * Default collect: pass the per-segment data through as-is — one array per segment
+ * that pushed, in segment order. Lossless, so a consumer can tell which/how-many
+ * segments contributed. Callers that want a single flat list opt in with
+ * `createHandle((segments) => segments.flat())`.
  */
-function defaultCollect<T>(segments: T[][]): T[] {
-  return segments.flat();
+function defaultCollect<T>(segments: T[][]): T[][] {
+  return segments;
 }
 
 // Module-level registry mapping $$id to collect functions.
@@ -62,13 +68,22 @@ export function getCollectFn(
  * The $$id is auto-generated by the Vite exposeInternalIds plugin based on
  * file path and export name. No manual naming required.
  *
- * @param collect - Optional collect function (default: flatten into array)
+ * @param collect - Optional collect function. Default: pass the per-segment data
+ *   through as-is (one array per segment that pushed, in segment order). Lossless,
+ *   so a consumer can tell which/how-many segments contributed. Opt into a single
+ *   flat list with `(segments) => segments.flat()`.
  * @param __injectedId - Auto-injected by Vite plugin, do not provide manually
  *
  * @example
  * ```ts
- * // Default: flatten into array
- * export const Breadcrumbs = createHandle<BreadcrumbItem>();
+ * // Default: per-segment grouping, as-is
+ * export const Pushed = createHandle<string>();
+ * // Result type: string[][]  (e.g. [["a"], ["b", "c"]])
+ *
+ * // Opt into a single flat list
+ * export const Breadcrumbs = createHandle<BreadcrumbItem, BreadcrumbItem[]>(
+ *   (segments) => segments.flat()
+ * );
  * // Result type: BreadcrumbItem[]
  *
  * // Custom: last value wins
@@ -83,8 +98,9 @@ export function getCollectFn(
  * );
  * // Result type: MetaTags
  *
- * // Custom: dedupe by href
- * export const Breadcrumbs = createHandle<BreadcrumbItem>(
+ * // Custom: dedupe by href (TAccumulated must be given — a custom collect that
+ * // returns a flat array no longer matches the default TData[][])
+ * export const Breadcrumbs = createHandle<BreadcrumbItem, BreadcrumbItem[]>(
  *   (segments) => {
  *     const all = segments.flat();
  *     return all.filter((item, i) => all.findIndex(x => x.href === item.href) === i);
@@ -92,7 +108,7 @@ export function getCollectFn(
  * );
  * ```
  */
-export function createHandle<TData, TAccumulated = TData[]>(
+export function createHandle<TData, TAccumulated = TData[][]>(
   collect?: (segments: TData[][]) => TAccumulated,
   __injectedId?: string,
 ): Handle<TData, TAccumulated> {
@@ -156,12 +172,18 @@ export function collectHandleData<TData, TAccumulated>(
   data: Record<string, Record<string, unknown[]>>,
   segmentOrder: string[],
 ): TAccumulated {
+  // Fall back to the default (identity, pass-through) collect when none is
+  // registered — e.g. the handle's module was not imported so createHandle() never
+  // ran. This is harmless for a handle that wanted the default, but a handle with a
+  // CUSTOM collect that failed to register silently gets the wrong shape (identity
+  // TData[][]) cast as its declared TAccumulated. The runtime can't tell the two
+  // apart (a Handle only carries $$id), so warn in dev (folded out of production).
   const collectFn = getCollectFn(handle.$$id);
   if (!collectFn && process.env.NODE_ENV !== "production") {
     console.warn(
-      `[rango] Handle "${handle.$$id}" has no registered collect function. ` +
-        `Falling back to flat array. Ensure the handle module is imported so ` +
-        `createHandle() runs and registers the collect function.`,
+      `[rango] Handle "${handle.$$id}" has no registered collect — falling back ` +
+        `to the identity (per-segment data as-is). If this handle declares a ` +
+        `CUSTOM collect, import its module so createHandle() runs where it is read.`,
     );
   }
   const collect = (collectFn ??

package/src/handles/MetaTags.tsx

@@ -3,8 +3,9 @@
 /**
  * Component to render collected meta descriptors in the document head.
  *
- * Supports both sync and async meta descriptors. Async descriptors
- * (Promise<MetaDescriptorBase>) are resolved using React's use() hook.
+ * Deferred (Promise) meta descriptors are resolved before MetaTags renders
+ * (server-side on the full render, client-side before apply on navigation), so
+ * it only ever receives resolved descriptors and never suspends.
  *
  * When theme is enabled in the router config, MetaTags also renders
  * the theme initialization script to prevent FOUC (flash of unstyled content).
@@ -28,11 +29,9 @@
  * ```
  */
 
-import { use } from "react";
 import { useHandle } from "../browser/react/use-handle.js";
 import { Meta } from "./meta.js";
-import { isThenable } from "./is-thenable.js";
-import type { MetaDescriptor, MetaDescriptorBase } from "../router/types.js";
+import type { MetaDescriptorBase } from "../router/types.js";
 import { useThemeContext } from "../theme/theme-context.js";
 import { generateThemeScript } from "../theme/theme-script.js";
 import { useNonce } from "../browser/react/nonce-context.js";
@@ -96,17 +95,7 @@ function hasTagName(
   );
 }
 
-/**
- * Check if a value is a Promise. Uses the shared thenable predicate (callable
- * `then`) so collect (meta.ts) and render never disagree: an object carrying a
- * non-callable `then` (e.g. `{ then: 5 }`) is a SYNC descriptor on both sides,
- * not a Promise that would crash React's `use()`.
- */
-function isPromise(value: unknown): value is Promise<unknown> {
-  return isThenable(value);
-}
-
-function renderMetaDescriptor(
+export function renderMetaDescriptor(
   descriptor: MetaDescriptorBase,
   index: number,
 ): React.ReactNode {
@@ -189,57 +178,6 @@ function renderMetaDescriptor(
   );
 }
 
-// Sentinel a rejected async descriptor resolves to: renderMetaDescriptor sees
-// no recognized fields and returns nothing renderable (see renderRejected).
-const REJECTED_META: unique symbol = Symbol("rango.rejectedMeta");
-
-// Cache the rejection-swallowing wrapper per source promise so use() gets a
-// stable reference across re-renders (a fresh .then() each render would make
-// React treat it as a new pending promise and never settle). WeakMap keys on
-// the original promise so entries are collected with it.
-const safeMetaPromises = new WeakMap<
-  Promise<MetaDescriptorBase>,
-  Promise<MetaDescriptorBase | typeof REJECTED_META>
->();
-
-function toSafeMetaPromise(
-  promise: Promise<MetaDescriptorBase>,
-): Promise<MetaDescriptorBase | typeof REJECTED_META> {
-  let safe = safeMetaPromises.get(promise);
-  if (!safe) {
-    // Swallow the rejection at the promise boundary, not via an error boundary:
-    // an error boundary above a suspended use() makes React abandon the whole
-    // Suspense subtree (and on the server switch it to client rendering). A
-    // settled-to-sentinel promise degrades the single bad descriptor to nothing
-    // while every sibling descriptor still renders.
-    //
-    // Normalize via Promise.resolve first: a collected async descriptor may be a
-    // non-native thenable (a React wakeable in SSR/RSC) whose .then() returns
-    // void rather than a Promise. Calling .then directly would leave `safe`
-    // undefined and use(undefined) would throw ("unsupported type passed to
-    // use()"), 500-ing the page. Promise.resolve adopts the thenable into a
-    // native Promise whose .then always returns one.
-    safe = Promise.resolve(promise).then(
-      (value) => value,
-      () => REJECTED_META,
-    );
-    safeMetaPromises.set(promise, safe);
-  }
-  return safe;
-}
-
-export function AsyncMetaTag({
-  promise,
-  index,
-}: {
-  promise: Promise<MetaDescriptorBase>;
-  index: number;
-}): React.ReactNode {
-  const resolved = use(toSafeMetaPromise(promise));
-  if (resolved === REJECTED_META) return null;
-  return renderMetaDescriptor(resolved, index);
-}
-
 /**
  * Renders all collected meta descriptors from route handlers.
  *
@@ -249,11 +187,16 @@ export function AsyncMetaTag({
  * When theme is enabled in router config, also renders the theme initialization
  * script to prevent FOUC (flash of unstyled content).
  *
- * Async meta descriptors (Promise<MetaDescriptorBase>) are resolved using
- * React's use() hook. RSC streaming handles the Promise resolution.
+ * Deferred (Promise) meta descriptors are resolved BEFORE MetaTags renders —
+ * server-side on the full/SSR render, client-side before apply on navigation
+ * (resolve-by-default) — so MetaTags only ever receives resolved descriptors and
+ * never suspends.
  */
 export function MetaTags(): React.ReactNode {
-  const descriptors = useHandle(Meta) as MetaDescriptor[];
+  // Deferred descriptors are resolved BEFORE collect runs (resolve-by-default),
+  // and collectMeta strips unset markers, so the collected output is always
+  // resolved base descriptors (never a Promise).
+  const descriptors = useHandle(Meta) as MetaDescriptorBase[];
   const themeConfig = useThemeContext()?.config ?? null;
   const nonce = useNonce();
 
@@ -266,18 +209,9 @@ export function MetaTags(): React.ReactNode {
           dangerouslySetInnerHTML={{ __html: generateThemeScript(themeConfig) }}
         />
       )}
-      {descriptors.map((descriptor, index) => {
-        if (isPromise(descriptor)) {
-          return (
-            <AsyncMetaTag
-              key={`async-${index}`}
-              promise={descriptor}
-              index={index}
-            />
-          );
-        }
-        return renderMetaDescriptor(descriptor, index);
-      })}
+      {descriptors.map((descriptor, index) =>
+        renderMetaDescriptor(descriptor, index),
+      )}
     </>
   );
 }

package/src/handles/breadcrumbs.ts

@@ -23,7 +23,6 @@
 
 import type { ReactNode } from "react";
 import { createHandle, type Handle } from "../handle.js";
-import { isThenable } from "./is-thenable.js";
 
 /**
  * A single breadcrumb item.
@@ -42,34 +41,33 @@ export interface BreadcrumbItem {
  * Collect function for Breadcrumbs handle.
  * Flattens segments in parent-to-child order with deduplication by href: each
  * href keeps its FIRST position but takes the LAST value (re-pushing a parent
- * href refreshes the label in place without reordering the trail).
- * Deferred slots (`ctx.use(Breadcrumbs).defer()`)
- * arrive as pending Promise entries with no href yet; they are passed through by
- * identity and excluded from the href dedup so concurrent deferred crumbs do not
- * all collapse under a single `undefined` href.
+ * href refreshes the label in place without reordering the trail). Deferred
+ * crumbs (a pushed Promise or `ctx.use(Breadcrumbs).defer()`) are resolved
+ * BEFORE collect runs (resolve-by-default), so collect only ever sees resolved
+ * items. An item without a string `href` is passed through by identity and
+ * excluded from the href dedup.
  */
 function collectBreadcrumbs(segments: BreadcrumbItem[][]): BreadcrumbItem[] {
   const all = segments.flat();
 
-  const isResolvedItem = (item: unknown): item is BreadcrumbItem =>
+  const hasHref = (item: unknown): item is BreadcrumbItem =>
     item != null &&
     typeof item === "object" &&
-    !isThenable(item) &&
     typeof (item as { href?: unknown }).href === "string";
 
-  // Dedup resolved crumbs by href: keep the FIRST position (preserving
-  // parent->child order) but the LAST value (a child re-pushing a parent's href
-  // can refresh its label). Deferred items bypass dedup entirely (they have no
-  // href yet) and are passed through by identity at their original position.
+  // Dedup crumbs by href: keep the FIRST position (preserving parent->child
+  // order) but the LAST value (a child re-pushing a parent's href can refresh
+  // its label). Items without an href pass through by identity at their original
+  // position.
   const valueByHref = new Map<string, BreadcrumbItem>();
   for (const item of all) {
-    if (isResolvedItem(item)) valueByHref.set(item.href, item);
+    if (hasHref(item)) valueByHref.set(item.href, item);
   }
 
   const result: BreadcrumbItem[] = [];
   const emitted = new Set<string>();
   for (const item of all) {
-    if (!isResolvedItem(item)) {
+    if (!hasHref(item)) {
       result.push(item);
       continue;
     }

package/src/handles/deferred-resolution.ts

@@ -0,0 +1,127 @@
+import type { HandleData, HandleStore } from "../server/handle-store.js";
+import { isThenable } from "./is-thenable.js";
+
+/**
+ * Runtime-neutral resolution of deferred (Promise) handle values. Shared by the
+ * server full-render path (resolve before the payload is finalized so SSR sees
+ * resolved values) and the client soft-nav path (NavigationProvider resolves
+ * each yield before applying it). Pure — imports only `isThenable` — so it is
+ * safe in both the RSC server environment AND the browser.
+ *
+ * Resolution is SHALLOW: only an entry that is ITSELF a thenable is awaited. A
+ * value that merely contains a promise (e.g. `{ data: somePromise }`) is a
+ * non-thenable, so the `isThenable` check skips it and it passes through verbatim
+ * — the nested promise is the consumer's responsibility. Resolution runs each
+ * entry through `Promise.all` with a per-entry `try/catch` (NOT `allSettled`), so
+ * one rejecting entry is dropped without rejecting the batch or aborting siblings.
+ */
+
+/**
+ * Handle names ($$id) whose snapshot carries a deferred (top-level Promise)
+ * value. Used by the client to decide which buckets to hold-and-resolve, and
+ * `.size > 0` answers "does this snapshot have any deferred value".
+ */
+export function deferredHandleNames(data: HandleData): Set<string> {
+  const names = new Set<string>();
+  for (const [handleName, segments] of Object.entries(data)) {
+    for (const values of Object.values(segments)) {
+      if (values.some(isThenable)) {
+        names.add(handleName);
+        break;
+      }
+    }
+  }
+  return names;
+}
+
+/**
+ * Snapshot with deferred (Promise) values awaited (shallow — only top-level
+ * thenables). A rejected deferred is dropped, and a deferred that resolves to
+ * `null`/`undefined` is dropped (the `.defer({ else })` skip semantics), so a
+ * nullish deferred slot never reaches a collector. Sync (non-thenable) values —
+ * including a legitimate sync `null` push — pass through unchanged.
+ */
+export async function resolveDeferredHandleValues(
+  data: HandleData,
+): Promise<HandleData> {
+  const out: HandleData = {};
+  await Promise.all(
+    Object.entries(data).flatMap(([handleName, segments]) => {
+      out[handleName] = {};
+      return Object.entries(segments).map(async ([segmentId, values]) => {
+        out[handleName][segmentId] = await resolveValues(values);
+      });
+    }),
+  );
+  return out;
+}
+
+// Resolve each entry IN ORDER. A non-thenable passes through verbatim (including
+// a legitimate sync `null`/`undefined` push — the "await iff thenable" contract).
+// A thenable is awaited and dropped when it rejects OR resolves to null/undefined
+// (the `.defer({ else })` skip semantics: a forgotten resolver times out to
+// `else ?? undefined`), so a nullish deferred slot never reaches a collector.
+async function resolveValues(values: unknown[]): Promise<unknown[]> {
+  const resolved = await Promise.all(
+    values.map(async (v) => {
+      if (!isThenable(v)) return { keep: true, value: v };
+      try {
+        const value = await v;
+        return { keep: value != null, value };
+      } catch {
+        return { keep: false, value: undefined };
+      }
+    }),
+  );
+  return resolved.filter((r) => r.keep).map((r) => r.value);
+}
+
+/**
+ * Full-render handle stream: a one-shot async generator that yields the FINAL
+ * handle snapshot with every top-level deferred value resolved. Drop-in for
+ * `handleStore.stream()` on full / HTML renders (initial load, 404, progressive
+ * enhancement), where the consumer drains the generator to completion before
+ * rendering anyway — so the single final yield is equivalent to the streamed
+ * yields' converged state, and the SSR markup plus the first sync `useHandle`
+ * read see resolved values. `getData()` seals the store and awaits the handler
+ * barrier; `resolveDeferredHandleValues` then awaits the pushed-value promises.
+ * A hung handle promise blocks the full render like any unresolved await (no
+ * handle-specific timeout). Partial / action payloads keep streaming via
+ * `handleStore.stream()`.
+ */
+export async function* resolvedHandleStream(
+  handleStore: HandleStore,
+): AsyncGenerator<HandleData, void, unknown> {
+  // Drain stream() (NOT getData()) for the converged snapshot: stream() sets the
+  // store's `completed` flag on seal+settle, and that flag is what makes a LATE
+  // push throw LateHandlePushError — an async JSX subtree that suspended and later
+  // calls ctx.use(Handle)(...) after collection. getData() never sets `completed`,
+  // so the late push would silently land. Both wait for the same settle barrier, so
+  // the final yielded value is identical; we just keep the late-push guard.
+  let snapshot: HandleData = {};
+  for await (const data of handleStore.stream()) {
+    snapshot = data;
+  }
+  yield await resolveDeferredHandleValues(snapshot);
+}
+
+/**
+ * Resolve the deferred (Promise) values in ONE segment's handle bucket
+ * (`handleName -> entries[]`). Same shallow + drop-rejections rule as
+ * {@link resolveDeferredHandleValues}, but for the segment-keyed shape the
+ * prerender/static collection paths use (`getDataForSegment`). Prerender is a
+ * build-time cache, so the baked artifact must hold resolved values — a hit
+ * replays them into the segment system, where collect/useHandle expect resolved
+ * data.
+ */
+export async function resolveSegmentHandleValues(
+  segHandles: Record<string, unknown[]>,
+): Promise<Record<string, unknown[]>> {
+  const out: Record<string, unknown[]> = {};
+  await Promise.all(
+    Object.entries(segHandles).map(async ([handleName, values]) => {
+      out[handleName] = await resolveValues(values);
+    }),
+  );
+  return out;
+}

package/src/handles/is-thenable.ts

@@ -1,14 +1,13 @@
 /**
- * Single thenable predicate shared by the built-in handles that distinguish a
- * synchronous descriptor/item from a deferred `Promise` one (Meta collect, the
- * MetaTags render side, and Breadcrumbs).
+ * Single thenable predicate for the resolve-by-default handle machinery
+ * (`handles/deferred-resolution.ts`, its sole owner) — it decides which top-level
+ * handle entries are deferred (`Promise`) values to await before any consumer
+ * sees them, and which pass through verbatim.
  *
  * Requires a CALLABLE `then` (`typeof obj.then === "function"`), not merely a
- * `"then" in obj` membership check. The two had drifted: a descriptor carrying a
- * non-callable `then` (e.g. a serialized shape `{ then: 5 }`) was classified as
- * synchronous by collect but as a Promise by render — so render would call
- * React's `use()` on a non-thenable and throw. One owner keeps the collect and
- * render sides from ever disagreeing.
+ * `"then" in obj` membership check, so a non-promise carrying a `then` field
+ * (e.g. a serialized shape `{ then: 5 }`) is treated as a plain sync value rather
+ * than awaited. A single predicate keeps that classification consistent.
  */
 export function isThenable(value: unknown): value is PromiseLike<unknown> {
   return (

package/src/handles/meta.ts

@@ -29,7 +29,6 @@
  */
 
 import { createHandle, type Handle } from "../handle.js";
-import { isThenable } from "./is-thenable.js";
 import type {
   MetaDescriptor,
   MetaDescriptorBase,
@@ -37,12 +36,6 @@ import type {
   UnsetDescriptor,
 } from "../router/types.js";
 
-function isPromiseDescriptor(
-  descriptor: MetaDescriptor,
-): descriptor is Promise<MetaDescriptorBase> {
-  return isThenable(descriptor);
-}
-
 function isUnsetDescriptor(
   descriptor: MetaDescriptor,
 ): descriptor is UnsetDescriptor {
@@ -166,37 +159,9 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
 
   for (const descriptors of segments) {
     for (const descriptor of descriptors) {
-      // Promise descriptors cannot be inspected synchronously (their content is
-      // unknown until resolved in <MetaTags> via React's use()), so they bypass
-      // key-based dedup and title-templating: they are appended verbatim. Warn in
-      // dev when a title template is active so the author knows an async
-      // descriptor will NOT participate in the template/dedup.
-      //
-      // The warning is deliberately a GENERAL note, not a duplicate-<title>
-      // prediction: collectMeta cannot tell whether this Promise resolves to a
-      // title (which would indeed yield a 2nd <title>) or to an ordinary
-      // descriptor like an async og:image (which would not). Asserting a
-      // duplicate <title> here is a false positive for the common og:image case,
-      // so the message states only that async descriptors bypass templating —
-      // not that a duplicate <title> WILL occur.
-      if (isPromiseDescriptor(descriptor)) {
-        if (
-          titleTemplate !== undefined &&
-          process.env.NODE_ENV !== "production"
-        ) {
-          console.warn(
-            `[Meta] A Promise meta descriptor was pushed while a title template is active. ` +
-              `Async descriptors bypass deduplication and title-templating: the template is ` +
-              `not applied to them. If this Promise resolves to a title, resolve the value ` +
-              `before pushing (or push a synchronous descriptor) so it participates in the ` +
-              `template; if it resolves to a non-title descriptor (e.g. og:image), this ` +
-              `note does not apply.`,
-          );
-        }
-        result.push(descriptor);
-        continue;
-      }
-
+      // Deferred (Promise) descriptors are resolved BEFORE collectMeta runs
+      // (resolve-by-default), so every descriptor here is synchronous and
+      // participates in key-based dedup + title-templating like any other.
       if (isUnsetDescriptor(descriptor)) {
         const keyToRemove = descriptor.unset;
         if (keyToIndex.has(keyToRemove)) {
@@ -262,12 +227,10 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
  * Use `ctx.use(Meta)` in route handlers to push meta descriptors.
  * Use `<MetaTags />` component to render them in the document head.
  *
- * Deduplication and title-templating apply only to SYNCHRONOUS descriptors.
- * A Promise descriptor (`Promise<MetaDescriptorBase>`) is appended verbatim —
- * its content is not known until it resolves in `<MetaTags>`, so it cannot be
- * keyed for dedup nor receive a parent title template. If you need a child title
- * to participate in a layout's `%s` template, push the resolved string title
- * synchronously rather than a `Promise<{ title }>`.
+ * Deferred (Promise) descriptors are resolved before collectMeta runs
+ * (resolve-by-default), so they participate in deduplication and `%s`
+ * title-templating identically to synchronous descriptors. A descriptor that
+ * resolves to `null`/`undefined` (or rejects) is dropped.
  */
 export const Meta: Handle<MetaDescriptor, MetaDescriptor[]> = createHandle<
   MetaDescriptor,