@transitrix/diagrams 1.8.11 → 1.8.18

package/dist/repo-validate/types.js

@@ -7,7 +7,26 @@
 // runtime (methodology ADR "Validation Two-Axis Model"; Studio decision
 // "Validation Runtime Convergence").
 //
-// The finding shape is deliberately minimal — `{ scope, id, message }`. The
-// richer `target` / `category` reporting taxonomy is explicitly DEFERRED per the
-// ADR until a real consumer needs it; do not add it here.
+// The finding shape was originally frozen minimal — `{ scope, id, message }` —
+// with the richer `target` / `category` reporting taxonomy explicitly DEFERRED
+// per the ADR until a real consumer needed it. This un-freezes one field,
+// `ruleId`: DSM (migrating off its own Go `Validate*` functions) needs a
+// stable code per finding to map onto its existing import-log rule taxonomy
+// (`api02/internal/importer/{goals,activities,fgca}.go`). The richer
+// `target`/`category` taxonomy stays deferred — only `ruleId` is added.
+// `ruleId` is optional: only checks with a stable, documented code set it
+// (`docs/validation.md` § repo-scope rule list); the original structural
+// checks (syntax/uniqueness/atomicity/referential-integrity/policy) stay
+// uncoded rather than being retrofitted with invented codes.
+//
+// A second field, `severity`, is un-frozen for the same reason: DSM's
+// warn-severity strategy-chain rules (GOALS-009/011, ACT-005, FGCA-012..014
+// — see check-strategy-chain.ts) are non-fatal by
+// DSM's own taxonomy ("import anyway, record the warning"); without a
+// severity field, porting them here would silently make them blocking,
+// since every existing repo-scope finding is implicitly blocking. `severity`
+// is optional and defaults to `'error'` when omitted — every finding from
+// before this field existed (syntax/uniqueness/atomicity/referential-
+// integrity/policy, plus the error-tier strategy-chain rules and
+// TSVC-003/INT-002) stays blocking with no code change at the call site.
 export {};

package/dist/repo-validate/validate-repo.d.ts

@@ -1,8 +1,19 @@
-import type { RepoFinding, RepoModelInput } from './types.js';
+import type { RepoDoc, RepoFinding, RepoModelInput } from './types.js';
+export declare function isRecord(v: unknown): v is Record<string, unknown>;
+/** Read a string `id` from a parsed doc, or `null` if absent/non-string.
+ *  Mirrors lint.py, which only treats a doc as an element/relation when it has
+ *  a top-level `id` (sidecars such as versioned-attribute files have no `id`
+ *  and are ignored). Exported for reuse by `resolve-model.ts`, which needs the
+ *  same id/endpoint reading rules to stay in lockstep with this validator. */
+export declare function docId(doc: RepoDoc): string | null;
+/** Resolve a relation endpoint, which may be a bare id string or a `{ id }`
+ *  mapping (lint.py accepts both). Returns the id string or `null`. */
+export declare function endpointId(value: unknown): string | null;
 /**
  * Run all repo-scope checks over a loaded canon model and return the findings.
  * Pure: no IO, deterministic order (syntax, uniqueness, atomicity, referential,
- * semantics, policy). Reaches parity with `lint.py` on the `acme_corp` fixture
- * (zero findings on a clean tree).
+ * semantics, policy, strategy-chain). Reaches parity with `lint.py` on the
+ * `acme_corp` fixture (zero findings on a clean tree from the original
+ * lint.py-ported phases).
  */
 export declare function validateRepoModel(input: RepoModelInput): RepoFinding[];

package/dist/repo-validate/validate-repo.js

@@ -23,19 +23,23 @@
 //   6. Policy             (phase 6) — element marked Active/Production with no
 //                                     owner.
 //
-// Findings stay `{ scope, id, message }` — no severity, no target/category
-// taxonomy (deferred per the ADR).
+// Findings stay `{ scope, id, message }` plus the two un-frozen optional
+// fields `ruleId` and `severity` — the richer target/category taxonomy stays
+// deferred per the ADR.
+import { checkStrategyChainSemantics } from './check-strategy-chain.js';
+import { checkElementHygiene } from './check-element-hygiene.js';
 const PScope = 'repo';
 /** Statuses that, per lint.py's policy check, require an owner. */
 const OWNER_REQUIRED_STATUSES = new Set(['Active', 'Production']);
-function isRecord(v) {
+export function isRecord(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
 /** Read a string `id` from a parsed doc, or `null` if absent/non-string.
  *  Mirrors lint.py, which only treats a doc as an element/relation when it has
  *  a top-level `id` (sidecars such as versioned-attribute files have no `id`
- *  and are ignored). */
-function docId(doc) {
+ *  and are ignored). Exported for reuse by `resolve-model.ts`, which needs the
+ *  same id/endpoint reading rules to stay in lockstep with this validator. */
+export function docId(doc) {
     if (!doc.data)
         return null;
     const id = doc.data['id'];
@@ -43,7 +47,7 @@ function docId(doc) {
 }
 /** Resolve a relation endpoint, which may be a bare id string or a `{ id }`
  *  mapping (lint.py accepts both). Returns the id string or `null`. */
-function endpointId(value) {
+export function endpointId(value) {
     if (typeof value === 'string')
         return value.length > 0 ? value : null;
     if (isRecord(value)) {
@@ -329,6 +333,7 @@ function checkLayerSemantics(input, findings) {
             findings.push({
                 scope: PScope,
                 id: svcId,
+                ruleId: 'TSVC-003',
                 message: `TSVC-003: TECHNOLOGY_SERVICE '${svcId}' node '${nodeRef}' ` +
                     `must resolve to a NODE element; got notation='${resolved['notation']}'.`,
             });
@@ -353,6 +358,7 @@ function checkLayerSemantics(input, findings) {
                 findings.push({
                     scope: PScope,
                     id: intId,
+                    ruleId: 'INT-002',
                     message: `INT-002: INTEGRATION '${intId}' interface_semantics endpoint '${endpointId}' ` +
                         `(${field}) must resolve to an APPLICATION element; got notation='${resolved['notation']}'.`,
                 });
@@ -383,8 +389,9 @@ function checkPolicy(input, findings) {
 /**
  * Run all repo-scope checks over a loaded canon model and return the findings.
  * Pure: no IO, deterministic order (syntax, uniqueness, atomicity, referential,
- * semantics, policy). Reaches parity with `lint.py` on the `acme_corp` fixture
- * (zero findings on a clean tree).
+ * semantics, policy, strategy-chain). Reaches parity with `lint.py` on the
+ * `acme_corp` fixture (zero findings on a clean tree from the original
+ * lint.py-ported phases).
  */
 export function validateRepoModel(input) {
     const findings = [];
@@ -399,5 +406,11 @@ export function validateRepoModel(input) {
     checkReferentialIntegrity(input, findings);
     checkLayerSemantics(input, findings);
     checkPolicy(input, findings);
+    // Phase 7 — strategy-chain semantic rules ported from DSM's Go Validate*
+    // functions (GOALS-010, ACT-006..009, FGCA-008..011).
+    checkStrategyChainSemantics(input, findings);
+    // Phase 8 — standalone-element envelope rules ported from DSM's Go
+    // Validate*Element functions (GOAL-ELEM-001..003, ACTION-001/002/005).
+    checkElementHygiene(input, findings);
     return findings;
 }

package/dist/webview/render-blocks.d.ts

@@ -1,4 +1,4 @@
-import type { BlocksFile, BlocksLayout, BlocksLayoutOptions } from '../blocks/types.js';
+import type { BlocksFile, BlocksLayout, BlocksLayoutOptions, GridFile, GridLayout, GridLayoutOptions } from '../blocks/types.js';
 import { type NodeSizePreset } from '../node-size-presets.js';
 import { type ThemeId } from '../theme/index.js';
 export interface RenderBlocksOptions {
@@ -29,3 +29,25 @@ export declare function renderBlocksLayoutSvg(layout: BlocksLayout, options?: Re
  * with the shared theme CSS embedded so the output is self-contained.
  */
 export declare function renderBlocksSvg(doc: BlocksFile, options?: RenderBlocksOptions): string;
+/**
+ * Emit the grid body (headers, cells, grid lines) at the given origin offset.
+ * Shared by the host-neutral wrapper below; VS Code's blocks preview wraps
+ * this the same way it wraps {@link renderBlocksLayoutSvg} for the tree form.
+ */
+export declare function renderGridBody(layout: GridLayout, ox: number, oy: number): string;
+export interface RenderGridLayoutOptions {
+    /** Extra vertical space reserved at the top of the canvas (e.g. for a title block). */
+    topInset?: number;
+    /** Raw SVG injected immediately after the opening tag — a header line or a full title block. */
+    title?: string;
+    /** When set, the theme CSS is embedded as `<style>` so the SVG is self-contained. */
+    embedCssTheme?: ThemeId;
+}
+/** The single grid (matrix subset) SVG emitter shared by every host. */
+export declare function renderGridLayoutSvg(layout: GridLayout, options?: RenderGridLayoutOptions): string;
+export interface RenderGridOptions {
+    title?: string;
+    layoutOptions?: GridLayoutOptions;
+}
+/** Host-neutral grid (matrix subset) renderer (IntelliJ/UI). */
+export declare function renderGridSvg(doc: GridFile, options?: RenderGridOptions): string;

package/dist/webview/render-blocks.js

@@ -12,10 +12,10 @@
  * the shared theme CSS embedded in a `<style>` element and a simple optional
  * title `<text>`.
  */
-import { layoutNestedBlocks } from '../blocks/layout.js';
+import { layoutNestedBlocks, layoutGrid } from '../blocks/layout.js';
 import { parseNodeSizePreset, resolveBlocksLeafSize } from '../node-size-presets.js';
 import { generateSvgEmbedCss } from '../theme/index.js';
-import { emitCenteredTextSvg, layoutHeaderBlockText, layoutLeafBlockText, } from './entity-text-layout.js';
+import { CHAR_W_PRIMARY, emitCenteredTextSvg, layoutHeaderBlockText, layoutLeafBlockText, maxCharsForInnerWidth, wrapWords, } from './entity-text-layout.js';
 import { escXml } from './render-util.js';
 import { ENTITY_NODE_RX } from './notation-style.js';
 const PAD = 24;
@@ -105,3 +105,101 @@ export function renderBlocksSvg(doc, options = {}) {
         : '';
     return renderBlocksLayoutSvg(layout, { title: titleSvg, embedCssTheme: 'transitrix' });
 }
+/**
+ * Matrix subset (08-blocks.md §4a) — first cut: a single-layer rectangular
+ * `grid:` document (the RACI-style matrix case) rendered as a plain
+ * HTML/CSS-table-like SVG grid. Layers, arbitrary
+ * (non-rectangular) cell sets, and nested sub-grids belong to the general
+ * layered-grid superset, which is still in design upstream (methodology) and
+ * out of scope here — see 08-blocks.md §4a / §8.
+ */
+const GRID_CELL_PAD_X = 8;
+const GRID_LINE_HEIGHT = 15;
+const GRID_EMBED_CSS = `
+.blocks-grid-border { fill: none; stroke: var(--ts-border, #cbd5e1); }`;
+function centeredGridCellTextSvg(lines, cls, cx, cellTop, cellHeight) {
+    const ls = lines.length > 0 ? lines : [''];
+    const firstY = cellTop + cellHeight / 2 - ((ls.length - 1) / 2) * GRID_LINE_HEIGHT;
+    const tspans = ls
+        .map((ln, i) => `<tspan x="${cx}" y="${firstY + i * GRID_LINE_HEIGHT}">${escXml(ln)}</tspan>`)
+        .join('');
+    return `<text class="${cls}" text-anchor="middle" dominant-baseline="central">${tspans}</text>`;
+}
+/**
+ * Emit the grid body (headers, cells, grid lines) at the given origin offset.
+ * Shared by the host-neutral wrapper below; VS Code's blocks preview wraps
+ * this the same way it wraps {@link renderBlocksLayoutSvg} for the tree form.
+ */
+export function renderGridBody(layout, ox, oy) {
+    const tw = layout.bounds.width;
+    const th = layout.bounds.height;
+    const parts = [];
+    parts.push(`<rect class="diagram-node level-0" x="${ox}" y="${oy}" width="${tw}" height="${th}" stroke="none"/>`);
+    // Corner cell (above the row headers, left of the column headers).
+    parts.push(`<rect class="diagram-node level-1" x="${ox}" y="${oy}" width="${layout.rowHeaderWidth}" height="${layout.headerHeight}" stroke="none"/>`);
+    for (const col of layout.columns) {
+        const x = col.x + ox;
+        parts.push(`<rect class="diagram-node level-1" x="${x}" y="${oy}" width="${col.width}" height="${layout.headerHeight}" stroke="none"/>`);
+        const maxChars = maxCharsForInnerWidth(col.width - GRID_CELL_PAD_X * 2, CHAR_W_PRIMARY);
+        const lines = wrapWords(col.name, maxChars, 2);
+        parts.push(centeredGridCellTextSvg(lines, 'text-header', x + col.width / 2, oy, layout.headerHeight));
+    }
+    for (const row of layout.rows) {
+        const y = row.y + oy;
+        parts.push(`<rect class="diagram-node level-2" x="${ox}" y="${y}" width="${layout.rowHeaderWidth}" height="${row.height}" stroke="none"/>`);
+        const maxChars = maxCharsForInnerWidth(layout.rowHeaderWidth - GRID_CELL_PAD_X * 2, CHAR_W_PRIMARY);
+        const lines = wrapWords(row.name, maxChars, 2);
+        parts.push(centeredGridCellTextSvg(lines, 'text-primary', ox + layout.rowHeaderWidth / 2, y, row.height));
+    }
+    for (const cell of layout.cells) {
+        if (cell.value === undefined)
+            continue;
+        const cx = cell.x + ox + cell.width / 2;
+        const cy = cell.y + oy + cell.height / 2;
+        parts.push(`<text class="text-secondary" x="${cx}" y="${cy}" text-anchor="middle" dominant-baseline="central">${escXml(cell.value)}</text>`);
+    }
+    const gridX1 = ox;
+    const gridX2 = ox + tw;
+    const gridY1 = oy;
+    const gridY2 = oy + th;
+    const headerBottomY = oy + layout.headerHeight;
+    parts.push(`<line class="diagram-edge" x1="${gridX1}" y1="${headerBottomY}" x2="${gridX2}" y2="${headerBottomY}"/>`);
+    for (const row of layout.rows) {
+        const rowBottomY = oy + row.y + row.height;
+        parts.push(`<line class="diagram-edge" x1="${gridX1}" y1="${rowBottomY}" x2="${gridX2}" y2="${rowBottomY}"/>`);
+    }
+    const rowHeaderLineX = ox + layout.rowHeaderWidth;
+    parts.push(`<line class="diagram-edge" x1="${rowHeaderLineX}" y1="${gridY1}" x2="${rowHeaderLineX}" y2="${gridY2}"/>`);
+    for (const col of layout.columns) {
+        const colLineX = ox + col.x + col.width;
+        parts.push(`<line class="diagram-edge" x1="${colLineX}" y1="${gridY1}" x2="${colLineX}" y2="${gridY2}"/>`);
+    }
+    parts.push(`<rect class="blocks-grid-border" x="${ox}" y="${oy}" width="${tw}" height="${th}"/>`);
+    return parts.join('\n');
+}
+/** The single grid (matrix subset) SVG emitter shared by every host. */
+export function renderGridLayoutSvg(layout, options = {}) {
+    const { topInset = 0, title = '', embedCssTheme } = options;
+    const w = layout.bounds.width + PAD * 2;
+    const h = layout.bounds.height + PAD * 2 + topInset;
+    const ox = PAD;
+    const oy = PAD + topInset;
+    const body = renderGridBody(layout, ox, oy);
+    const styleLine = embedCssTheme ? `\n<style>${generateSvgEmbedCss(embedCssTheme)}${GRID_EMBED_CSS}</style>` : '';
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">${styleLine}
+${title}
+${body}
+</svg>`;
+}
+/** Host-neutral grid (matrix subset) renderer (IntelliJ/UI). */
+export function renderGridSvg(doc, options = {}) {
+    const { title = '', layoutOptions } = options;
+    const layout = layoutGrid(doc, layoutOptions);
+    if (layout.columns.length === 0 || layout.rows.length === 0) {
+        return `<svg xmlns="http://www.w3.org/2000/svg" width="0" height="0" viewBox="0 0 0 0"></svg>`;
+    }
+    const titleSvg = title
+        ? `<text class="text-header" x="${PAD}" y="${PAD - 6}">${escXml(`Nested Blocks — ${title}`)}</text>`
+        : '';
+    return renderGridLayoutSvg(layout, { title: titleSvg, embedCssTheme: 'transitrix' });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transitrix/diagrams",
-  "version": "1.8.11",
+  "version": "1.8.18",
   "type": "module",
   "description": "Shared rendering, validation, and pure mutations for Transitrix custom diagram formats.",
   "license": "MIT",

package/src/activities/validate.ts

@@ -19,7 +19,15 @@ export function validateActivities(input: unknown): ActivityValidationResult {
 
   const raw = input as Record<string, unknown>;
 
-  // ACT-001: notation must be "action"
+  // ACT-001: notation must be "action". ACT-020 is deliberately NOT ported
+  // here (DSM's api02/internal/importer/activities.go ValidateActivities
+  // still accepts the pre-2026-06-25 "activities" notation/root-key alias
+  // with a warning) — PR #320 ("drop deprecated notation aliases
+  // fgca/fga/activities/activity-card") already removed that leniency from
+  // this validator on purpose, with tests asserting it is "no longer
+  // accepted". Re-introducing it would reverse a deliberate, shipped
+  // decision, not fill a gap; flagged in the PR for a call rather than
+  // silently reversed either way.
   if (raw.notation === undefined) {
     errors.push({ code: 'ACT-001', message: 'notation field is required' });
     return { valid: false, errors, warnings };

package/src/blocks/index.ts

@@ -5,13 +5,27 @@ export type {
   BlocksLayoutOptions,
   LaidOutBlock,
   BlocksLayout,
+  GridColumn,
+  GridRow,
+  GridHeader,
+  GridFile,
+  GridLayoutOptions,
+  LaidOutGridColumn,
+  LaidOutGridRow,
+  LaidOutGridCell,
+  GridLayout,
 } from './types.js';
 
-export { validateNestedBlocks, isWellFormedBlock } from './validate.js';
+export { validateNestedBlocks, validateGrid, validateBlocks, isWellFormedBlock } from './validate.js';
 export type {
   ValidationError as BlocksValidationError,
   ValidationWarning as BlocksValidationWarning,
   ValidationResult as BlocksValidationResult,
+  GridRule,
+  ValidateGridOptions,
+  ValidateBlocksOptions,
 } from './validate.js';
 
-export { layoutNestedBlocks, iterateBlocks } from './layout.js';
+export { layoutNestedBlocks, layoutGrid, iterateBlocks } from './layout.js';
+
+export { GRID_TEMPLATE_RULES } from './templates/index.js';

package/src/blocks/layout.ts

@@ -3,7 +3,13 @@ import type {
   BlocksFile,
   BlocksLayout,
   BlocksLayoutOptions,
+  GridFile,
+  GridLayout,
+  GridLayoutOptions,
   LaidOutBlock,
+  LaidOutGridCell,
+  LaidOutGridColumn,
+  LaidOutGridRow,
 } from './types.js';
 import { ENTITY_NODE_SIZE } from '../node-size-presets.js';
 
@@ -16,6 +22,13 @@ const DEFAULTS: Required<BlocksLayoutOptions> = {
   topLevelGap: 24,
 };
 
+const GRID_DEFAULTS: Required<GridLayoutOptions> = {
+  columnWidth: 130,
+  rowHeight: 44,
+  rowHeaderWidth: 200,
+  headerHeight: 56,
+};
+
 interface MeasuredBlock {
   width: number;
   height: number;
@@ -185,3 +198,60 @@ export function* iterateBlocks(layout: BlocksLayout): Iterable<LaidOutBlock> {
   }
   for (const b of layout.blocks) yield* walk(b);
 }
+
+/**
+ * Matrix subset (08-blocks.md §4a): lay out a `grid:` root document as a
+ * single-layer rectangular table — a row-header column, a column-header row,
+ * and one cell per `(row, column)` pair. Assumes the document is already
+ * well-formed ({@link validateGrid}); callers validate first.
+ */
+export function layoutGrid(file: GridFile, options?: GridLayoutOptions): GridLayout {
+  const opts = { ...GRID_DEFAULTS, ...(options ?? {}) };
+  const grid = file?.grid;
+  const rawColumns = Array.isArray(grid?.columns) ? grid.columns : [];
+  const rawRows = Array.isArray(grid?.rows) ? grid.rows : [];
+
+  const columns: LaidOutGridColumn[] = rawColumns.map((c, i) => ({
+    id: c.id,
+    name: c.name,
+    x: opts.rowHeaderWidth + i * opts.columnWidth,
+    width: opts.columnWidth,
+  }));
+
+  const rows: LaidOutGridRow[] = rawRows.map((r, i) => ({
+    id: r.id,
+    name: r.name,
+    y: opts.headerHeight + i * opts.rowHeight,
+    height: opts.rowHeight,
+  }));
+
+  const cells: LaidOutGridCell[] = [];
+  for (let ri = 0; ri < rawRows.length; ri++) {
+    const row = rawRows[ri];
+    for (let ci = 0; ci < rawColumns.length; ci++) {
+      const col = rawColumns[ci];
+      const raw = row.assign?.[col.id];
+      cells.push({
+        rowId: row.id,
+        colId: col.id,
+        x: columns[ci].x,
+        y: rows[ri].y,
+        width: opts.columnWidth,
+        height: opts.rowHeight,
+        value: raw === undefined ? undefined : String(raw),
+      });
+    }
+  }
+
+  const width = opts.rowHeaderWidth + rawColumns.length * opts.columnWidth;
+  const height = opts.headerHeight + rawRows.length * opts.rowHeight;
+
+  return {
+    bounds: { x: 0, y: 0, width, height },
+    rowHeaderWidth: opts.rowHeaderWidth,
+    headerHeight: opts.headerHeight,
+    columns,
+    rows,
+    cells,
+  };
+}

package/src/blocks/templates/index.ts

@@ -0,0 +1,13 @@
+import type { GridRule } from '../validate.js';
+import { RACI_GRID_RULES } from './raci.js';
+
+/**
+ * Closed registry of built-in grid templates (§6a): each entry is a template
+ * name (as passed to `--template <name>`) mapped to its `GridRule`s. Adding a
+ * new template means adding one rule module + one entry here — the same
+ * shape as adding a new notation validator, not a plugin/config-loading
+ * mechanism (deliberately out of scope — see the design note on `RACI-001`).
+ */
+export const GRID_TEMPLATE_RULES: Record<string, GridRule[]> = {
+  raci: RACI_GRID_RULES,
+};

package/src/blocks/templates/raci.ts

@@ -0,0 +1,28 @@
+import type { GridRule } from '../validate.js';
+
+/**
+ * RACI-as-matrix template (methodology `templates/raci/`), built on the
+ * `blocks` matrix subset (08-blocks.md §4a). The base grid validator does not
+ * fix a cell-value vocabulary, so this invariant — exactly one Accountable
+ * owner per row — lives here, not in `validateGrid` (see §6a).
+ */
+export const raciExactlyOneAccountableRule: GridRule = {
+  ruleId: 'RACI-001',
+  severity: 'error',
+  check(grid) {
+    const findings: Array<{ message: string; path?: string }> = [];
+    grid.rows.forEach((row, i) => {
+      const accountableCount = Object.values(row.assign ?? {}).filter((v) => v === 'A').length;
+      if (accountableCount !== 1) {
+        findings.push({
+          message:
+            `Row "${row.name}" (${row.id}) must have exactly one column assigned "A" (Accountable); found ${accountableCount}`,
+          path: `grid.rows[${i}]`,
+        });
+      }
+    });
+    return findings;
+  },
+};
+
+export const RACI_GRID_RULES: GridRule[] = [raciExactlyOneAccountableRule];

package/src/blocks/types.ts

@@ -21,6 +21,73 @@ export interface BlocksFile {
   nested_blocks: NestedBlocksHeader;
 }
 
+export interface GridColumn {
+  id: string;
+  name: string;
+}
+
+export interface GridRow {
+  id: string;
+  name: string;
+  assign?: Record<string, unknown>;
+}
+
+export interface GridHeader {
+  columns: GridColumn[];
+  rows: GridRow[];
+}
+
+export interface GridFile {
+  notation: string;
+  spec_version?: string;
+  grid: GridHeader;
+}
+
+export interface GridLayoutOptions {
+  /** Width of each data column (px). */
+  columnWidth?: number;
+  /** Height of each data row (px). */
+  rowHeight?: number;
+  /** Width of the row-header column carrying each row's name (px). */
+  rowHeaderWidth?: number;
+  /** Height of the column-header row carrying each column's name (px). */
+  headerHeight?: number;
+}
+
+export interface LaidOutGridColumn {
+  id: string;
+  name: string;
+  x: number;
+  width: number;
+}
+
+export interface LaidOutGridRow {
+  id: string;
+  name: string;
+  y: number;
+  height: number;
+}
+
+export interface LaidOutGridCell {
+  rowId: string;
+  colId: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** The cell's `assign` value, stringified; omitted (blank) when unassigned. */
+  value?: string;
+}
+
+export interface GridLayout {
+  bounds: LayoutBounds;
+  rowHeaderWidth: number;
+  headerHeight: number;
+  columns: LaidOutGridColumn[];
+  rows: LaidOutGridRow[];
+  cells: LaidOutGridCell[];
+}
+
 export interface BlocksLayoutOptions {
   /** Width of a leaf block (a block with no children). */
   leafWidth?: number;