@lesto/ui 0.1.0

package/src/render.tsx

@@ -0,0 +1,349 @@
+/**
+ * tree -> React (+ optionally, the island hydration manifest).
+ *
+ * The renderer turns a validated JSON tree into a React element against the
+ * registry. It degrades safely: an unknown or malformed node renders nothing
+ * (and is reported), and a component whose own `render()` throws is contained
+ * here — at build time — rather than crashing the whole tree. The renderer
+ * itself NEVER throws.
+ *
+ * Why contain the throw eagerly instead of leaning on a React error boundary?
+ * Because boundaries only fire during client reconciliation — server rendering
+ * (`renderToStaticMarkup`) lets a throw propagate straight out. A try/catch
+ * around each component's render is the one mechanism that holds on both sides.
+ *
+ * Islands ride the SAME walk. Where a node's `type` names a *client* component,
+ * the server cannot run it — it emits a marked wrapper element carrying an
+ * optional server `fallback`, and (when building a page) records the mount in a
+ * manifest the browser later hydrates. `renderTree` keeps its exact shape and
+ * behavior: an island renders its static fallback and is invisible to callers
+ * that never asked for a manifest. `renderPage` is the additive door to the
+ * manifest.
+ *
+ * SCOPE (ADR 0011 Increment 2 — the path convergence): this whole `UiNode`/
+ * Registry walk is the DEMOTED niche — the AI-/DB-driven content tree, where a
+ * `type` is a JSON string a model emitted and an island is collected into one
+ * page-wide `#lesto-islands` manifest. The CANONICAL island path is `defineIsland`
+ * in a hand-authored `.page` (co-located mount scripts, `hydrateDocumentIslands`,
+ * the synthesized `@lesto/assets` client) — that path does NOT come through here.
+ * Both emit the byte-identical {@link IslandMount} (the shared `islandMount`
+ * author), so the one wire contract and the one set of island invariants serve
+ * both; only the EMISSION (page-wide array vs. co-located per island) differs.
+ */
+
+import { createElement, Fragment } from "react";
+import type { ComponentType, ReactElement, ReactNode } from "react";
+import { renderToStaticMarkup, renderToString } from "react-dom/server";
+
+import { ISLAND_ATTR } from "./island";
+import type { ClientComponentDef, IslandMount } from "./island";
+import { islandMount } from "./mount";
+import { isNodeObject } from "./node";
+import { validateProps } from "./props";
+import type { Registry } from "./registry";
+
+/**
+ * One thing the renderer couldn't render, located by `path`.
+ *
+ * `type` is the stable diagnostic kind (`invalid_node`, `unknown_component`,
+ * `invalid_props`, `render_threw`) — branch on it, never on the prose. `detail`
+ * is a human-readable note (the offending component name, the prop-validation
+ * message); `cause` carries the actual thrown value for a `render_threw` (the
+ * component's own `Error`, or the `UI_ISLAND_PROPS_NOT_SERIALIZABLE` an island's
+ * bad prop raised), so an operator gets the real stack rather than a bare
+ * "something threw". Both are OPTIONAL — a plain `invalid_node` needs neither —
+ * and mirror `validate.ts`'s `TreeError.detail`, so the render walk and the pure
+ * tree walk report the same diagnostic shape.
+ */
+export interface RenderError {
+  path: string;
+  type: string;
+  detail?: string;
+  cause?: unknown;
+}
+
+/**
+ * The injectable server-render dialect: the two functions {@link renderPageMarkup}
+ * needs to serialize a built {@link Page} to body HTML.
+ *
+ * It is the SAME two-function surface `react-dom/server` exposes (`renderToString`
+ * + `renderToStaticMarkup`), narrowed to what this module calls — so the default
+ * is a thin pass-through and every existing caller is byte-for-byte unchanged.
+ *
+ * Why a seam at all? An `ssr: true` island ships its real server render into the
+ * shell for the client to `hydrateRoot`, and hydration only succeeds when the
+ * server- and client-emitted markup agree. React and Preact emit DIFFERENT
+ * hydration markup (notably how they delimit adjacent text segments), so a page
+ * whose client bundle is Preact (the opt-in `react`→`preact/compat` alias, ADR
+ * 0007) MUST be server-rendered by Preact too, or every `ssr: true` island
+ * mismatches on hydration. This seam lets the caller pick the dialect that matches
+ * its client; the default keeps the React dialect this engine has always emitted.
+ *
+ * It mirrors `hydrate.tsx`'s injectable `mount` seam: the thing that varies by
+ * runtime is injected, never reached for as a global, so both halves of the
+ * hydration contract are chosen by the same explicit decision.
+ *
+ * The `dialect` tag names which client this renderer's markup is meant to hydrate
+ * against (`"react"` / `"preact"`). It is the load-bearing half of ADR 0008's
+ * matched pair: the wiring that turns a single `ui.dialect` key into a client
+ * alias AND a server renderer compares this tag to the client dialect and refuses
+ * a mismatch (client Preact + server React) with a coded error, so the
+ * silently-mismatching hydration this seam exists to prevent can never be wired.
+ */
+export interface ServerRenderer {
+  /** Which client this renderer's markup hydrates against — the matched-pair tag. */
+  dialect: "react" | "preact";
+  renderToString(node: ReactElement): string;
+  renderToStaticMarkup(node: ReactElement): string;
+}
+
+/**
+ * The default dialect: React's own `react-dom/server`. Statically imported (not
+ * lazy) because it is this engine's baseline renderer — the one the tests, the
+ * stream path, and the deploy all already use — so there is nothing to defer.
+ * Selecting a different dialect (e.g. {@link ./server-preact}) is the caller's
+ * explicit opt-in via {@link renderPageMarkup}'s `renderer` argument.
+ */
+export const reactServerRenderer: ServerRenderer = {
+  dialect: "react",
+  renderToStaticMarkup,
+  renderToString,
+};
+
+/**
+ * The mutable scratch a single render walk threads through itself: the errors it
+ * accumulates and, only when a page is being built, the island manifest it fills.
+ */
+interface Walk {
+  registry: Registry;
+  errors: RenderError[];
+  islands: IslandMount[] | undefined;
+}
+
+/** Build the React element for a tree, plus the list of nodes that degraded. */
+export function renderTree(
+  registry: Registry,
+  tree: unknown,
+): { element: ReactElement | null; errors: RenderError[] } {
+  const walk: Walk = { registry, errors: [], islands: undefined };
+
+  const element = build(walk, tree, "$");
+
+  return { element, errors: walk.errors };
+}
+
+/** A fully built page: the HTML element tree plus the islands to hydrate. */
+export interface Page {
+  element: ReactElement | null;
+  errors: RenderError[];
+  islands: IslandMount[];
+}
+
+/**
+ * Render a tree AND collect its island hydration manifest in one walk.
+ *
+ * This is `renderTree` plus the wire payload: every island in the tree yields an
+ * `IslandMount { id, component, props }` whose `id` matches the `data-lesto-island`
+ * attribute on its wrapper, so the client can pair DOM to data. Server-only and
+ * additive — existing `renderTree` callers are untouched.
+ */
+export function renderPage(registry: Registry, tree: unknown): Page {
+  const islands: IslandMount[] = [];
+
+  const walk: Walk = { registry, errors: [], islands };
+
+  const element = build(walk, tree, "$");
+
+  return { element, errors: walk.errors, islands };
+}
+
+/**
+ * Serialize a built {@link Page} to its body HTML, choosing the React server
+ * renderer that the page's own hydration contract requires.
+ *
+ * This is where the framework's headline feature lives or dies. An `ssr: true`
+ * island ships its REAL server render into the shell so the client can
+ * `hydrateRoot` it — reuse the DOM, no re-render. But `hydrateRoot` matches the
+ * server tree to the client tree by walking *text-segment comment markers*
+ * (`<!-- -->`) that React emits between adjacent text children. `renderToString`
+ * emits those markers; `renderToStaticMarkup` deliberately STRIPS them (its
+ * markup is for documents that will never hydrate). Hydrating
+ * `renderToStaticMarkup` output therefore mismatches the instant a component
+ * renders two or more adjacent text segments under one parent (`'Hi, ', name`),
+ * firing `onRecoverableError` and forcing React to re-render the whole island —
+ * defeating `ssr: true` entirely. Single-text-child trees happen to survive,
+ * which is exactly the trap: the common shape (interpolated text) is the broken
+ * one.
+ *
+ * So the rule is mechanical, never a guess: **if any island in the manifest is
+ * `ssr: true`, the body MUST be rendered with `renderToString`** to keep the
+ * hydration markers the client needs. A page with no SSR islands (pure static,
+ * or only deferred `createRoot` islands whose shells are mounted fresh and never
+ * hydrated) uses `renderToStaticMarkup` — smaller, marker-free output, and the
+ * deferred shells are replaced wholesale so their markers are irrelevant.
+ *
+ * A page whose element degraded to `null` has no body to render.
+ *
+ * The `renderer` is the dialect seam. It DEFAULTS to {@link reactServerRenderer}
+ * (real `react-dom/server`), so every existing caller — estate's `document.ts`,
+ * the render/hydrate/stream tests — is byte-for-byte unchanged. A page whose
+ * client bundle is Preact passes the Preact adapter (`@lesto/ui/server`) so
+ * the server emits the same markup the Preact client will hydrate against; only
+ * then is an `ssr: true` island safe under the `preact/compat` alias.
+ */
+export function renderPageMarkup(
+  page: Page,
+  renderer: ServerRenderer = reactServerRenderer,
+): string {
+  if (page.element === null) return "";
+
+  // The manifest is the single source of truth for which renderer is safe: it is
+  // the same data the client reads to decide hydrate-vs-mount, so server and
+  // client can never disagree about whether markers were emitted. WHICH dialect
+  // emits those markers is the `renderer`'s business; this rule (markers iff any
+  // ssr island) is identical across dialects.
+  const needsHydrationMarkers = page.islands.some((island) => island.ssr);
+
+  return needsHydrationMarkers
+    ? renderer.renderToString(page.element)
+    : renderer.renderToStaticMarkup(page.element);
+}
+
+/** Recursively build one node into a React element, collecting render errors. */
+function build(walk: Walk, node: unknown, path: string): ReactElement | null {
+  // A bare string leaf becomes a text node, wrapped so the return type stays a
+  // uniform ReactElement (callers get ReactElement | null, never raw strings).
+  if (typeof node === "string") {
+    return createElement(Fragment, { key: path }, node);
+  }
+
+  // Malformed: not a string, not a node object. Render nothing, report it.
+  if (!isNodeObject(node)) {
+    walk.errors.push({ path, type: "invalid_node", detail: "node must be a string or an object" });
+
+    return null;
+  }
+
+  // An island short-circuits the server component path: the client owns it.
+  const client = walk.registry.getClient(node.type);
+
+  if (client !== undefined) {
+    return buildIsland(walk, client, node.props ?? {}, path);
+  }
+
+  const def = walk.registry.get(node.type);
+
+  // Unknown component: nothing vetted to render. Degrade to nothing.
+  if (def === undefined) {
+    walk.errors.push({ path, type: "unknown_component", detail: node.type });
+
+    return null;
+  }
+
+  // Validate props as the pure `validateTree` walk does, but here in the render
+  // path too: a missing-required or out-of-enum prop was previously DROPPED on
+  // the floor (only the parallel `validateTree` reported it), so a renderer-only
+  // caller got a silently-degraded component with no diagnostic. Surface each as
+  // an `invalid_props` (the same kind `validate.ts` emits), then render with the
+  // reconciled bag — the render still proceeds (defaults applied, the bad value
+  // dropped), it is just no longer silent.
+  const { props, errors: propErrors } = validateProps(def.props, node.props ?? {});
+
+  for (const detail of propErrors) {
+    walk.errors.push({ path, type: "invalid_props", detail });
+  }
+
+  const childNodes: ReactNode = (node.children ?? []).map((child, index) =>
+    build(walk, child, `${path}.children[${index}]`),
+  );
+
+  // Contain the component's own render: a throw becomes a reported diagnostic,
+  // never an exception that escapes the walk.
+  return safeRender(def.render, props, childNodes, path, walk.errors);
+}
+
+/**
+ * Build an island's server footprint: a marked wrapper element holding either the
+ * fallback (deferred island) or the component's real output (an `ssr` island),
+ * plus (when a page is being built) its manifest entry.
+ *
+ * Props are validated against the client schema and asserted serializable; a
+ * non-serializable prop is contained as a `render_threw` diagnostic carrying the
+ * raised `UiError` as its `cause`, exactly like a server component that throws,
+ * so the island degrades to nothing rather than crashing the surrounding page.
+ *
+ * The shell contents are the crux of the hydration contract. A deferred island
+ * (`ssr` falsy) holds only the fallback — the client mounts the live component
+ * fresh, so the two need not match. An `ssr` island holds the component's actual
+ * server render, which the client then `hydrateRoot`s — the markup MUST match, so
+ * the same `component` runs on both sides with the same wire props. The `ssr`
+ * flag rides into the manifest so the client picks the right mount without
+ * guessing.
+ */
+function buildIsland(
+  walk: Walk,
+  client: ClientComponentDef,
+  rawProps: Record<string, unknown>,
+  path: string,
+): ReactElement | null {
+  try {
+    // The mount shape (validated + serializable props, ssr, the optional
+    // strategy/bind) is authored once in `islandMount`, shared with the `.page`
+    // path's `defineIsland` so the two emit byte-identical wire entries. Building
+    // it is the serialize guard `buildIsland` contains — a non-serializable prop
+    // throws here and the island is reported, never crashing the page render.
+    const { mount, props } = islandMount(client, rawProps, path);
+
+    // Only a page build cares about the manifest; `renderTree` leaves it absent.
+    walk.islands?.push(mount);
+
+    // An `ssr` island ships its REAL output (the markup the client will hydrate
+    // and find unchanged); a deferred island ships only its fallback placeholder.
+    //
+    // The ssr component is placed LAZILY (`createElement`, not an eager call):
+    // an island's `component` is a full React component that may use hooks, so it
+    // can only be run by React's renderer (during the caller's
+    // `renderToStaticMarkup`), never invoked as a plain function here. This keeps
+    // the renderer's invariant honest — *building* the element tree never throws;
+    // the island's own render runs when React renders the tree.
+    const contents: ReactNode = mount.ssr
+      ? createElement(client.component as ComponentType<Record<string, unknown>>, mount.props)
+      : (client.fallback?.(props) as ReactNode);
+
+    return createElement("div", { key: path, [ISLAND_ATTR]: path }, contents);
+  } catch (error) {
+    // Carry the actual throw (an island's `UI_ISLAND_PROPS_NOT_SERIALIZABLE`, or
+    // a coded `UI_ISLAND_SSR_DATA_UNRESOLVED`) as `cause` so an operator sees the
+    // real error, plus its message as `detail` — instead of a bare "threw".
+    walk.errors.push({ path, type: "render_threw", detail: errorDetail(error), cause: error });
+
+    return null;
+  }
+}
+
+/** A human-readable note for a thrown value: its `.message` if it has one, else its `String`. */
+function errorDetail(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Invoke a component's render, containing any throw as a reported error. */
+function safeRender(
+  render: (props: Record<string, unknown>, children: ReactNode) => ReactElement,
+  props: Record<string, unknown>,
+  children: ReactNode,
+  path: string,
+  errors: RenderError[],
+): ReactElement | null {
+  try {
+    const element = render(props, children);
+
+    // Re-key so React can place sibling elements without a missing-key warning.
+    return createElement(Fragment, { key: path }, element);
+  } catch (error) {
+    // The component's own throw, carried (not swallowed): `cause` is the real
+    // error for an operator's stack, `detail` its message for a quick read.
+    errors.push({ path, type: "render_threw", detail: errorDetail(error), cause: error });
+
+    return null;
+  }
+}

package/src/resources.ts

@@ -0,0 +1,233 @@
+/**
+ * Resource hints over React 19's native resource APIs.
+ *
+ * React 19 turns `preload`/`preinit`/`preconnect`/`prefetchDNS` (from `react-dom`)
+ * and document-metadata tags into real `<link>`/`<script>` elements during SSR —
+ * and it does so even under the framework's buffered `renderToStaticMarkup`
+ * render, hoisting them to the FRONT of the emitted markup. That is the whole
+ * Tier-0 win: the browser learns about the LCP image, fonts, and island bundles
+ * before it has finished parsing the body, with no streaming and no new transport.
+ *
+ * This module is a thin, Lesto-flavored seam over those primitives. Two reasons it
+ * exists rather than telling callers to import `react-dom` directly:
+ *   - the `react-dom` resource functions are imperative side effects that only
+ *     register a hint while a render is in flight; wrapping them keeps the import
+ *     surface small and lets us inject a fake registrar in tests (no real render
+ *     needed to prove we called the right thing with the right options);
+ *   - the LCP-image and island-bundle conventions (`fetchpriority="high"`,
+ *     `<link rel="modulepreload">`) are Lesto decisions, not React ones, and belong
+ *     in one named place.
+ *
+ * The element-returning helpers (`lcpImage`, `modulePreload`) emit React elements
+ * the caller drops into the tree; React hoists the `<link>`s itself. The
+ * imperative helpers (`preload`/`preinit`/…) register a hint as a side effect and
+ * return nothing — call them from inside a component's render.
+ */
+
+import { createElement } from "react";
+import type { ReactElement } from "react";
+import {
+  preconnect as reactPreconnect,
+  prefetchDNS as reactPrefetchDNS,
+  preinit as reactPreinit,
+  preinitModule as reactPreinitModule,
+  preload as reactPreload,
+} from "react-dom";
+
+/**
+ * The subset of React's resource API we lean on, named as one seam so a test can
+ * substitute a recorder and assert the exact calls without rendering. The shapes
+ * mirror `react-dom`'s own (intentionally loose option bags — React validates).
+ */
+export interface ResourceRegistrar {
+  preload: (href: string, options: PreloadOptions) => void;
+  preinit: (href: string, options: PreinitOptions) => void;
+  preinitModule: (href: string, options?: PreinitModuleOptions) => void;
+  preconnect: (href: string, options?: PreconnectOptions) => void;
+  prefetchDNS: (href: string) => void;
+}
+
+/** Options for a `preload` hint — `as` is required; the rest mirror react-dom. */
+export interface PreloadOptions {
+  as:
+    | "audio"
+    | "document"
+    | "embed"
+    | "fetch"
+    | "font"
+    | "image"
+    | "object"
+    | "script"
+    | "style"
+    | "track"
+    | "video"
+    | "worker";
+  crossOrigin?: "anonymous" | "use-credentials";
+  integrity?: string;
+  type?: string;
+  fetchPriority?: "high" | "low" | "auto";
+  imageSrcSet?: string;
+  imageSizes?: string;
+}
+
+/** Options for a `preinit` hint — load AND execute/apply a script or stylesheet. */
+export interface PreinitOptions {
+  as: "script" | "style";
+  precedence?: string;
+  crossOrigin?: "anonymous" | "use-credentials";
+  integrity?: string;
+  fetchPriority?: "high" | "low" | "auto";
+}
+
+/** Options for a `preinitModule` hint — load AND execute an ES module. */
+export interface PreinitModuleOptions {
+  as?: "script";
+  crossOrigin?: "anonymous" | "use-credentials";
+  integrity?: string;
+}
+
+/** Options for a `preconnect` hint — open the connection early. */
+export interface PreconnectOptions {
+  crossOrigin?: "anonymous" | "use-credentials";
+}
+
+/** The real react-dom functions, the default registrar everywhere but tests. */
+const reactRegistrar: ResourceRegistrar = {
+  preload: reactPreload,
+  preinit: reactPreinit,
+  preinitModule: reactPreinitModule,
+  preconnect: reactPreconnect,
+  prefetchDNS: reactPrefetchDNS,
+};
+
+/**
+ * Register a `preload` hint: fetch `href` early at the given priority, but do not
+ * execute it. The browser caches it for the moment the parser reaches the real
+ * reference. React hoists the resulting `<link rel="preload">` into the document.
+ */
+export function preload(
+  href: string,
+  options: PreloadOptions,
+  registrar: ResourceRegistrar = reactRegistrar,
+): void {
+  registrar.preload(href, options);
+}
+
+/**
+ * Register a `preinit` hint: fetch AND execute/apply `href` early. Use it for a
+ * critical script or stylesheet whose effect the page needs as soon as possible.
+ */
+export function preinit(
+  href: string,
+  options: PreinitOptions,
+  registrar: ResourceRegistrar = reactRegistrar,
+): void {
+  registrar.preinit(href, options);
+}
+
+/**
+ * Register a `preinitModule` hint: fetch AND execute an ES module early. This
+ * EXECUTES the module — for execute-free hint use {@link modulePreload} instead.
+ */
+export function preinitModule(
+  href: string,
+  options?: PreinitModuleOptions,
+  registrar: ResourceRegistrar = reactRegistrar,
+): void {
+  // Forward `options` only when given: react-dom's signature makes it optional,
+  // and passing an explicit `undefined` under exactOptionalPropertyTypes is noise.
+  if (options === undefined) {
+    registrar.preinitModule(href);
+
+    return;
+  }
+
+  registrar.preinitModule(href, options);
+}
+
+/**
+ * Register a `preconnect` hint: open the TCP+TLS connection to `href`'s origin
+ * before the first request to it, shaving the handshake off the critical path.
+ */
+export function preconnect(
+  href: string,
+  options?: PreconnectOptions,
+  registrar: ResourceRegistrar = reactRegistrar,
+): void {
+  if (options === undefined) {
+    registrar.preconnect(href);
+
+    return;
+  }
+
+  registrar.preconnect(href, options);
+}
+
+/**
+ * Register a `prefetchDNS` hint: resolve `href`'s DNS early. Cheaper than
+ * `preconnect` (no socket), for an origin you are likely — but not certain — to hit.
+ */
+export function prefetchDNS(href: string, registrar: ResourceRegistrar = reactRegistrar): void {
+  registrar.prefetchDNS(href);
+}
+
+/** Optional attributes for {@link lcpImage} beyond the load-bearing ones. */
+export interface LcpImageProps {
+  src: string;
+  alt: string;
+  width?: number;
+  height?: number;
+  className?: string;
+  sizes?: string;
+  srcSet?: string;
+}
+
+/**
+ * The hero image, marked as the Largest Contentful Paint candidate.
+ *
+ * `fetchpriority="high"` tells the browser to prioritize this fetch over the
+ * default-`low` images; React 19 *also* auto-emits a `<link rel="preload"
+ * as="image" fetchpriority="high">` from an `<img fetchPriority>` during SSR, so
+ * the hint reaches the browser in the document head before the body is parsed —
+ * the single highest-ROI LCP lever. We never lazy-load the LCP image (`loading`
+ * stays eager) for the same reason: deferring the most important paint is a
+ * regression dressed as an optimization.
+ */
+export function lcpImage(props: LcpImageProps): ReactElement {
+  return createElement("img", {
+    src: props.src,
+    alt: props.alt,
+    // React 19 emits this in its DOM-property casing (`fetchPriority`), which the
+    // browser reads case-insensitively; it also auto-emits a `<link rel="preload"
+    // as="image">` from an `<img fetchPriority>`. Marking the LCP image is the one
+    // place this attribute earns its keep.
+    fetchPriority: "high",
+    // Spell the load behavior out: an eager LCP image is the point.
+    loading: "eager",
+    decoding: "async",
+    ...(props.width === undefined ? {} : { width: props.width }),
+    ...(props.height === undefined ? {} : { height: props.height }),
+    ...(props.className === undefined ? {} : { className: props.className }),
+    ...(props.sizes === undefined ? {} : { sizes: props.sizes }),
+    ...(props.srcSet === undefined ? {} : { srcSet: props.srcSet }),
+  });
+}
+
+/**
+ * A `<link rel="modulepreload">` for an island's client bundle.
+ *
+ * `modulepreload` fetches AND compiles a module graph WITHOUT executing it — the
+ * right hint for code that runs only after hydration. (Contrast `preinitModule`,
+ * which executes.) React hoists this `<link>` into the head, so the island's JS
+ * is parsed and ready the moment `hydrateIslands` reaches for it.
+ */
+export function modulePreload(
+  href: string,
+  crossOrigin?: "anonymous" | "use-credentials",
+): ReactElement {
+  return createElement("link", {
+    rel: "modulepreload",
+    href,
+    ...(crossOrigin === undefined ? {} : { crossOrigin }),
+  });
+}

package/src/route.ts

@@ -0,0 +1,62 @@
+/**
+ * `route(pattern, params)` — build a typed URL from a known route pattern.
+ *
+ * The compile-time-CHECKED companion to `<Link>`: where `href` only autocompletes
+ * (a typo still compiles), `route` CONSTRAINS its pattern argument to the app's
+ * registered route patterns — a typo'd or stale pattern is a `tsc` error — and types
+ * `params` from the pattern's `:segments` via `@lesto/router`'s `PathParams`. It
+ * returns a `string` assignable to a `<Link href>`, so the type-safe dynamic link is:
+ *
+ *   <Link href={route("/lab/gallery/:id", { id: listing.id })}>{listing.title}</Link>
+ *   route("/lab/gallery")   // a param-less pattern takes no second argument
+ *
+ * This is the higher-value half of typed routing (ADR/`docs/plans/dx-parity.md`,
+ * Workstream 1 Increment 2): `<Link href>` made navigation route-AWARE; `route` makes
+ * a dynamic link route-SAFE. With no route codegen the pattern is any `string` and the
+ * params are unconstrained — the unchanged escape hatch, nothing breaks.
+ *
+ * Authored as a plain pure function with native string ops, so it stays in
+ * `@lesto/ui`'s isomorphic, react-free core alongside `<Link>` (its sibling on the
+ * link-authoring surface).
+ */
+
+import { UiError } from "./errors";
+import type { KnownPatterns, ParamArgs } from "./routes";
+
+/**
+ * The pattern argument: the app's known patterns when codegen has augmented
+ * `RegisteredRoutes`, else any `string` (unchanged). The `[KnownPatterns] extends
+ * [never]` tuple guards the empty case without distributing over the union.
+ */
+type PatternArg = [KnownPatterns] extends [never] ? string : KnownPatterns;
+
+/**
+ * Build a URL from a route pattern, substituting each `:name` segment from `params`
+ * (URL-encoded). The pattern is constrained to the app's {@link KnownPatterns} and the
+ * params are typed via {@link ParamArgs} from the pattern's `:segments` — so a typo or
+ * a missing/mistyped param is a compile error.
+ *
+ * The runtime missing-param guard (a coded {@link UiError}) is unreachable through the
+ * types, but an untyped JS caller could trip it — mirrors `@lesto/client`'s
+ * `applyParams`, the same `:param`-substitution this is the navigation twin of.
+ */
+export function route<P extends PatternArg>(pattern: P, ...args: ParamArgs<P>): string {
+  const params = args[0] as Record<string, string | number> | undefined;
+
+  return pattern.replace(/:([A-Za-z0-9_]+)/g, (_match, name: string) => {
+    const value = params?.[name];
+
+    if (value === undefined) {
+      throw new UiError(
+        "UI_ROUTE_MISSING_PARAM",
+        `route "${pattern}" needs a value for ":${name}"`,
+        {
+          pattern,
+          param: name,
+        },
+      );
+    }
+
+    return encodeURIComponent(String(value));
+  });
+}