@loomwork/blueprint-runtime 0.0.0-stage → 0.1.0

package/src/normalize.ts

@@ -0,0 +1,130 @@
+import { BLUEPRINT_IR_VERSION } from "./irVersion";
+import type { BindingStatus, Blueprint, GridCell, Layout, Widget } from "./types";
+
+export const IR_VERSION_LEGACY = "1.0.0";
+
+// ── Path resolution ───────────────────────────────────────────────────────────
+//
+// Lives here (not traverseBlueprint.ts) to avoid an import cycle: traverseBlueprint imports
+// `asCell` from this module, and `resolveWidgetStatus` below needs `resolvePath`. Re-exported
+// from traverseBlueprint.ts unchanged for existing consumers.
+
+// Resolve a dot-path (e.g. "a.b.c") against a projection state. Null-safe and
+// generic — no widget/UI coupling — so any live rendering surface can build a
+// slice selector for `ProjectionRuntime.subscribeSelector` without duplicating
+// this traversal (see useWidgetValue). An empty path binds to the whole state.
+export function resolvePath(state: unknown, path: string): unknown {
+  // An empty path binds the widget to the whole projection surface (the root),
+  // not a nested field — otherwise `"".split(".")` yields `[""]` and dereferences
+  // a non-existent "" key, silently returning undefined.
+  if (path === "") return state;
+  const parts = path.split(".");
+  let current: unknown = state;
+  for (const part of parts) {
+    if (current === null || current === undefined) return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+export const isWidget = (n: unknown): n is Widget =>
+  typeof n === "object" && n !== null && (n as { _tag?: unknown })._tag === "Widget";
+const isCell = (n: unknown): n is GridCell =>
+  typeof n === "object" && n !== null && "node" in n && !("_tag" in n) && !("type" in n);
+
+/** The one place a legacy bare grid child becomes a cell. Every walker calls this; nothing else branches on the union. */
+export function asCell(child: GridCell | Widget | Layout): GridCell {
+  return isCell(child) ? child : { span: 1, node: child };
+}
+/** An explicit-span cell, optionally placed (IR 2.1.0). Only the placement fields given are written. */
+export function cell(
+  span: number,
+  node: Widget | Layout,
+  placement: Pick<GridCell, "row" | "rowSpan" | "column"> = {}
+): GridCell {
+  return {
+    span,
+    node,
+    ...(placement.row !== undefined && { row: placement.row }),
+    ...(placement.rowSpan !== undefined && { rowSpan: placement.rowSpan }),
+    ...(placement.column !== undefined && { column: placement.column }),
+  };
+}
+
+export function blueprintIrVersion(bp: Blueprint): string {
+  return bp.irVersion ?? IR_VERSION_LEGACY;
+}
+
+function upgradeLayout(layout: Layout): Layout {
+  if (layout.type === "grid") {
+    return {
+      ...layout,
+      children: (layout.children as Array<GridCell | Widget | Layout>).map((c) => {
+        const k = asCell(c);
+        return isWidget(k.node) ? k : { ...k, node: upgradeLayout(k.node) };
+      }),
+    };
+  }
+  return { ...layout, children: layout.children.map((c) => (isWidget(c) ? c : upgradeLayout(c))) };
+}
+
+/**
+ * Every IR version this build reads AS-IS. 2.1.0 (ADR 0098) and 2.2.0 (ADR 0099) only added
+ * optional fields, and 2.3.0 (ADR 0100) only a `BindingState` literal (a runtime status value
+ * no artifact carries), 2.4.0 (ADR 0101) only an optional layout `id`, and 2.5.0 (ADR 0097
+ * amendment) only an optional `source.redacted`, so a 2.0.0 through 2.4.0 artifact is already a valid current-major artifact: re-stamping it would change its
+ * content address with no change to its shape.
+ *
+ * Add the outgoing version here on every minor bump.
+ */
+export const IR_VERSIONS_READ_AS_IS: ReadonlySet<string> = new Set([
+  "2.0.0",
+  "2.1.0",
+  "2.2.0",
+  "2.3.0",
+  "2.4.0",
+  BLUEPRINT_IR_VERSION,
+]);
+
+/**
+ * A current-major artifact from any readable one. Identity (same reference) on 2.0.0, 2.1.0,
+ * 2.2.0, 2.3.0, 2.4.0 and 2.5.0 input; a 1.0.0 (or unstamped) artifact is wrapped and stamped. Never
+ * mutates its input.
+ */
+export function upgradeBlueprint(bp: Blueprint): Blueprint {
+  if (bp.irVersion !== undefined && IR_VERSIONS_READ_AS_IS.has(bp.irVersion)) return bp;
+  return { ...bp, irVersion: BLUEPRINT_IR_VERSION, layout: upgradeLayout(bp.layout) };
+}
+
+// `empty` since IR 2.3.0 (ADR 0100). A reader built before it rejects `{ state: "empty" }` here,
+// so the status resolves to `undefined` and that reader's matrix falls back to loading/ready —
+// never to the error row (ADR 0100 D4).
+const STATES = new Set(["pending", "ready", "stale", "error", "empty"]);
+export function isBindingStatus(v: unknown): v is BindingStatus {
+  if (typeof v !== "object" || v === null) return false;
+  const s = v as Record<string, unknown>;
+  if (typeof s.state !== "string" || !STATES.has(s.state)) return false;
+  if (s.seq !== undefined && typeof s.seq !== "number") return false;
+  if (s.finding !== undefined) {
+    const f = s.finding as Record<string, unknown> | null;
+    if (
+      typeof f !== "object" ||
+      f === null ||
+      typeof f.code !== "string" ||
+      typeof f.message !== "string"
+    )
+      return false;
+  }
+  return true;
+}
+
+/** Status lives in the SAME projection state as the value; a malformed value is `undefined`, never a throw. */
+export function resolveWidgetStatus(
+  widget: Widget,
+  stateMap: Map<string, unknown>
+): BindingStatus | undefined {
+  const b = widget.binding;
+  if (b?.status === undefined) return undefined;
+  const raw = resolvePath(stateMap.get(b.projectionId), b.status.path);
+  return isBindingStatus(raw) ? raw : undefined;
+}

package/src/pins.ts

@@ -0,0 +1,84 @@
+import { checkVersionPins } from "@loomwork/core";
+import type { PinReport, VersionPins } from "@loomwork/core";
+import type { Blueprint } from "./types";
+
+// ── The blueprint spelling of the binding-semantics pin (ADR 0095) ────────────
+//
+// `validateBlueprint` checks a composition against a catalogue; `preservesNodes` checks one
+// tree against another. Neither can see the failure this covers, because it is not in the
+// tree at all: a `DataBinding` names a projection, the projection is live code registered
+// under that name, and the content address that makes a promoted view "the same view"
+// freezes the NAME.
+//
+// So a view can be byte-identical to the one an operator promoted, hydrate cleanly, validate
+// cleanly, and render a number that means something else — because the fold behind
+// `latency` was edited, or its window moved from rolling to fixed, since the day it was
+// composed.
+//
+// The comparison itself is `@loomwork/core`'s `checkVersionPins`, over `id -> version` maps
+// rather than blueprints: its other consumer (`ReadModelService.checkPins`) has no tree.
+// These two functions are the blueprint case spelled once, the way `blueprintNodeIds` /
+// `preservesBlueprintNodes` spell it for identity.
+
+/**
+ * The versions a blueprint recorded for the projections it binds to.
+ *
+ * Only ids the blueprint actually DECLARES are returned. A pin for an id absent from
+ * `projections` freezes nothing this view reads, and counting it would pad the comparison
+ * with agreements that carry no information — the denominator problem `PinReport.compared`
+ * exists to make visible.
+ */
+export function blueprintPins(blueprint: Blueprint): VersionPins {
+  const recorded = blueprint.projectionVersions;
+  if (recorded === undefined) return emptyPins();
+  const pins = emptyPins();
+  for (const projectionId of blueprint.projections) {
+    const version = recordedVersion(recorded, projectionId);
+    if (version !== undefined) pins[projectionId] = version;
+  }
+  return pins;
+}
+
+/**
+ * Does this blueprint still mean what it meant when it was composed?
+ *
+ * `current` is what the runtime about to hydrate it declares —
+ * `projectionRuntime.pins?.() ?? {}`. Findings, never a throw: a drift can be a deliberate
+ * re-promotion or a silent re-definition, and only the caller can tell.
+ *
+ * The comparison is scoped to the blueprint's own `projections` in BOTH directions, and
+ * every declared projection is entered on the recorded side even when nothing pinned it
+ * (as `""`, which `checkVersionPins` reads as "declared nothing"). That is deliberate:
+ * projections this view never binds are none of its business, and a binding that nobody
+ * pinned must produce a visible `unpinned` finding rather than vanishing from a report that
+ * would then read `ok: true` over an empty comparison.
+ */
+export function checkBlueprintPins(blueprint: Blueprint, current: VersionPins): PinReport {
+  const recorded = emptyPins();
+  const scoped = emptyPins();
+  for (const projectionId of blueprint.projections) {
+    recorded[projectionId] = recordedVersion(blueprint.projectionVersions, projectionId) ?? "";
+    const now = recordedVersion(current, projectionId);
+    if (now !== undefined) scoped[projectionId] = now;
+  }
+  return checkVersionPins(recorded, scoped);
+}
+
+/**
+ * A pin map with NO prototype, built rather than written into `{}`.
+ *
+ * A blueprint is data — the whole premise of ADR 0088 is that a model may have composed it
+ * — so a `projectionId` is an untrusted string, and `{}["__proto__"] = "1"` sets a
+ * prototype instead of a key: the pin vanishes, `Object.keys` never sees it, and the
+ * binding drops out of the report entirely with no finding. Silent omission is precisely
+ * what this seam exists to prevent, so the maps it builds cannot have a prototype to hit.
+ */
+function emptyPins(): Record<string, string> {
+  return Object.create(null) as Record<string, string>;
+}
+
+/** An OWN-property read, so an inherited member never answers for a recorded version. */
+function recordedVersion(pins: VersionPins | undefined, id: string): string | undefined {
+  if (pins === undefined || !Object.hasOwn(pins, id)) return undefined;
+  return pins[id];
+}

package/src/traverseBlueprint.bench.ts

@@ -0,0 +1,47 @@
+import { bench, describe } from "vitest";
+import { grid } from "./layout";
+import { traverseBlueprint } from "./traverseBlueprint";
+import type { Layout, Widget } from "./types";
+
+// ── Regression gate ───────────────────────────────────────────────────────────
+// traverseBlueprint is the synchronous render fast-path. It is deliberately left
+// untouched by the scheduler work; this bench is the committed baseline that CI
+// compares against so any accidental regression to the hot path is caught.
+
+function buildTree(nodeCount: number): Layout {
+  // Build a balanced grid tree whose leaves are widgets, totalling ~nodeCount
+  // widgets. Each level fans out by `branch`.
+  const branch = 4;
+  let leaves: Array<Widget | Layout> = Array.from({ length: nodeCount }, (_unused, i) => ({
+    _tag: "Widget",
+    id: `w${i}`,
+    kind: "MetricCard",
+    props: { label: `metric ${i}` },
+    binding: { projectionId: "p", path: "value" },
+  }));
+
+  while (leaves.length > 1) {
+    const parents: Array<Widget | Layout> = [];
+    for (let i = 0; i < leaves.length; i += branch) {
+      parents.push(grid({ columns: branch, children: leaves.slice(i, i + branch) }));
+    }
+    leaves = parents;
+  }
+  return leaves[0] as Layout;
+}
+
+const stateMap = new Map<string, unknown>([["p", { value: 42 }]]);
+
+const options = {
+  renderWidget: ({ value }: { value: unknown }) => value,
+  renderContainer: ({ children }: { children: unknown[] }) => children,
+};
+
+for (const size of [10, 100, 1000, 10000]) {
+  describe(`traverseBlueprint / ${size} nodes`, () => {
+    const tree = buildTree(size);
+    bench("traverse", () => {
+      traverseBlueprint(tree, stateMap, options);
+    });
+  });
+}

package/src/traverseBlueprint.ts

@@ -0,0 +1,94 @@
+import { asCell, isWidget, resolvePath, resolveWidgetStatus } from "./normalize";
+import type { Layout, Widget, WidgetAction, WidgetRendererProps } from "./types";
+
+// Re-exported unchanged for existing consumers; it now lives in normalize.ts to avoid an
+// import cycle (normalize.ts's `resolveWidgetStatus` needs it, and this module imports
+// `asCell`/`isWidget`/`resolveWidgetStatus` from normalize.ts as of Task 2).
+export { resolvePath };
+
+// ── Context types ─────────────────────────────────────────────────────────────
+
+export interface ContainerContext<TNode> {
+  layout: Layout;
+  children: TNode[];
+  /**
+   * Grid containers only: each child with the columns it occupies (default 1), in document
+   * order, plus its explicit placement (IR 2.1.0) — `row`/`rowSpan`/`column` are present only
+   * when the cell sets them.
+   */
+  cells?: Array<{ span: number; row?: number; rowSpan?: number; column?: number; child: TNode }>;
+}
+
+// ── Value resolution ──────────────────────────────────────────────────────────
+
+export function resolveWidgetValue(widget: Widget, stateMap: Map<string, unknown>): unknown {
+  if (!widget.binding) return undefined;
+  const state = stateMap.get(widget.binding.projectionId);
+  return resolvePath(state, widget.binding.path);
+}
+
+// ── traverseBlueprint ─────────────────────────────────────────────────────────
+//
+// Framework-agnostic recursive tree walker. Given a blueprint layout node and a
+// projection state map, walks the tree calling `renderWidget` for leaf nodes and
+// `renderContainer` for layout nodes. Returns a single TNode representing the
+// whole subtree — whatever type makes sense for the target framework:
+//   React:    traverseBlueprint<React.ReactNode>(...)
+//   DOM:      traverseBlueprint<HTMLElement>(...)
+//   string:   traverseBlueprint<string>(...)  // server-side HTML
+//
+// Example (plain DOM adapter):
+//   const el = traverseBlueprint<HTMLElement>(blueprint.layout, stateMap, {
+//     renderWidget({ widget, value, onAction }) {
+//       const div = document.createElement("div");
+//       div.dataset.widgetId = widget.id;
+//       div.textContent = String(value ?? "—");
+//       return div;
+//     },
+//     renderContainer({ layout, children }) {
+//       const div = document.createElement("div");
+//       div.style.display = layout.type === "flex" ? "flex" : "grid";
+//       children.forEach(c => div.appendChild(c));
+//       return div;
+//     },
+//   });
+
+export interface BlueprintTraversalOptions<TNode> {
+  renderWidget: (ctx: WidgetRendererProps) => TNode;
+  renderContainer: (ctx: ContainerContext<TNode>) => TNode;
+  onAction?: (action: WidgetAction) => void;
+}
+
+export function traverseBlueprint<TNode>(
+  node: Layout | Widget,
+  stateMap: Map<string, unknown>,
+  options: BlueprintTraversalOptions<TNode>
+): TNode {
+  const { renderWidget, renderContainer, onAction } = options;
+
+  if (isWidget(node)) {
+    const status = resolveWidgetStatus(node, stateMap);
+    return renderWidget({
+      widget: node,
+      value: resolveWidgetValue(node, stateMap),
+      ...(status !== undefined && { status }),
+      ...(onAction !== undefined && { onAction }),
+    });
+  }
+
+  const layout = node;
+  if (layout.type === "grid") {
+    const cells = layout.children.map(asCell).map((c) => ({
+      span: c.span ?? 1,
+      ...(c.row !== undefined && { row: c.row }),
+      ...(c.rowSpan !== undefined && { rowSpan: c.rowSpan }),
+      ...(c.column !== undefined && { column: c.column }),
+      child: traverseBlueprint(c.node, stateMap, options),
+    }));
+    return renderContainer({ layout, children: cells.map((c) => c.child), cells });
+  }
+
+  const children = layout.children.map((child) => traverseBlueprint(child, stateMap, options));
+
+  return renderContainer({ layout, children });
+}

package/src/traverseBlueprintAsync.ts

@@ -0,0 +1,92 @@
+import { throwIfAborted, yieldControl } from "@loomwork/scheduler";
+import { asCell, isWidget, resolveWidgetStatus } from "./normalize";
+import { resolveWidgetValue } from "./traverseBlueprint";
+import type { Layout, Widget, WidgetAction, WidgetRendererProps } from "./types";
+
+// ── traverseBlueprintAsync ────────────────────────────────────────────────────
+//
+// An interruptible, incremental-commit counterpart to the synchronous
+// traverseBlueprint. The synchronous walker is a PULL model (assemble the whole
+// TNode bottom-up, then hand it back) — fine for renderers that need the complete
+// tree (React, string/SSR). This async walker is a PUSH model for scheduler-less
+// renderers that mutate a target as the tree resolves (direct DOM, canvas, native):
+// it creates each node top-down, appends children as they resolve, and cooperatively
+// yields against a budget so the host stays responsive on large trees or expensive
+// BYOC widgets. It is opt-in and has no effect on the synchronous fast path.
+//
+// No production renderer ships against this yet (all current renderers are pull);
+// it is the validated BYOR extension point. See traverseBlueprintAsync.test.ts for
+// a reference IncrementalRenderer.
+
+export interface IncrementalRenderer<TNode> {
+  createContainer(layout: Layout): TNode;
+  createWidget(ctx: WidgetRendererProps): TNode;
+  appendChild(parent: TNode, child: TNode): void;
+}
+
+export interface AsyncTraversalOptions<TNode> {
+  renderer: IncrementalRenderer<TNode>;
+  onAction?: (action: WidgetAction) => void;
+  /** Abort a stale/interrupted render; checked at every node. */
+  signal?: AbortSignal;
+  /** Whether to yield before processing the next node. Default: every 64 nodes. */
+  shouldYield?: (nodesSinceYield: number) => boolean;
+  /** How to yield. Default: @loomwork/scheduler yieldControl (macrotask). */
+  yieldTo?: () => Promise<void>;
+}
+
+const DEFAULT_YIELD_EVERY = 64;
+
+export async function traverseBlueprintAsync<TNode>(
+  node: Layout | Widget,
+  stateMap: Map<string, unknown>,
+  options: AsyncTraversalOptions<TNode>
+): Promise<TNode> {
+  const { renderer, onAction, signal } = options;
+  const yieldTo = options.yieldTo ?? yieldControl;
+  const shouldYield = options.shouldYield ?? ((n) => n >= DEFAULT_YIELD_EVERY);
+
+  // Counter-based budget (no clock) so behavior is deterministic and testable.
+  let nodesSinceYield = 0;
+  const tick = async (): Promise<void> => {
+    throwIfAborted(signal);
+    nodesSinceYield++;
+    if (shouldYield(nodesSinceYield)) {
+      nodesSinceYield = 0;
+      await yieldTo();
+      throwIfAborted(signal);
+    }
+  };
+
+  const walk = async (current: Layout | Widget): Promise<TNode> => {
+    await tick();
+
+    if (isWidget(current)) {
+      const status = resolveWidgetStatus(current, stateMap);
+      return renderer.createWidget({
+        widget: current,
+        value: resolveWidgetValue(current, stateMap),
+        ...(status !== undefined && { status }),
+        ...(onAction !== undefined && { onAction }),
+      });
+    }
+
+    const layout = current;
+    // Create the container FIRST so children can be committed into it as they
+    // resolve (incremental commit / progressive paint between yields).
+    const container = renderer.createContainer(layout);
+    // Only the iteration source changes for a grid (unwrap each child via `asCell`) — this
+    // walker has no `cells`/span surface of its own: the container is created and committed
+    // to before its children resolve, so there is nowhere to hand spans alongside them. A
+    // renderer that needs them can read `layout.children` itself in `createContainer`.
+    const nodes =
+      layout.type === "grid" ? layout.children.map((c) => asCell(c).node) : layout.children;
+    for (const child of nodes) {
+      const childNode = await walk(child);
+      renderer.appendChild(container, childNode);
+    }
+    return container;
+  };
+
+  return walk(node);
+}

package/src/types.ts

@@ -0,0 +1,195 @@
+// ── Built-in widget kinds ────────────────────────────────────────────────────
+// WidgetKind is a convenience union for the built-in widgets shipped with Loom.
+// Widget.kind is widened to `string` so custom renderers can register any kind.
+export type WidgetKind =
+  | "MetricCard"
+  | "Timeline"
+  | "ApprovalCard"
+  | "StatusBadge"
+  | "ProgressBar"
+  | "DataTable"
+  | "AlertCard"
+  | "StreamingText";
+
+import type { DataClass } from "@loomwork/classify";
+
+/**
+ * `empty` (IR 2.3.0, ADR 0100): delivery succeeded and the upstream answered with NO subject to
+ * show (e.g. a template indexed past the end of an empty array). It is not an error and triggers
+ * nothing; a value written beside it is ignored by every renderer.
+ */
+export type BindingState = "pending" | "ready" | "stale" | "error" | "empty";
+/** A binding's delivery state, read from the same projection state as its value (IR 2.0.0). */
+export interface BindingStatus {
+  state: BindingState;
+  /** Monotonic per binding; lets a renderer coalesce out-of-order updates. */
+  seq?: number;
+  finding?: { code: string; message: string };
+}
+
+export interface DataBinding {
+  projectionId: string;
+  path: string;
+  /** Where, in the SAME projection state, this binding's status lives. Absent ⇒ no status channel. */
+  status?: { path: string };
+  /** `@loomwork/classify` DataClass. Read by compilers and delivery; never by renderers. */
+  sensitivity?: DataClass;
+}
+
+/** What a widget stands for: the semantic type it renders and the degradations that led to `kind`. */
+export interface WidgetSource {
+  type: string;
+  version: string;
+  /** Outermost first. */
+  degradedFrom?: Array<{ type: string; version: string }>;
+  /**
+   * IR 2.5.0 (ADR 0097, amendment 2026-10-11): `true` asserts this widget's content was WITHHELD
+   * for the audience the surface was compiled for. A renderer draws NO value and NO label from a
+   * redacted widget (not `title`, `props`, `binding` or `kind`) and draws a redaction marker
+   * instead. The compiler records the RESULT of resolving audience, never the audience itself.
+   * Only `true` is legal (absent = not redacted); with it `binding` and `degradedFrom` MUST be
+   * absent, and `type`/`version` are a generic placeholder (`"redacted"`/`"1"`) — the original
+   * widget's type may itself be sensitive.
+   */
+  redacted?: true;
+}
+
+export interface Widget {
+  readonly _tag: "Widget";
+  id: string;
+  // Widened to `string` so custom widget kinds can be registered. Built-in
+  // widgets still produce the exact WidgetKind literal via their builder fns.
+  kind: string;
+  title?: string;
+  props: Record<string, unknown>;
+  binding?: DataBinding;
+  source?: WidgetSource;
+}
+
+/**
+ * One child of a grid: the columns it occupies (`span`, default 1) and, since IR 2.1.0
+ * (ADR 0098), an optional explicit placement. Every placement field is independently optional;
+ * all absent = flow placement (the grid's auto-placement, exactly as under 2.0.0). Coordinates
+ * are 1-based grid lines: `column` is the start column (the cell occupies `column..column+span-1`),
+ * `row` the start row, `rowSpan` the rows occupied (default 1).
+ */
+export interface GridCell {
+  span?: number;
+  row?: number;
+  rowSpan?: number;
+  column?: number;
+  node: Widget | Layout;
+}
+export interface GridLayout {
+  type: "grid";
+  /**
+   * This container's stable identity (IR 2.4.0, ADR 0101) — the same rule as `Widget.id`: a
+   * non-empty string, no charset, no length cap, and ONE namespace with widget ids
+   * (`duplicate-node-id` spans both). A renderer that reconciles keys the container by it, so a
+   * sibling inserted or moved around it keeps its subtree's state. A renderer uses it only as a
+   * `Map` key — never markup. Absent or malformed (`layout-id-invalid`) ⇒ keyed positionally, as
+   * under 2.3.0.
+   */
+  id?: string;
+  columns: number;
+  gap?: number;
+  /** A section heading for this container (IR 2.1.0). Absent ⇒ no heading. */
+  title?: string;
+  /**
+   * What this container IS to a renderer that knows it (IR 2.2.0, ADR 0099) — the open,
+   * app-defined axis for containers that `Widget.kind` is for widgets (`"stepped"`, `"tabbed"`,
+   * …). `type` stays the geometry. Absent, malformed (see `isLayoutRole`) or unknown to the
+   * renderer in use ⇒ the plain container. Never an ARIA role, never display text.
+   */
+  role?: string;
+  children: GridCell[];
+}
+
+export interface FlexLayout {
+  type: "flex";
+  /**
+   * This container's stable identity (IR 2.4.0, ADR 0101) — the same rule as `Widget.id`: a
+   * non-empty string, no charset, no length cap, and ONE namespace with widget ids
+   * (`duplicate-node-id` spans both). A renderer that reconciles keys the container by it, so a
+   * sibling inserted or moved around it keeps its subtree's state. A renderer uses it only as a
+   * `Map` key — never markup. Absent or malformed (`layout-id-invalid`) ⇒ keyed positionally, as
+   * under 2.3.0.
+   */
+  id?: string;
+  direction: "row" | "column";
+  gap?: number;
+  /** A section heading for this container (IR 2.1.0). Absent ⇒ no heading. */
+  title?: string;
+  /**
+   * What this container IS to a renderer that knows it (IR 2.2.0, ADR 0099) — the open,
+   * app-defined axis for containers that `Widget.kind` is for widgets (`"stepped"`, `"tabbed"`,
+   * …). `type` stays the geometry. Absent, malformed (see `isLayoutRole`) or unknown to the
+   * renderer in use ⇒ the plain container. Never an ARIA role, never display text.
+   */
+  role?: string;
+  children: Array<Widget | Layout>;
+}
+
+export interface StackLayout {
+  type: "stack";
+  /**
+   * This container's stable identity (IR 2.4.0, ADR 0101) — the same rule as `Widget.id`: a
+   * non-empty string, no charset, no length cap, and ONE namespace with widget ids
+   * (`duplicate-node-id` spans both). A renderer that reconciles keys the container by it, so a
+   * sibling inserted or moved around it keeps its subtree's state. A renderer uses it only as a
+   * `Map` key — never markup. Absent or malformed (`layout-id-invalid`) ⇒ keyed positionally, as
+   * under 2.3.0.
+   */
+  id?: string;
+  gap?: number;
+  /** A section heading for this container (IR 2.1.0). Absent ⇒ no heading. */
+  title?: string;
+  /**
+   * What this container IS to a renderer that knows it (IR 2.2.0, ADR 0099) — the open,
+   * app-defined axis for containers that `Widget.kind` is for widgets (`"stepped"`, `"tabbed"`,
+   * …). `type` stays the geometry. Absent, malformed (see `isLayoutRole`) or unknown to the
+   * renderer in use ⇒ the plain container. Never an ARIA role, never display text.
+   */
+  role?: string;
+  children: Array<Widget | Layout>;
+}
+
+export type Layout = GridLayout | FlexLayout | StackLayout;
+
+export interface Blueprint {
+  readonly _tag: "Blueprint";
+  /** The IR shape this artifact was written in. Absent ⇒ "1.0.0". Writers always set it. */
+  irVersion?: string;
+  id: string;
+  title: string;
+  layout: Layout;
+  projections: string[];
+  /**
+   * ADR 0095 — the declared semantics of the projections this view binds to, by id, as they
+   * were at composition.
+   *
+   * It lives on the blueprint rather than beside it because a composed surface is
+   * content-addressed: a field of the value is part of the address, so this is what makes
+   * "the meaning of a view never changes silently" a property of the artifact instead of a
+   * paragraph. A binding freezes a NAME; this freezes what that name meant.
+   *
+   * Read it with `blueprintPins`, compare it with `checkBlueprintPins`.
+   */
+  projectionVersions?: Readonly<Record<string, string>>;
+}
+
+// ── Framework-agnostic renderer contract ─────────────────────────────────────
+
+export interface WidgetAction {
+  type: string;
+  widgetId: string;
+  payload?: unknown;
+}
+
+// The props passed to any widget renderer regardless of framework.
+export interface WidgetRendererProps {
+  widget: Widget;
+  value: unknown;
+  status?: BindingStatus;
+  onAction?: (action: WidgetAction) => void;
+}