@lesto/ui 0.1.0

package/src/metadata.ts

@@ -0,0 +1,195 @@
+/**
+ * Document metadata — `<title>`, `<meta>`, `<link>` — that any component may
+ * render, anywhere in the tree.
+ *
+ * React 19 hoists these tags out of the body and into the document head during
+ * SSR (and under the framework's buffered `renderToStaticMarkup`, to the front of
+ * the emitted markup). So a deeply nested component can declare the page's title
+ * or description and React floats it up — no prop-drilling a metadata bag to the
+ * document shell.
+ *
+ * The catch React leaves to the framework: **React hoists but does not dedupe.**
+ * Two components that each render a `<title>` ship two `<title>` tags, and the
+ * browser honors the first — a silent footgun. A page has exactly one title and
+ * one canonical link; many `<meta name>` are singletons too. So this module pairs
+ * the thin element helpers with {@link dedupeMetadata}, a pure pass the document
+ * shell runs over collected metadata to keep the last value per logical key.
+ *
+ * The helpers return plain React elements; nothing here renders or touches the
+ * DOM. `dedupeMetadata` is pure data-in/data-out so it is fully testable without
+ * React at all.
+ */
+
+import { createElement } from "react";
+import type { ReactElement } from "react";
+
+/** Render `<title>{text}</title>`. A page should resolve to exactly one. */
+export function title(text: string): ReactElement {
+  return createElement("title", null, text);
+}
+
+/** A `<meta name=… content=…>` tag (description, theme-color, robots, …). */
+export interface NamedMeta {
+  name: string;
+  content: string;
+}
+
+/** A `<meta property=… content=…>` tag (Open Graph / `og:` namespace). */
+export interface PropertyMeta {
+  property: string;
+  content: string;
+}
+
+/** A `<meta charset>` tag — the one meta that must come first in the head. */
+export interface CharsetMeta {
+  charSet: string;
+}
+
+/** Any meta tag this module knows how to render and dedupe. */
+export type MetaSpec = NamedMeta | PropertyMeta | CharsetMeta;
+
+/** A `<link>` tag — canonical, alternate, icon, preconnect authored by hand, … */
+export interface LinkSpec {
+  rel: string;
+  href: string;
+  hrefLang?: string;
+  type?: string;
+  sizes?: string;
+  media?: string;
+}
+
+/** Render a `<meta>` from any {@link MetaSpec}. */
+export function meta(spec: MetaSpec): ReactElement {
+  return createElement("meta", { ...spec });
+}
+
+/**
+ * Render a `<link>` from a {@link LinkSpec}, dropping absent optionals. An
+ * optional `key` is stamped for use inside a sibling list (see {@link renderMetadata}).
+ */
+export function link(spec: LinkSpec, key?: string): ReactElement {
+  return createElement("link", {
+    ...(key === undefined ? {} : { key }),
+    rel: spec.rel,
+    href: spec.href,
+    ...(spec.hrefLang === undefined ? {} : { hrefLang: spec.hrefLang }),
+    ...(spec.type === undefined ? {} : { type: spec.type }),
+    ...(spec.sizes === undefined ? {} : { sizes: spec.sizes }),
+    ...(spec.media === undefined ? {} : { media: spec.media }),
+  });
+}
+
+/**
+ * A single declared piece of metadata before it is rendered or deduped. Keeping
+ * metadata as data (not elements) until the last moment is what lets the document
+ * shell dedupe it — you cannot inspect a built React element's identity cheaply.
+ */
+export type MetadataEntry =
+  | { kind: "title"; text: string }
+  | { kind: "meta"; spec: MetaSpec }
+  | { kind: "link"; spec: LinkSpec };
+
+/** The dedupe key charset entries collapse to — also the key we promote first. */
+const CHARSET_KEY = "meta:charset";
+
+/**
+ * The logical identity of a metadata entry — entries sharing a key are the "same"
+ * tag, and the LAST one wins. This encodes the de-facto HTML singletons:
+ *   - a page has one `<title>`;
+ *   - one `<meta charset>`;
+ *   - one `<meta name="x">` per name, one `<meta property="og:y">` per property;
+ *   - one `<link rel="canonical">` (rel alone), but MANY `<link rel="alternate">`
+ *     (keyed by rel+href+hrefLang, so hreflang variants and icon sizes coexist).
+ */
+function dedupeKey(entry: MetadataEntry): string {
+  if (entry.kind === "title") return "title";
+
+  if (entry.kind === "meta") return metaKey(entry.spec);
+
+  return linkKey(entry.spec);
+}
+
+/** The dedupe key for a meta entry: charset, name, or og-property are singletons. */
+function metaKey(spec: MetaSpec): string {
+  if ("charSet" in spec) return CHARSET_KEY;
+
+  if ("name" in spec) return `meta:name:${spec.name}`;
+
+  return `meta:property:${spec.property}`;
+}
+
+/**
+ * The dedupe key for a link entry. `rel="canonical"` is a true singleton (keyed by
+ * rel alone). Everything else — stylesheets, icons, alternates, preloads — may
+ * legitimately repeat, so it is keyed by rel+href+hrefLang and only an exact
+ * duplicate collapses.
+ */
+function linkKey(spec: LinkSpec): string {
+  if (spec.rel === "canonical") return "link:canonical";
+
+  return `link:${spec.rel}:${spec.href}:${spec.hrefLang ?? ""}`;
+}
+
+/**
+ * Collapse a metadata list so each logical key appears once, keeping the LAST
+ * occurrence (a nested component's value overrides a layout's default) while
+ * preserving the order in which surviving keys first appeared.
+ *
+ * One position is NOT first-seen: `<meta charset>` is hoisted to the FRONT
+ * regardless of where it was declared. The HTML spec requires the charset
+ * declaration within the first 1024 bytes of the document and ideally first;
+ * since any component may declare it from deep in the tree, a first-seen order
+ * would let a late declaration sit after other hoisted tags and miss that window.
+ * Promoting it is mechanical and safe — charset is a singleton, so there is only
+ * ever one to move.
+ *
+ * Pure: same input, same output; no React, no DOM. The document shell runs this
+ * before rendering the entries, so duplicate `<title>`s never ship — closing the
+ * gap React's hoist-without-dedupe leaves open.
+ */
+export function dedupeMetadata(entries: readonly MetadataEntry[]): MetadataEntry[] {
+  // First appearance fixes order; last value wins. We record both, then emit in
+  // first-seen order with the winning value — stable and intention-revealing.
+  const order: string[] = [];
+
+  const winner = new Map<string, MetadataEntry>();
+
+  for (const entry of entries) {
+    const key = dedupeKey(entry);
+
+    if (!winner.has(key)) order.push(key);
+
+    winner.set(key, entry);
+  }
+
+  // Charset must lead the head, so pull it out of its first-seen slot and emit it
+  // first. Everything else keeps first-seen order behind it.
+  const charsetFirst = winner.has(CHARSET_KEY)
+    ? [CHARSET_KEY, ...order.filter((key) => key !== CHARSET_KEY)]
+    : order;
+
+  // Surviving entries in (charset-first) order, each with its winning value.
+  return charsetFirst.map((key) => winner.get(key) as MetadataEntry);
+}
+
+/**
+ * Render one {@link MetadataEntry} to its React element, stamping `key` so the
+ * element can sit in a sibling list without a missing-key warning. The key flows
+ * into the element config alongside the tag's own attributes.
+ */
+export function renderMetadataEntry(entry: MetadataEntry, key: string): ReactElement {
+  if (entry.kind === "title") return createElement("title", { key }, entry.text);
+
+  if (entry.kind === "meta") return createElement("meta", { key, ...entry.spec });
+
+  return link(entry.spec, key);
+}
+
+/**
+ * Dedupe then render a metadata list into React elements, each keyed by its
+ * first-seen index so React places the siblings cleanly. Drop this array into the
+ * tree and React hoists every tag into the head.
+ */
+export function renderMetadata(entries: readonly MetadataEntry[]): ReactElement[] {
+  return dedupeMetadata(entries).map((entry, index) => renderMetadataEntry(entry, `m${index}`));
+}

package/src/mount.ts

@@ -0,0 +1,99 @@
+/**
+ * Build an island's wire `IslandMount` from its declaration — the single author
+ * of those bytes, shared by the two server paths that emit islands:
+ *
+ *   - `buildIsland` (render.tsx) — the Registry/`UiNode` tree path, one page-wide
+ *     `#lesto-islands` manifest array;
+ *   - `defineIsland` (define-island.ts) — the `.page` path (ADR 0011), one
+ *     co-located mount script per island.
+ *
+ * Both must produce byte-identical mount shapes (props validated + serializable,
+ * `ssr`, the optional `strategy`/`bind` emitted only when they deviate from the
+ * default), so the shape lives here once rather than drifting between them.
+ */
+
+import { dataSourceHref } from "./data";
+import type { IslandBind } from "./data";
+import { UiError } from "./errors";
+import type { ClientComponentDef, IslandMount } from "./island";
+import { validateProps } from "./props";
+import { assertSerializable } from "./serialize";
+
+/**
+ * Validate `rawProps` against the island's schema, prove them serializable, and
+ * assemble the wire mount. Returns the mount AND the validated props (the caller
+ * renders the fallback / ssr output from the same validated bag). May throw
+ * `UI_ISLAND_PROPS_NOT_SERIALIZABLE` — the caller decides whether to contain it.
+ *
+ * `resolved` is the render-time-resolved data (ADR 0012, the canonical island):
+ * when present, its entries are merged into the props AFTER schema validation
+ * (bound props were never schema-validated — they bypass `validateProps` on the
+ * client path today, kept symmetric) and BEFORE `assertSerializable` (inlined
+ * data rides the wire, so it passes the same JSON guard). A `bind` is then
+ * emitted only for `def.data` entries NOT in `resolved` (e.g. a `visible`
+ * island's deferred source). The Registry path (`buildIsland`) passes nothing,
+ * so its mount is byte-for-byte unchanged.
+ */
+export function islandMount(
+  def: ClientComponentDef,
+  rawProps: Record<string, unknown>,
+  id: string,
+  resolved?: Record<string, unknown>,
+): { mount: IslandMount; props: Record<string, unknown> } {
+  const validated = def.props === undefined ? rawProps : validateProps(def.props, rawProps).props;
+
+  // Inlined data merges OVER the validated props (a bound prop wins over a static
+  // one of the same name), then the whole bag must pass the serialize guard.
+  const props = resolved === undefined ? validated : { ...validated, ...resolved };
+
+  const serializable = assertSerializable(def.name, props);
+
+  const mount: IslandMount = {
+    id,
+    component: def.name,
+    props: serializable,
+    ssr: def.ssr === true,
+  };
+
+  // `strategy`/`bind` ride the wire only when they deviate from the default, so a
+  // plain eager island's mount is byte-for-byte what it has always been.
+  if (def.hydrate === "visible") {
+    mount.strategy = "visible";
+  }
+
+  if (def.data !== undefined) {
+    const bind: Record<string, IslandBind> = {};
+
+    for (const [prop, source] of Object.entries(def.data)) {
+      // A source already resolved into props needs no client-side bind — its
+      // value crossed the wire inline. Only unresolved sources keep a bind.
+      if (resolved !== undefined && prop in resolved) continue;
+
+      bind[prop] = { source: source.name, href: dataSourceHref(source.name) };
+    }
+
+    // Emit `bind` only when at least one source is still unresolved, so a fully
+    // inlined island's wire entry has no `bind` key at all (byte-stable).
+    if (Object.keys(bind).length > 0) {
+      mount.bind = bind;
+    }
+  }
+
+  // The shared invariant, authored here so BOTH emission paths obey it by
+  // construction (chief-architect review 2c — it had drifted onto only the
+  // `defineIsland` path): an `ssr: true` island that still carries a `bind` would
+  // be server-rendered WITHOUT its bound data and then hydrated WITH it — a
+  // guaranteed mismatch. It is legal only when the data was resolved at render
+  // (a dynamic page's resolver inlines it, leaving no bind). Refuse it otherwise:
+  // the Registry/`buildIsland` path contains this throw as a reported render
+  // error; the `defineIsland` path propagates it to the page boundary.
+  if (mount.ssr && mount.bind !== undefined) {
+    throw new UiError(
+      "UI_ISLAND_SSR_DATA_UNRESOLVED",
+      `island "${def.name}" is ssr: true with unresolved data bindings — the server cannot render correct markup without the data, so hydration would mismatch; render it on a dynamic page (where a resolver inlines the values) or drop ssr`,
+      { name: def.name },
+    );
+  }
+
+  return { mount, props };
+}

package/src/node.ts

@@ -0,0 +1,8 @@
+/** Shared guard for distinguishing a UI node object from a string leaf or junk. */
+
+import type { UiNode } from "./types";
+
+/** Is `value` a UiNode-shaped object (vs a string leaf, array, or null)? */
+export function isNodeObject(value: unknown): value is UiNode {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/props.ts

@@ -0,0 +1,95 @@
+/**
+ * Prop validation: take whatever the AI emitted and reconcile it against a
+ * component's declared `PropSpec`s. The result is a clean prop bag the renderer
+ * can trust, plus a list of human-readable errors for anything that went wrong.
+ *
+ * The rules, per spec:
+ *   - unknown props (not in the schema) are silently dropped
+ *   - an absent prop falls back to its `default`, if one is declared
+ *   - a missing *required* prop is an error
+ *   - values are coerced to their declared type where it's safe
+ *   - an enum value outside the allowed `values` is an error
+ */
+
+import type { PropSpec, PropType } from "./types";
+
+/** Coerce a raw value toward `type`. Returns the value unchanged if it can't. */
+function coerce(type: PropType, value: unknown): unknown {
+  if (type === "number") return coerceNumber(value);
+
+  if (type === "boolean") return coerceBoolean(value);
+
+  // string / enum / object / array pass through; the renderer and enum check
+  // handle them. We never invent structure that wasn't there.
+  return value;
+}
+
+/** A numeric string becomes a number; anything non-finite is left as-is. */
+function coerceNumber(value: unknown): unknown {
+  if (typeof value === "number") return value;
+
+  if (typeof value === "string") {
+    const n = Number(value);
+
+    if (value.trim() !== "" && Number.isFinite(n)) return n;
+  }
+
+  return value;
+}
+
+/** The strings "true"/"false" become booleans; everything else is left as-is. */
+function coerceBoolean(value: unknown): unknown {
+  if (typeof value === "boolean") return value;
+
+  if (value === "true") return true;
+
+  if (value === "false") return false;
+
+  return value;
+}
+
+/** Is `value` one of these allowed enum strings? A non-string is never a member. */
+function isAllowed(values: readonly string[], value: unknown): boolean {
+  return typeof value === "string" && values.includes(value);
+}
+
+/**
+ * Validate `props` against `specs`. Pure: no throws, no mutation of the input.
+ */
+export function validateProps(
+  specs: Record<string, PropSpec>,
+  props: Record<string, unknown>,
+): { props: Record<string, unknown>; errors: string[] } {
+  const out: Record<string, unknown> = {};
+
+  const errors: string[] = [];
+
+  for (const [name, spec] of Object.entries(specs)) {
+    const present = Object.hasOwn(props, name);
+
+    // Absent prop: apply a default if one exists, else flag if required.
+    if (!present) {
+      if (spec.default !== undefined) {
+        out[name] = spec.default;
+      } else if (spec.required === true) {
+        errors.push(`missing required prop "${name}"`);
+      }
+
+      continue;
+    }
+
+    const value = coerce(spec.type, props[name]);
+
+    // An enum value must be one of the declared options. An enum spec with no
+    // `values` constrains nothing, so only a present-and-mismatched value errs.
+    if (spec.type === "enum" && spec.values !== undefined && !isAllowed(spec.values, value)) {
+      errors.push(`prop "${name}" must be one of [${spec.values.join(", ")}]`);
+
+      continue;
+    }
+
+    out[name] = value;
+  }
+
+  return { props: out, errors };
+}

package/src/registry.ts

@@ -0,0 +1,141 @@
+/**
+ * The registry is the vetted vocabulary: only components defined here can ever
+ * appear in a rendered tree. The AI proposes; the registry disposes.
+ */
+
+import { assertClientDef } from "./island";
+import type { ClientComponentDef } from "./island";
+import type { ComponentDef } from "./types";
+
+/**
+ * Where a cross-namespace shadowing warning goes. A name resolves to exactly ONE
+ * thing, so registering a server component over an existing client one of the
+ * same name (or vice versa) silently changes which side of the wire that `type`
+ * lives on — a likely copy-paste/rename slip, not an intent. We warn (never
+ * throw: last-write-wins is a legitimate redefinition) so the slip is loud.
+ * Injectable, defaulting to `console.warn`, so the warning is asserted in a test
+ * without spying on the global (the codebase's seam-not-global pattern).
+ */
+export type ShadowWarn = (message: string) => void;
+
+const consoleShadowWarn: ShadowWarn = (message) => console.warn(`[lesto/ui] ${message}`);
+
+/**
+ * A mutable, fluent catalog of the components the engine is allowed to render.
+ *
+ * Two flavors live side by side: ordinary server components (`define`) that
+ * render to HTML in place, and *client* components (`defineClient`) that mark an
+ * island — a region the server stubs out and the browser later hydrates. Both
+ * share one namespace, because at the authoring layer an island is just another
+ * node `type`; the registry is what remembers which side of the wire it belongs
+ * to.
+ */
+export class Registry {
+  // Insertion order is preserved so `all()` and the generated schema read
+  // predictably, in the order a human declared them.
+  private readonly byName = new Map<string, ComponentDef>();
+
+  private readonly clientsByName = new Map<string, ClientComponentDef>();
+
+  private readonly warn: ShadowWarn;
+
+  /**
+   * @param warn where a cross-namespace shadowing warning goes (default
+   * `console.warn`). Injectable so a test asserts the warning without spying on
+   * the global; an app rarely sets it.
+   */
+  constructor(warn: ShadowWarn = consoleShadowWarn) {
+    this.warn = warn;
+  }
+
+  /**
+   * Register a server component. Last definition for a name wins. Chainable.
+   * A name resolves to exactly one thing, so this shadows any client component
+   * of the same name (the inverse of `defineClient`) — and warns when it does,
+   * since flipping a `type` from an island to a server component is almost
+   * always a rename/copy-paste slip, not intent.
+   */
+  define(def: ComponentDef): this {
+    if (this.clientsByName.has(def.name)) {
+      this.warn(
+        `server component "${def.name}" shadows a client component of the same name — ` +
+          `a name resolves to one thing, so the island is no longer reachable`,
+      );
+    }
+
+    this.byName.set(def.name, def);
+    this.clientsByName.delete(def.name);
+
+    return this;
+  }
+
+  /**
+   * Register a client component — an island. Last definition for a name wins.
+   * Chainable. A name may be a server component OR a client one, never both;
+   * declaring a client shadows any server component of the same name and vice
+   * versa, so a `type` resolves to exactly one thing — and warns when it crosses
+   * the namespace, the same loud-when-likely-wrong as {@link define}.
+   *
+   * The eager/lazy union is re-checked at runtime for un-typed callers via the
+   * shared {@link assertClientDef} (the rule lives once, so this path and the
+   * `.page` `defineIsland` path refuse identical broken unions identically).
+   *
+   * The parameter is the ERASED {@link ClientComponentDef}, ON PURPOSE — the
+   * item-9/F8 phantom-type deferral (ADR 0012) is resolved here by *decision*,
+   * not by faking generics: the typed island authoring path is `defineIsland`
+   * (whose `IslandDef<P, D>` links each `DataSource<P[K]>` to the component's
+   * props and narrows the returned component to the unbound remainder). The
+   * Registry is the DB-/AI-content niche the manifest path now serves (ADR 0011
+   * Increment 2): its storage is a `Map<string, ClientComponentDef>` and its
+   * consumers (the `UiNode` walk, `getClient(name)`) are stringly by their nature
+   * — a `type` is a JSON string the model emitted — so a prop/data generic on
+   * this method would be cosmetic, erased the instant the def enters the map.
+   * `Island.island` (a `ClientComponentDef`) flows straight in; the type safety
+   * already happened at `defineIsland`.
+   */
+  defineClient(def: ClientComponentDef): this {
+    assertClientDef(def);
+
+    if (this.byName.has(def.name)) {
+      this.warn(
+        `client component "${def.name}" shadows a server component of the same name — ` +
+          `a name resolves to one thing, so the server component is no longer reachable`,
+      );
+    }
+
+    this.clientsByName.set(def.name, def);
+    this.byName.delete(def.name);
+
+    return this;
+  }
+
+  /** Look up a server component by its `type` name, or `undefined` if unknown. */
+  get(name: string): ComponentDef | undefined {
+    return this.byName.get(name);
+  }
+
+  /** Look up a client component (island) by name, or `undefined` if unknown. */
+  getClient(name: string): ClientComponentDef | undefined {
+    return this.clientsByName.get(name);
+  }
+
+  /** Is this name a registered server component? */
+  has(name: string): boolean {
+    return this.byName.has(name);
+  }
+
+  /** Is this name a registered client component (island)? */
+  hasClient(name: string): boolean {
+    return this.clientsByName.has(name);
+  }
+
+  /** Every registered server component, in declaration order. */
+  all(): ComponentDef[] {
+    return [...this.byName.values()];
+  }
+
+  /** Every registered client component (island), in declaration order. */
+  clients(): ClientComponentDef[] {
+    return [...this.clientsByName.values()];
+  }
+}