npm - @rangojs/router - Versions diffs - 0.0.0-experimental.132 → 0.0.0-experimental.133 - Mend

@rangojs/router 0.0.0-experimental.132 → 0.0.0-experimental.133

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (141) hide show

package/AGENTS.md +8 -0
package/README.md +43 -2
package/dist/bin/rango.js +92 -16
package/dist/vite/index.js +166 -70
package/package.json +19 -18
package/skills/breadcrumbs/SKILL.md +1 -1
package/skills/bundle-analysis/SKILL.md +2 -2
package/skills/cache-guide/SKILL.md +2 -2
package/skills/caching/SKILL.md +16 -9
package/skills/debug-manifest/SKILL.md +4 -2
package/skills/document-cache/SKILL.md +2 -2
package/skills/handler-use/SKILL.md +1 -1
package/skills/hooks/SKILL.md +2 -2
package/skills/host-router/SKILL.md +1 -1
package/skills/intercept/SKILL.md +1 -1
package/skills/loader/SKILL.md +2 -0
package/skills/migrate-react-router/SKILL.md +4 -2
package/skills/mime-routes/SKILL.md +1 -1
package/skills/prerender/SKILL.md +2 -0
package/skills/rango/SKILL.md +12 -11
package/skills/response-routes/SKILL.md +2 -2
package/skills/route/SKILL.md +4 -0
package/skills/router-setup/SKILL.md +3 -0
package/skills/scripts/SKILL.md +179 -0
package/skills/testing/SKILL.md +1 -1
package/skills/testing/bindings.md +20 -6
package/skills/testing/cache-prerender.md +5 -2
package/skills/testing/client-components.md +2 -0
package/skills/testing/e2e-parity.md +1 -1
package/skills/testing/flight.md +8 -9
package/skills/testing/render-handler.md +1 -1
package/skills/testing/response-routes.md +1 -1
package/skills/testing/server-actions.md +11 -11
package/skills/testing/setup.md +3 -0
package/skills/typesafety/SKILL.md +3 -2
package/skills/use-cache/SKILL.md +10 -9
package/src/browser/event-controller.ts +109 -2
package/src/browser/partial-update.ts +12 -0
package/src/browser/prefetch/cache.ts +17 -0
package/src/browser/prefetch/fetch.ts +69 -2
package/src/browser/react/Link.tsx +30 -5
package/src/browser/react/NavigationProvider.tsx +12 -2
package/src/browser/react/location-state-shared.ts +14 -2
package/src/browser/react/use-href.tsx +8 -1
package/src/browser/react/use-link-status.ts +23 -2
package/src/browser/response-adapter.ts +14 -3
package/src/browser/rsc-router.tsx +3 -0
package/src/browser/scroll-restoration.ts +8 -3
package/src/browser/server-action-bridge.ts +46 -11
package/src/browser/types.ts +6 -0
package/src/build/generate-route-types.ts +0 -1
package/src/build/route-trie.ts +33 -9
package/src/build/route-types/include-resolution.ts +7 -1
package/src/build/route-types/router-processing.ts +0 -6
package/src/build/route-types/source-scan.ts +105 -7
package/src/cache/cache-policy.ts +42 -8
package/src/cache/cache-runtime.ts +65 -5
package/src/cache/cache-scope.ts +71 -11
package/src/cache/cache-tag.ts +7 -2
package/src/cache/cf/cf-base64.ts +33 -0
package/src/cache/cf/cf-cache-constants.ts +127 -0
package/src/cache/cf/cf-cache-store.ts +85 -613
package/src/cache/cf/cf-cache-types.ts +349 -0
package/src/cache/cf/cf-kv-utils.ts +46 -0
package/src/cache/cf/cf-tag-marker-memo.ts +105 -0
package/src/cache/document-cache.ts +11 -0
package/src/cache/handle-snapshot.ts +8 -1
package/src/cache/profile-registry.ts +25 -1
package/src/cache/segment-codec.ts +9 -1
package/src/cache/types.ts +4 -0
package/src/client.rsc.tsx +38 -0
package/src/client.tsx +11 -0
package/src/components/DefaultDocument.tsx +8 -2
package/src/context-var.ts +1 -1
package/src/decode-loader-results.ts +7 -1
package/src/escape-script.ts +52 -0
package/src/handles/MetaTags.tsx +56 -5
package/src/handles/Scripts.tsx +183 -0
package/src/handles/breadcrumbs.ts +29 -11
package/src/handles/is-thenable.ts +19 -0
package/src/handles/meta.ts +46 -0
package/src/handles/script.ts +244 -0
package/src/host/cookie-handler.ts +7 -3
package/src/host/pattern-matcher.ts +16 -2
package/src/index.rsc.ts +5 -0
package/src/index.ts +5 -0
package/src/response-utils.ts +25 -0
package/src/route-definition/dsl-helpers.ts +7 -0
package/src/route-definition/redirect.ts +1 -2
package/src/router/content-negotiation.ts +58 -10
package/src/router/intercept-resolution.ts +9 -0
package/src/router/match-middleware/cache-store.ts +10 -1
package/src/router/middleware.ts +10 -3
package/src/router/pattern-matching.ts +25 -23
package/src/router/prefetch-cache-ttl.ts +51 -0
package/src/router/router-interfaces.ts +7 -0
package/src/router/router-options.ts +23 -0
package/src/router/segment-resolution/fresh.ts +10 -0
package/src/router/segment-resolution/helpers.ts +35 -1
package/src/router/segment-resolution/loader-cache.ts +10 -6
package/src/router/segment-resolution/revalidation.ts +6 -0
package/src/router/segment-resolution.ts +1 -0
package/src/router/trie-matching.ts +14 -9
package/src/router.ts +18 -10
package/src/rsc/handler.ts +52 -13
package/src/rsc/helpers.ts +7 -1
package/src/rsc/index.ts +1 -4
package/src/rsc/loader-fetch.ts +107 -37
package/src/rsc/progressive-enhancement.ts +18 -6
package/src/rsc/response-cache-serve.ts +238 -0
package/src/rsc/response-route-handler.ts +16 -133
package/src/rsc/rsc-rendering.ts +13 -4
package/src/rsc/server-action.ts +52 -6
package/src/rsc/types.ts +7 -0
package/src/search-params.ts +24 -5
package/src/segment-loader-promise.ts +17 -2
package/src/server/loader-registry.ts +16 -18
package/src/server/request-context.ts +47 -20
package/src/testing/dispatch.ts +108 -25
package/src/testing/flight.ts +25 -0
package/src/testing/internal/context.ts +25 -2
package/src/testing/render-handler.ts +3 -1
package/src/testing/render-route.tsx +15 -0
package/src/testing/run-loader.ts +10 -3
package/src/theme/ThemeProvider.tsx +20 -6
package/src/theme/ThemeScript.tsx +7 -3
package/src/theme/constants.ts +54 -3
package/src/theme/theme-script.ts +22 -7
package/src/types/request-scope.ts +8 -3
package/src/vite/plugins/cjs-to-esm.ts +8 -1
package/src/vite/plugins/expose-id-utils.ts +10 -1
package/src/vite/plugins/expose-ids/handler-transform.ts +5 -16
package/src/vite/plugins/expose-ids/loader-transform.ts +12 -5
package/src/vite/plugins/expose-ids/router-transform.ts +6 -1
package/src/vite/plugins/expose-internal-ids.ts +0 -1
package/src/vite/plugins/version-plugin.ts +5 -17
package/src/vite/plugins/virtual-entries.ts +12 -2
package/src/vite/rango.ts +15 -6
package/src/vite/utils/ast-handler-extract.ts +11 -4
package/src/vite/utils/directive-prologue.ts +40 -0
package/src/vite/utils/prerender-utils.ts +17 -2

package/src/client.tsx CHANGED Viewed

@@ -340,6 +340,11 @@ export { useRouter } from "./browser/react/use-router.js";
 export { usePathname } from "./browser/react/use-pathname.js";
 export { useSearchParams } from "./browser/react/use-search-params.js";
 export { useParams } from "./browser/react/use-params.js";
+// CSP nonce for the active request, for userland components that inject their
+// own <script>/<style> into the document head (analytics, GTM, inline init).
+// Returns the nonce during SSR and undefined in the browser; render the tag
+// server-side so the nonce lands in the SSR HTML and hydration stays clean.
+export { useNonce } from "./browser/react/nonce-context.js";
 export type {
   RouterInstance,
   RouterNavigateOptions,
@@ -391,6 +396,12 @@ export type { DeferredHandleEntry } from "./defer.js";
 export { Meta } from "./handles/meta.js";
 export { MetaTags } from "./handles/MetaTags.js";
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
+export {
+  Script,
+  type ScriptConfig,
+  type ScriptAttributes,
+} from "./handles/script.js";
+export { Scripts } from "./handles/Scripts.js";
 export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
 export {

package/src/components/DefaultDocument.tsx CHANGED Viewed

@@ -2,11 +2,13 @@
 import type { ReactNode, ReactElement } from "react";
 import { MetaTags } from "../handles/MetaTags.js";
+import { Scripts } from "../handles/Scripts.js";
 /**
  * Default document component that provides a basic HTML structure.
  * Used when no custom document is provided to createRouter.
- * Includes MetaTags for automatic charset, viewport, and route meta support.
+ * Includes MetaTags for automatic charset, viewport, and route meta support,
+ * and Scripts (head + body sites) so the Script handle works out of the box.
  *
  * Uses suppressHydrationWarning on <html> because the theme script
  * may modify class/style attributes before React hydrates.
@@ -20,8 +22,12 @@ export function DefaultDocument({
     <html lang="en" suppressHydrationWarning>
       <head>
         <MetaTags />
+        <Scripts />
       </head>
-      <body>{children}</body>
+      <body>
+        <Scripts position="body" />
+        {children}
+      </body>
     </html>
   );
 }

package/src/context-var.ts CHANGED Viewed

@@ -88,7 +88,7 @@ export function hasContextVars(variables: object): boolean {
  */
 const NON_CACHEABLE_KEYS: unique symbol = Symbol.for(
   "rango:non-cacheable-keys",
-) as any;
+);
 function getNonCacheableKeys(variables: any): Set<string | symbol> {
   if (!variables[NON_CACHEABLE_KEYS]) {

package/src/decode-loader-results.ts CHANGED Viewed

@@ -25,7 +25,13 @@ export function decodeLoaderResults(
       continue;
     }
-    if (result.fallback) {
+    // null/undefined is the producer's ONLY "no boundary found" sentinel
+    // (loader-resolution.ts sets fallback: null for the no-boundary and the
+    // fallback-render-threw cases). A matched boundary's rendered ReactNode can
+    // legitimately be falsy (0, "", false), so test for null explicitly rather
+    // than truthiness, otherwise a valid falsy fallback is discarded and the
+    // original loader error is rethrown.
+    if (result.fallback != null) {
       errorFallback = result.fallback;
     } else {
       // No boundary: rethrow preserving the ErrorInfo identity (name/stack/

package/src/escape-script.ts ADDED Viewed

@@ -0,0 +1,52 @@
+/**
+ * Escape a JSON (or JSON-derived) string for safe embedding inside an HTML
+ * <script> element via dangerouslySetInnerHTML. Without this a value containing
+ * "</script>" closes the tag early — the rest of the page leaks as raw HTML, and
+ * in an executable script the trailing content runs. Escaping "<" defeats the
+ * early close; ">" and "&" are escaped for completeness so the serialized payload
+ * can never form HTML syntax. The result is still valid JSON and a valid JS
+ * string literal (\uXXXX escapes are legal in both) and re-parses identically.
+ *
+ * Used by every site that interpolates JSON.stringify(...) into inline <script>
+ * content: the JSON-LD meta descriptors (handles/MetaTags) and the FOUC theme
+ * init script (theme/theme-script).
+ */
+export function escapeJsonForScript(json: string): string {
+  return json
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026");
+}
+/**
+ * Escape an inline <script> body so it cannot terminate or corrupt the document.
+ * Two sequences are rewritten, each via a JS escape that is valid in string,
+ * template, regex (including the `u`/`v` flags), and JSON contexts — so the body
+ * still parses identically as code AND as JSON (application/json, ld+json):
+ * - "</script" -> "<\/script": stops a literal close tag inside the body from
+ *   ending the element early. `\/` is a valid JSON escape and a valid regex escape.
+ * - "<!--": the "!" (U+0021) is emitted as a unicode escape (see the replacement
+ *   string below), so the literal "<!--" token never reaches the HTML parser. A
+ *   literal "<!--" puts the parser into the "script data escaped" state and a
+ *   following "<script" into "script data DOUBLE escaped", where the real
+ *   "</script>" no longer closes the element — `var x = "<!--<script>"` would
+ *   swallow the rest of the document. The unicode-escape form decodes back to "!"
+ *   in string/template/JSON/regex contexts, unlike "\!" (invalid JSON, invalid
+ *   /u-regex escape).
+ * Real operators such as `a < b` and `a && b` are untouched (unlike
+ * escapeJsonForScript, which \u-escapes every "<", "&", ">").
+ *
+ * GUARANTEE / LIMITATION: value-preserving for the contexts where these sequences
+ * legitimately appear — string/template literals, regexes (incl. `u`/`v`), and
+ * JSON. It is NOT source-text-preserving (e.g. String.raw`</script>` sees the
+ * extra backslash), and it cannot rewrite "</script"/"<!--" that appear as bare
+ * code (a legacy `<!--` line comment, or `</script` outside any literal) — neither
+ * occurs in valid script payloads. Not a general sanitizer for arbitrary UNTRUSTED
+ * source; for untrusted dynamic data, JSON-encode it and read it back, rather than
+ * inlining it as code.
+ *
+ * Used by the Script handle's <Scripts> renderer for inline `children`.
+ */
+export function escapeScriptBody(js: string): string {
+  return js.replace(/<!--/g, "<\\u0021--").replace(/<\/(script)/gi, "<\\/$1");
+}

package/src/handles/MetaTags.tsx CHANGED Viewed

@@ -8,6 +8,10 @@
  *
  * When theme is enabled in the router config, MetaTags also renders
  * the theme initialization script to prevent FOUC (flash of unstyled content).
+ * This makes MetaTags the sole FOUC-script injector for apps that render it;
+ * the standalone `<ThemeScript />` is only needed when MetaTags is not used.
+ * Rendering both is safe (the inline script guards listener registration) but
+ * redundant.
  *
  * @example
  * ```tsx
@@ -27,10 +31,12 @@
 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 { useThemeContext } from "../theme/theme-context.js";
 import { generateThemeScript } from "../theme/theme-script.js";
 import { useNonce } from "../browser/react/nonce-context.js";
+import { escapeJsonForScript } from "../escape-script.js";
 // Type guards for MetaDescriptorBase variants
 function hasCharSet(d: MetaDescriptorBase): d is { charSet: "utf-8" } {
@@ -91,10 +97,13 @@ function hasTagName(
 }
 /**
- * Check if a value is a Promise.
+ * 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 value !== null && typeof value === "object" && "then" in value;
+  return isThenable(value);
 }
 function renderMetaDescriptor(
@@ -140,7 +149,9 @@ function renderMetaDescriptor(
   }
   if (hasScriptLdJson(descriptor)) {
-    const json = JSON.stringify(descriptor["script:ld+json"]);
+    const json = escapeJsonForScript(
+      JSON.stringify(descriptor["script:ld+json"]),
+    );
     return (
       <script
         key={`ld-json-${index}`}
@@ -178,14 +189,54 @@ function renderMetaDescriptor(
   );
 }
-function AsyncMetaTag({
+// 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(promise);
+  const resolved = use(toSafeMetaPromise(promise));
+  if (resolved === REJECTED_META) return null;
   return renderMetaDescriptor(resolved, index);
 }

package/src/handles/Scripts.tsx ADDED Viewed

@@ -0,0 +1,183 @@
+"use client";
+/**
+ * Renders the scripts collected by the Script handle into the document.
+ *
+ * Place `<Scripts />` inside `<head>` (default) and, if you push body scripts,
+ * `<Scripts position="body" />` at the top of `<body>`. Each site renders the
+ * configs whose `position` matches; the request CSP nonce is applied
+ * automatically to every DOCUMENT-RENDERED <script> (consumers never pass it). An
+ * async script first encountered on a soft navigation is injected client-side
+ * where the nonce is unavailable, so it carries no nonce and relies on
+ * 'strict-dynamic' (or a host allowance) — see the nonce caveat in the /scripts
+ * skill.
+ *
+ * EXECUTION CONTRACT — see the Script handle's docs. Inline + ordered (defer)
+ * scripts are document-load: they execute only when present in the initial HTML,
+ * so this component FREEZES that set after hydration (the initializer below runs
+ * once) — a later soft navigation never inserts an inert <script> (React creates
+ * client-mounted scripts via innerHTML, which the HTML spec makes non-executing).
+ * Async external scripts are React resources and stay reactive: React loads them
+ * on first encounter, including after navigation, deduped by src.
+ *
+ * @example
+ * ```tsx
+ * <html>
+ *   <head>
+ *     <MetaTags />
+ *     <Scripts />
+ *   </head>
+ *   <body>
+ *     <Scripts position="body" />
+ *     {children}
+ *   </body>
+ * </html>
+ * ```
+ */
+import { useState, type ReactNode } from "react";
+import { useHandle } from "../browser/react/use-handle.js";
+import { useNonce } from "../browser/react/nonce-context.js";
+import { escapeScriptBody } from "../escape-script.js";
+import { Script, type ScriptAttributes, type ScriptConfig } from "./script.js";
+/** An external async script is a React-managed resource (reactive on nav). */
+function isAsyncResource(config: ScriptConfig): boolean {
+  return config.src != null && config.async === true;
+}
+// Fields the Script handle owns (set via the ScriptConfig fields, applied as
+// explicit props by renderScript) plus the inline-content props. Dropped from the
+// attributes bag so untyped/serialized input cannot smuggle them in — e.g.
+// `children`/`dangerouslySetInnerHTML` alongside an inline body makes React throw,
+// or `src` on an inline script. The discriminated type already excludes these;
+// this is the runtime guard.
+const MANAGED_ATTRS = new Set([
+  "id",
+  "src",
+  "async",
+  "defer",
+  "type",
+  "children",
+  "nonce",
+  "dangerouslySetInnerHTML",
+]);
+// Drop managed fields + any `on*` event handlers (a config serializes across the
+// server -> client boundary, so a function cannot survive it) from the passthrough
+// attributes, warning in dev.
+function passthroughAttributes(
+  attributes: ScriptAttributes | undefined,
+): Record<string, unknown> {
+  if (!attributes) return {};
+  const out: Record<string, unknown> = {};
+  const dev = process.env.NODE_ENV !== "production";
+  for (const [key, value] of Object.entries(
+    attributes as Record<string, unknown>,
+  )) {
+    const isHandler = key.startsWith("on");
+    if (isHandler || MANAGED_ATTRS.has(key)) {
+      if (dev) {
+        console.warn(
+          isHandler
+            ? `[Scripts] event handler "${key}" in a script's attributes is ` +
+                `dropped; callbacks cannot cross the server -> client handle ` +
+                `boundary. Use a "use client" component for load/error handling.`
+            : `[Scripts] managed field "${key}" in a script's attributes is ` +
+                `dropped; set it via the ScriptConfig fields (the request nonce ` +
+                `is applied automatically).`,
+        );
+      }
+      continue;
+    }
+    out[key] = value;
+  }
+  return out;
+}
+function renderScript(
+  config: ScriptConfig,
+  nonce: string | undefined,
+  index: number,
+): ReactNode {
+  const { id, src, children, async, defer, type, attributes } = config;
+  const key = id ?? src ?? `rango-script-${index}`;
+  const attrs = passthroughAttributes(attributes);
+  // Inline: rendered in place (never hoisted), escaped against </script> breakout.
+  // The server-only nonce makes the attribute differ from the (undefined) client
+  // value, so suppressHydrationWarning is required — the same sanctioned pattern
+  // as the theme/Meta inline scripts.
+  if (src == null) {
+    if (children == null) return null;
+    return (
+      <script
+        key={key}
+        {...attrs}
+        id={id}
+        type={type}
+        nonce={nonce}
+        suppressHydrationWarning
+        dangerouslySetInnerHTML={{ __html: escapeScriptBody(children) }}
+      />
+    );
+  }
+  if (
+    process.env.NODE_ENV !== "production" &&
+    config.position === "body" &&
+    async
+  ) {
+    console.warn(
+      `[Scripts] An async external script (src="${src}") is hoisted into ` +
+        `<head> by React; position: "body" is ignored for it.`,
+    );
+  }
+  // External: async => React-hoisted, src-deduped resource; otherwise in place
+  // (defer or plain), preserving authoring order.
+  return (
+    <script
+      key={key}
+      {...attrs}
+      id={id}
+      type={type}
+      src={src}
+      async={async}
+      defer={defer}
+      nonce={nonce}
+      suppressHydrationWarning
+    />
+  );
+}
+export function Scripts({
+  position = "head",
+}: { position?: "head" | "body" } = {}): ReactNode {
+  const all = useHandle(Script) as ScriptConfig[];
+  const nonce = useNonce();
+  const forPosition = all.filter(
+    (config) => (config.position ?? "head") === position,
+  );
+  // Document-load scripts (inline + ordered external) execute only from the
+  // initial HTML, so freeze them to the first-render set. The initializer runs
+  // during SSR and again at hydration with the same handle data, so the output
+  // matches; afterwards a navigation cannot add an inert <script>.
+  const [documentLoad] = useState(() =>
+    forPosition.filter((config) => !isAsyncResource(config)),
+  );
+  // Async external scripts are resources React loads on first encounter; keep
+  // them reactive so a script first reached via navigation still loads.
+  const asyncResources = forPosition.filter(isAsyncResource);
+  return (
+    <>
+      {documentLoad.map((config, index) => renderScript(config, nonce, index))}
+      {asyncResources.map((config, index) =>
+        renderScript(config, nonce, index),
+      )}
+    </>
+  );
+}

package/src/handles/breadcrumbs.ts CHANGED Viewed

@@ -3,7 +3,8 @@
  *
  * Each layout/route pushes breadcrumb items via `ctx.use(Breadcrumbs)`.
  * Items are collected in parent-to-child order with automatic deduplication
- * by `href` (last item for each href wins).
+ * by `href`: each href keeps its FIRST position but takes the LAST value, so a
+ * child re-pushing a parent href refreshes the label without reordering the trail.
  *
  * @example
  * ```tsx
@@ -22,6 +23,7 @@
 import type { ReactNode } from "react";
 import { createHandle, type Handle } from "../handle.js";
+import { isThenable } from "./is-thenable.js";
 /**
  * A single breadcrumb item.
@@ -38,8 +40,10 @@ export interface BreadcrumbItem {
 /**
  * Collect function for Breadcrumbs handle.
- * Flattens segments in parent-to-child order with deduplication by href
- * (last item for each href wins). Deferred slots (`ctx.use(Breadcrumbs).defer()`)
+ * 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.
@@ -50,18 +54,32 @@ function collectBreadcrumbs(segments: BreadcrumbItem[][]): BreadcrumbItem[] {
   const isResolvedItem = (item: unknown): item is BreadcrumbItem =>
     item != null &&
     typeof item === "object" &&
-    typeof (item as { then?: unknown }).then !== "function" &&
+    !isThenable(item) &&
     typeof (item as { href?: unknown }).href === "string";
-  const seen = new Map<string, number>();
-  for (let i = 0; i < all.length; i++) {
-    if (isResolvedItem(all[i])) seen.set(all[i].href, i);
+  // 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.
+  const valueByHref = new Map<string, BreadcrumbItem>();
+  for (const item of all) {
+    if (isResolvedItem(item)) valueByHref.set(item.href, item);
   }
-  // Deferred items bypass dedup (excluded via !isResolvedItem check).
-  return all.filter(
-    (item, index) => !isResolvedItem(item) || seen.get(item.href) === index,
-  );
+  const result: BreadcrumbItem[] = [];
+  const emitted = new Set<string>();
+  for (const item of all) {
+    if (!isResolvedItem(item)) {
+      result.push(item);
+      continue;
+    }
+    // Emit each href once, at its first occurrence, with the final value.
+    if (!emitted.has(item.href)) {
+      emitted.add(item.href);
+      result.push(valueByHref.get(item.href)!);
+    }
+  }
+  return result;
 }
 /**

package/src/handles/is-thenable.ts ADDED Viewed

@@ -0,0 +1,19 @@
+/**
+ * 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).
+ *
+ * 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.
+ */
+export function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}

package/src/handles/meta.ts CHANGED Viewed

@@ -29,12 +29,20 @@
  */
 import { createHandle, type Handle } from "../handle.js";
+import { isThenable } from "./is-thenable.js";
 import type {
   MetaDescriptor,
+  MetaDescriptorBase,
   TitleDescriptor,
   UnsetDescriptor,
 } from "../router/types.js";
+function isPromiseDescriptor(
+  descriptor: MetaDescriptor,
+): descriptor is Promise<MetaDescriptorBase> {
+  return isThenable(descriptor);
+}
 function isUnsetDescriptor(
   descriptor: MetaDescriptor,
 ): descriptor is UnsetDescriptor {
@@ -158,6 +166,37 @@ 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;
+      }
       if (isUnsetDescriptor(descriptor)) {
         const keyToRemove = descriptor.unset;
         if (keyToIndex.has(keyToRemove)) {
@@ -222,6 +261,13 @@ 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 }>`.
  */
 export const Meta: Handle<MetaDescriptor, MetaDescriptor[]> = createHandle<
   MetaDescriptor,