@rangojs/router 0.0.0-experimental.79 → 0.0.0-experimental.7c7e4327

package/src/handles/MetaTags.tsx

@@ -3,11 +3,16 @@
 /**
  * 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).
+ * 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
@@ -24,13 +29,13 @@
  * ```
  */
 
-import { use } from "react";
 import { useHandle } from "../browser/react/use-handle.js";
 import { Meta } from "./meta.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";
+import { escapeJsonForScript } from "../escape-script.js";
 
 // Type guards for MetaDescriptorBase variants
 function hasCharSet(d: MetaDescriptorBase): d is { charSet: "utf-8" } {
@@ -90,31 +95,18 @@ function hasTagName(
   );
 }
 
-/**
- * Check if a value is a Promise.
- */
-function isPromise(value: unknown): value is Promise<unknown> {
-  return value !== null && typeof value === "object" && "then" in value;
-}
-
-/**
- * Render a single meta descriptor as a React element.
- */
-function renderMetaDescriptor(
+export function renderMetaDescriptor(
   descriptor: MetaDescriptorBase,
   index: number,
 ): React.ReactNode {
-  // charset
   if (hasCharSet(descriptor)) {
     return <meta key="charSet" charSet={descriptor.charSet} />;
   }
 
-  // title
   if (hasTitle(descriptor)) {
     return <title key="title">{descriptor.title}</title>;
   }
 
-  // name + content (description, viewport, etc.)
   if (hasNameContent(descriptor)) {
     return (
       <meta
@@ -125,7 +117,6 @@ function renderMetaDescriptor(
     );
   }
 
-  // property + content (Open Graph, etc.)
   if (hasPropertyContent(descriptor)) {
     return (
       <meta
@@ -136,7 +127,6 @@ function renderMetaDescriptor(
     );
   }
 
-  // http-equiv + content
   if (hasHttpEquivContent(descriptor)) {
     return (
       <meta
@@ -147,9 +137,10 @@ function renderMetaDescriptor(
     );
   }
 
-  // JSON-LD structured data
   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}`}
@@ -159,7 +150,6 @@ function renderMetaDescriptor(
     );
   }
 
-  // Custom tagName (meta or link with arbitrary attributes)
   if (hasTagName(descriptor)) {
     const { tagName, ...rest } = descriptor;
     if (tagName === "link") {
@@ -180,7 +170,6 @@ function renderMetaDescriptor(
     }
   }
 
-  // Fallback: treat as meta attributes
   return (
     <meta
       key={`meta-fallback-${index}`}
@@ -189,20 +178,6 @@ function renderMetaDescriptor(
   );
 }
 
-/**
- * Wrapper component to resolve a Promise<MetaDescriptorBase> using use().
- */
-function AsyncMetaTag({
-  promise,
-  index,
-}: {
-  promise: Promise<MetaDescriptorBase>;
-  index: number;
-}): React.ReactNode {
-  const resolved = use(promise);
-  return renderMetaDescriptor(resolved, index);
-}
-
 /**
  * Renders all collected meta descriptors from route handlers.
  *
@@ -212,11 +187,16 @@ 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();
 
@@ -229,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/Scripts.tsx

@@ -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

@@ -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
@@ -38,19 +39,45 @@ 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).
+ * 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
+ * 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 seen = new Map<string, number>();
 
-  for (let i = 0; i < all.length; i++) {
-    seen.set(all[i].href, i);
+  const hasHref = (item: unknown): item is BreadcrumbItem =>
+    item != null &&
+    typeof item === "object" &&
+    typeof (item as { href?: unknown }).href === "string";
+
+  // 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 (hasHref(item)) valueByHref.set(item.href, item);
   }
 
-  // Return items in order, keeping only the last occurrence per href
-  return all.filter((item, index) => seen.get(item.href) === index);
+  const result: BreadcrumbItem[] = [];
+  const emitted = new Set<string>();
+  for (const item of all) {
+    if (!hasHref(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/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

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