@transitrix/diagrams 1.0.0

package/dist/fgca/__tests__/parse-canonical.test.js

@@ -0,0 +1,224 @@
+import { describe, it, expect } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+import { parseCanonicalFGCA, parseCanonicalFGA } from '../parse-canonical.js';
+const VALID = {
+    notation: 'fgca',
+    spec_version: '0.1',
+    id: 'FGCA-SAMPLE-1',
+    name: 'Sample FGCA chain',
+    factors: [
+        { id: 'FACTOR-1', name: 'Driver one', type: 'external' },
+    ],
+    goals: [
+        { id: 'GOAL-1', name: 'Outcome one', factors: ['FACTOR-1'] },
+    ],
+    changes: [
+        { id: 'CHANGE-1', name: 'Transformation', goals: ['GOAL-1'] },
+    ],
+    activities: [
+        { id: 'ACTIVITY-1', name: 'Workstream', changes: ['CHANGE-1'] },
+    ],
+};
+describe('parseCanonicalFGCA', () => {
+    it('accepts a valid canonical document', () => {
+        const r = parseCanonicalFGCA(VALID);
+        expect(r.valid).toBe(true);
+        expect(r.errors).toEqual([]);
+        expect(r.parsed).toBeDefined();
+        expect(r.parsed?.factors).toHaveLength(1);
+        expect(r.parsed?.goals).toHaveLength(1);
+        expect(r.parsed?.changes).toHaveLength(1);
+        expect(r.parsed?.activities).toHaveLength(1);
+    });
+    it('FGCA-001: rejects non-object input', () => {
+        expect(parseCanonicalFGCA(null).errors[0].code).toBe('FGCA-001');
+        expect(parseCanonicalFGCA('string').errors[0].code).toBe('FGCA-001');
+    });
+    it('FGCA-001: rejects wrong notation', () => {
+        const r = parseCanonicalFGCA({ ...VALID, notation: 'fga' });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some((e) => e.code === 'FGCA-001')).toBe(true);
+    });
+    it('FGCA-002: rejects malformed doc id', () => {
+        const r = parseCanonicalFGCA({ ...VALID, id: 'fgca-lowercase-1' });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some((e) => e.code === 'FGCA-002')).toBe(true);
+    });
+    it('FGCA-003: rejects missing name', () => {
+        const { name: _, ...rest } = VALID;
+        const r = parseCanonicalFGCA(rest);
+        expect(r.valid).toBe(false);
+        expect(r.errors.some((e) => e.code === 'FGCA-003')).toBe(true);
+    });
+    it('FGCA-004: rejects missing factors array', () => {
+        const { factors: _, ...rest } = VALID;
+        const r = parseCanonicalFGCA(rest);
+        expect(r.valid).toBe(false);
+        expect(r.errors.some((e) => e.code === 'FGCA-004')).toBe(true);
+    });
+    it('FGCA-006: rejects duplicate IDs within a layer', () => {
+        const r = parseCanonicalFGCA({
+            ...VALID,
+            factors: [
+                { id: 'FACTOR-1', name: 'A' },
+                { id: 'FACTOR-1', name: 'B' },
+            ],
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some((e) => e.code === 'FGCA-006')).toBe(true);
+    });
+    it('FGCA-007: rejects malformed factor id', () => {
+        const r = parseCanonicalFGCA({
+            ...VALID,
+            factors: [{ id: 'F-1', name: 'A' }],
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some((e) => e.code === 'FGCA-007')).toBe(true);
+    });
+    it('FGCA-008: rejects goal.factors[] referencing undefined factor', () => {
+        const r = parseCanonicalFGCA({
+            ...VALID,
+            goals: [{ id: 'GOAL-1', name: 'A', factors: ['FACTOR-99'] }],
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some((e) => e.code === 'FGCA-008')).toBe(true);
+    });
+    it('FGCA-009: rejects change.goals[] referencing undefined goal', () => {
+        const r = parseCanonicalFGCA({
+            ...VALID,
+            changes: [{ id: 'CHANGE-1', name: 'A', goals: ['GOAL-99'] }],
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some((e) => e.code === 'FGCA-009')).toBe(true);
+    });
+    it('FGCA-010: rejects activity.changes[] referencing undefined change', () => {
+        const r = parseCanonicalFGCA({
+            ...VALID,
+            activities: [{ id: 'ACTIVITY-1', name: 'A', changes: ['CHANGE-99'] }],
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some((e) => e.code === 'FGCA-010')).toBe(true);
+    });
+    it('FGCA-015: rejects factor.references_constraint with malformed ID', () => {
+        const r = parseCanonicalFGCA({
+            ...VALID,
+            factors: [{ id: 'FACTOR-1', name: 'A', references_constraint: ['BAD-1'] }],
+        });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some((e) => e.code === 'FGCA-015')).toBe(true);
+    });
+    it('accepts factor.references_constraint with valid CONSTRAINT ID', () => {
+        const r = parseCanonicalFGCA({
+            ...VALID,
+            factors: [{ id: 'FACTOR-1', name: 'A', references_constraint: ['CONSTRAINT-GDPR-1'] }],
+        });
+        expect(r.valid).toBe(true);
+    });
+    it('populates internal change.activity_ids from canonical activity.changes (reversed direction)', () => {
+        const r = parseCanonicalFGCA({
+            ...VALID,
+            changes: [{ id: 'CHANGE-1', name: 'C', goals: ['GOAL-1'] }],
+            activities: [
+                { id: 'ACTIVITY-1', name: 'A1', changes: ['CHANGE-1'] },
+                { id: 'ACTIVITY-2', name: 'A2', changes: ['CHANGE-1'] },
+            ],
+        });
+        expect(r.valid).toBe(true);
+        expect(r.parsed?.changes[0].activity_ids).toHaveLength(2);
+    });
+});
+// The "FGCA preview blank / FGA no edges" regression (vkgeorgia/strategy#65,
+// transitrix/methodology#65) was a data defect: the canonical flat shape was
+// not being mapped to the internal cross-ref fields the renderer turns into
+// edges. These assert the edge-driving fields are populated, so the renderer
+// has something to draw — locking the fix.
+describe('parseCanonicalFGCA — edge-driving fields populated', () => {
+    it('maps goal.factors → goal.factor[], change.goals → change.goal_id, activity.changes → change.activity_ids', () => {
+        const r = parseCanonicalFGCA(VALID);
+        expect(r.valid).toBe(true);
+        const parsed = r.parsed;
+        // factor → goal edge source
+        expect(parsed.goals[0].factor).toHaveLength(1);
+        // goal → change edge
+        expect(parsed.changes[0].goal_id).not.toBe(0);
+        // change → activity edge
+        expect(parsed.changes[0].activity_ids).toHaveLength(1);
+    });
+});
+describe('parseCanonicalFGA', () => {
+    const VALID_FGA = {
+        notation: 'fga',
+        spec_version: '0.1',
+        id: 'FGA-SAMPLE-1',
+        name: 'Sample FGA chain',
+        factors: [{ id: 'FACTOR-1', name: 'Driver' }],
+        goals: [{ id: 'GOAL-1', name: 'Outcome', factors: ['FACTOR-1'] }],
+        activities: [{ id: 'ACTIVITY-1', name: 'Workstream', goals: ['GOAL-1'] }],
+    };
+    it('accepts a valid canonical FGA document (no changes layer)', () => {
+        const r = parseCanonicalFGA(VALID_FGA);
+        expect(r.valid).toBe(true);
+        expect(r.errors).toEqual([]);
+        expect(r.parsed?.factors).toHaveLength(1);
+        expect(r.parsed?.goals).toHaveLength(1);
+        expect(r.parsed?.activities).toHaveLength(1);
+    });
+    it('populates activity.goal_id from activity.goals[] (the FGA edge-driving field)', () => {
+        // The "FGA nodes render, no edges" bug: activities had no resolvable
+        // goal_id, so the renderer drew no goal → activity edges.
+        const r = parseCanonicalFGA(VALID_FGA);
+        expect(r.valid).toBe(true);
+        expect(r.parsed?.activities[0].goal_id).not.toBeNull();
+        expect(r.parsed?.activities[0].goal_id).not.toBe(0);
+    });
+    it('FGA-001: rejects wrong notation', () => {
+        const r = parseCanonicalFGA({ ...VALID_FGA, notation: 'fgca' });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some((e) => e.code === 'FGA-001')).toBe(true);
+    });
+    it('FGA-002: rejects malformed doc id', () => {
+        const r = parseCanonicalFGA({ ...VALID_FGA, id: 'fga-lower-1' });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some((e) => e.code === 'FGA-002')).toBe(true);
+    });
+    it('remaps FGCA layer codes into the FGA registry (e.g. FGA-007 for a bad id)', () => {
+        const r = parseCanonicalFGA({ ...VALID_FGA, factors: [{ id: 'F-1', name: 'bad' }] });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some((e) => e.code === 'FGA-007')).toBe(true);
+        // No raw FGCA-prefixed code should leak through the remap.
+        expect(r.errors.every((e) => !e.code.startsWith('FGCA-'))).toBe(true);
+    });
+});
+describe('parseCanonicalFGCA — example file regression', () => {
+    const EXAMPLES_DIR = path.resolve(process.cwd(), '..', '..', 'tests', 'fixtures', 'notation-corpus', 'fgca');
+    const files = fs.existsSync(EXAMPLES_DIR)
+        ? fs.readdirSync(EXAMPLES_DIR).filter((f) => f.endsWith('.transitrix.yaml'))
+        : [];
+    for (const file of files) {
+        it(`accepts tests/fixtures/notation-corpus/fgca/${file}`, () => {
+            const text = fs.readFileSync(path.join(EXAMPLES_DIR, file), 'utf8');
+            const parsedYaml = yaml.load(text);
+            const r = parseCanonicalFGCA(parsedYaml);
+            expect(r.errors).toEqual([]);
+            expect(r.valid).toBe(true);
+        });
+    }
+});
+describe('parseCanonicalFGA — example file regression', () => {
+    const EXAMPLES_DIR = path.resolve(process.cwd(), '..', '..', 'tests', 'fixtures', 'notation-corpus', 'fga');
+    const files = fs.existsSync(EXAMPLES_DIR)
+        ? fs.readdirSync(EXAMPLES_DIR).filter((f) => f.endsWith('.transitrix.yaml'))
+        : [];
+    for (const file of files) {
+        it(`accepts tests/fixtures/notation-corpus/fga/${file} and resolves every activity to a goal`, () => {
+            const text = fs.readFileSync(path.join(EXAMPLES_DIR, file), 'utf8');
+            const r = parseCanonicalFGA(yaml.load(text));
+            expect(r.errors).toEqual([]);
+            expect(r.valid).toBe(true);
+            // Every activity must carry a goal_id, or the FGA preview draws no edges.
+            expect(r.parsed.activities.every((a) => a.goal_id != null && a.goal_id !== 0)).toBe(true);
+        });
+    }
+});

package/dist/fgca/__tests__/preview-layout.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/fgca/__tests__/preview-layout.test.js

@@ -0,0 +1,106 @@
+import { describe, it, expect } from 'vitest';
+import { layoutFGCAPreview, FGCA_PAD, FGCA_NODE_W, } from '../preview-layout.js';
+const doc = {
+    factors: [
+        { id: 1, name: 'F1' },
+        { id: 2, name: 'F2' },
+    ],
+    goals: [
+        { id: 10, name: 'G1', factor: [{ id: 1 }] },
+        { id: 11, name: 'G2', factor: [{ id: 2 }] },
+    ],
+    changes: [{ id: 20, name: 'C1', goal_id: 10, activity_ids: [30] }],
+    activities: [
+        { id: 30, name: 'A1', goal_id: 10 },
+        { id: 31, name: 'A2', goal_id: 11 },
+    ],
+};
+describe('layoutFGCAPreview', () => {
+    it('lays out all four columns in order (FGCA)', () => {
+        const layout = layoutFGCAPreview(doc);
+        expect(layout.columns.map(c => c.col)).toEqual(['factor', 'goal', 'change', 'activity']);
+        // 2 factors + 2 goals + 1 change + 2 activities
+        expect(layout.nodes).toHaveLength(7);
+        expect(layout.width).toBeGreaterThan(0);
+        expect(layout.height).toBeGreaterThan(0);
+    });
+    it('produces the expected FGCA edge set', () => {
+        // F1→G1, F2→G2 (2), G1→C1 (1), C1→A1 (1), G2→A2 direct (1) = 5
+        const layout = layoutFGCAPreview(doc);
+        expect(layout.edges).toHaveLength(5);
+    });
+    it('hideChanges (FGA) drops the Changes column and links goals to activities', () => {
+        const layout = layoutFGCAPreview(doc, { hideChanges: true });
+        expect(layout.columns.map(c => c.col)).toEqual(['factor', 'goal', 'activity']);
+        // 2 factors + 2 goals + 2 activities
+        expect(layout.nodes).toHaveLength(6);
+        // F1→G1, F2→G2 (2), G1→A1, G2→A2 (2) = 4
+        expect(layout.edges).toHaveLength(4);
+    });
+    it('first column sits at the pad origin', () => {
+        const layout = layoutFGCAPreview(doc);
+        expect(layout.columns[0].x).toBe(FGCA_PAD);
+    });
+    it('empty options reproduce the default layout', () => {
+        const a = layoutFGCAPreview(doc);
+        const b = layoutFGCAPreview(doc, {});
+        expect(b.nodes.map(n => `${n.id}:${n.x},${n.y}`)).toEqual(a.nodes.map(n => `${n.id}:${n.x},${n.y}`));
+    });
+    it('larger colGap widens the column step', () => {
+        const stepOf = (colGap) => {
+            const cols = layoutFGCAPreview(doc, { colGap }).columns;
+            return cols[1].x - cols[0].x;
+        };
+        expect(stepOf(80)).toBe(FGCA_NODE_W + 80);
+        expect(stepOf(240)).toBe(FGCA_NODE_W + 240);
+        expect(stepOf(240)).toBeGreaterThan(stepOf(80));
+    });
+    it('larger rowGap increases the gap between stacked nodes', () => {
+        const gapOf = (rowGap) => {
+            const factors = layoutFGCAPreview(doc, { rowGap }).nodes.filter(n => n.col === 'factor');
+            return factors[1].y - factors[0].y;
+        };
+        expect(gapOf(120)).toBeGreaterThan(gapOf(20));
+    });
+    // vkgeorgia/strategy#77 — scope filtering. FGCA goals are flat, so 'root'
+    // selects the single matching goal plus the factors/changes/activities that
+    // touch it.
+    describe('scope', () => {
+        const idsOf = (layout) => new Set(layout.nodes.map(n => n.id));
+        it("mode 'root' keeps only the root goal and what connects to it", () => {
+            // root 10 → factor 1 (referenced by G10), change 20 (goal_id 10),
+            // activity 30 (via change 20). G11/F2/A31 are dropped.
+            const layout = layoutFGCAPreview(doc, { scope: { mode: 'root', rootGoalId: '10' } });
+            expect(idsOf(layout)).toEqual(new Set(['factor_1', 'goal_10', 'change_20', 'activity_30']));
+        });
+        it("mode 'root' filters factors and activities to those touching the visible goal", () => {
+            // root 11 → factor 2, activity 31 (direct goal link); no change touches G11.
+            const layout = layoutFGCAPreview(doc, { scope: { mode: 'root', rootGoalId: '11' } });
+            expect(idsOf(layout)).toEqual(new Set(['factor_2', 'goal_11', 'activity_31']));
+            // F1, A30, C20 (which only touch the hidden G10) are excluded.
+            expect(layout.nodes.some(n => n.id === 'factor_1')).toBe(false);
+            expect(layout.nodes.some(n => n.id === 'activity_30')).toBe(false);
+        });
+        it("mode 'level' trims goals above the cap and their connections", () => {
+            const leveled = {
+                factors: [{ id: 1, name: 'F1' }, { id: 2, name: 'F2' }],
+                goals: [
+                    { id: 10, name: 'G1', level: 0, factor: [{ id: 1 }] },
+                    { id: 11, name: 'G2', level: 1, factor: [{ id: 2 }] },
+                ],
+                changes: [],
+                activities: [
+                    { id: 30, name: 'A1', goal_id: 10 },
+                    { id: 31, name: 'A2', goal_id: 11 },
+                ],
+            };
+            const layout = layoutFGCAPreview(leveled, { scope: { mode: 'level', maxLevel: 0 } });
+            expect(idsOf(layout)).toEqual(new Set(['factor_1', 'goal_10', 'activity_30']));
+        });
+        it("mode 'root' returns an empty layout when the root is absent", () => {
+            const layout = layoutFGCAPreview(doc, { scope: { mode: 'root', rootGoalId: '999' } });
+            expect(layout.nodes).toHaveLength(0);
+            expect(layout.edges).toHaveLength(0);
+        });
+    });
+});

package/dist/fgca/__tests__/validate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/fgca/__tests__/validate.test.js

@@ -0,0 +1,125 @@
+import { describe, it, expect } from 'vitest';
+import { validateFGCADoc } from '../validate.js';
+const VALID_DOC = {
+    notation: 'fgca',
+    factors: [{ id: 1, name: 'Market pressure' }],
+    goals: [{ id: 1, name: 'Grow revenue', factor: [{ id: 1 }] }],
+    changes: [{ id: 1, name: 'Launch product', goal_id: 1, activity_ids: [1] }],
+    activities: [{ id: 1, name: 'Market research', goal_id: 1 }],
+};
+describe('validateFGCADoc', () => {
+    it('accepts a valid document', () => {
+        const result = validateFGCADoc(VALID_DOC);
+        expect(result.valid).toBe(true);
+        expect(result.errors).toHaveLength(0);
+    });
+    it('rejects non-object input', () => {
+        expect(validateFGCADoc('string').valid).toBe(false);
+        expect(validateFGCADoc(null).valid).toBe(false);
+        expect(validateFGCADoc(42).valid).toBe(false);
+    });
+    it('errors on missing notation field', () => {
+        const { notation: _, ...without } = VALID_DOC;
+        const result = validateFGCADoc(without);
+        expect(result.valid).toBe(false);
+        expect(result.errors[0].code).toBe('MISSING_NOTATION');
+    });
+    it('errors on wrong notation value', () => {
+        const result = validateFGCADoc({ ...VALID_DOC, notation: 'goals' });
+        expect(result.valid).toBe(false);
+        expect(result.errors[0].code).toBe('WRONG_NOTATION');
+    });
+    it('errors when factors array is missing', () => {
+        const { factors: _, ...without } = VALID_DOC;
+        const result = validateFGCADoc({ ...without, notation: 'fgca' });
+        expect(result.valid).toBe(false);
+        expect(result.errors.some(e => e.path === 'factors')).toBe(true);
+    });
+    it('errors when goals array is missing', () => {
+        const { goals: _, ...without } = VALID_DOC;
+        const result = validateFGCADoc({ ...without, notation: 'fgca' });
+        expect(result.valid).toBe(false);
+        expect(result.errors.some(e => e.path === 'goals')).toBe(true);
+    });
+    it('errors when changes array is missing', () => {
+        const { changes: _, ...without } = VALID_DOC;
+        const result = validateFGCADoc({ ...without, notation: 'fgca' });
+        expect(result.valid).toBe(false);
+        expect(result.errors.some(e => e.path === 'changes')).toBe(true);
+    });
+    it('errors when activities array is missing', () => {
+        const { activities: _, ...without } = VALID_DOC;
+        const result = validateFGCADoc({ ...without, notation: 'fgca' });
+        expect(result.valid).toBe(false);
+        expect(result.errors.some(e => e.path === 'activities')).toBe(true);
+    });
+    it('errors on empty factor name', () => {
+        const result = validateFGCADoc({ ...VALID_DOC, factors: [{ id: 1, name: '' }] });
+        expect(result.valid).toBe(false);
+        expect(result.errors.some(e => e.code === 'EMPTY_NAME')).toBe(true);
+    });
+    it('errors on empty goal name', () => {
+        const result = validateFGCADoc({ ...VALID_DOC, goals: [{ id: 1, name: '  ', factor: [] }] });
+        expect(result.valid).toBe(false);
+        expect(result.errors.some(e => e.code === 'EMPTY_NAME')).toBe(true);
+    });
+    it('warns on broken factor reference in goal', () => {
+        const result = validateFGCADoc({
+            ...VALID_DOC,
+            goals: [{ id: 1, name: 'Goal', factor: [{ id: 99 }] }],
+        });
+        expect(result.valid).toBe(true);
+        expect(result.warnings.some(w => w.code === 'BROKEN_REF' && w.message.includes('factor 99'))).toBe(true);
+    });
+    it('warns on broken goal reference in change', () => {
+        const result = validateFGCADoc({
+            ...VALID_DOC,
+            changes: [{ id: 1, name: 'Change', goal_id: 99, activity_ids: [] }],
+        });
+        expect(result.valid).toBe(true);
+        expect(result.warnings.some(w => w.code === 'BROKEN_REF' && w.message.includes('goal 99'))).toBe(true);
+    });
+    it('warns on broken activity reference in change', () => {
+        const result = validateFGCADoc({
+            ...VALID_DOC,
+            changes: [{ id: 1, name: 'Change', goal_id: 1, activity_ids: [99] }],
+        });
+        expect(result.valid).toBe(true);
+        expect(result.warnings.some(w => w.code === 'BROKEN_REF' && w.message.includes('activity 99'))).toBe(true);
+    });
+    it('accepts a document with empty arrays', () => {
+        const result = validateFGCADoc({
+            notation: 'fgca',
+            factors: [],
+            goals: [],
+            changes: [],
+            activities: [],
+        });
+        expect(result.valid).toBe(true);
+    });
+    it('accepts optional spec_version field', () => {
+        const result = validateFGCADoc({ ...VALID_DOC, spec_version: '0.1' });
+        expect(result.valid).toBe(true);
+    });
+    // Pre-release blocker regression (orchestrator review 2026-05-21).
+    it('[blocker] tolerates a null element in goals[] without throwing', () => {
+        const r = validateFGCADoc({ ...VALID_DOC, goals: [null] });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'SCHEMA_INVALID')).toBe(true);
+    });
+    it('[blocker] tolerates a string element in factors[] without throwing', () => {
+        const r = validateFGCADoc({ ...VALID_DOC, factors: ['x'] });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'SCHEMA_INVALID')).toBe(true);
+    });
+    it('[blocker] tolerates a null element in changes[] without throwing', () => {
+        const r = validateFGCADoc({ ...VALID_DOC, changes: [null] });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'SCHEMA_INVALID')).toBe(true);
+    });
+    it('[blocker] tolerates a null element in activities[] without throwing', () => {
+        const r = validateFGCADoc({ ...VALID_DOC, activities: [null] });
+        expect(r.valid).toBe(false);
+        expect(r.errors.some(e => e.code === 'SCHEMA_INVALID')).toBe(true);
+    });
+});

package/dist/fgca/chain-table.d.ts

@@ -0,0 +1,36 @@
+import type { FGCAPreviewDoc } from './preview-layout.js';
+export type ChainColumn = 'factor' | 'goal' | 'change' | 'activity';
+export interface ChainCell {
+    /** Column-qualified identity (e.g. "goal:3") — stable, unique across columns. */
+    key: string;
+    /** Display text — the element name, falling back to its id. */
+    label: string;
+}
+export interface ChainTableCell {
+    /** The element to render, or null for a gap in the chain (empty cell). */
+    cell: ChainCell | null;
+    /** Vertical span — how many rows this cell covers. */
+    rowSpan: number;
+}
+export interface ChainTable {
+    /** Columns left→right: FGA omits 'change'. */
+    columns: ChainColumn[];
+    /**
+     * Grid of rendered cells. `rows[r][c]` is the cell to emit at (r, c), or null
+     * when that position is covered by a `rowSpan` from a row above (emit no
+     * `<td>`). Each row corresponds to one path through the chain.
+     */
+    rows: Array<Array<ChainTableCell | null>>;
+}
+export interface ChainTableOptions {
+    /** FGA hides the Change column (Goal links straight to Activity). */
+    hideChanges?: boolean;
+}
+/**
+ * Flattens an FGCA/FGA doc into a chain table with rowspan-merged parent cells.
+ *
+ * Rows are enumerated in document order (deterministic). A parent that links to
+ * several children spans those children's rows; an element with no downstream
+ * link still appears, with empty cells to its right.
+ */
+export declare function buildChainTable(doc: FGCAPreviewDoc, options?: ChainTableOptions): ChainTable;

package/dist/fgca/chain-table.js

@@ -0,0 +1,177 @@
+// Chain-table model for the FGCA / FGA previews (vkgeorgia/strategy#137).
+//
+// The tree/chain preview (`layoutFGCAPreview`) shows Factor → Goal → Change →
+// Activity as columns of nodes joined by edges. This module produces the
+// *tabular* alternative: the same chain flattened into rows, with shared
+// parents collapsed into vertically-merged (rowspan) cells.
+//
+// It is the pure, unit-testable half of the feature — no DOM, no vscode. The
+// Studio preview renders the returned model as an HTML `<table>`.
+//
+// Link semantics mirror `layoutFGCAPreview` exactly (the authoritative source):
+//   - F → G via `goal.factor[]`
+//   - G → C via `change.goal_id`            (FGCA only)
+//   - C → A via `change.activity_ids[]`     (FGCA only)
+//   - G → A directly via `activity.goal_id` for activities not covered by any
+//     change (FGCA) / for every activity (FGA, no Change column)
+//
+// Broken references are validation *warnings*, not errors, so a rendered doc
+// can contain a goal with a missing factor, a change with a missing goal, or an
+// unlinked activity. Every element still appears in the table — rooted where it
+// links, or as a trailing orphan row with empty cells to its left — so the
+// table mirrors the document the same way the tree does.
+function cellOf(col, id, name) {
+    const label = name && name.trim() ? name : String(id);
+    return { key: `${col}:${id}`, label };
+}
+/** Identity comparison for the rowspan grouping; both-null counts as equal. */
+function sameCell(a, b) {
+    if (a === null || b === null)
+        return a === b;
+    return a.key === b.key;
+}
+/**
+ * Flattens an FGCA/FGA doc into a chain table with rowspan-merged parent cells.
+ *
+ * Rows are enumerated in document order (deterministic). A parent that links to
+ * several children spans those children's rows; an element with no downstream
+ * link still appears, with empty cells to its right.
+ */
+export function buildChainTable(doc, options = {}) {
+    const { hideChanges = false } = options;
+    const columns = hideChanges
+        ? ['factor', 'goal', 'activity']
+        : ['factor', 'goal', 'change', 'activity'];
+    const changes = doc.changes ?? [];
+    const factorIds = new Set(doc.factors.map(f => f.id));
+    const activityById = new Map(doc.activities.map(a => [a.id, a]));
+    // An activity is "covered" by a change when any change lists it — those render
+    // under their change, not directly under the goal (mirrors the tree).
+    const coveredActivityIds = new Set(changes.flatMap(c => c.activity_ids));
+    const emittedGoals = new Set();
+    const emittedChanges = new Set();
+    const emittedActivities = new Set();
+    // Each path is an array (length = columns.length) of ChainCell | null.
+    const paths = [];
+    const pad = (cells) => {
+        // Defensive: ensure every path matches the column count.
+        while (cells.length < columns.length)
+            cells.push(null);
+        return cells;
+    };
+    const emitGoal = (factorCell, goal) => {
+        emittedGoals.add(goal.id);
+        const goalCell = cellOf('goal', goal.id, goal.name);
+        if (hideChanges) {
+            const acts = doc.activities.filter(a => a.goal_id != null && a.goal_id === goal.id);
+            if (acts.length === 0) {
+                paths.push(pad([factorCell, goalCell]));
+                return;
+            }
+            for (const a of acts) {
+                emittedActivities.add(a.id);
+                paths.push([factorCell, goalCell, cellOf('activity', a.id, a.name)]);
+            }
+            return;
+        }
+        const goalChanges = changes.filter(c => c.goal_id === goal.id);
+        const directActs = doc.activities.filter(a => a.goal_id != null && a.goal_id === goal.id && !coveredActivityIds.has(a.id));
+        if (goalChanges.length === 0 && directActs.length === 0) {
+            paths.push([factorCell, goalCell, null, null]);
+            return;
+        }
+        for (const c of goalChanges) {
+            emittedChanges.add(c.id);
+            const changeCell = cellOf('change', c.id, c.name);
+            const acts = c.activity_ids.map(id => activityById.get(id)).filter((a) => a != null);
+            if (acts.length === 0) {
+                paths.push([factorCell, goalCell, changeCell, null]);
+                continue;
+            }
+            for (const a of acts) {
+                emittedActivities.add(a.id);
+                paths.push([factorCell, goalCell, changeCell, cellOf('activity', a.id, a.name)]);
+            }
+        }
+        // Change-less paths: activities bound straight to the goal (gap in Change).
+        for (const a of directActs) {
+            emittedActivities.add(a.id);
+            paths.push([factorCell, goalCell, null, cellOf('activity', a.id, a.name)]);
+        }
+    };
+    // Phase 1 — factor-rooted paths.
+    for (const f of doc.factors) {
+        const factorCell = cellOf('factor', f.id, f.name);
+        const goalsOfFactor = doc.goals.filter(g => (g.factor ?? []).some(ref => ref.id === f.id));
+        if (goalsOfFactor.length === 0) {
+            paths.push(pad([factorCell]));
+            continue;
+        }
+        for (const g of goalsOfFactor)
+            emitGoal(factorCell, g);
+    }
+    // Phase 2 — goals with no existing factor (orphan or broken-ref): empty Factor.
+    for (const g of doc.goals) {
+        if (emittedGoals.has(g.id))
+            continue;
+        const hasExistingFactor = (g.factor ?? []).some(ref => factorIds.has(ref.id));
+        if (hasExistingFactor)
+            continue; // emitted under its factor in phase 1
+        emitGoal(null, g);
+    }
+    // Phase 3 — changes whose goal is missing (FGCA only): empty Factor + Goal.
+    if (!hideChanges) {
+        for (const c of changes) {
+            if (emittedChanges.has(c.id))
+                continue;
+            emittedChanges.add(c.id);
+            const changeCell = cellOf('change', c.id, c.name);
+            const acts = c.activity_ids.map(id => activityById.get(id)).filter((a) => a != null);
+            if (acts.length === 0) {
+                paths.push([null, null, changeCell, null]);
+                continue;
+            }
+            for (const a of acts) {
+                emittedActivities.add(a.id);
+                paths.push([null, null, changeCell, cellOf('activity', a.id, a.name)]);
+            }
+        }
+    }
+    // Phase 4 — activities linked to nothing: empty cells to their left.
+    for (const a of doc.activities) {
+        if (emittedActivities.has(a.id))
+            continue;
+        const row = columns.map(() => null);
+        row[columns.length - 1] = cellOf('activity', a.id, a.name);
+        paths.push(row);
+    }
+    return { columns, rows: computeRowSpans(paths, columns.length) };
+}
+/**
+ * Turns a flat list of equal-length paths into a render grid. For each column,
+ * a cell spans the run of consecutive rows that share identical values in every
+ * column from 0 through that column (so a child only merges within one parent).
+ */
+function computeRowSpans(paths, colCount) {
+    const n = paths.length;
+    const grid = paths.map(() => new Array(colCount).fill(null));
+    for (let c = 0; c < colCount; c++) {
+        let r = 0;
+        while (r < n) {
+            let end = r + 1;
+            while (end < n && prefixEqual(paths[end], paths[r], c))
+                end++;
+            grid[r][c] = { cell: paths[r][c], rowSpan: end - r };
+            r = end;
+        }
+    }
+    return grid;
+}
+/** True when two paths agree on every column 0..c (inclusive). */
+function prefixEqual(a, b, c) {
+    for (let i = 0; i <= c; i++) {
+        if (!sameCell(a[i], b[i]))
+            return false;
+    }
+    return true;
+}