@ultimat3/render 1.2.0 → 2.0.0

package/src/registry.ts

@@ -11,7 +11,7 @@ import {
   RouteUnnormalizedError,
   SurfaceBoundaryError,
 } from './errors';
-import { assertModeInvariants } from './modes';
+import { assertModeInvariants, defaultIslandBudget } from './modes';
 import type {
   HydrateStrategy,
   OfflineStrategy,
@@ -21,8 +21,9 @@ import type {
   RouteParams,
 } from './route';
 import { isRouteConfig, tagKeys } from './route';
+import type { RouteComponent } from './route-component';
 import type { Surface } from './surfaces';
-import { surfaceOf } from './surfaces';
+import { locateSurface } from './surfaces';
 
 /**
  * The one filename a route may carry, per surface. `shared/` is absent on purpose: it is a leaf
@@ -47,6 +48,11 @@ export interface RouteEntry<TData = RouteData> {
   readonly suspenseBoundaries: number;
   readonly islands: readonly string[];
   readonly pattern: CompiledPattern;
+  /**
+   * The module's page component. Absent for `api/` routes and for a module that exports none —
+   * a `spa` shell is the mode that legitimately has no server-rendered body.
+   */
+  readonly component?: RouteComponent;
 }
 
 export interface RouteDescriptor {
@@ -93,16 +99,19 @@ export interface CompiledPattern {
  */
 export function routePathFromFile(file: string): { surface: Surface; path: string } {
   const normalized = file.replace(/\\/g, '/').replace(/^\.\//, '');
-  const surface = surfaceOf(normalized);
-  if (surface === null) {
+  // One reader of the surface segment, and it answers WHERE as well as WHICH. Slicing at
+  // `indexOf('app/')` instead matched inside `myapp/`, so `apps/myapp/app/page.tsx` resolved to
+  // `/app` rather than `/` — the surface came from an anchored regex and the URL from a substring.
+  const located = locateSurface(normalized);
+  if (located === null) {
     throw new SurfaceBoundaryError(
       `${file} is not inside a surface directory, so it has no URL and no bundle graph`,
       `move ${file} under site/, app/ or api/`,
     );
   }
+  const surface = located.surface;
 
-  const afterSurface = normalized.slice(normalized.indexOf(`${surface}/`) + surface.length + 1);
-  const rawSegments = afterSurface.split('/').filter((s) => s.length > 0);
+  const rawSegments = located.rest.split('/').filter((s) => s.length > 0);
   assertRouteFilename(normalized, surface, rawSegments[rawSegments.length - 1]);
 
   const urlSegments = rawSegments
@@ -197,9 +206,14 @@ export interface RegisterRouteInput<TData = RouteData> {
   readonly config: RouteConfig<TData>;
   /** Counted from the module's JSX by the build; `stream` requires >= 1. */
   readonly suspenseBoundaries?: number;
-  readonly islands?: readonly string[];
+  // No `islands` key: an island is declared by `island()` and reaches the entry through
+  // `config.islands`. It was here, undocumented, passed by nothing, and read as
+  // `input.islands ?? []` — so the only thing a caller could do with it was un-weigh a
+  // declaration. One question, one answer.
   /** Override the convention (locale roots, rewrites). Rarely needed. */
   readonly path?: string;
+  /** The page component, resolved from the module by `pageComponentOf`. */
+  readonly component?: RouteComponent;
 }
 
 /** Register a route and enforce every invariant that needs the surrounding module. */
@@ -220,8 +234,11 @@ export function registerRoute<TData = RouteData>(
   const derived = routePathFromFile(input.file);
   const path = input.path ?? derived.path;
   const suspenseBoundaries = input.suspenseBoundaries ?? 0;
+  // Explicit `<TData>`: `isRouteConfig` is a guard over the default `RouteData`, so inference off
+  // the narrowed argument would resolve the route's own data generic away here.
+  const config = withIslandBudget<TData>(input.config, derived.surface);
 
-  assertModeInvariants(input.config, {
+  assertModeInvariants(config, {
     file: input.file,
     path,
     surface: derived.surface,
@@ -240,15 +257,43 @@ export function registerRoute<TData = RouteData>(
     file: input.file,
     path,
     surface: derived.surface,
-    config: input.config,
+    config,
     suspenseBoundaries,
-    islands: input.islands ?? [],
+    // The declaration is the ONLY source. It was `input.islands ?? []`, which nothing ever passed,
+    // so `routeJsBytes`'s "what registration declared" half read `[]` on every route in the
+    // framework's history — and keeping the input as a fallback would be a second answer to one
+    // question that can only ever weaken it: a caller passing `[]` un-weighs a declared island.
+    islands: config.islands.map((spec) => spec.moduleId),
     pattern: compilePattern(path),
+    // Spread, never assigned: `exactOptionalPropertyTypes` makes an explicit `undefined` a
+    // different answer from an absent key, and every reader tests presence.
+    ...(input.component === undefined ? {} : { component: input.component }),
   };
   routes.set(path, entry as RouteEntry);
   return entry;
 }
 
+/**
+ * The half of the derivation `defineRoute` cannot make: a budget is only meaningful against a
+ * surface baseline, and the surface is a fact of the file path, which the route table is already
+ * the one reader of. `defineRoute` stays the normalizer of everything the declaration alone
+ * decides; this fills in the one value that needs the URL.
+ *
+ * Returns the descriptor untouched unless there is something to derive, so identity is preserved
+ * for every route that declared a budget or has no island.
+ */
+function withIslandBudget<TData>(config: RouteConfig<TData>, surface: Surface): RouteConfig<TData> {
+  // `'never'` is left bare on purpose: a route that ships no JavaScript has nothing to budget, and
+  // a derived ceiling there would paper over the one contradiction `X_ISLAND_NOT_HYDRATED` names.
+  if (config.hydrate === 'never') return config;
+  if (config.islands.length === 0 || config.budget.js !== undefined) return config;
+  const derived: RouteConfig<TData> = {
+    ...config,
+    budget: { ...config.budget, js: defaultIslandBudget(surface) },
+  };
+  return Object.freeze(derived);
+}
+
 export function clearRoutes(): void {
   routes.clear();
 }
@@ -303,11 +348,32 @@ export function matchRoute(pathname: string): RouteMatch | null {
     const match = entry.pattern.regex.exec(pathname);
     if (match === null) continue;
     const params: Record<string, string> = {};
+    let undecodable = false;
     entry.pattern.keys.forEach((key, index) => {
       const value = match[index + 1];
-      if (value !== undefined) params[key] = decodeURIComponent(value);
+      if (value === undefined) return;
+      const decoded = decodeSegment(value);
+      if (decoded === undefined) undecodable = true;
+      else params[key] = decoded;
     });
+    // A segment that will not decode fails only the branch that would have decoded it, exactly as
+    // `@ultimat3/http`'s router already answers: a literal route matching the same text still wins,
+    // and a pathname nothing else claims is the 404 it always was.
+    if (undecodable) continue;
     return { entry, params };
   }
   return null;
 }
+
+/**
+ * `undefined` for a malformed percent-escape. A pathname is whatever the client typed, and
+ * `decodeURIComponent('%zz')` throws a bare `URIError` — no code, no fix line — which escaped
+ * `matchRoute` as a 500 and an error-monitor page for somebody's typo.
+ */
+function decodeSegment(value: string): string | undefined {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return undefined;
+  }
+}

package/src/render-html.ts

@@ -0,0 +1,149 @@
+/**
+ * The tree walker: a JSX node in, an HTML string out. It is the one place that knows what a
+ * component call means on the server, so every render mode gets the same markup from the same
+ * component — `static` at build time, `ssr`/`stream` per request, all through `renderToHtml`.
+ */
+
+import {
+  IslandInvalidError,
+  IslandNotHydratedError,
+  IslandPropsInvalidError,
+  PrerenderFailedError,
+} from './errors';
+import { escapeText, renderAttributes, VOID_ELEMENTS } from './html';
+import { emitIslandAttributes, emitIslandProps } from './hydrate';
+import type { IslandNode } from './island';
+import { isIslandNode } from './island';
+import type { IslandCollector } from './island-collector';
+import { islandWithoutCollector } from './island-collector';
+import type { JsxComponent, JsxProps } from './jsx';
+import { isJsxNode } from './jsx';
+
+/** Depth is bounded so a component that renders itself fails with a cause instead of a stack trace. */
+const MAX_DEPTH = 500;
+
+/**
+ * What the walk carries besides depth. One object per render, never module-global: two concurrent
+ * requests render different params, and a shared collector would bill one page for the other's JS.
+ */
+export interface RenderHtmlOptions {
+  readonly islands?: IslandCollector;
+}
+
+const describe = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+/**
+ * A thunk is called, not stringified. Solid's reactive reads are accessors (`count()`), and a
+ * `children` prop is routinely a function — evaluating it once is exactly the server's job.
+ */
+async function unwrap(value: unknown, depth: number, walk: RenderHtmlOptions): Promise<string> {
+  if (value === null || value === undefined || value === false || value === true) return '';
+  if (typeof value === 'string') return escapeText(value);
+  if (typeof value === 'number' || typeof value === 'bigint') return escapeText(String(value));
+  if (value instanceof Promise) return unwrap(await value, depth, walk);
+  // Before the array branch, never after: an island node IS an array — the only object shape the
+  // configured `JSX.Element` admits — so the generic branch would render its empty contents and
+  // drop the island, its props script and its budget line without a word.
+  if (isIslandNode(value)) return renderIsland(value, depth, walk);
+  if (Array.isArray(value)) {
+    const parts = await Promise.all(value.map((item) => unwrap(item, depth + 1, walk)));
+    return parts.join('');
+  }
+  if (isJsxNode(value)) return renderNode(value.type, value.props, depth, walk);
+  if (typeof value === 'function') return unwrap((value as () => unknown)(), depth + 1, walk);
+  return escapeText(String(value));
+}
+
+/**
+ * `innerHTML` is the one escape hatch that emits unescaped markup, and it is deliberate: the
+ * `<head>` renderers and the streaming reveal chunks are already-serialized HTML, and re-escaping
+ * them would print the tags. Nothing else in this file trusts a string.
+ */
+async function renderElement(
+  tag: string,
+  props: JsxProps,
+  depth: number,
+  walk: RenderHtmlOptions,
+): Promise<string> {
+  const open = `<${tag}${renderAttributes(props)}>`;
+  if (VOID_ELEMENTS.has(tag)) return open;
+  const raw = (props as { innerHTML?: unknown }).innerHTML;
+  const inner =
+    raw === undefined || raw === null
+      ? await unwrap((props as { children?: unknown }).children, depth + 1, walk)
+      : String(raw);
+  return `${open}${inner}</${tag}>`;
+}
+
+/**
+ * An island renders its SHELL on the server — the children the page wrote — and nothing of the
+ * client module: the specifier is data, so there is no import to follow and the static page's
+ * bundle graph never grows. The props script travels inside the wrapper so a document assembler
+ * has exactly one thing left to remember, the runtime.
+ */
+async function renderIsland(
+  node: IslandNode,
+  depth: number,
+  walk: RenderHtmlOptions,
+): Promise<string> {
+  const collector = walk.islands;
+  if (collector === undefined) throw islandWithoutCollector(node.spec);
+  const directive = collector.record(node.spec, node.props);
+  const shell = await unwrap((node.props as { children?: unknown }).children, depth + 1, walk);
+  const tag = node.spec.tag;
+  return `<${tag} ${emitIslandAttributes(directive)}>${shell}${emitIslandProps(directive)}</${tag}>`;
+}
+
+async function renderNode(
+  type: string | JsxComponent,
+  props: JsxProps,
+  depth: number,
+  walk: RenderHtmlOptions,
+): Promise<string> {
+  if (depth > MAX_DEPTH) {
+    throw new PrerenderFailedError(
+      `component tree exceeded ${MAX_DEPTH} levels, so it renders itself`,
+      'remove the self-reference from the component that renders its own tag',
+    );
+  }
+  if (typeof type === 'string') return renderElement(type, props, depth, walk);
+  return unwrap(type(props), depth + 1, walk);
+}
+
+/**
+ * Render a component tree to HTML. Async throughout so a component may await its own data — the
+ * `ssr` mode's whole point — without a second sync renderer existing beside this one.
+ */
+export async function renderToHtml(
+  node: unknown,
+  options: RenderHtmlOptions = {},
+): Promise<string> {
+  return unwrap(node, 0, options);
+}
+
+/**
+ * Render a route's page component, naming the file in the failure. A component that throws is a
+ * build failure with a cause, never a blank body that looks like a routing problem.
+ */
+export async function renderComponent(
+  component: JsxComponent,
+  props: JsxProps,
+  file: string,
+  options: RenderHtmlOptions = {},
+): Promise<string> {
+  try {
+    return await renderToHtml(component(props), options);
+  } catch (error) {
+    // An island failure already names the file, the prop and the edit. Wrapping it would replace
+    // three stable codes with one that says only "the component threw".
+    if (error instanceof PrerenderFailedError) throw error;
+    if (error instanceof IslandInvalidError) throw error;
+    if (error instanceof IslandPropsInvalidError) throw error;
+    if (error instanceof IslandNotHydratedError) throw error;
+    throw new PrerenderFailedError(
+      `rendering the component in ${file} threw: ${describe(error)}`,
+      `run \`bun test ${file.replace(/\.tsx?$/, '.test.ts')}\` to reproduce, then fix ${file}`,
+    );
+  }
+}

package/src/render-isr.ts

@@ -5,7 +5,7 @@
  * and tag-driven staleness (an action's `invalidates` marks exactly the dependent routes).
  */
 
-import type { CacheTag } from '@ultimat3/cache';
+import type { CacheTag, Revalidator } from '@ultimat3/cache';
 import {
   dependentsOfKind,
   invalidateTags,
@@ -38,12 +38,34 @@ export interface IsrStore {
   paths(): readonly string[];
 }
 
-export function memoryIsrStore(): IsrStore {
+/**
+ * How many rendered pages the default store holds. A route table supports `:params` and `*`, so
+ `/blog/:slug` has as many ISR paths as the blog has slugs — 404-shaped ones that still render
+ * included. Unbounded, a crawler over 100k slugs is 100k HTML strings resident for the life of
+ * the process.
+ */
+export const DEFAULT_ISR_MAX_ENTRIES = 1_000;
+
+export interface MemoryIsrStoreOptions {
+  /** Pages retained. The least recently generated goes first. */
+  readonly maxEntries?: number;
+}
+
+export function memoryIsrStore(options: MemoryIsrStoreOptions = {}): IsrStore {
+  const maxEntries = options.maxEntries ?? DEFAULT_ISR_MAX_ENTRIES;
   const map = new Map<string, IsrEntry>();
   return {
     get: (path) => map.get(path),
     set: (entry) => {
+      // Re-inserted rather than overwritten, so the Map's iteration order IS generation order and
+      // the first key is the least recently generated page.
+      map.delete(entry.path);
       map.set(entry.path, entry);
+      while (map.size > maxEntries) {
+        const oldest = map.keys().next();
+        if (oldest.done === true) break;
+        map.delete(oldest.value);
+      }
     },
     delete: (path) => {
       map.delete(path);
@@ -109,6 +131,15 @@ export interface IsrController {
   attach(): () => void;
 }
 
+/**
+ * `@ultimat3/cache` holds ONE revalidator and offers no read back, so detaching has to know
+ * whether the slot is still this controller's — a controller that attached after it owns it now.
+ */
+let installedRevalidator: Revalidator | undefined;
+
+/** What `registerRevalidator` is handed on detach: the framework's "nothing to revalidate". */
+const NO_REVALIDATION: Revalidator = () => undefined;
+
 export function createIsrController(options: IsrControllerOptions = {}): IsrController {
   const store = options.store ?? memoryIsrStore();
   const now = options.now ?? (() => Date.now());
@@ -135,6 +166,23 @@ export function createIsrController(options: IsrControllerOptions = {}): IsrCont
     registered.add(path);
   }
 
+  /**
+   * A registration is only true while the store still holds the page. The store evicts silently
+   * and offers no callback — and a custom `IsrStore` need not have one at all — so the store's own
+   * `paths()` is the authority, reconciled after every generation. Left alone, `registered` and
+   * the cache graph behind it only ever grew: `/blog/:slug` retains one edge per slug ever
+   * requested, 404-shaped ones included, for the life of the process.
+   */
+  function forgetEvictedPaths(): void {
+    if (registered.size === 0) return;
+    const live = new Set(store.paths());
+    for (const path of registered) {
+      if (live.has(path)) continue;
+      unregisterDependent({ kind: 'isr-route', id: path });
+      registered.delete(path);
+    }
+  }
+
   function isFresh(entry: IsrEntry): boolean {
     if (entry.stale) return false;
     if (entry.ttlMs === null) return true; // tag-only revalidation: fresh until invalidated
@@ -158,6 +206,7 @@ export function createIsrController(options: IsrControllerOptions = {}): IsrCont
       };
       store.set(entry);
       registerPath(path, descriptor);
+      forgetEvictedPaths();
       return entry;
     })();
 
@@ -223,12 +272,23 @@ export function createIsrController(options: IsrControllerOptions = {}): IsrCont
 
     attach() {
       // The cache fanout owns the trigger; render owns only "what does stale mean here".
-      registerRevalidator((path) => {
+      const revalidate: Revalidator = (path) => {
         markStale(path);
-      });
+      };
+      registerRevalidator(revalidate);
+      installedRevalidator = revalidate;
       return () => {
         for (const path of registered) unregisterDependent({ kind: 'isr-route', id: path });
         registered.clear();
+        // Left installed, this closure — and the whole store behind it — stayed reachable from
+        // the cache graph and kept receiving revalidations. `x dev`'s hot reload detached A and
+        // created B, and `invalidateTags` still called A's `markStale`: B's pages never went
+        // stale and A's store was never collected. Only if the slot is still OURS: a controller
+        // that attached after us owns it, and clearing that one is this bug pointed backwards.
+        if (installedRevalidator === revalidate) {
+          registerRevalidator(NO_REVALIDATION);
+          installedRevalidator = undefined;
+        }
       };
     },
   };

package/src/render-stream.ts

@@ -19,7 +19,11 @@ export interface StreamHole {
   readonly id: string;
   /** Rendered synchronously into the first flush (the `<Suspense fallback>`). */
   readonly fallback: string;
-  readonly resolve: () => Promise<string>;
+  /**
+   * `signal` aborts when the response is cancelled — a client that disconnected mid-stream. A
+   * hole that ignores it still finishes; it just finishes into a document nobody reads.
+   */
+  readonly resolve: (signal: AbortSignal) => Promise<string>;
 }
 
 export interface StreamPlan {
@@ -56,10 +60,25 @@ export function revealChunk(id: string, html: string): string {
   return `<template data-x-hole="${key}">${html}</template><script>$X("${key}")</script>`;
 }
 
+/**
+ * How long one hole may take before it is treated as failed. A hole is application code the
+ * framework `await`s — a query with no statement timeout, a fetch with no `AbortSignal.timeout` —
+ * and nothing else in the system bounds one: `settle` fires from the hole's own promise, so a
+ * promise that never settles holds the response, the socket and everything its closure retains
+ * for the life of the process. Long enough that a slow page still renders, short enough that a
+ * hung one is a fallback rather than a leak.
+ */
+export const DEFAULT_HOLE_TIMEOUT_MS = 15_000;
+
 export interface StreamOptions {
   readonly buildId: string;
   /** Rendered into a hole whose promise rejected. Keep it a token-styled inline block. */
   readonly errorFallback?: (holeId: string) => string;
+  /**
+   * Per-hole deadline in ms. `null` waits forever — the deliberate opt-out for a hole that owns
+   * its own timeout, never the default, because "forever" is not a deadline anyone chose.
+   */
+  readonly holeTimeoutMs?: number | null;
 }
 
 /**
@@ -75,20 +94,40 @@ export function renderStreamHtml(
   const tail = plan.tail ?? '</body></html>';
   const errorFallback =
     options.errorFallback ?? ((id) => `<div data-x-hole-error="${id}" hidden></div>`);
+  const timeoutMs =
+    options.holeTimeoutMs === undefined ? DEFAULT_HOLE_TIMEOUT_MS : options.holeTimeoutMs;
+  /**
+   * The response's own lifetime. A client that disconnects mid-stream cancels the stream, and
+   * both halves of that have to be honoured: nothing more may be enqueued — `settle`'s
+   * `write(tail)`/`close()` on a cancelled controller threw out of a `void`ed promise, one
+   * unhandled rejection per response — and the holes still running must be told to stop doing
+   * their database work for a document nobody will read.
+   */
+  const holes = new AbortController();
+  let closed = false;
 
   return new ReadableStream<Uint8Array>({
     start(controller) {
       const write = (chunk: string): void => {
+        // `desiredSize` is null once the controller is closed or errored, which is the half a
+        // cancellation flag cannot see on its own.
+        if (closed || controller.desiredSize === null) return;
         controller.enqueue(encoder.encode(chunk));
       };
 
+      const close = (): void => {
+        if (closed) return;
+        closed = true;
+        controller.close();
+      };
+
       // No holes, no reveal script: a page that streams nothing pays nothing.
       write(plan.head + (plan.holes.length > 0 ? REVEAL_SCRIPT : '') + plan.shell);
 
       let pending = plan.holes.length;
       if (pending === 0) {
         write(tail);
-        controller.close();
+        close();
         return;
       }
 
@@ -96,27 +135,51 @@ export function renderStreamHtml(
         pending -= 1;
         if (pending === 0) {
           write(tail);
-          controller.close();
+          close();
         }
       };
 
       for (const hole of plan.holes) {
-        void hole
-          .resolve()
-          .then(
-            (html) => {
-              write(revealChunk(hole.id, html));
-            },
-            (error: unknown) => {
-              logger.warn(
-                `stream hole ${hole.id} rejected: ${error instanceof Error ? error.message : String(error)}`,
-              );
-              write(revealChunk(hole.id, errorFallback(hole.id)));
-            },
-          )
-          .then(settle, settle);
+        // One hole reveals exactly once, whichever of the three finishes first: its own promise,
+        // its rejection, or its deadline. A late resolve after the deadline writes nothing —
+        // the placeholder it would fill was replaced by the fallback and the document is closed.
+        let revealed = false;
+        const reveal = (html: string): void => {
+          if (revealed) return;
+          revealed = true;
+          if (timer !== undefined) clearTimeout(timer);
+          write(revealChunk(hole.id, html));
+          settle();
+        };
+        const timer =
+          timeoutMs === null
+            ? undefined
+            : setTimeout(() => {
+                logger.warn(`stream hole ${hole.id} missed its ${timeoutMs}ms deadline`);
+                reveal(errorFallback(hole.id));
+              }, timeoutMs);
+        // A response nobody is reading must not hold the process open until its deadline.
+        timer?.unref?.();
+
+        void hole.resolve(holes.signal).then(
+          (html) => {
+            reveal(html);
+          },
+          (error: unknown) => {
+            logger.warn(
+              `stream hole ${hole.id} rejected: ${error instanceof Error ? error.message : String(error)}`,
+            );
+            reveal(errorFallback(hole.id));
+          },
+        );
       }
     },
+
+    /** The client went away. Stop enqueueing, and stop the work that was going to be enqueued. */
+    cancel(reason: unknown) {
+      closed = true;
+      holes.abort(reason);
+    },
   });
 }
 

package/src/route-component.ts

@@ -0,0 +1,36 @@
+/**
+ * Which export of a route module is its page. Named exports only (the repo forbids `default`), and
+ * the generators do not agree on one name — `Page`, `HomePage`, `DashboardPage`, `AdminHome` all
+ * ship today — so the rule is a fixed precedence, evaluated once, here.
+ */
+
+import type { JsxComponent } from './jsx';
+
+/** The page component of a route module: a function of props, sync or async. */
+export type RouteComponent = JsxComponent;
+
+const isComponentExport = (name: string, value: unknown): value is RouteComponent =>
+  typeof value === 'function' && /^[A-Z]/.test(name);
+
+/**
+ * `Page` first, because that is the name `examples/dummy` uses and the one the generators should
+ * converge on; then a single `…Page`; then a single capitalised function. Sorted before the last
+ * fallback so a module with two components resolves to the same one on every machine.
+ */
+export function pageComponentOf(
+  module: Readonly<Record<string, unknown>>,
+): RouteComponent | undefined {
+  const components = Object.entries(module)
+    .filter(([name, value]) => isComponentExport(name, value))
+    .sort(([a], [b]) => a.localeCompare(b)) as readonly (readonly [string, RouteComponent])[];
+  if (components.length === 0) return undefined;
+
+  const exact = components.find(([name]) => name === 'Page');
+  if (exact !== undefined) return exact[1];
+
+  const suffixed = components.filter(([name]) => name.endsWith('Page'));
+  const onlySuffixed = suffixed.length === 1 ? suffixed[0] : undefined;
+  if (onlySuffixed !== undefined) return onlySuffixed[1];
+
+  return components[0]?.[1];
+}

package/src/route-data.ts

@@ -0,0 +1,59 @@
+/**
+ * Resolving a route's data, once per render. Every consumer that renders a document — `x dev`, the
+ * build's prerenderer, every render mode — MUST come through here, because `meta` and the page
+ * component have to be given the SAME object. Two resolutions is a `<title>` describing content
+ * the body does not contain.
+ */
+
+import { isUltimateError } from '@ultimat3/core';
+import { useI18n } from '@ultimat3/i18n';
+import { RouteLoadFailedError } from './errors';
+import type { RouteConfig, RouteContext, RouteData, RouteMetaContext } from './route';
+
+/**
+ * The route's data for one render.
+ *
+ * With no `load` the context itself is the data, which is exactly what `meta` received before
+ * `load` existed — so an untouched route keeps reading `data.url` and `data.params` and nothing
+ * that shipped has to change. Callers therefore never branch on whether a route declared one.
+ */
+export async function routeDataFor<TData = RouteData>(
+  config: RouteConfig<TData>,
+  ctx: RouteContext,
+): Promise<TData> {
+  // The context IS the data, and `defineRoute`'s `LoadRequirement` is what makes that true: a
+  // route whose `meta` reads more than `{ params, url }` cannot compile without a `load`, so
+  // `RouteContext` satisfies `TData` on this line. One narrowing assertion backed by a build
+  // error, in place of the `as unknown as` that used to hand back any shape a caller named.
+  if (config.load === undefined) return ctx as RouteContext & TData;
+  try {
+    return await config.load(ctx);
+  } catch (cause) {
+    // Rethrown as-is when it is already one of ours: a loader that failed its OWN way — a policy
+    // denial, a missing row — has a better code and a better fix than anything this frame knows,
+    // and wrapping it would bury both behind a generic one. Read through core's brand, never a
+    // `code` property: an ENOENT off `Bun.file` carries `code: 'ENOENT'`, and the duck-type let
+    // every one of them out of here unwrapped — no fix line, and no mention of the route to fix.
+    if (isUltimateError(cause)) throw cause;
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    throw new RouteLoadFailedError(
+      `load() threw while rendering ${new URL(ctx.url).pathname}: ${detail}`,
+      `fix the load function for ${new URL(ctx.url).pathname}, or return a fallback so the page can render`,
+    );
+  }
+}
+
+/**
+ * The argument `meta` is called with. Built here rather than at each call site so `x dev` and the
+ * build's prerenderer cannot disagree about what `meta` receives — two builders is a `<title>`
+ * that differs between the page a developer sees and the one a crawler gets.
+ *
+ * `t` is resolved per call from the ambient locale, never captured: a translator held across
+ * requests would render every visitor the first one's language.
+ */
+export function metaContextFor<TData = RouteData>(
+  ctx: RouteContext,
+  data: TData,
+): RouteMetaContext<TData> {
+  return { data, params: ctx.params, url: ctx.url, t: useI18n() };
+}