@lesto/ui 0.1.0

package/src/data-resolve.tsx

@@ -0,0 +1,120 @@
+/**
+ * Render-time data resolution — the canonical island's machinery (ADR 0012).
+ *
+ * The static delivery tier (`dataPrimerScript`, see `data.ts`) hands the client
+ * an unresolved `bind` + a parse-time primer: correct on a shared-cacheable
+ * document, but it arrives too late to feed an `ssr: true` island's SERVER
+ * markup. This module is the DYNAMIC tier: a per-request resolver that runs each
+ * bound source's loader DURING the render, so `defineIsland` can read the value
+ * with React's `use()` and render the island's real component with the data
+ * inlined — server markup is the per-user truth, the client hydrates it, zero
+ * extra requests.
+ *
+ * It supersedes and deletes ADR 0010's `resolveIslandData`, whose post-walk
+ * manifest mutation could never reach an `ssr: true` island's server render.
+ *
+ * Two pieces:
+ *   - {@link createSourceResolver} — wraps a `load(name)` in a per-name memo, so
+ *     one loader runs per distinct source per request, its promise shared by
+ *     every island that binds it (ADR 0010 §2's parallel-batch/no-chaining
+ *     semantics, now compatible with streaming: one run, started on first use).
+ *   - {@link IslandDataProvider} / {@link IslandDataContext} — carry the resolver
+ *     down the server React tree; `defineIsland` reads it. Absent context means a
+ *     static/prerender emission (the primer tier, or a loud refusal for
+ *     `ssr: true` + `data`).
+ */
+
+import { createContext } from "react";
+import type { FC, ReactNode } from "react";
+
+/** Resolve a bound data source by name, memoized — one loader run per source per request. */
+export interface SourceResolver {
+  resolve(source: string): PromiseLike<unknown>;
+}
+
+/**
+ * A thenable React's `use()` can read SYNCHRONOUSLY when its value is already
+ * known. React tracks a thenable's `status`/`value`; a pre-fulfilled one lets
+ * `use()` return without suspending, so a synchronous loader (estate's pure-HMAC
+ * session) renders under the non-streaming renderers (`renderToString`,
+ * `renderToStaticMarkup`) too, not only under Suspense.
+ */
+interface FulfilledThenable<T> extends PromiseLike<T> {
+  status: "fulfilled";
+  value: T;
+}
+
+/**
+ * Wrap an already-known value as a fulfilled tracked thenable React reads
+ * synchronously. The `then` is deliberate — this IS a thenable React's `use()`
+ * consumes (it reads `status`/`value` for the sync return, and `then` is the
+ * promise contract for any async consumer) — so the no-thenable rule is silenced
+ * here on purpose.
+ */
+function fulfilled<T>(value: T): FulfilledThenable<T> {
+  return {
+    status: "fulfilled",
+    value,
+    // eslint-disable-next-line unicorn/no-thenable
+    then(onFulfilled) {
+      return Promise.resolve(onFulfilled ? onFulfilled(value) : (value as never));
+    },
+  };
+}
+
+/**
+ * Build a memoized {@link SourceResolver} over a `load(name)` function.
+ *
+ * The first `resolve(name)` runs `load(name)` and caches the result keyed by
+ * name; every later `resolve(name)` returns the same thenable, so two islands
+ * binding one source share a single loader run. Chaining still has no API — the
+ * loader receives only `name`, never another source's value (whatever request
+ * context it needs, the caller closed over when building `load`).
+ *
+ * A loader that returns a real promise is memoized as-is and `use()` instruments
+ * it the way React expects. A loader that returns a plain VALUE is stored as a
+ * pre-fulfilled tracked thenable so `use()` reads it synchronously — keeping sync
+ * loaders compatible with the buffered renderers and the tests simple.
+ */
+export function createSourceResolver(
+  load: (source: string) => Promise<unknown> | unknown,
+): SourceResolver {
+  const memo = new Map<string, PromiseLike<unknown>>();
+
+  return {
+    resolve(source) {
+      const cached = memo.get(source);
+
+      if (cached !== undefined) return cached;
+
+      const loaded = load(source);
+
+      const thenable: PromiseLike<unknown> =
+        typeof (loaded as { then?: unknown } | null)?.then === "function"
+          ? (loaded as PromiseLike<unknown>)
+          : fulfilled(loaded);
+
+      memo.set(source, thenable);
+
+      return thenable;
+    },
+  };
+}
+
+/**
+ * The server-side context carrying the per-request {@link SourceResolver} to
+ * every `defineIsland` in the tree. `null` by default — its absence is the
+ * signal that this is a static/prerender emission (no render-time resolution),
+ * which `defineIsland`'s resolution rule branches on.
+ */
+export const IslandDataContext = createContext<SourceResolver | null>(null);
+
+/**
+ * Provide a {@link SourceResolver} to the page subtree it wraps (dynamic render
+ * only). `children` is optional so the provider may be created with positional
+ * children via `createElement` (the `.page` renderer's form) as well as JSX.
+ */
+export const IslandDataProvider: FC<{ resolver: SourceResolver; children?: ReactNode }> = ({
+  resolver,
+  children,
+}) => <IslandDataContext.Provider value={resolver}>{children}</IslandDataContext.Provider>;

package/src/data.ts

@@ -0,0 +1,183 @@
+/**
+ * Island data sources — declared data, framework-owned delivery (ADR 0010).
+ *
+ * An island gets its per-request data through a typed, implementation-free
+ * TOKEN shared between server and client. The server binds an implementation to
+ * the token (`lesto().data(source, loader)`); an island binds a prop to the
+ * token (`defineClient({ data: { session: sessionSource } })`); the component
+ * receives the value as a prop and is a pure function of it. There is no
+ * `fetch`-in-effect for the author to write, and therefore no waterfall to
+ * write — the whole point.
+ *
+ * The token carries only a NAME, a SCOPE (per-user vs shared — it picks the auto
+ * route's cache header, ADR 0010 §3a), and a phantom TYPE. It deliberately holds
+ * no implementation, so importing the shared token module from the client bundle
+ * (as the island registry does) drags no server code across the wire.
+ *
+ * Delivery is chosen by topology, never by the author:
+ *   - dynamically rendered → the render-time resolver in `data-resolve.tsx`
+ *     (ADR 0012) runs loaders DURING the render and `defineIsland` inlines the
+ *     values straight into the island's props — feeding even an `ssr: true`
+ *     island's server markup (the canonical island, 0 extra requests). This
+ *     module owns only the STATIC tier;
+ *   - static / prerendered with a server in the path → the document carries the
+ *     unresolved bind plus the {@link dataPrimerScript} primer, which kicks the
+ *     fetch at HTML-parse time (parallel with `client.js`), and the client
+ *     hydration runtime awaits it (1 RTT, never the serial `doc → js → fetch`).
+ *     A `hydrate: "visible"` island is EXCLUDED from the primer — its data is
+ *     deferred to first intersection along with its mount, or `"visible"` would
+ *     be defeated by a parse-time fetch.
+ */
+
+import { UiError } from "./errors";
+
+import type { IslandMount } from "./island";
+
+/**
+ * Whether a source's value is per-user (`"private"`) or the same for everyone
+ * (`"shared"`). It is a MEANING only the author can know, so it is declared, not
+ * inferred — and it drives the cache header on the auto-exposed route (ADR 0010
+ * §3a): `private` → `no-store` (a per-user JSON GET with no cache header is a
+ * session leak waiting for a CDN), `shared` → revalidated-but-cacheable.
+ */
+export type DataSourceScope = "private" | "shared";
+
+/**
+ * A typed handle to a named data source — no implementation, just a name, a
+ * scope, and a phantom value type. `defineDataSource<User | null>("session")`
+ * names the source and pins what its loader returns / its bound prop receives.
+ */
+export interface DataSource<T = unknown> {
+  readonly name: string;
+
+  /** Per-user or shared — drives the route's cache header. Defaults to `"private"`. */
+  readonly scope: DataSourceScope;
+
+  /** Phantom: carries the resolved value's type to the binding. Never present at runtime. */
+  readonly __value?: T;
+}
+
+/**
+ * A source name must be a single safe URL/identifier segment: it becomes a path
+ * segment (`/__lesto/data/<name>`) AND is embedded in the executable primer
+ * script, so anything outside this charset could break out of the route or the
+ * string literal. Locking the charset is what keeps the primer injection-safe
+ * without escaping gymnastics (the primer carries names + hrefs, never data).
+ */
+const VALID_SOURCE_NAME = /^[a-zA-Z0-9_-]+$/;
+
+/** The route prefix the framework auto-exposes every registered source under. */
+export const DATA_ROUTE_PREFIX = "/__lesto/data/";
+
+/** The endpoint a source's client fallback fetch hits — `/__lesto/data/<name>`. */
+export function dataSourceHref(name: string): string {
+  return `${DATA_ROUTE_PREFIX}${name}`;
+}
+
+/**
+ * Declare a data source: a typed token bound to an implementation elsewhere
+ * (server) and to a prop elsewhere (island). The name is validated here so an
+ * unsafe one fails loudly at declaration, not as a broken route or a malformed
+ * primer at request time.
+ *
+ * `scope` declares whether the value is per-user (`"private"`, the default) or
+ * the same for every visitor (`"shared"`) — the meaning that picks the auto
+ * route's cache header (ADR 0010 §3a). Private-by-default keeps the dangerous
+ * configuration (a per-user value heuristically cached by a CDN) unrepresentable
+ * without a visible declaration.
+ */
+export function defineDataSource<T>(
+  name: string,
+  options?: { scope?: DataSourceScope },
+): DataSource<T> {
+  if (!VALID_SOURCE_NAME.test(name)) {
+    throw new UiError(
+      "UI_INVALID_DATA_SOURCE_NAME",
+      `data source name "${name}" must match ${String(VALID_SOURCE_NAME)} (it is a URL segment and a script literal)`,
+      { name },
+    );
+  }
+
+  return { name, scope: options?.scope ?? "private" };
+}
+
+/** One bound prop on an island: which source feeds it, and where the client fetches it. */
+export interface IslandBind {
+  source: string;
+
+  href: string;
+}
+
+/**
+ * Collect the distinct sources every PRIMED island on the page binds.
+ *
+ * A `hydrate: "visible"` island is excluded: its mount work — and so its data
+ * fetch — is deferred to first intersection (resolved then by the client's
+ * fallback fetch), or the whole point of `"visible"` is defeated by priming it
+ * at parse time (ADR 0010 corrections #4). A source bound by both an eager and a
+ * visible island still primes once: the eager mount keeps it in the map.
+ *
+ * Shared by the primer (which kicks one fetch per distinct source) and the
+ * server resolver (which runs one loader per distinct source) — a source bound
+ * by three islands is fetched/run once, not three times.
+ */
+function distinctSources(manifest: readonly IslandMount[]): Map<string, string> {
+  const sources = new Map<string, string>();
+
+  for (const mount of manifest) {
+    if (mount.bind === undefined) continue;
+
+    if (mount.strategy === "visible") continue;
+
+    for (const bind of Object.values(mount.bind)) {
+      sources.set(bind.source, bind.href);
+    }
+  }
+
+  return sources;
+}
+
+/**
+ * Build the inline primer that starts every unresolved bind's fetch at
+ * HTML-parse time, so the data request runs parallel with `client.js` instead
+ * of waiting for it (ADR 0010 §3, the static default). Returns the script body
+ * (the caller wraps it in `<script>`); an empty string when the page has no
+ * unresolved binds, so a page without data emits no primer at all.
+ *
+ * The promise per source lands on `window.__lestoData[<name>]`, exactly what the
+ * hydration runtime awaits before mounting a bound island. The script embeds
+ * only framework-controlled, charset-validated names and hrefs (never data),
+ * so the JSON-encoded literals cannot break out of the `<script>`.
+ *
+ * Three properties the emitted body carries (ADR 0010 corrections #3, Seam 1 §3):
+ *   - `w[name]=w[name]||fetch(...)` is IDEMPOTENT: two islands binding one source
+ *     (each emitting its own primer) issue a single credentialed fetch, not two.
+ *   - the `if(!r.ok)throw` rejects the stored promise on a 401/429 etc., so a
+ *     JSON error body never becomes the island's prop value; `hydrateIslands`
+ *     routes that rejection to `onMountError`/`failed` and the island keeps its
+ *     fallback — correct for an unauthenticated visitor.
+ *   - the trailing detached `.catch(function(){})` marks the rejection HANDLED so
+ *     a failure that lands before hydration attaches its handler does not fire a
+ *     spurious `unhandledrejection`. It does NOT swallow the error for the
+ *     hydration runtime, which awaits the ORIGINAL stored promise (`w[name]`),
+ *     not this detached branch.
+ */
+export function dataPrimerScript(manifest: readonly IslandMount[]): string {
+  const sources = distinctSources(manifest);
+
+  if (sources.size === 0) return "";
+
+  const assignments = [...sources]
+    .map(([name, href]) => {
+      const w = `w[${JSON.stringify(name)}]`;
+
+      return (
+        `${w}=${w}||fetch(${JSON.stringify(href)},{credentials:"same-origin"})` +
+        `.then(function(r){if(!r.ok)throw new Error("lesto data "+r.status);return r.json()});` +
+        `${w}.catch(function(){})`
+      );
+    })
+    .join(";");
+
+  return `(function(){var w=window.__lestoData=window.__lestoData||{};${assignments};})()`;
+}

package/src/define-island.tsx

@@ -0,0 +1,222 @@
+/**
+ * `defineIsland` — a self-describing island usable directly in a `.page` (ADR 0011).
+ *
+ * Where the Registry/`UiNode` path collects every island into one page-wide
+ * `#lesto-islands` manifest emitted after the body, a `.page` is a plain React
+ * tree with nothing to walk. So an island describes ITSELF at render time: the
+ * component `defineIsland` returns emits, co-located in the stream, its marked
+ * shell, its own mount script, and (for bound data) its primer — siblings, not
+ * children, so the hydration container is exactly the shell and nothing else.
+ *
+ *   export default defineIsland({ name: "Account", component: Account,
+ *     fallback: AccountFallback, data: { session: sessionSource } });
+ *   // in a page:  <AccountIsland />
+ *
+ * Co-located emission is streaming-safe by construction: an island inside a late
+ * `<Suspense>` boundary flushes with its own mount script, so there is no
+ * "manifest after the body" ordering problem, and its primer fires the instant
+ * the parser reaches it. The client (`hydrateDocumentIslands`) scans the mount
+ * scripts and feeds the same `hydrateIslands` machinery — binds, strategies, and
+ * mount resilience all unchanged.
+ *
+ * The returned component carries its `.island` def so the build's client-entry
+ * synthesizer (`@lesto/assets`) and the client registry can read it from the
+ * island's module without a separate registration.
+ *
+ * ## Data resolution rule (ADR 0012, the canonical island)
+ *
+ * The component reads {@link IslandDataContext}. What it does with a `data`
+ * declaration depends on whether a render-time resolver is in scope (dynamic
+ * page) and on the island's own `ssr`/`hydrate`:
+ *
+ * | resolver | ssr     | hydrate     | behavior                                            |
+ * |----------|---------|-------------|-----------------------------------------------------|
+ * | present  | `true`  | any         | resolve ALL sources via `use()`, inline into props, |
+ * |          |         |             | no bind, no primer; shell = the REAL component WITH  |
+ * |          |         |             | the data (the canonical island — no fallback flash). |
+ * | present  | falsy   | ≠ `visible` | resolve + inline too (0 RTT; the client `createRoot`s|
+ * |          |         |             | with complete props), no bind, no primer.           |
+ * | present  | falsy   | `visible`   | do NOT resolve (work deferred with the mount); emit  |
+ * |          |         |             | bind, no primer (item 2's filter); fetch-on-view.   |
+ * | absent   | `true`  | (has data)  | THROW `UI_ISLAND_SSR_DATA_UNRESOLVED` — on a static  |
+ * |          |         |             | doc this would inline per-user bytes or guarantee a  |
+ * |          |         |             | mismatch; the build fails (ADR 0012, by design).    |
+ * | absent   | falsy   | any         | today's behavior: bind + primer (the static tier).  |
+ */
+
+import { createElement, Fragment, useContext, useId } from "react";
+import * as React from "react";
+import type { ComponentType, ReactElement, ReactNode } from "react";
+
+import { dataPrimerScript } from "./data";
+import type { DataSource } from "./data";
+import { IslandDataContext } from "./data-resolve";
+import type { SourceResolver } from "./data-resolve";
+import { assertClientDef, ISLAND_ATTR, ISLAND_MOUNT_ATTR } from "./island";
+import type { ClientComponentDef, HydrationStrategy } from "./island";
+import { islandMount } from "./mount";
+import { serializeScriptJson } from "./serialize";
+import type { PropSpec } from "./types";
+
+/**
+ * A React component for a `.page`, carrying its island declaration for the build +
+ * client registry. Generic over `Rest` — the props the CALLER must still pass in
+ * JSX (the component's props minus the ones the framework resolves from data).
+ */
+export interface IslandComponent<Rest extends Record<string, unknown> = Record<string, unknown>> {
+  (props: Rest): ReactElement;
+
+  /** The island's declaration — read by the entry synthesizer and the client registry. */
+  readonly island: ClientComponentDef;
+}
+
+/**
+ * Resolve a `data`-declared island's sources at render time, or decide not to,
+ * per the resolution-rule table in the module doc. Returns the `{ prop: value }`
+ * bag to inline (and so omit each resolved source's `bind`), or `undefined` to
+ * keep the static bind + primer behavior.
+ *
+ * `React.use()` may be called here in a loop and conditionally — it is the one
+ * React Hook that may. A real promise suspends the render (Suspense + the
+ * stream's 10s deadline own that); a sync loader's pre-fulfilled thenable reads
+ * synchronously.
+ *
+ * `use` is read off the React namespace, NOT a named import: under the
+ * preact-dialect client alias (`react → preact/compat`, ADR 0007) `preact/compat`
+ * exports no `use`, and a named `import { use }` would fail the client bundle —
+ * `define-island` rides the client graph via the `@lesto/ui` barrel. It is only
+ * ever *called* here, server-side (a resolver is in scope only under
+ * `renderPageResponse`'s provider; the client mounts the registered component
+ * directly and never renders this wrapper), where React is real and `use`
+ * exists. The proper fix is splitting the `@lesto/ui` barrel so server-only
+ * machinery leaves the client graph entirely (chief-architect review 2a); this
+ * namespace access is the contained unbreak until then.
+ */
+function resolveData(
+  def: ClientComponentDef,
+  resolver: SourceResolver | null,
+): Record<string, unknown> | undefined {
+  if (def.data === undefined) return undefined;
+
+  if (resolver === null) {
+    // No render-time resolver in scope: nothing is inlined. A deferred island
+    // keeps today's bind + primer behavior (the static tier). An `ssr: true` +
+    // `data` island is refused — but the refusal now lives uniformly in
+    // `islandMount` (it sees the unresolved `bind` on an ssr mount and throws
+    // UI_ISLAND_SSR_DATA_UNRESOLVED), so BOTH the Registry and `.page` paths
+    // obey it by construction (review 2c). We simply return no inlined data.
+    return undefined;
+  }
+
+  // A `visible` (lazy-mount) island's data is deferred along with its mount, so
+  // it is NOT resolved at render even under a resolver — it keeps its bind and
+  // fetches on first intersection (the meaning of "visible").
+  if (def.ssr !== true && def.hydrate === "visible") return undefined;
+
+  // Resolve every bound source (memoized: two islands binding one source share a
+  // single loader run) and inline the values.
+  const inlined: Record<string, unknown> = {};
+
+  for (const [prop, source] of Object.entries(def.data)) {
+    inlined[prop] = React.use(resolver.resolve(source.name));
+  }
+
+  return inlined;
+}
+
+/**
+ * The typed declaration `defineIsland` accepts (review F8).
+ *
+ * `P` is the component's full props. `D` binds a SUBSET of those props to data
+ * sources, each `DataSource<P[K]>` — so binding a `DataSource<number>` to a
+ * `string` prop is a compile error (the token's phantom type finally reaches the
+ * component). `fallback` and the returned component see only `Omit<P, keyof D>` —
+ * the props NOT supplied by data — so the island component requires the unbound
+ * props and rejects the bound ones.
+ */
+export interface IslandDef<
+  P extends Record<string, unknown>,
+  D extends { [K in keyof P]?: DataSource<P[K]> },
+> {
+  name: string;
+  component: ComponentType<P>;
+  ssr?: boolean;
+  hydrate?: HydrationStrategy;
+  fallback?: (props: Omit<P, keyof D>) => ReactNode;
+  data?: D;
+  props?: Record<string, PropSpec>;
+}
+
+/**
+ * Wrap a typed island declaration into a `.page`-usable React component that
+ * self-emits its shell + mount script + data primer.
+ *
+ * The public signature is generic over the component's props (review F8): `data`
+ * is typed as `{ [K in keyof P]?: DataSource<P[K]> }` and the returned island
+ * component accepts the non-bound remainder `Omit<P, keyof D>`. Internally the
+ * def is cast ONCE to the erased {@link ClientComponentDef} — the same
+ * one-erasure-boundary precedent `lesto().page()` uses, because a React component
+ * is contravariant in its props, so a specific def is not directly assignable to
+ * the open one. `Registry.defineClient` typing stays deferred (ADR 0011
+ * Increment 2 / the `island.ts` doc): its storage is erased, its consumers
+ * stringly, so generics there are cosmetic until that path migrates.
+ *
+ * The shell is the `ssr: true` real render or the deferred `fallback`; the mount
+ * script and primer are SIBLINGS of the shell wrapper so the client's
+ * `createRoot`/`hydrateRoot` adopts only the shell (a script inside the
+ * container would mismatch hydration). A non-serializable prop throws out of the
+ * render exactly as the Registry path's does — the page's error boundary owns it.
+ */
+export function defineIsland<
+  P extends Record<string, unknown>,
+  const D extends { [K in keyof P]?: DataSource<P[K]> } = Record<never, never>,
+>(declaration: IslandDef<P, D>): IslandComponent<Omit<P, keyof D>> {
+  const def = declaration as unknown as ClientComponentDef;
+
+  // The `.page` path never passes through a Registry, so the union rules are
+  // enforced here at wrap time (module init): an un-typed caller can hand
+  // `defineIsland` a broken union too.
+  assertClientDef(def);
+
+  function Island(props: Record<string, unknown>): ReactElement {
+    const id = useId();
+
+    const resolver = useContext(IslandDataContext);
+
+    // Decide whether to resolve this island's data AT RENDER (the canonical,
+    // dynamic tier) and inline it, per the table in the module doc.
+    const resolved = resolveData(def, resolver);
+
+    const { mount, props: validated } = islandMount(def, props, id, resolved);
+
+    const shell: ReactNode =
+      mount.ssr && def.component !== undefined
+        ? createElement(def.component as ComponentType<Record<string, unknown>>, mount.props)
+        : (def.fallback?.(validated) as ReactNode);
+
+    const primer = mount.bind === undefined ? "" : dataPrimerScript([mount]);
+
+    return createElement(
+      Fragment,
+      null,
+      createElement("div", { [ISLAND_ATTR]: id }, shell),
+      createElement("script", {
+        type: "application/json",
+        [ISLAND_MOUNT_ATTR]: "",
+        // serializeScriptJson is the one audited escape; dangerouslySetInnerHTML
+        // is required because React would HTML-entity-escape text children, which
+        // is NOT decoded inside <script> and would corrupt the JSON.
+        dangerouslySetInnerHTML: { __html: serializeScriptJson(mount) },
+      }),
+      ...(primer === ""
+        ? []
+        : [createElement("script", { dangerouslySetInnerHTML: { __html: primer } })]),
+    );
+  }
+
+  Island.island = def;
+
+  // One erasure boundary: the runtime component takes the open props record; the
+  // public type narrows it to the unbound remainder. The cast lives only here.
+  return Island as unknown as IslandComponent<Omit<P, keyof D>>;
+}

package/src/errors.ts

@@ -0,0 +1,36 @@
+/**
+ * Errors carry codes, not just prose.
+ *
+ * Every failure surfaces a stable, machine-readable `code`. Callers branch on
+ * the code — never on a message string, which is free to change for humans
+ * without breaking machines.
+ */
+
+import { LestoError } from "@lesto/errors";
+
+export { LestoError };
+
+export type UiErrorCode =
+  | "UI_CLIENT_COMPONENT_MISSING"
+  | "UI_CLIENT_SSR_NEEDS_COMPONENT"
+  | "UI_INVALID_DATA_SOURCE_NAME"
+  | "UI_INVALID_ENUM_SPEC"
+  | "UI_ISLAND_DATA_FETCH_FAILED"
+  | "UI_ISLAND_DATA_TIMEOUT"
+  | "UI_ISLAND_PROPS_NOT_SERIALIZABLE"
+  | "UI_ISLAND_SSR_DATA_UNRESOLVED"
+  | "UI_ISLAND_UNKNOWN_COMPONENT"
+  | "UI_RESERVED_COMPONENT_NAME"
+  | "UI_ROUTE_MISSING_PARAM"
+  | "UI_SOFTNAV_PREFETCH_UNSUPPORTED"
+  | "UI_STREAM_INCOMPLETE"
+  | "UI_STREAM_TIMEOUT";
+
+/** Anything the UI engine can refuse to do while building a schema. */
+export class UiError extends LestoError<UiErrorCode> {
+  constructor(code: UiErrorCode, message: string, details?: Record<string, unknown>) {
+    super(code, message, details);
+
+    this.name = "UiError";
+  }
+}