@loomwork/blueprint-runtime 0.0.0-stage → 0.1.1

package/dist/irVersion.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BLUEPRINT_IR_SHAPE = exports.BLUEPRINT_IR_VERSION = void 0;
+// ── 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.
+exports.BLUEPRINT_IR_VERSION = "2.5.0";
+const WIDGET = {
+    _tag: "required",
+    id: "required",
+    kind: "required",
+    title: "optional",
+    props: "required",
+    binding: "optional",
+    source: "optional",
+};
+const DATA_BINDING = {
+    projectionId: "required",
+    path: "required",
+    status: "optional",
+    sensitivity: "optional",
+};
+const BINDING_STATUS_REF = {
+    path: "required",
+};
+const BINDING_STATUS = {
+    state: "required",
+    seq: "optional",
+    finding: "optional",
+};
+// 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",
+};
+const WIDGET_SOURCE = {
+    type: "required",
+    version: "required",
+    degradedFrom: "optional",
+    redacted: "optional",
+};
+const DEGRADED_FROM = {
+    type: "required",
+    version: "required",
+};
+const GRID_CELL = {
+    span: "optional",
+    row: "optional",
+    rowSpan: "optional",
+    column: "optional",
+    node: "required",
+};
+const BINDING_STATES = {
+    pending: true,
+    ready: true,
+    stale: true,
+    error: true,
+    empty: true,
+};
+const GRID_LAYOUT = {
+    type: "required",
+    id: "optional",
+    columns: "required",
+    gap: "optional",
+    title: "optional",
+    role: "optional",
+    children: "required",
+};
+const FLEX_LAYOUT = {
+    type: "required",
+    id: "optional",
+    direction: "required",
+    gap: "optional",
+    title: "optional",
+    role: "optional",
+    children: "required",
+};
+const STACK_LAYOUT = {
+    type: "required",
+    id: "optional",
+    gap: "optional",
+    title: "optional",
+    role: "optional",
+    children: "required",
+};
+const BLUEPRINT = {
+    _tag: "required",
+    irVersion: "optional",
+    id: "required",
+    title: "required",
+    layout: "required",
+    projections: "required",
+    projectionVersions: "optional",
+};
+const WIDGET_KINDS = {
+    MetricCard: true,
+    Timeline: true,
+    ApprovalCard: true,
+    StatusBadge: true,
+    ProgressBar: true,
+    DataTable: true,
+    AlertCard: true,
+    StreamingText: true,
+};
+const LAYOUT_TYPES = { grid: true, flex: true, stack: 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) => Object.entries(manifest)
+    .map(([key, shape]) => `${key}:${shape}`)
+    .sort();
+const plainKeysOf = (manifest) => 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.
+ */
+exports.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),
+};
+//# sourceMappingURL=irVersion.js.map

package/dist/irVersion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"irVersion.js","sourceRoot":"","sources":["../src/irVersion.ts"],"names":[],"mappings":"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"}

package/dist/layout.d.ts

@@ -0,0 +1,57 @@
+import type { FlexLayout, GridCell, GridLayout, Layout, StackLayout, Widget } from "./types";
+/**
+ * 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 declare function isLayoutRole(value: unknown): value is string;
+/**
+ * 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 declare function isLayoutId(value: unknown): value is string;
+/** `isLayoutId` on a node's `id`, narrowing the node. Internal. */
+export declare function hasLayoutId(layout: unknown): layout is {
+    id: string;
+};
+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 declare function grid(options: GridOptions): GridLayout;
+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 declare function flex(options: FlexOptions): FlexLayout;
+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 declare function stack(options: StackOptions): StackLayout;
+//# sourceMappingURL=layout.d.ts.map

package/dist/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAQ7F;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE5D;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE1D;AAED,mEAAmE;AACnE,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAErE;AAED,MAAM,WAAW,WAAW;IAC1B,4FAA4F;IAC5F,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yFAAyF;IACzF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,KAAK,CAAC,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC;CAC7C;AAED,wBAAgB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,UAAU,CAUrD;AAED,MAAM,WAAW,WAAW;IAC1B,4FAA4F;IAC5F,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yFAAyF;IACzF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;CAClC;AAED,wBAAgB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,UAAU,CAUrD;AAED,MAAM,WAAW,YAAY;IAC3B,4FAA4F;IAC5F,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yFAAyF;IACzF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;CAClC;AAED,wBAAgB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,WAAW,CASxD"}

package/dist/layout.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLayoutRole = isLayoutRole;
+exports.isLayoutId = isLayoutId;
+exports.hasLayoutId = hasLayoutId;
+exports.grid = grid;
+exports.flex = flex;
+exports.stack = stack;
+const normalize_1 = require("./normalize");
+// 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.
+ */
+function isLayoutRole(value) {
+    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).
+ */
+function isLayoutId(value) {
+    return typeof value === "string" && value !== "";
+}
+/** `isLayoutId` on a node's `id`, narrowing the node. Internal. */
+function hasLayoutId(layout) {
+    return isLayoutId(layout?.id);
+}
+function grid(options) {
+    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(normalize_1.asCell),
+    };
+}
+function flex(options) {
+    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,
+    };
+}
+function stack(options) {
+    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,
+    };
+}
+//# sourceMappingURL=layout.js.map

package/dist/layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":";;AAgBA,oCAEC;AASD,gCAEC;AAGD,kCAEC;AAcD,oBAUC;AAcD,oBAUC;AAaD,sBASC;AAxGD,2CAAqC;AAGrC,6FAA6F;AAC7F,0FAA0F;AAC1F,gGAAgG;AAChG,0EAA0E;AAC1E,MAAM,WAAW,GAAG,wBAAwB,CAAC;AAE7C;;;;;;GAMG;AACH,SAAgB,YAAY,CAAC,KAAc;IACzC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,UAAU,CAAC,KAAc;IACvC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE,CAAC;AACnD,CAAC;AAED,mEAAmE;AACnE,SAAgB,WAAW,CAAC,MAAe;IACzC,OAAO,UAAU,CAAE,MAA8C,EAAE,EAAE,CAAC,CAAC;AACzE,CAAC;AAcD,SAAgB,IAAI,CAAC,OAAoB;IACvC,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,GAAG,CAAC,OAAO,CAAC,EAAE,KAAK,SAAS,IAAI,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC;QACnD,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;QACtD,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QAC5D,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;QACzD,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,kBAAM,CAAC;KACvC,CAAC;AACJ,CAAC;AAcD,SAAgB,IAAI,CAAC,OAAoB;IACvC,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,GAAG,CAAC,OAAO,CAAC,EAAE,KAAK,SAAS,IAAI,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC;QACnD,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,KAAK;QACrC,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;QACtD,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QAC5D,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;QACzD,QAAQ,EAAE,OAAO,CAAC,QAAQ;KAC3B,CAAC;AACJ,CAAC;AAaD,SAAgB,KAAK,CAAC,OAAqB;IACzC,OAAO;QACL,IAAI,EAAE,OAAO;QACb,GAAG,CAAC,OAAO,CAAC,EAAE,KAAK,SAAS,IAAI,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC;QACnD,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;QACtD,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QAC5D,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;QACzD,QAAQ,EAAE,OAAO,CAAC,QAAQ;KAC3B,CAAC;AACJ,CAAC"}

package/dist/normalize.d.ts

@@ -0,0 +1,29 @@
+import type { BindingStatus, Blueprint, GridCell, Layout, Widget } from "./types";
+export declare const IR_VERSION_LEGACY = "1.0.0";
+export declare function resolvePath(state: unknown, path: string): unknown;
+export declare const isWidget: (n: unknown) => n is Widget;
+/** The one place a legacy bare grid child becomes a cell. Every walker calls this; nothing else branches on the union. */
+export declare function asCell(child: GridCell | Widget | Layout): GridCell;
+/** An explicit-span cell, optionally placed (IR 2.1.0). Only the placement fields given are written. */
+export declare function cell(span: number, node: Widget | Layout, placement?: Pick<GridCell, "row" | "rowSpan" | "column">): GridCell;
+export declare function blueprintIrVersion(bp: Blueprint): string;
+/**
+ * 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 declare const IR_VERSIONS_READ_AS_IS: ReadonlySet<string>;
+/**
+ * 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 declare function upgradeBlueprint(bp: Blueprint): Blueprint;
+export declare function isBindingStatus(v: unknown): v is BindingStatus;
+/** Status lives in the SAME projection state as the value; a malformed value is `undefined`, never a throw. */
+export declare function resolveWidgetStatus(widget: Widget, stateMap: Map<string, unknown>): BindingStatus | undefined;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../src/normalize.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAElF,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAYzC,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAYjE;AAED,eAAO,MAAM,QAAQ,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,MACyC,CAAC;AAIrF,0HAA0H;AAC1H,wBAAgB,MAAM,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAElE;AACD,wGAAwG;AACxG,wBAAgB,IAAI,CAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,SAAS,GAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,GAAG,SAAS,GAAG,QAAQ,CAAM,GAC3D,QAAQ,CAQV;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CAExD;AAeD;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAOrD,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,SAAS,GAAG,SAAS,CAGzD;AAMD,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,aAAa,CAgB9D;AAED,+GAA+G;AAC/G,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,aAAa,GAAG,SAAS,CAK3B"}

package/dist/normalize.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IR_VERSIONS_READ_AS_IS = exports.isWidget = exports.IR_VERSION_LEGACY = void 0;
+exports.resolvePath = resolvePath;
+exports.asCell = asCell;
+exports.cell = cell;
+exports.blueprintIrVersion = blueprintIrVersion;
+exports.upgradeBlueprint = upgradeBlueprint;
+exports.isBindingStatus = isBindingStatus;
+exports.resolveWidgetStatus = resolveWidgetStatus;
+const irVersion_1 = require("./irVersion");
+exports.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.
+function resolvePath(state, path) {
+    // 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 = state;
+    for (const part of parts) {
+        if (current === null || current === undefined)
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+const isWidget = (n) => typeof n === "object" && n !== null && n._tag === "Widget";
+exports.isWidget = isWidget;
+const isCell = (n) => 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. */
+function asCell(child) {
+    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. */
+function cell(span, node, placement = {}) {
+    return {
+        span,
+        node,
+        ...(placement.row !== undefined && { row: placement.row }),
+        ...(placement.rowSpan !== undefined && { rowSpan: placement.rowSpan }),
+        ...(placement.column !== undefined && { column: placement.column }),
+    };
+}
+function blueprintIrVersion(bp) {
+    return bp.irVersion ?? exports.IR_VERSION_LEGACY;
+}
+function upgradeLayout(layout) {
+    if (layout.type === "grid") {
+        return {
+            ...layout,
+            children: layout.children.map((c) => {
+                const k = asCell(c);
+                return (0, exports.isWidget)(k.node) ? k : { ...k, node: upgradeLayout(k.node) };
+            }),
+        };
+    }
+    return { ...layout, children: layout.children.map((c) => ((0, exports.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.
+ */
+exports.IR_VERSIONS_READ_AS_IS = new Set([
+    "2.0.0",
+    "2.1.0",
+    "2.2.0",
+    "2.3.0",
+    "2.4.0",
+    irVersion_1.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.
+ */
+function upgradeBlueprint(bp) {
+    if (bp.irVersion !== undefined && exports.IR_VERSIONS_READ_AS_IS.has(bp.irVersion))
+        return bp;
+    return { ...bp, irVersion: irVersion_1.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"]);
+function isBindingStatus(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    const s = v;
+    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;
+        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. */
+function resolveWidgetStatus(widget, stateMap) {
+    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;
+}
+//# sourceMappingURL=normalize.js.map

package/dist/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../src/normalize.ts"],"names":[],"mappings":"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"}

package/dist/pins.d.ts

@@ -0,0 +1,27 @@
+import type { PinReport, VersionPins } from "@loomwork/core";
+import type { Blueprint } from "./types";
+/**
+ * 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 declare function blueprintPins(blueprint: Blueprint): VersionPins;
+/**
+ * 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 declare function checkBlueprintPins(blueprint: Blueprint, current: VersionPins): PinReport;
+//# sourceMappingURL=pins.d.ts.map

package/dist/pins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pins.d.ts","sourceRoot":"","sources":["../src/pins.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAoBzC;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG,WAAW,CAS/D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,GAAG,SAAS,CASxF"}

package/dist/pins.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.blueprintPins = blueprintPins;
+exports.checkBlueprintPins = checkBlueprintPins;
+const core_1 = require("@loomwork/core");
+// ── 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.
+ */
+function blueprintPins(blueprint) {
+    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.
+ */
+function checkBlueprintPins(blueprint, current) {
+    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 (0, core_1.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() {
+    return Object.create(null);
+}
+/** An OWN-property read, so an inherited member never answers for a recorded version. */
+function recordedVersion(pins, id) {
+    if (pins === undefined || !Object.hasOwn(pins, id))
+        return undefined;
+    return pins[id];
+}
+//# sourceMappingURL=pins.js.map

package/dist/pins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pins.js","sourceRoot":"","sources":["../src/pins.ts"],"names":[],"mappings":";;AA8BA,sCASC;AAgBD,gDASC;AAhED,yCAAkD;AAIlD,iFAAiF;AACjF,EAAE;AACF,4FAA4F;AAC5F,0FAA0F;AAC1F,0FAA0F;AAC1F,sFAAsF;AACtF,oBAAoB;AACpB,EAAE;AACF,6FAA6F;AAC7F,mFAAmF;AACnF,wFAAwF;AACxF,YAAY;AACZ,EAAE;AACF,4FAA4F;AAC5F,yFAAyF;AACzF,wFAAwF;AACxF,mDAAmD;AAEnD;;;;;;;GAOG;AACH,SAAgB,aAAa,CAAC,SAAoB;IAChD,MAAM,QAAQ,GAAG,SAAS,CAAC,kBAAkB,CAAC;IAC9C,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,SAAS,EAAE,CAAC;IAC/C,MAAM,IAAI,GAAG,SAAS,EAAE,CAAC;IACzB,KAAK,MAAM,YAAY,IAAI,SAAS,CAAC,WAAW,EAAE,CAAC;QACjD,MAAM,OAAO,GAAG,eAAe,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;QACxD,IAAI,OAAO,KAAK,SAAS;YAAE,IAAI,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC;IAC1D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,kBAAkB,CAAC,SAAoB,EAAE,OAAoB;IAC3E,MAAM,QAAQ,GAAG,SAAS,EAAE,CAAC;IAC7B,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,KAAK,MAAM,YAAY,IAAI,SAAS,CAAC,WAAW,EAAE,CAAC;QACjD,QAAQ,CAAC,YAAY,CAAC,GAAG,eAAe,CAAC,SAAS,CAAC,kBAAkB,EAAE,YAAY,CAAC,IAAI,EAAE,CAAC;QAC3F,MAAM,GAAG,GAAG,eAAe,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QACnD,IAAI,GAAG,KAAK,SAAS;YAAE,MAAM,CAAC,YAAY,CAAC,GAAG,GAAG,CAAC;IACpD,CAAC;IACD,OAAO,IAAA,uBAAgB,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,SAAS;IAChB,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAA2B,CAAC;AACvD,CAAC;AAED,yFAAyF;AACzF,SAAS,eAAe,CAAC,IAA6B,EAAE,EAAU;IAChE,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IACrE,OAAO,IAAI,CAAC,EAAE,CAAC,CAAC;AAClB,CAAC"}

package/dist/traverseBlueprint.d.ts

@@ -0,0 +1,27 @@
+import { resolvePath } from "./normalize";
+import type { Layout, Widget, WidgetAction, WidgetRendererProps } from "./types";
+export { resolvePath };
+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;
+    }>;
+}
+export declare function resolveWidgetValue(widget: Widget, stateMap: Map<string, unknown>): unknown;
+export interface BlueprintTraversalOptions<TNode> {
+    renderWidget: (ctx: WidgetRendererProps) => TNode;
+    renderContainer: (ctx: ContainerContext<TNode>) => TNode;
+    onAction?: (action: WidgetAction) => void;
+}
+export declare function traverseBlueprint<TNode>(node: Layout | Widget, stateMap: Map<string, unknown>, options: BlueprintTraversalOptions<TNode>): TNode;
+//# sourceMappingURL=traverseBlueprint.d.ts.map

package/dist/traverseBlueprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traverseBlueprint.d.ts","sourceRoot":"","sources":["../src/traverseBlueprint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,WAAW,EAAuB,MAAM,aAAa,CAAC;AACjF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAKjF,OAAO,EAAE,WAAW,EAAE,CAAC;AAIvB,MAAM,WAAW,gBAAgB,CAAC,KAAK;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,KAAK,EAAE,CAAC;IAClB;;;;OAIG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC,CAAC;CAChG;AAID,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAI1F;AA4BD,MAAM,WAAW,yBAAyB,CAAC,KAAK;IAC9C,YAAY,EAAE,CAAC,GAAG,EAAE,mBAAmB,KAAK,KAAK,CAAC;IAClD,eAAe,EAAE,CAAC,GAAG,EAAE,gBAAgB,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC;IACzD,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;CAC3C;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EACrC,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,yBAAyB,CAAC,KAAK,CAAC,GACxC,KAAK,CA4BP"}