@loomwork/blueprint-runtime 0.0.0-stage → 0.1.1

package/src/customWidget.ts

@@ -0,0 +1,42 @@
+import type { DataBinding, Widget } from "./types";
+
+function stableId(kind: string, props: object): string {
+  const str = kind + JSON.stringify(props, Object.keys(props as Record<string, unknown>).sort());
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    hash = (Math.imul(31, hash) + str.charCodeAt(i)) | 0;
+  }
+  return `${kind}-${(hash >>> 0).toString(16)}`;
+}
+
+export interface CustomWidgetConfig {
+  kind: string;
+  title?: string;
+  binding?: DataBinding;
+  props?: Record<string, unknown>;
+  id?: string;
+}
+
+// Builder for user-defined widget kinds that live outside the WidgetKind union.
+// Register a matching renderer in your RendererRegistry under the same `kind` string.
+//
+//   const HeatmapWidget = customWidget$({
+//     kind: "Heatmap",
+//     title: "CPU Heatmap",
+//     binding: { projectionId: "metrics", path: "cpu.history" },
+//     props: { buckets: 20 },
+//   });
+//   registry.register("Heatmap", HeatmapComponent);
+export function customWidget$(config: CustomWidgetConfig): Widget {
+  const propsRecord = config.props ?? {};
+  return {
+    _tag: "Widget",
+    id:
+      config.id ??
+      stableId(config.kind, { title: config.title, binding: config.binding, ...propsRecord }),
+    kind: config.kind,
+    ...(config.title !== undefined && { title: config.title }),
+    props: propsRecord,
+    ...(config.binding !== undefined && { binding: config.binding }),
+  };
+}

package/src/identity.ts

@@ -0,0 +1,178 @@
+import { hasLayoutId } from "./layout";
+import { asCell } from "./normalize";
+import type { Blueprint, GridCell, Layout, Widget } from "./types";
+
+// ── Node identity across a structural change ─────────────────────────────────
+//
+// `validateBlueprint` checks one tree against a catalogue, including the ids WITHIN it
+// (`duplicate-node-id`). Nothing checked one tree against ANOTHER, and that is where node
+// identity is actually lost.
+//
+// It is lost silently, because ids are derived by default: `stableId` hashes kind + props,
+// so a node keeps its identity only while its props stay byte-identical. Two situations
+// depend on that and neither gets a warning today:
+//
+//   • REVISION — a composer re-emits a view with one prop edited. The edited node is a new
+//     node as far as every consumer is concerned: it remounts, and any pin, annotation or
+//     agent reference keyed on the old id dangles. (`docs/composed-surfaces.md` says supply
+//     an explicit id; this is how you find out you didn't.)
+//   • VARIANTS — two trees generated separately are meant to share a set of nodes: the
+//     "floor" every variant must contain, a panel a runbook step names. Vary a title
+//     between variants and the two trees quietly stop agreeing about what the node IS.
+//
+// Both reduce to one question — which ids did this change drop? — so this is one function
+// over id sets rather than a blueprint-shaped API: the second consumer is A2UI's
+// `recompose`, whose components are a flat list, not a Blueprint.
+//
+// It reports rather than throws, and for the same reason `validateBlueprint` does: dropping
+// a node is legitimate (a subtree replacement, a variant that genuinely drops a panel) and
+// illegitimate (a re-identification nobody intended), and only the caller knows which.
+
+/** Why a node id went missing. Shares `validateBlueprint`'s vocabulary deliberately. */
+export interface IdentityFinding {
+  readonly code: "dropped-node-id";
+  readonly severity: "error";
+  readonly nodeId: string;
+  readonly message: string;
+}
+
+export interface IdentityReport {
+  /** True iff no id present before is missing after. */
+  readonly ok: boolean;
+  readonly findings: readonly IdentityFinding[];
+  /**
+   * Ids the change introduced. Not a defect — adding is how a variant sits above a floor,
+   * and how a recompose adds a panel — but a `dropped` finding beside an `added` id of the
+   * same component is what a RE-IDENTIFICATION looks like, and telling those apart is the
+   * caller's job.
+   */
+  readonly added: readonly string[];
+  /**
+   * Ids compared (the size of `before`). The denominator: `ok: true` over an empty `before`
+   * is not evidence that identity was preserved, and this is how a caller tells.
+   */
+  readonly compared: number;
+}
+
+/**
+ * The one total, iterative, pre-order walk behind every id list below. `onWidget` sees each
+ * widget id; `onLayout` each WELL-FORMED layout id (IR 2.4.0, ADR 0101) — an absent or malformed
+ * one is skipped, exactly as a renderer treats it as absent.
+ */
+function walkNodeIds(
+  blueprint: Blueprint,
+  onWidget: ((id: string) => void) | undefined,
+  onLayout: ((id: string) => void) | undefined
+): void {
+  // Iterative, matching `eachNode` in catalog.ts: a deep composed tree must not be able
+  // to blow the call stack.
+  //
+  // Length-driven, not `pop() !== undefined`: a blueprint is data an agent or a composer
+  // may have authored, so a layout child CAN legitimately be `undefined` (a malformed
+  // `cell(6, undefined)`, a hole from a revision) — and `stack.pop()` returns `undefined`
+  // both for "the stack is empty" and for "the next element IS `undefined`". A sentinel
+  // loop conflates the two and stops early, silently dropping every id not yet visited.
+  // Rejecting the hole is `validateBlueprint`'s job (`malformed-node`); this walk stays
+  // total and skips only the one non-object child.
+  const stack: unknown[] = [blueprint.layout];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    if (typeof node !== "object" || node === null) continue;
+    if ("_tag" in node && (node as Widget)._tag === "Widget") {
+      onWidget?.((node as Widget).id);
+      continue;
+    }
+    const layout = node as Layout;
+    if (!Array.isArray(layout.children)) continue;
+    if (onLayout !== undefined && hasLayoutId(layout)) onLayout(layout.id);
+    for (let i = layout.children.length - 1; i >= 0; i--) {
+      stack.push(
+        layout.type === "grid"
+          ? asCell(layout.children[i] as GridCell).node
+          : (layout.children[i] as Layout | Widget)
+      );
+    }
+  }
+}
+
+/**
+ * Every WIDGET id in a blueprint, in pre-order. Duplicates are `validateBlueprint`'s job.
+ *
+ * Widget-only by contract, also after IR 2.4.0: callers read its output as widget ids (a
+ * renderer's remount report, the a2ui bridge's `identityDiff`). Layout ids are
+ * `blueprintLayoutIds`; `preservesBlueprintNodes` compares both.
+ */
+export function blueprintNodeIds(blueprint: Blueprint): string[] {
+  const ids: string[] = [];
+  walkNodeIds(blueprint, (id) => ids.push(id), undefined);
+  return ids;
+}
+
+/**
+ * Every well-formed LAYOUT id in a blueprint (IR 2.4.0, ADR 0101), in pre-order, the root
+ * included. Absent and malformed ids are skipped. Duplicates are `validateBlueprint`'s job.
+ */
+export function blueprintLayoutIds(blueprint: Blueprint): string[] {
+  const ids: string[] = [];
+  walkNodeIds(blueprint, undefined, (id) => ids.push(id));
+  return ids;
+}
+
+/**
+ * Which of `before`'s node ids survive into `after`.
+ *
+ * Two readings, one function:
+ * - *"did this revision keep the nodes it kept?"* — `before` is the previous tree;
+ * - *"does this variant contain the floor?"* — `before` is the floor's ids, and any finding
+ *   is a floor violation. Nodes above the floor land in `added`, which is exactly right:
+ *   a variant may add, never subtract.
+ *
+ * One pass over each side, `Set`-backed: O(|before| + |after|).
+ */
+export function preservesNodes(before: Iterable<string>, after: Iterable<string>): IdentityReport {
+  const afterIds = new Set(after);
+  const findings: IdentityFinding[] = [];
+  const seen = new Set<string>();
+
+  for (const id of before) {
+    // A repeated id in `before` is one node's worth of identity, so report it once —
+    // otherwise a duplicated id inflates the finding count for a single lost node.
+    if (seen.has(id)) continue;
+    seen.add(id);
+    if (!afterIds.has(id)) {
+      findings.push({
+        code: "dropped-node-id",
+        severity: "error",
+        nodeId: id,
+        message: `node "${id}" is present before the change and absent after — either it was removed, or a prop edit re-identified it (ids are derived from kind + props unless supplied explicitly)`,
+      });
+    }
+  }
+
+  const added: string[] = [];
+  for (const id of afterIds) {
+    if (!seen.has(id)) added.push(id);
+  }
+
+  return { ok: findings.length === 0, findings, added, compared: seen.size };
+}
+
+/** Widget ids and layout ids together, in one pre-order (document) walk. */
+function allNodeIds(blueprint: Blueprint): string[] {
+  const ids: string[] = [];
+  const push = (id: string) => {
+    ids.push(id);
+  };
+  walkNodeIds(blueprint, push, push);
+  return ids;
+}
+
+/**
+ * `preservesNodes` over two blueprints — the common case, spelled once. Compares widget ids AND
+ * layout ids (IR 2.4.0, ADR 0101): they are one identity axis, so a re-identified container is a
+ * `dropped-node-id` finding rather than a silent loss of the state under it. A `before` with no
+ * layout ids (any pre-2.4.0 artifact) contributes none, so upgrading only adds to `added`.
+ */
+export function preservesBlueprintNodes(before: Blueprint, after: Blueprint): IdentityReport {
+  return preservesNodes(allNodeIds(before), allNodeIds(after));
+}

package/src/index.ts

@@ -0,0 +1,84 @@
+export { blueprint$ } from "./Blueprint";
+export { grid, flex, stack, isLayoutId, isLayoutRole } from "./layout";
+export {
+  asCell,
+  cell,
+  upgradeBlueprint,
+  blueprintIrVersion,
+  isBindingStatus,
+  isWidget,
+  resolveWidgetStatus,
+  IR_VERSION_LEGACY,
+} from "./normalize";
+export {
+  MetricCard,
+  Timeline,
+  ApprovalCard,
+  StatusBadge,
+  ProgressBar,
+  DataTable,
+  AlertCard,
+  StreamingText,
+} from "./widgets";
+export { customWidget$ } from "./customWidget";
+export { BLUEPRINT_IR_SHAPE, BLUEPRINT_IR_VERSION } from "./irVersion";
+export {
+  validateBlueprint,
+  defineWidgetCatalog,
+  builtinCatalog,
+  BUILTIN_CATALOG_ID,
+} from "./catalog";
+export { catalogCoverage } from "./coverage";
+export {
+  blueprintLayoutIds,
+  blueprintNodeIds,
+  preservesBlueprintNodes,
+  preservesNodes,
+} from "./identity";
+export { blueprintPins, checkBlueprintPins } from "./pins";
+// Re-exported from @loomwork/core so a consumer of the blueprint spelling types its report
+// from the package it already imports — `IdentityReport` does not send anyone elsewhere
+// either. The comparison itself stays in core, where its other consumer can reach it.
+export type { PinFinding, PinFindingCode, PinReport, VersionPins } from "@loomwork/core";
+export { RendererRegistry } from "./RendererRegistry";
+export { traverseBlueprint, resolveWidgetValue, resolvePath } from "./traverseBlueprint";
+export { describeWidgetFrame, describeWidgetStatus } from "./widgetStatus";
+export type {
+  WidgetShownState,
+  WidgetStatusDescriptor,
+  WidgetStatusFrame,
+  WidgetStatusMarker,
+  WidgetValueCheck,
+} from "./widgetStatus";
+export { traverseBlueprintAsync } from "./traverseBlueprintAsync";
+export type {
+  AsyncTraversalOptions,
+  IncrementalRenderer,
+} from "./traverseBlueprintAsync";
+export type {
+  BindingState,
+  BindingStatus,
+  Blueprint,
+  DataBinding,
+  FlexLayout,
+  GridCell,
+  GridLayout,
+  Layout,
+  StackLayout,
+  Widget,
+  WidgetKind,
+  WidgetSource,
+  WidgetAction,
+  WidgetRendererProps,
+} from "./types";
+export type { DataClass } from "@loomwork/classify";
+export type { ContainerContext, BlueprintTraversalOptions } from "./traverseBlueprint";
+export type {
+  CatalogEntry,
+  WidgetCatalog,
+  BlueprintFinding,
+  BlueprintFindingCode,
+  BlueprintValidation,
+} from "./catalog";
+export type { CoverageReport } from "./coverage";
+export type { IdentityFinding, IdentityReport } from "./identity";

package/src/irVersion.ts

@@ -0,0 +1,195 @@
+import type {
+  BindingState,
+  BindingStatus,
+  Blueprint,
+  DataBinding,
+  FlexLayout,
+  GridCell,
+  GridLayout,
+  Layout,
+  StackLayout,
+  Widget,
+  WidgetKind,
+  WidgetSource,
+} from "./types";
+
+// ── The Blueprint as a stable rendering IR (ADR 0096) ─────────────────────────
+//
+// A `Blueprint` used to be a value one app authored and one renderer drew. Once an external
+// framework COMPILES to it, its shape is an interface others depend on, and a field added or
+// renamed here is a breaking change in a repository nothing in this workspace builds.
+//
+// So the shape is declared twice, on purpose. The types below are the truth; the manifests are a
+// second spelling that `tsc` checks against them exhaustively — `AllKeys<T>` makes every key
+// required, and `satisfies` on an object literal rejects an excess key — so any change to
+// `Widget`, `Layout` or `Blueprint` fails the build until the manifest agrees. `irVersion.test.ts`
+// then pins a digest of the manifests to BLUEPRINT_IR_VERSION, so the manifest cannot change
+// without the version changing either. Neither half is sufficient alone.
+//
+// What this guards: field presence, field optionality (a required↔optional flip fails the
+// build), the WidgetKind literals, the layout `type` literals. What it does not: a field's type
+// being narrowed or widened, nor a `readonly` change. A consumer's typecheck catches those.
+//
+// Adding a Layout variant means adding its field manifest here too; `Record<Layout["type"], true>`
+// catches the variant, not its fields.
+
+export const BLUEPRINT_IR_VERSION = "2.5.0";
+
+type OptionalKeys<T> = { [K in keyof T]-?: object extends Pick<T, K> ? K : never }[keyof T];
+/** Every key of T, each tagged by whether T declares it optional. `satisfies` rejects a missing key,
+ *  an excess key, AND an optional↔required flip — the three shape changes a compile target can break on. */
+type KeyShape<T> = {
+  readonly [K in keyof T]-?: K extends OptionalKeys<T> ? "optional" : "required";
+};
+
+const WIDGET = {
+  _tag: "required",
+  id: "required",
+  kind: "required",
+  title: "optional",
+  props: "required",
+  binding: "optional",
+  source: "optional",
+} as const satisfies KeyShape<Widget>;
+
+const DATA_BINDING = {
+  projectionId: "required",
+  path: "required",
+  status: "optional",
+  sensitivity: "optional",
+} as const satisfies KeyShape<DataBinding>;
+
+const BINDING_STATUS_REF = {
+  path: "required",
+} as const satisfies KeyShape<NonNullable<DataBinding["status"]>>;
+
+const BINDING_STATUS = {
+  state: "required",
+  seq: "optional",
+  finding: "optional",
+} as const satisfies KeyShape<BindingStatus>;
+
+// The NESTED shapes, manifested in their own right. `KeyShape<BindingStatus>` only records that
+// `finding` exists and is optional — a key added to, removed from or flipped inside the finding
+// (or a `degradedFrom` entry) is a change to the compile target that the parent manifest cannot
+// see. A consumer reads `finding.code`/`d.type`, so those key sets are part of the contract.
+const BINDING_FINDING = {
+  code: "required",
+  message: "required",
+} as const satisfies KeyShape<NonNullable<BindingStatus["finding"]>>;
+
+const WIDGET_SOURCE = {
+  type: "required",
+  version: "required",
+  degradedFrom: "optional",
+  redacted: "optional",
+} as const satisfies KeyShape<WidgetSource>;
+
+const DEGRADED_FROM = {
+  type: "required",
+  version: "required",
+} as const satisfies KeyShape<NonNullable<WidgetSource["degradedFrom"]>[number]>;
+
+const GRID_CELL = {
+  span: "optional",
+  row: "optional",
+  rowSpan: "optional",
+  column: "optional",
+  node: "required",
+} as const satisfies KeyShape<GridCell>;
+
+const BINDING_STATES = {
+  pending: true,
+  ready: true,
+  stale: true,
+  error: true,
+  empty: true,
+} as const satisfies Record<BindingState, true>;
+
+const GRID_LAYOUT = {
+  type: "required",
+  id: "optional",
+  columns: "required",
+  gap: "optional",
+  title: "optional",
+  role: "optional",
+  children: "required",
+} as const satisfies KeyShape<GridLayout>;
+
+const FLEX_LAYOUT = {
+  type: "required",
+  id: "optional",
+  direction: "required",
+  gap: "optional",
+  title: "optional",
+  role: "optional",
+  children: "required",
+} as const satisfies KeyShape<FlexLayout>;
+
+const STACK_LAYOUT = {
+  type: "required",
+  id: "optional",
+  gap: "optional",
+  title: "optional",
+  role: "optional",
+  children: "required",
+} as const satisfies KeyShape<StackLayout>;
+
+const BLUEPRINT = {
+  _tag: "required",
+  irVersion: "optional",
+  id: "required",
+  title: "required",
+  layout: "required",
+  projections: "required",
+  projectionVersions: "optional",
+} as const satisfies KeyShape<Blueprint>;
+
+const WIDGET_KINDS = {
+  MetricCard: true,
+  Timeline: true,
+  ApprovalCard: true,
+  StatusBadge: true,
+  ProgressBar: true,
+  DataTable: true,
+  AlertCard: true,
+  StreamingText: true,
+} as const satisfies Record<WidgetKind, true>;
+
+const LAYOUT_TYPES = { grid: true, flex: true, stack: true } as const satisfies Record<
+  Layout["type"],
+  true
+>;
+
+// Field manifests emit `"<key>:<required|optional>"` so an optional↔required flip changes the
+// digest even though the key set itself is unchanged. The two literal-union manifests (kinds,
+// layout types) have no optionality to capture, so they stay plain key lists.
+const keysOf = (manifest: Record<string, "required" | "optional">): readonly string[] =>
+  Object.entries(manifest)
+    .map(([key, shape]) => `${key}:${shape}`)
+    .sort();
+
+const plainKeysOf = (manifest: Record<string, true>): readonly string[] =>
+  Object.keys(manifest).sort();
+
+/**
+ * The shape of the Blueprint IR at `BLUEPRINT_IR_VERSION`, as sorted key sets. Digest this
+ * (`fnv1a64(canonicalJson(BLUEPRINT_IR_SHAPE))`) to compare two builds' IR without a type checker.
+ */
+export const BLUEPRINT_IR_SHAPE = {
+  widget: keysOf(WIDGET),
+  dataBinding: keysOf(DATA_BINDING),
+  bindingStatusRef: keysOf(BINDING_STATUS_REF),
+  bindingStatus: keysOf(BINDING_STATUS),
+  bindingFinding: keysOf(BINDING_FINDING),
+  widgetSource: keysOf(WIDGET_SOURCE),
+  degradedFrom: keysOf(DEGRADED_FROM),
+  gridCell: keysOf(GRID_CELL),
+  gridLayout: keysOf(GRID_LAYOUT),
+  flexLayout: keysOf(FLEX_LAYOUT),
+  stackLayout: keysOf(STACK_LAYOUT),
+  blueprint: keysOf(BLUEPRINT),
+  widgetKinds: plainKeysOf(WIDGET_KINDS),
+  layoutTypes: plainKeysOf(LAYOUT_TYPES),
+  bindingStates: plainKeysOf(BINDING_STATES),
+} as const;

package/src/layout.ts

@@ -0,0 +1,105 @@
+import { asCell } from "./normalize";
+import type { FlexLayout, GridCell, GridLayout, Layout, StackLayout, Widget } from "./types";
+
+// ADR 0099 D2 — a role is a registry KEY, so it has a key's shape: a lowercase ASCII letter,
+// then lowercase letters, digits or hyphens, at most 64 characters in all. No `_`, `.` or
+// uppercase, so `__proto__`/`constructor` can never be one and a role never needs escaping in a
+// CSS attribute selector (`[data-container-role=stepped]`) or a log line.
+const LAYOUT_ROLE = /^[a-z][a-z0-9-]{0,63}$/;
+
+/**
+ * Whether `value` is a well-formed layout role (ADR 0099 D2): `/^[a-z][a-z0-9-]{0,63}$/`. A
+ * renderer looks a container's role up only when this holds; anything else — absent, empty,
+ * a non-string, `"Stepped"`, a 65-character string — draws the plain container, exactly as an
+ * unknown role does. It is the ONE spelling of the rule, so a compiler's schema and a
+ * renderer's lookup cannot drift apart.
+ */
+export function isLayoutRole(value: unknown): value is string {
+  return typeof value === "string" && LAYOUT_ROLE.test(value);
+}
+
+/**
+ * Whether `value` is a well-formed layout id (IR 2.4.0, ADR 0101): the same rule as `Widget.id`,
+ * a non-empty string — no charset, no length cap. Anything else — absent, `""`, a number, `null`
+ * — is treated as ABSENT by every reader: the container is keyed positionally, the identity walk
+ * skips it, and it collides with nothing. It is the ONE spelling of the rule, so a compiler's
+ * schema and a renderer's keying cannot drift apart (as `isLayoutRole` is for roles).
+ */
+export function isLayoutId(value: unknown): value is string {
+  return typeof value === "string" && value !== "";
+}
+
+/** `isLayoutId` on a node's `id`, narrowing the node. Internal. */
+export function hasLayoutId(layout: unknown): layout is { id: string } {
+  return isLayoutId((layout as { id?: unknown } | null | undefined)?.id);
+}
+
+export interface GridOptions {
+  /** This container's stable identity, one namespace with widget ids (IR 2.4.0, ADR 0101). */
+  id?: string;
+  columns: number;
+  gap?: number;
+  /** A section heading (IR 2.1.0). */
+  title?: string;
+  /** What this container is to a renderer that knows it (IR 2.2.0; see `isLayoutRole`). */
+  role?: string;
+  children: Array<GridCell | Widget | Layout>;
+}
+
+export function grid(options: GridOptions): GridLayout {
+  return {
+    type: "grid",
+    ...(options.id !== undefined && { id: options.id }),
+    columns: options.columns,
+    ...(options.gap !== undefined && { gap: options.gap }),
+    ...(options.title !== undefined && { title: options.title }),
+    ...(options.role !== undefined && { role: options.role }),
+    children: options.children.map(asCell),
+  };
+}
+
+export interface FlexOptions {
+  /** This container's stable identity, one namespace with widget ids (IR 2.4.0, ADR 0101). */
+  id?: string;
+  direction?: "row" | "column";
+  gap?: number;
+  /** A section heading (IR 2.1.0). */
+  title?: string;
+  /** What this container is to a renderer that knows it (IR 2.2.0; see `isLayoutRole`). */
+  role?: string;
+  children: Array<Widget | Layout>;
+}
+
+export function flex(options: FlexOptions): FlexLayout {
+  return {
+    type: "flex",
+    ...(options.id !== undefined && { id: options.id }),
+    direction: options.direction ?? "row",
+    ...(options.gap !== undefined && { gap: options.gap }),
+    ...(options.title !== undefined && { title: options.title }),
+    ...(options.role !== undefined && { role: options.role }),
+    children: options.children,
+  };
+}
+
+export interface StackOptions {
+  /** This container's stable identity, one namespace with widget ids (IR 2.4.0, ADR 0101). */
+  id?: string;
+  gap?: number;
+  /** A section heading (IR 2.1.0). */
+  title?: string;
+  /** What this container is to a renderer that knows it (IR 2.2.0; see `isLayoutRole`). */
+  role?: string;
+  children: Array<Widget | Layout>;
+}
+
+export function stack(options: StackOptions): StackLayout {
+  return {
+    type: "stack",
+    ...(options.id !== undefined && { id: options.id }),
+    ...(options.gap !== undefined && { gap: options.gap }),
+    ...(options.title !== undefined && { title: options.title }),
+    ...(options.role !== undefined && { role: options.role }),
+    children: options.children,
+  };
+}