@lesto/ui 0.1.0

package/src/routes.ts

@@ -0,0 +1,101 @@
+/**
+ * The typed-route seam — how an app's generated `routes.gen.ts` teaches `<Link>` and
+ * {@link route} the app's real routes, with ZERO runtime and no react dependency
+ * (pure type-level — only a TYPE-only import of `PathParams` from `@lesto/router` —
+ * so the `@lesto/ui` isomorphic core stays react-free here and the type gate can pin
+ * it without pulling the component tree in).
+ *
+ * The mechanism is declaration merging — the same `Register` idiom TanStack Router
+ * uses. `@lesto/web`'s `generateRouteManifest` emits, into each app's
+ * `routes.gen.ts`, a `RoutePath` + `RoutePattern` union of every route plus:
+ *
+ *   declare module "@lesto/ui" {
+ *     interface RegisteredRoutes { href: RoutePath; pattern: RoutePattern }
+ *   }
+ *
+ * which merges `href`/`pattern` members into {@link RegisteredRoutes} below.
+ * {@link RouteHref} reads `href` (so `<Link href>` autocompletes the app's routes);
+ * {@link KnownPatterns} reads `pattern` (so {@link route} constrains its pattern arg
+ * and types its params). An app with NO route codegen leaves `RegisteredRoutes`
+ * empty, so both stay unconstrained (`string`): nothing breaks.
+ */
+
+import type { PathParams } from "@lesto/router";
+
+/**
+ * The route registry an app augments by declaration merging. Empty by design — it
+ * IS the extension point a generated `routes.gen.ts` merges a `href` member into
+ * (the same pattern as `@lesto/content-core`'s `CollectionRegistry`). Augmenting
+ * `@lesto/ui` reaches this interface because the package re-exports it.
+ */
+export interface RegisteredRoutes {}
+
+/**
+ * The known route hrefs a registry shape `Reg` declares, or `never` when it declares
+ * none. Internal helper for {@link HrefFor} — kept as a generic over the registry
+ * (not reading the global {@link RegisteredRoutes}) so {@link HrefFor}'s behavior is
+ * pinnable in the type gate without a program-global `declare module` augmentation.
+ */
+type KnownRoutesOf<Reg> = Reg extends { href: infer H extends string } ? H : never;
+
+/**
+ * The `<Link href>` type derived from a registry shape `Reg`:
+ *
+ *   - `Reg` declares no routes → exactly `string` (the unchanged default for an app
+ *     with no route codegen).
+ *   - `Reg` declares routes → the known routes (autocompleted) PLUS a `(string & {})`
+ *     escape that still accepts any other string — an external URL, a `?query`/`#hash`,
+ *     or a code-first route — so typed routes only SURFACE the known ones, never
+ *     BLOCK a valid link. Strict dead-link erroring is a follow-up (docs/plans/
+ *     dx-parity.md, Workstream 1 Increment 2).
+ *
+ * `[KnownRoutesOf<Reg>] extends [never]` guards the empty case without distributing
+ * over the union, and `string & {}` is the standard trick that keeps the literal
+ * members visible to autocomplete while staying assignable from any string.
+ */
+export type HrefFor<Reg> = [KnownRoutesOf<Reg>] extends [never]
+  ? string
+  : KnownRoutesOf<Reg> | (string & {});
+
+/** A `<Link>` href — see {@link HrefFor}, resolved against the app's {@link RegisteredRoutes}. */
+export type RouteHref = HrefFor<RegisteredRoutes>;
+
+/**
+ * Like {@link HrefFor} but WITHOUT the `(string & {})` escape — only the registry's
+ * known routes, so an unknown literal is NOT assignable (a typo'd link is a `tsc`
+ * error). A generic over `Reg` so it's pinnable in the type gate. An empty registry
+ * still yields `string` (no codegen → unchanged).
+ */
+export type StrictHrefFor<Reg> = [KnownRoutesOf<Reg>] extends [never] ? string : KnownRoutesOf<Reg>;
+
+/**
+ * A STRICT `<Link href>` type for {@link StrictLink}: the app's known routes with no
+ * escape, so a typo'd link does not compile. Sound only for a FULLY-file-routed app —
+ * every route is in the registry. A MIXED app (with code-first `.page()` routes the
+ * codegen can't see) must keep the lenient {@link RouteHref}, or strict mode would
+ * false-positive on those routes (making it strict BY DEFAULT for mixed apps needs
+ * code-first route capture, a deferred large refactor — docs/plans/dx-parity.md).
+ */
+export type StrictRouteHref = StrictHrefFor<RegisteredRoutes>;
+
+/**
+ * The known route PATTERNS a registry shape `Reg` declares (`"/blog/:id"`, with
+ * `:param` segments KEPT), or `never` when it declares none. {@link route} reads this
+ * to constrain its pattern argument to the app's real routes; a generic over `Reg`
+ * (like {@link HrefFor}) so it's pinnable in the type gate without a global augmentation.
+ */
+export type PatternsOf<Reg> = Reg extends { pattern: infer P extends string } ? P : never;
+
+/** The app's known route patterns once codegen augments {@link RegisteredRoutes}, else `never`. */
+export type KnownPatterns = PatternsOf<RegisteredRoutes>;
+
+/**
+ * The argument list a {@link route} call takes for a pattern `P`: the typed params
+ * object is REQUIRED when `P` has `:segments`, ABSENT otherwise — a tuple, so a
+ * param-less `route("/about")` needs no second argument (the `@lesto/client`
+ * `createApi` `GetArgs` precedent). Param names + value types come from
+ * `@lesto/router`'s `PathParams<P>`.
+ */
+export type ParamArgs<P extends string> = keyof PathParams<P> extends never
+  ? []
+  : [params: PathParams<P>];

package/src/schema.ts

@@ -0,0 +1,244 @@
+/**
+ * The model-facing description of the registry.
+ *
+ * `treeJsonSchema` emits a JSON Schema an AI can be constrained to: a UI node is
+ * either a bare string (a text leaf) or one of the registered components — a
+ * `oneOf` whose variants each pin `type` to a const and describe their props.
+ * Each variant lives in its own `#/$defs/<name>` entry so a children allow-list
+ * can `$ref` exactly the components it permits — the children narrowing mirrors
+ * the runtime `validateTree` `allowsChild` policy, no looser. `componentCatalog`
+ * is the friendlier prose summary for a model's system prompt.
+ */
+
+import { UiError } from "./errors";
+import type { Registry } from "./registry";
+import type { ChildrenPolicy, ComponentDef, PropSpec, PropType } from "./types";
+
+/** Map a `PropType` to the JSON Schema fragment that describes it. */
+function propSchema(spec: PropSpec): Record<string, unknown> {
+  const base = jsonTypeFor(spec.type, spec);
+
+  // Carry the human description through to the model when present.
+  return spec.description === undefined ? base : { ...base, description: spec.description };
+}
+
+/** The bare JSON Schema type fragment for a prop, before description is added. */
+function jsonTypeFor(type: PropType, spec: PropSpec): Record<string, unknown> {
+  if (type === "enum") {
+    // An enum without values is unbuildable: we'd emit a schema that admits
+    // nothing. Refuse loudly so the registry author fixes the spec.
+    if (spec.values === undefined) {
+      throw new UiError("UI_INVALID_ENUM_SPEC", "enum prop spec has no values", {
+        type,
+      });
+    }
+
+    return { type: "string", enum: [...spec.values] };
+  }
+
+  if (type === "object") return { type: "object" };
+
+  if (type === "array") return { type: "array" };
+
+  // string / number / boolean map straight across.
+  return { type };
+}
+
+/** The `properties` + `required` shape for one component's props. */
+function propsObjectSchema(specs: Record<string, PropSpec>): Record<string, unknown> {
+  const properties: Record<string, unknown> = {};
+
+  const required: string[] = [];
+
+  for (const [name, spec] of Object.entries(specs)) {
+    properties[name] = propSchema(spec);
+
+    if (spec.required === true) required.push(name);
+  }
+
+  // Only attach `required` when there is something to require — a cleaner schema.
+  return {
+    type: "object",
+    properties,
+    additionalProperties: false,
+    ...(required.length === 0 ? {} : { required }),
+  };
+}
+
+/** Does any of a component's props carry `required: true`? */
+function hasRequiredProp(specs: Record<string, PropSpec>): boolean {
+  return Object.values(specs).some((spec) => spec.required === true);
+}
+
+/**
+ * Does a component accept children at all?
+ *
+ * `true` admits any registered component; a non-empty allow-list admits only its
+ * members; `false` (and the degenerate empty list) is a leaf. Leaves get no
+ * `children` property, so the model is constrained no more loosely than the
+ * validator's missing/forbidden-child checks enforce.
+ */
+function acceptsChildren(policy: ChildrenPolicy): boolean {
+  if (policy === true) return true;
+
+  if (policy === false) return false;
+
+  return policy.length > 0;
+}
+
+/** A bare string is the universal text leaf — valid as a child of ANY parent. */
+const stringLeaf = { type: "string" };
+
+/**
+ * The `#/$defs/<name>` ref for one component variant.
+ *
+ * Component names are opaque strings, so the name is JSON-Pointer-escaped
+ * (`~` → `~0`, `/` → `~1`, in that order) before it goes into the ref — the def
+ * itself is keyed by the raw name (object keys are unrestricted), but a `$ref`
+ * is a JSON Pointer and must encode those two characters to resolve.
+ */
+function componentRef(name: string): { $ref: string } {
+  const pointer = name.replaceAll("~", "~0").replaceAll("/", "~1");
+
+  return { $ref: `#/$defs/${pointer}` };
+}
+
+/**
+ * The reserved `$defs` key for the node union (the schema root). A registered
+ * component may not share this name — `treeJsonSchema` refuses it, since it would
+ * otherwise clobber the union.
+ */
+const RESERVED_NODE_DEF = "node";
+
+/**
+ * The `items` schema for a children-accepting component, mirroring `allowsChild`.
+ *
+ *   - `policy === true`  → the full node union (any string leaf or component).
+ *   - allow-list `[A,B]` → ONLY the named variants, plus the string leaf.
+ *
+ * The allow-list case is the correctness pin: `validateTree`'s `allowsChild`
+ * only consults the list for *node objects* (`isNodeObject(child)`), so a bare
+ * string leaf is always permitted and a component child must be a list member.
+ * We mirror that exactly — `oneOf: [stringLeaf, ...refs to listed components]` —
+ * so a tree the runtime would reject for a disallowed child cannot pass the
+ * schema either. A listed name with no registered `$def` can never be satisfied
+ * (the runtime flags it `unknown_component`), so we drop it rather than emit a
+ * dangling `$ref`; the admitted set stays exactly what `allowsChild` *and*
+ * `validateTree` together accept.
+ */
+function childItemsSchema(policy: ChildrenPolicy, registered: ReadonlySet<string>): object {
+  // `true`: any node. Keep the full union ref so the tree nests arbitrarily.
+  // (Only ever called for children-accepting policies, so `false` never lands
+  // here — but a list is the only other shape, so we narrow on that.)
+  if (!Array.isArray(policy)) return { $ref: `#/$defs/${RESERVED_NODE_DEF}` };
+
+  const allowed = policy.filter((name) => registered.has(name)).map(componentRef);
+
+  // A string child is always allowed (allowsChild is guarded by isNodeObject),
+  // so the leaf is a member alongside each listed, registered component.
+  return { oneOf: [stringLeaf, ...allowed] };
+}
+
+/** The full JSON Schema fragment for one component variant. */
+function componentVariant(def: ComponentDef, registered: ReadonlySet<string>): object {
+  return {
+    type: "object",
+    properties: {
+      type: { const: def.name },
+      props: propsObjectSchema(def.props),
+
+      // Only children-accepting components advertise a `children` array; leaves
+      // omit it so the schema is as strict as the runtime policy. The `items`
+      // schema is narrowed to the allow-list when there is one (see
+      // `childItemsSchema`) so the schema matches `allowsChild` exactly.
+      ...(acceptsChildren(def.children)
+        ? { children: { type: "array", items: childItemsSchema(def.children, registered) } }
+        : {}),
+    },
+    // A component with required props must require the `props` object itself —
+    // otherwise the nested `props.required` never bites (a model could omit
+    // `props` wholesale, passing the schema yet failing `validateTree`'s
+    // missing-required-prop check). The two must agree, so require `props` here.
+    required: hasRequiredProp(def.props) ? ["type", "props"] : ["type"],
+    additionalProperties: false,
+  };
+}
+
+/**
+ * The recursive JSON Schema for a whole UI tree rooted at `#/$defs/node`.
+ *
+ * A node is a string leaf OR any one registered component. Each component gets
+ * its own `#/$defs/<name>` entry (so an allow-list can `$ref` individual
+ * variants); the `node` def is the `oneOf` of the string leaf and every variant.
+ * A component that accepts children also gets a `children` array whose `items`
+ * mirror the runtime `allowsChild` policy: the full node union for `children:
+ * true`, or a `oneOf` of just the allowed variants (plus the string leaf) for an
+ * allow-list — so a tree `validateTree` rejects for a disallowed child cannot
+ * pass the emitted schema either. A leaf omits `children` entirely.
+ */
+export function treeJsonSchema(registry: Registry): object {
+  const defs = registry.all();
+
+  // `node` is the reserved $defs key for the node union (the schema root). A
+  // component sharing that exact name would, via the `...componentDefs` spread
+  // below, clobber the union — leaving the root `$ref` resolving to one component
+  // and silently rejecting every other tree. Refuse it loudly rather than emit a
+  // corrupt schema.
+  const reserved = defs.find((def) => def.name === RESERVED_NODE_DEF);
+  if (reserved !== undefined) {
+    throw new UiError(
+      "UI_RESERVED_COMPONENT_NAME",
+      `a component may not be named "${RESERVED_NODE_DEF}": it is the reserved JSON Schema node-union key`,
+      { name: reserved.name },
+    );
+  }
+
+  const registered = new Set(defs.map((def) => def.name));
+
+  // One `$def` per component so an allow-list `oneOf` can reference individual
+  // variants by name; the `node` union refs them all (plus the string leaf).
+  const componentDefs: Record<string, object> = {};
+
+  for (const def of defs) {
+    componentDefs[def.name] = componentVariant(def, registered);
+  }
+
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $ref: `#/$defs/${RESERVED_NODE_DEF}`,
+    $defs: {
+      [RESERVED_NODE_DEF]: { oneOf: [stringLeaf, ...defs.map((def) => componentRef(def.name))] },
+      ...componentDefs,
+    },
+  };
+}
+
+/** A compact, model-friendly summary of every component in the registry. */
+export function componentCatalog(registry: Registry): object[] {
+  return registry.all().map(catalogEntry);
+}
+
+/** One component's entry in the catalog — only the fields that carry information. */
+function catalogEntry(def: ComponentDef): Record<string, unknown> {
+  const props = Object.fromEntries(
+    Object.entries(def.props).map(([name, spec]) => [name, catalogProp(spec)]),
+  );
+
+  return {
+    name: def.name,
+    children: def.children,
+    props,
+    ...(def.description === undefined ? {} : { description: def.description }),
+  };
+}
+
+/** One prop's entry in the catalog — only the fields that carry information. */
+function catalogProp(spec: PropSpec): Record<string, unknown> {
+  return {
+    type: spec.type,
+    ...(spec.required === true ? { required: true } : {}),
+    ...(spec.values === undefined ? {} : { values: [...spec.values] }),
+    ...(spec.default === undefined ? {} : { default: spec.default }),
+    ...(spec.description === undefined ? {} : { description: spec.description }),
+  };
+}

package/src/serialize.ts

@@ -0,0 +1,148 @@
+/**
+ * The wire guard for island props.
+ *
+ * Island props are serialized on the server and revived in the browser, so they
+ * must be pure JSON — the values `JSON.stringify`/`JSON.parse` round-trip
+ * losslessly. A function, a `Date`, a class instance, a `Symbol`, a `bigint`, or
+ * `undefined` would either vanish or arrive as something the client cannot use.
+ * We reject them at the boundary with a stable code, rather than let a prop
+ * silently disappear between server and client.
+ *
+ * The check is structural and reports the FIRST offending path (e.g.
+ * `props.user.onClick`), so the author is told exactly which value to fix.
+ */
+
+import { UiError } from "./errors";
+
+import type { IslandMount } from "./island";
+
+/** A JSON-shaped value: the closure of null/boolean/number/string under array/object. */
+type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
+
+/**
+ * The first path at which `value` is not JSON-serializable, or `undefined` if
+ * the whole structure is clean. `path` seeds the reported location.
+ */
+function firstNonSerializable(value: unknown, path: string): string | undefined {
+  if (value === null) return undefined;
+
+  // Primitives that JSON round-trips losslessly. A non-finite number (NaN,
+  // Infinity) becomes `null` through JSON, so it is not faithfully serializable.
+  if (typeof value === "boolean" || typeof value === "string") return undefined;
+
+  if (typeof value === "number") return Number.isFinite(value) ? undefined : path;
+
+  // Arrays: clean iff every element is clean, reported left to right.
+  if (Array.isArray(value)) {
+    for (const [index, element] of value.entries()) {
+      const offender = firstNonSerializable(element, `${path}[${index}]`);
+
+      if (offender !== undefined) return offender;
+    }
+
+    return undefined;
+  }
+
+  // A plain object: clean iff every own value is clean. Anything with a custom
+  // prototype (Date, Map, class instance) is rejected — it would not round-trip
+  // as the author intends.
+  if (typeof value === "object" && isPlainObject(value)) {
+    for (const [key, nested] of Object.entries(value)) {
+      const offender = firstNonSerializable(nested, `${path}.${key}`);
+
+      if (offender !== undefined) return offender;
+    }
+
+    return undefined;
+  }
+
+  // Everything else — function, symbol, bigint, undefined, exotic object — is
+  // not JSON and so cannot cross the wire.
+  return path;
+}
+
+/** Is `value` a plain `{}`-style object (Object.prototype or null prototype)? */
+function isPlainObject(value: object): boolean {
+  const proto = Object.getPrototypeOf(value) as object | null;
+
+  return proto === null || proto === Object.prototype;
+}
+
+/**
+ * Assert that `props` is pure JSON, returning the same bag typed as JSON. Throws
+ * `UI_ISLAND_PROPS_NOT_SERIALIZABLE` naming the offending path otherwise.
+ */
+export function assertSerializable(
+  component: string,
+  props: Record<string, unknown>,
+): Record<string, JsonValue> {
+  const offender = firstNonSerializable(props, "props");
+
+  if (offender !== undefined) {
+    throw new UiError(
+      "UI_ISLAND_PROPS_NOT_SERIALIZABLE",
+      `island "${component}" has a non-serializable prop at ${offender}`,
+      { component, path: offender },
+    );
+  }
+
+  // The structural walk above proves the cast true: every reachable value is JSON.
+  return props as Record<string, JsonValue>;
+}
+
+/**
+ * Serialize a page-wide island manifest ARRAY for safe embedding in an inline
+ * `<script>` — the DEMOTED Registry/`UiNode` content path's emission (ADR 0011
+ * Increment 2). The canonical `.page` path uses {@link serializeScriptJson} on
+ * one mount object per island (co-located, streaming-safe); this array form is
+ * the niche where `renderPage` walks an AI-/DB-driven tree into one
+ * `#lesto-islands` manifest. Same audited escape, applied to the whole array.
+ *
+ * `JSON.stringify` alone is NOT safe to drop into HTML. A string value carrying
+ * `</script>` (or `<!--`, or the JS line terminators U+2028 / U+2029) terminates
+ * the surrounding element and lets attacker-influenced prop data execute — a
+ * textbook SSR-serialization XSS. HTML-entity escaping does not help either:
+ * entities are not decoded inside `<script>`. So we escape the breakout
+ * characters to their `\uXXXX` JSON escapes, which `JSON.parse` reads back as the
+ * byte-identical string — `<` and `>` (defeat `</script>` and `<!--`), `&`
+ * (belt-and-braces), and the two separators a JS parser treats as line breaks.
+ *
+ * The emission that consumes this MUST use `<script type="application/json">` and
+ * revive with `JSON.parse(el.textContent)` on the client: a non-executable type
+ * keeps even a future escaping miss inert, and the payload stays compatible with
+ * a strict, nonce-based CSP. This is the one audited seam every manifest payload
+ * crosses — never hand-roll `JSON.stringify` into a `<script>`, and never splice
+ * it in with `String.prototype.replace`, whose `$&`/`$'` tokens are themselves an
+ * injection vector.
+ *
+ * Mirrors the script-context escape that `@lesto/seo` and `@lesto/content-shared`
+ * already apply to inline JSON-LD; kept local so `@lesto/ui`'s render hot path
+ * pulls in no extra dependency for it.
+ */
+export function serializeManifest(manifest: readonly IslandMount[]): string {
+  return serializeScriptJson(manifest);
+}
+
+/**
+ * Serialize any value to JSON safe to embed inside a `<script>` element.
+ *
+ * The same script-context escape {@link serializeManifest} applies, generalized
+ * to one value — used by the per-island co-located mount script (ADR 0011),
+ * where each island emits its OWN `IslandMount` object rather than the page-wide
+ * array. The same rules and the same one-audited-seam discipline apply: emit only
+ * as `<script type="application/json">`, revive with `JSON.parse`, never a bare
+ * `JSON.stringify` into a `<script>`.
+ */
+export function serializeScriptJson(value: unknown): string {
+  // The JS line/paragraph separators, built from code points so no raw
+  // U+2028/U+2029 byte sits in this source (where tooling may mangle it).
+  const lineSeparator = String.fromCharCode(0x2028);
+  const paragraphSeparator = String.fromCharCode(0x2029);
+
+  return JSON.stringify(value)
+    .replaceAll("<", "\\u003c")
+    .replaceAll(">", "\\u003e")
+    .replaceAll("&", "\\u0026")
+    .replaceAll(lineSeparator, "\\u2028")
+    .replaceAll(paragraphSeparator, "\\u2029");
+}

package/src/server-preact.ts

@@ -0,0 +1,59 @@
+/**
+ * The Preact server-render dialect — re-exported from the `@lesto/ui/server`
+ * subpath as `preactServerRenderer`.
+ *
+ * This is the adapter half of the {@link ServerRenderer} seam (declared in
+ * `render.tsx`). It backs the two functions {@link renderPageMarkup} needs with
+ * `preact-render-to-string` instead of `react-dom/server`, so a page whose client
+ * bundle is Preact (the opt-in `react`→`preact/compat` alias, ADR 0007) renders
+ * its server markup in the SAME dialect the client will hydrate against.
+ *
+ * Why this matters, mechanically: an `ssr: true` island ships its real server
+ * render into the shell for the client to `hydrateRoot`. Hydration only succeeds
+ * when the server- and client-emitted markup agree, and React and Preact do NOT
+ * emit identical markup — most visibly, React delimits adjacent text segments with
+ * `<!-- -->` comment markers while Preact does not. Hydrate React's server markup
+ * with Preact's `hydrateRoot` and the common interpolated-text shape (`'Hi, ',
+ * name`) mismatches, firing `onRecoverableError` and forcing a full re-render —
+ * defeating `ssr: true`. Rendering the server side with THIS adapter removes the
+ * mismatch at the source: both sides speak Preact, so the markup lines up.
+ *
+ * Why it lives behind `@lesto/ui/server` (not the core barrel): keeping `@lesto/ui`
+ * dialect-agnostic means its core never hard-depends on `preact-render-to-string`.
+ * A server importer of `@lesto/ui` (the default React path, estate's `document.ts`)
+ * must never drag Preact's renderer into its build. So `preact-render-to-string` is
+ * an OPTIONAL peer dependency — present only when an adopter chooses the Preact
+ * client alias — and this module is the only place that imports it. Reach for it
+ * explicitly (`import { preactServerRenderer } from "@lesto/ui/server"`) and pass it
+ * to {@link renderPageMarkup}; the default React path never loads this file.
+ *
+ * The `as` cast at the call boundary is the honest cost of bridging two element
+ * factories: `@lesto/ui` builds its tree with React's `createElement`, and under
+ * the `preact/compat` alias those calls resolve to Preact-shaped vnodes that
+ * `preact-render-to-string` renders natively. The adapter's job is purely to map
+ * the engine's `ReactElement`-typed node onto that renderer's `VNode` parameter;
+ * the runtime shape is already a Preact vnode wherever this adapter is wired.
+ */
+
+import type { ReactElement } from "react";
+// `preact-render-to-string` mirrors `react-dom/server`'s two entry points, which
+// is exactly the surface {@link ServerRenderer} asks for — so the adapter is a
+// direct one-to-one binding, not a translation layer.
+import { renderToStaticMarkup, renderToString } from "preact-render-to-string";
+
+import type { ServerRenderer } from "./render";
+
+/**
+ * The Preact dialect, ready to hand to {@link renderPageMarkup} as its `renderer`.
+ *
+ * Both functions forward straight to `preact-render-to-string`. The node arrives
+ * typed as `ReactElement` (the engine's element type), but at runtime — under the
+ * `preact/compat` alias that makes this adapter meaningful — it is a Preact vnode,
+ * which is what `preact-render-to-string` consumes. The cast names that bridge
+ * rather than widening either library's public types.
+ */
+export const preactServerRenderer: ServerRenderer = {
+  dialect: "preact",
+  renderToString: (node: ReactElement) => renderToString(node as never),
+  renderToStaticMarkup: (node: ReactElement) => renderToStaticMarkup(node as never),
+};

package/src/server.ts

@@ -0,0 +1,44 @@
+/**
+ * `@lesto/ui/server` — the server-render half of the engine.
+ *
+ * Everything here imports `react-dom/server` (or its Preact twin,
+ * `preact-render-to-string`) directly or transitively: the buffered and streamed
+ * page renderers and the two server-render dialects. It is split out of the core
+ * `@lesto/ui` barrel for one load-bearing reason — a CLIENT bundle that imports
+ * `@lesto/ui` (for `Registry`, `defineIsland`, the island/data tokens) must NEVER
+ * drag `react-dom/server` into the browser graph. React's `react-dom/server` is
+ * ~60 KB gzip of code the browser never runs (the browser only *hydrates*), and
+ * before this split the barrel pulled it into every client bundle, defeating the
+ * whole point of the opt-in ~10 KB Preact dialect (ADR 0007/0008).
+ *
+ * So the rule is mechanical: anything that calls `renderToString` /
+ * `renderToStaticMarkup` / `renderToReadableStream` lives behind this subpath; a
+ * server (the `@lesto/web` page renderer, estate's `document.ts`) reaches for it
+ * explicitly. The core barrel stays isomorphic — safe to import from a module the
+ * client bundle reaches.
+ *
+ * Mirrors `@lesto/ui/client` (the browser-only hydration runtime) and
+ * `react-dom`'s own server/client split.
+ */
+
+export { reactServerRenderer, renderPage, renderPageMarkup, renderTree } from "./render";
+export type { Page, RenderError, ServerRenderer } from "./render";
+
+// Streaming SSR: a live shell-first stream for humans, plus a buffered `allReady`
+// exit for crawlers/SSG. Additive over `renderPageMarkup` (which stays the
+// dependency-light buffered API). Server-safe — React's stream renderer runs on
+// Node as of React 19.2.
+export { renderPageStream, renderPageStreamToString } from "./stream";
+export type {
+  ErrorInfo,
+  ReactRenderStream,
+  RenderToReadableStream,
+  StreamErrorSink,
+  StreamOptions,
+} from "./stream";
+
+// The Preact server-render dialect — the matched pair (ADR 0008) for a client
+// bundle built under the `react`→`preact/compat` alias. An OPTIONAL peer
+// (`preact-render-to-string`), present only when an adopter chooses Preact, so a
+// default React server never drags Preact's renderer into its build.
+export { preactServerRenderer } from "./server-preact";