@transitrix/diagrams 1.0.0 → 1.1.0

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

@@ -0,0 +1,185 @@
+import { describe, it, expect } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+import { resolveFGCA, isFGCAViewDoc } from '../resolver.js';
+import { parseCanonicalFGCA } from '../parse-canonical.js';
+// ── Inline canon element store (mirrors strategy-2026 data split into per-element form) ─
+const ELEMENTS = [
+    { notation: 'driver', id: 'FACTOR-1', name: 'Competitive market pressure', type: 'external' },
+    { notation: 'driver', id: 'FACTOR-2', name: 'Digital adoption acceleration', type: 'external' },
+    { notation: 'goal', id: 'GOAL-1', name: 'Grow revenue by 20%', factors: ['FACTOR-1', 'FACTOR-2'] },
+    { notation: 'goal', id: 'GOAL-2', name: 'Reduce operational costs', factors: ['FACTOR-2'] },
+    { notation: 'goal', id: 'GOAL-3', name: 'Improve customer retention', factors: ['FACTOR-1'] },
+    { notation: 'change', id: 'CHANGE-1', name: 'Launch new product line', goals: ['GOAL-1'] },
+    { notation: 'change', id: 'CHANGE-2', name: 'Automate manual processes', goals: ['GOAL-2'] },
+    { notation: 'change', id: 'CHANGE-3', name: 'Enhance support platform', goals: ['GOAL-3'] },
+    { notation: 'activity', id: 'ACTIVITY-1', name: 'Market research', changes: ['CHANGE-1'] },
+    { notation: 'activity', id: 'ACTIVITY-2', name: 'MVP development', changes: ['CHANGE-1'] },
+    { notation: 'activity', id: 'ACTIVITY-3', name: 'Process audit', changes: ['CHANGE-2'] },
+    { notation: 'activity', id: 'ACTIVITY-4', name: 'RPA tooling rollout', changes: ['CHANGE-2'] },
+    { notation: 'activity', id: 'ACTIVITY-5', name: 'CRM implementation', changes: ['CHANGE-3'] },
+];
+const SOURCES = { elements: ELEMENTS, relations: [] };
+const VIEW_DOC = {
+    notation: 'fgca',
+    id: 'FGCA-STRAT-1',
+    name: 'Strategy 2026 — FGCA chain',
+    spec_version: '0.1',
+    view_config: {
+        goals: { filter: 'all' },
+        factors: { surface: 'derived' },
+        changes: { surface: 'derived' },
+        activities: { surface: 'derived' },
+    },
+};
+// ── isFGCAViewDoc ─────────────────────────────────────────────────────────────
+describe('isFGCAViewDoc', () => {
+    it('returns true for a view_config-based doc', () => {
+        expect(isFGCAViewDoc(VIEW_DOC)).toBe(true);
+    });
+    it('returns false for an inline doc with factors/goals arrays', () => {
+        expect(isFGCAViewDoc({
+            notation: 'fgca', id: 'FGCA-1', name: 'x',
+            factors: [], goals: [], changes: [], activities: [],
+        })).toBe(false);
+    });
+    it('returns false for non-objects', () => {
+        expect(isFGCAViewDoc(null)).toBe(false);
+        expect(isFGCAViewDoc('string')).toBe(false);
+        expect(isFGCAViewDoc(42)).toBe(false);
+    });
+});
+// ── resolveFGCA — goals.filter=all (default) ──────────────────────────────────
+describe('resolveFGCA — goals.filter=all', () => {
+    it('includes all goals, changes, and activities', () => {
+        const doc = resolveFGCA(VIEW_DOC, SOURCES);
+        expect(doc['goals'].length).toBe(3);
+        expect(doc['changes'].length).toBe(3);
+        expect(doc['activities'].length).toBe(5);
+    });
+    it('derives factors from all goal.factors[] refs', () => {
+        const doc = resolveFGCA(VIEW_DOC, SOURCES);
+        const factorIds = doc['factors'].map((f) => f.id);
+        expect(factorIds).toContain('FACTOR-1');
+        expect(factorIds).toContain('FACTOR-2');
+        expect(factorIds.length).toBe(2);
+    });
+    it('passes parseCanonicalFGCA and produces a fully valid internal doc', () => {
+        const doc = resolveFGCA(VIEW_DOC, SOURCES);
+        const r = parseCanonicalFGCA(doc);
+        expect(r.valid).toBe(true);
+        expect(r.errors).toEqual([]);
+        expect(r.parsed?.goals).toHaveLength(3);
+        expect(r.parsed?.factors).toHaveLength(2);
+        expect(r.parsed?.changes).toHaveLength(3);
+        expect(r.parsed?.activities).toHaveLength(5);
+    });
+    it('carries view doc metadata (id, name, spec_version)', () => {
+        const doc = resolveFGCA(VIEW_DOC, SOURCES);
+        expect(doc['notation']).toBe('fgca');
+        expect(doc['id']).toBe('FGCA-STRAT-1');
+        expect(doc['name']).toBe('Strategy 2026 — FGCA chain');
+        expect(doc['spec_version']).toBe('0.1');
+    });
+});
+// ── resolveFGCA — goals.filter=ids ────────────────────────────────────────────
+describe('resolveFGCA — goals.filter=ids', () => {
+    it('narrows to the specified goal and its derived changes + activities', () => {
+        const viewDoc = {
+            ...VIEW_DOC,
+            view_config: { goals: { filter: 'ids', ids: ['GOAL-1'] }, factors: { surface: 'derived' }, changes: { surface: 'derived' }, activities: { surface: 'derived' } },
+        };
+        const doc = resolveFGCA(viewDoc, SOURCES);
+        const goalIds = doc['goals'].map((g) => g.id);
+        expect(goalIds).toEqual(['GOAL-1']);
+        const changeIds = doc['changes'].map((c) => c.id);
+        expect(changeIds).toEqual(['CHANGE-1']);
+        const actIds = doc['activities'].map((a) => a.id).sort();
+        expect(actIds).toEqual(['ACTIVITY-1', 'ACTIVITY-2']);
+        const r = parseCanonicalFGCA(doc);
+        expect(r.valid).toBe(true);
+    });
+    it('returns empty arrays when none of the requested ids exist in canon', () => {
+        const viewDoc = {
+            ...VIEW_DOC,
+            view_config: { goals: { filter: 'ids', ids: ['GOAL-NONEXISTENT-1'] }, factors: { surface: 'derived' }, changes: { surface: 'derived' }, activities: { surface: 'derived' } },
+        };
+        const doc = resolveFGCA(viewDoc, SOURCES);
+        expect(doc['goals'].length).toBe(0);
+        expect(doc['changes'].length).toBe(0);
+        expect(doc['factors'].length).toBe(0);
+    });
+});
+// ── resolveFGCA — surface=all ─────────────────────────────────────────────────
+describe('resolveFGCA — surface=all', () => {
+    it('factors.surface=all includes every factor even when only some are referenced', () => {
+        const viewDoc = {
+            ...VIEW_DOC,
+            view_config: { goals: { filter: 'ids', ids: ['GOAL-3'] }, factors: { surface: 'all' }, changes: { surface: 'derived' }, activities: { surface: 'derived' } },
+        };
+        const doc = resolveFGCA(viewDoc, SOURCES);
+        // GOAL-3 only references FACTOR-1, but surface=all → both factors
+        expect(doc['factors'].length).toBe(2);
+    });
+    it('changes.surface=all includes every change', () => {
+        const viewDoc = {
+            ...VIEW_DOC,
+            view_config: { goals: { filter: 'ids', ids: ['GOAL-1'] }, factors: { surface: 'derived' }, changes: { surface: 'all' }, activities: { surface: 'derived' } },
+        };
+        const doc = resolveFGCA(viewDoc, SOURCES);
+        expect(doc['changes'].length).toBe(3);
+    });
+});
+// ── resolveFGCA — empty / degenerate inputs ───────────────────────────────────
+describe('resolveFGCA — empty sources', () => {
+    it('returns empty arrays when canon has no elements', () => {
+        const doc = resolveFGCA(VIEW_DOC, { elements: [], relations: [] });
+        expect(doc['goals'].length).toBe(0);
+        expect(doc['factors'].length).toBe(0);
+        expect(doc['changes'].length).toBe(0);
+        expect(doc['activities'].length).toBe(0);
+    });
+    it('returns empty arrays for a non-object viewDoc', () => {
+        const doc = resolveFGCA(null, SOURCES);
+        expect(doc['goals'].length).toBe(0);
+    });
+});
+// ── File-based regression — resolver + canon fixture + parseCanonicalFGCA ─────
+describe('resolveFGCA — file-based regression against canon fixture', () => {
+    const CANON_ROOT = path.resolve(process.cwd(), '..', '..', 'tests', 'fixtures', 'notation-corpus', 'fgca', 'canon');
+    const VIEW_DIR = path.join(CANON_ROOT, 'views');
+    const ELEM_DIR = path.join(CANON_ROOT, 'elements');
+    function loadYamlsUnder(dir) {
+        if (!fs.existsSync(dir))
+            return [];
+        const out = [];
+        function walk(d) {
+            for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+                const full = path.join(d, entry.name);
+                if (entry.isDirectory()) {
+                    walk(full);
+                }
+                else if (entry.name.endsWith('.yaml')) {
+                    out.push(yaml.load(fs.readFileSync(full, 'utf8')));
+                }
+            }
+        }
+        walk(dir);
+        return out;
+    }
+    const viewFiles = fs.existsSync(VIEW_DIR)
+        ? fs.readdirSync(VIEW_DIR).filter((f) => f.endsWith('.transitrix.yaml'))
+        : [];
+    for (const file of viewFiles) {
+        it(`resolves ${file} against canon fixtures and passes parseCanonicalFGCA`, () => {
+            const viewDoc = yaml.load(fs.readFileSync(path.join(VIEW_DIR, file), 'utf8'));
+            expect(isFGCAViewDoc(viewDoc)).toBe(true);
+            const elements = loadYamlsUnder(ELEM_DIR);
+            const doc = resolveFGCA(viewDoc, { elements, relations: [] });
+            const r = parseCanonicalFGCA(doc);
+            expect(r.valid).toBe(true);
+            expect(r.errors).toEqual([]);
+        });
+    }
+});

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

@@ -1,5 +1,5 @@
 import type { FGCAPreviewDoc } from './preview-layout.js';
-export type ChainColumn = 'factor' | 'goal' | 'change' | 'activity';
+export type ChainColumn = 'driver' | 'goal' | 'change' | 'activity';
 export interface ChainCell {
     /** Column-qualified identity (e.g. "goal:3") — stable, unique across columns. */
     key: string;

package/dist/fgca/chain-table.js

@@ -1,6 +1,6 @@
 // Chain-table model for the FGCA / FGA previews (vkgeorgia/strategy#137).
 //
-// The tree/chain preview (`layoutFGCAPreview`) shows Factor → Goal → Change →
+// The tree/chain preview (`layoutFGCAPreview`) shows Driver → 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.
@@ -40,8 +40,8 @@ function sameCell(a, b) {
 export function buildChainTable(doc, options = {}) {
     const { hideChanges = false } = options;
     const columns = hideChanges
-        ? ['factor', 'goal', 'activity']
-        : ['factor', 'goal', 'change', 'activity'];
+        ? ['driver', 'goal', 'activity']
+        : ['driver', '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]));
@@ -101,7 +101,7 @@ export function buildChainTable(doc, options = {}) {
     };
     // Phase 1 — factor-rooted paths.
     for (const f of doc.factors) {
-        const factorCell = cellOf('factor', f.id, f.name);
+        const factorCell = cellOf('driver', 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]));

package/dist/fgca/index.d.ts

@@ -7,8 +7,10 @@ export type { ChainTable, ChainTableCell, ChainColumn, ChainCell, ChainTableOpti
 export { validateFGCADoc } from "./validate";
 export type { FGCADoc, FGCAValidationResult, FGCAValidationError, FGCAValidationWarning } from "./validate";
 export { ALL_FGCA_COLUMNS, FGCA_COLUMN_LABELS, } from "./types";
-export type { FactorItem, GoalItem, BdnChangeWithActivities, ActivityItem, ActivityTypeItem, DiagramStyle, FGCAColumn, } from "./types";
-export { default as FGCAFactorNode } from "./nodes/FGCAFactorNode";
+export type { DriverItem, GoalItem, BdnChangeWithActivities, ActivityItem, ActivityTypeItem, DiagramStyle, FGCAColumn, } from "./types";
+export { resolveFGCA, isFGCAViewDoc } from './resolver.js';
+export type { FGCAViewConfig, FGCACanonSources } from './resolver.js';
+export { default as FGCADriverNode } from "./nodes/FGCAFactorNode";
 export { default as FGCAGoalNode } from "./nodes/FGCAGoalNode";
 export { default as FGCAChangeNode } from "./nodes/FGCAChangeNode";
 export { default as FGCAActivityNode } from "./nodes/FGCAActivityNode";

package/dist/fgca/index.js

@@ -3,7 +3,8 @@ export { layoutFGCAPreview, selectScopedFGCA, FGCA_NODE_W, FGCA_NODE_H, FGCA_HEA
 export { buildChainTable } from "./chain-table";
 export { validateFGCADoc } from "./validate";
 export { ALL_FGCA_COLUMNS, FGCA_COLUMN_LABELS, } from "./types";
-export { default as FGCAFactorNode } from "./nodes/FGCAFactorNode";
+export { resolveFGCA, isFGCAViewDoc } from './resolver.js';
+export { default as FGCADriverNode } from "./nodes/FGCAFactorNode";
 export { default as FGCAGoalNode } from "./nodes/FGCAGoalNode";
 export { default as FGCAChangeNode } from "./nodes/FGCAChangeNode";
 export { default as FGCAActivityNode } from "./nodes/FGCAActivityNode";

package/dist/fgca/layout.d.ts

@@ -1,5 +1,5 @@
 import type { Node, Edge } from "reactflow";
-import type { FactorItem, GoalItem, BdnChangeWithActivities, ActivityItem, ActivityTypeItem, DiagramStyle, FGCAColumn } from "./types";
+import type { DriverItem, GoalItem, BdnChangeWithActivities, ActivityItem, ActivityTypeItem, DiagramStyle, FGCAColumn } from "./types";
 export declare const NODE_WIDTH = 250;
 export declare const NODE_HEIGHT = 80;
 export declare const COLUMN_GAP = 180;
@@ -7,7 +7,7 @@ export declare const ROW_GAP = 24;
 /** Default background colours per column. */
 export declare const COLUMN_BG: Record<FGCAColumn, string>;
 export interface FGCALayoutInput {
-    factors: FactorItem[];
+    factors: DriverItem[];
     goals: GoalItem[];
     changes: BdnChangeWithActivities[];
     activities: ActivityItem[];

package/dist/fgca/layout.js

@@ -6,7 +6,7 @@ export const COLUMN_GAP = 180;
 export const ROW_GAP = 24;
 /** Default background colours per column. */
 export const COLUMN_BG = {
-    factor: "#fef3c7",
+    driver: "#fef3c7",
     goal: "#e0e7ff",
     change: "#dbeafe",
     activity: "#d4edda",
@@ -27,12 +27,12 @@ export function buildFGCALayout({ factors, goals, changes, activities, visibleCo
     const goalIds = new Set(goals.map((g) => g.id));
     const edgeStyle = { strokeWidth: edgeWidth, stroke: edgeColor };
     const baseNodeStyle = { borderColor: nodeBorderColor, borderWidth: nodeBorderWidth, borderStyle: "solid" };
-    if (visibleColumns.has("factor")) {
+    if (visibleColumns.has("driver")) {
         factors.forEach((f, i) => {
             nodes.push({
-                id: `factor_${f.id}`,
-                type: "fgcaFactor",
-                position: { x: colX["factor"], y: i * (NODE_HEIGHT + ROW_GAP) },
+                id: `driver_${f.id}`,
+                type: "fgcaDriver",
+                position: { x: colX["driver"], y: i * (NODE_HEIGHT + ROW_GAP) },
                 data: { id: f.id, name: f.name, ...baseNodeStyle },
                 sourcePosition: Position.Right,
                 targetPosition: Position.Left,
@@ -88,13 +88,13 @@ export function buildFGCALayout({ factors, goals, changes, activities, visibleCo
             });
         });
     }
-    // Factor→Goal edges (via embedded factor[] on each goal)
-    if (visibleColumns.has("factor") && visibleColumns.has("goal")) {
+    // Driver→Goal edges (via embedded factor[] on each goal)
+    if (visibleColumns.has("driver") && visibleColumns.has("goal")) {
         goals.forEach((g) => {
             g.factor?.forEach((f) => {
                 edges.push({
-                    id: `edge_f${f.id}_g${g.id}`,
-                    source: `factor_${f.id}`,
+                    id: `edge_d${f.id}_g${g.id}`,
+                    source: `driver_${f.id}`,
                     target: `goal_${g.id}`,
                     markerEnd: { type: MarkerType.ArrowClosed },
                     type: "smoothstep",

package/dist/fgca/nodeTypes.d.ts

@@ -1,5 +1,5 @@
 export declare const FGCA_NODE_TYPES: {
-    readonly fgcaFactor: import("react").MemoExoticComponent<({ data, isConnectable }: import("./nodes/FGCAFactorNode").FGCAFactorNodeProps) => import("react/jsx-runtime").JSX.Element>;
+    readonly fgcaDriver: import("react").MemoExoticComponent<({ data, isConnectable }: import("./nodes/FGCAFactorNode").FGCADriverNodeProps) => import("react/jsx-runtime").JSX.Element>;
     readonly fgcaGoal: import("react").MemoExoticComponent<({ data, isConnectable }: import("./nodes/FGCAGoalNode").FGCAGoalNodeProps) => import("react/jsx-runtime").JSX.Element>;
     readonly fgcaChange: import("react").MemoExoticComponent<({ data, isConnectable }: import("./nodes/FGCAChangeNode").FGCAChangeNodeProps) => import("react/jsx-runtime").JSX.Element>;
     readonly fgcaActivity: import("react").MemoExoticComponent<({ data, isConnectable }: import("./nodes/FGCAActivityNode").FGCAActivityNodeProps) => import("react/jsx-runtime").JSX.Element>;

package/dist/fgca/nodeTypes.js

@@ -1,9 +1,9 @@
-import FGCAFactorNode from "./nodes/FGCAFactorNode";
+import FGCADriverNode from "./nodes/FGCAFactorNode";
 import FGCAGoalNode from "./nodes/FGCAGoalNode";
 import FGCAChangeNode from "./nodes/FGCAChangeNode";
 import FGCAActivityNode from "./nodes/FGCAActivityNode";
 export const FGCA_NODE_TYPES = {
-    fgcaFactor: FGCAFactorNode,
+    fgcaDriver: FGCADriverNode,
     fgcaGoal: FGCAGoalNode,
     fgcaChange: FGCAChangeNode,
     fgcaActivity: FGCAActivityNode,

package/dist/fgca/nodes/FGCAFactorNode.d.ts

@@ -1,5 +1,5 @@
 import React from "react";
-export interface FGCAFactorNodeProps {
+export interface FGCADriverNodeProps {
     data: {
         id: number;
         name: string;
@@ -8,5 +8,5 @@ export interface FGCAFactorNodeProps {
     };
     isConnectable?: boolean;
 }
-declare const FGCAFactorNode: React.MemoExoticComponent<({ data, isConnectable }: FGCAFactorNodeProps) => import("react/jsx-runtime").JSX.Element>;
-export default FGCAFactorNode;
+declare const FGCADriverNode: React.MemoExoticComponent<({ data, isConnectable }: FGCADriverNodeProps) => import("react/jsx-runtime").JSX.Element>;
+export default FGCADriverNode;

package/dist/fgca/nodes/FGCAFactorNode.js

@@ -3,8 +3,8 @@ import { memo } from "react";
 import { Handle, Position } from "reactflow";
 const NODE_WIDTH = 250;
 const NODE_HEIGHT = 80;
-const FGCAFactorNode = memo(({ data, isConnectable }) => (_jsxs("div", { style: {
-        background: "var(--ts-layer-factor)",
+const FGCADriverNode = memo(({ data, isConnectable }) => (_jsxs("div", { style: {
+        background: "var(--ts-layer-driver)",
         width: NODE_WIDTH,
         height: NODE_HEIGHT,
         padding: "6px 8px",
@@ -30,6 +30,6 @@ const FGCAFactorNode = memo(({ data, isConnectable }) => (_jsxs("div", { style:
                 wordBreak: "break-word",
                 padding: "0 4px",
                 width: "100%",
-            }, title: data.name, children: data.name }), _jsxs("div", { style: { fontSize: "10px", color: "var(--ts-text-secondary)", marginTop: 2 }, children: ["F-", String(data.id).padStart(4, "0")] })] })));
-FGCAFactorNode.displayName = "FGCAFactorNode";
-export default FGCAFactorNode;
+            }, title: data.name, children: data.name }), _jsxs("div", { style: { fontSize: "10px", color: "var(--ts-text-secondary)", marginTop: 2 }, children: ["D-", String(data.id).padStart(4, "0")] })] })));
+FGCADriverNode.displayName = "FGCADriverNode";
+export default FGCADriverNode;

package/dist/fgca/parse-canonical.js

@@ -27,10 +27,12 @@
 // is fixed per layer; middle segments are optional; the terminal is a
 // positive integer with no leading zeros.
 const FACTOR_ID_RE = /^FACTOR(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const DRIVER_ID_RE = /^DRIVER(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const FACTOR_OR_DRIVER_ID_RE = /^(FACTOR|DRIVER)(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
 const GOAL_ID_RE = /^GOAL(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
 const CHANGE_ID_RE = /^CHANGE(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
 const ACTIVITY_ID_RE = /^ACTIVITY(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
-const FGCA_DOC_ID_RE = /^FGCA(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const FGCA_DOC_ID_RE = /^(FGCA|DGCA)(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
 const CONSTRAINT_ID_RE = /^CONSTRAINT(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
 function isNonEmptyString(v) {
     return typeof v === 'string' && v.trim().length > 0;
@@ -55,18 +57,21 @@ export function parseCanonicalFGCA(input) {
         };
     }
     const raw = input;
-    if ('notation' in raw && raw['notation'] !== 'fgca') {
+    if ('notation' in raw && raw['notation'] !== 'fgca' && raw['notation'] !== 'dgca') {
         return {
             valid: false,
             errors: [
                 {
                     code: 'FGCA-001',
-                    message: `notation must be "fgca", got "${String(raw['notation'])}"`,
+                    message: `notation must be "dgca" (or legacy "fgca"), got "${String(raw['notation'])}"`,
                 },
             ],
             warnings,
         };
     }
+    if ('notation' in raw && raw['notation'] === 'fgca') {
+        warnings.push({ code: 'FGCA-001', message: 'notation "fgca" is deprecated — rename to "dgca"' });
+    }
     // FGCA-002 — document id (optional in v1.4 per the canonical spec? — spec
     // says required; absence is FGCA-002).
     if (raw['id'] !== undefined) {
@@ -137,7 +142,7 @@ export function parseCanonicalFGCA(input) {
         }
         return { id, name: isNonEmptyString(name) ? name : '' };
     }
-    factors.forEach((el, i) => checkLayerElement(el, `factors[${i}]`, FACTOR_ID_RE, factorIds));
+    factors.forEach((el, i) => checkLayerElement(el, `factors[${i}]`, FACTOR_OR_DRIVER_ID_RE, factorIds));
     goals.forEach((el, i) => checkLayerElement(el, `goals[${i}]`, GOAL_ID_RE, goalIds));
     changes.forEach((el, i) => checkLayerElement(el, `changes[${i}]`, CHANGE_ID_RE, changeIds));
     activities.forEach((el, i) => checkLayerElement(el, `activities[${i}]`, ACTIVITY_ID_RE, activityIds));
@@ -188,7 +193,7 @@ export function parseCanonicalFGCA(input) {
         name: String(el['name'] ?? ''),
     }));
     const internalGoals = goals.map((el, i) => {
-        const refIds = checkRefArray(el, 'factors', factorIds, FACTOR_ID_RE, 'FGCA-008', `goals[${i}]`);
+        const refIds = checkRefArray(el, 'factors', factorIds, FACTOR_OR_DRIVER_ID_RE, 'FGCA-008', `goals[${i}]`);
         return {
             id: intId(String(el['id'])),
             name: String(el['name'] ?? ''),
@@ -261,7 +266,7 @@ export function parseCanonicalFGCA(input) {
     if (errors.length > 0)
         return { valid: false, errors, warnings };
     const parsed = {
-        notation: 'fgca',
+        notation: raw['notation'] ?? 'dgca',
         spec_version: typeof raw['spec_version'] === 'string' ? raw['spec_version'] : undefined,
         factors: internalFactors,
         goals: internalGoals,
@@ -270,7 +275,7 @@ export function parseCanonicalFGCA(input) {
     };
     return { valid: true, errors, warnings, parsed };
 }
-const FGA_DOC_ID_RE = /^FGA(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+const FGA_DOC_ID_RE = /^(FGA|DGA)(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
 /**
  * Canonical-form FGA parser + validator.
  *
@@ -293,10 +298,10 @@ export function parseCanonicalFGA(input) {
         return { valid: false, errors: [{ code: 'FGA-001', message: 'document root is not an object' }], warnings: [] };
     }
     const raw = input;
-    if ('notation' in raw && raw['notation'] !== 'fga') {
+    if ('notation' in raw && raw['notation'] !== 'fga' && raw['notation'] !== 'dga') {
         return {
             valid: false,
-            errors: [{ code: 'FGA-001', message: `notation must be "fga", got "${String(raw['notation'])}"` }],
+            errors: [{ code: 'FGA-001', message: `notation must be "dga" (or legacy "fga"), got "${String(raw['notation'])}"` }],
             warnings: [],
         };
     }
@@ -314,7 +319,7 @@ export function parseCanonicalFGA(input) {
     // changes. Per-layer / per-ref checks all reuse the FGCA implementation;
     // codes are remapped on the way out. FGCA-009 / 010 / 014 (changes-related)
     // are unreachable here because `changes` is empty.
-    const synth = { ...raw, notation: 'fgca', id: 'FGCA-FROM-FGA-1', changes: [] };
+    const synth = { ...raw, notation: 'dgca', id: 'DGCA-FROM-DGA-1', changes: [] };
     const r = parseCanonicalFGCA(synth);
     const remap = {
         'FGCA-001': 'FGA-001',

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

@@ -1,5 +1,5 @@
 import type { Scope } from '../scope.js';
-export type FGCAPreviewColumn = 'factor' | 'goal' | 'change' | 'activity';
+export type FGCAPreviewColumn = 'driver' | 'goal' | 'change' | 'activity';
 export interface FGCAPreviewFactor {
     id: number | string;
     name: string;

package/dist/fgca/preview-layout.js

@@ -52,11 +52,11 @@ export function layoutFGCAPreview(inputDoc, options = {}) {
     const doc = selectScopedFGCA(inputDoc, scope);
     const colStride = FGCA_NODE_W + colGap;
     const cols = hideChanges
-        ? ['factor', 'goal', 'activity']
-        : ['factor', 'goal', 'change', 'activity'];
+        ? ['driver', 'goal', 'activity']
+        : ['driver', 'goal', 'change', 'activity'];
     const changes = doc.changes ?? [];
     const colItems = {
-        factor: doc.factors.map(f => ({ id: `factor_${f.id}`, label: f.name })),
+        driver: doc.factors.map(f => ({ id: `driver_${f.id}`, label: f.name })),
         goal: doc.goals.map(g => ({ id: `goal_${g.id}`, label: g.name })),
         change: changes.map(c => ({ id: `change_${c.id}`, label: c.name })),
         activity: doc.activities.map(a => ({ id: `activity_${a.id}`, label: a.name })),
@@ -86,7 +86,7 @@ export function layoutFGCAPreview(inputDoc, options = {}) {
     }
     for (const g of doc.goals) {
         for (const f of (g.factor ?? []))
-            addEdge(`factor_${f.id}`, `goal_${g.id}`);
+            addEdge(`driver_${f.id}`, `goal_${g.id}`);
     }
     if (hideChanges) {
         const connectedViaChange = new Set();

package/dist/fgca/resolver.d.ts

@@ -0,0 +1,49 @@
+/**
+ * FGCA canon resolver — assembles a flat canonical FGCA document from a
+ * view_config projection and a canon element/relation store (VP-3).
+ *
+ * Output shape matches the flat form that `parseCanonicalFGCA` expects:
+ * top-level `factors[]`, `goals[]`, `changes[]`, `activities[]` with typed
+ * string IDs.  Filesystem-free — callable from unit tests without vscode.
+ */
+export interface FGCAViewConfig {
+    goals?: {
+        filter?: 'all' | 'ids' | 'tags';
+        ids?: string[];
+        tags?: string[];
+    };
+    factors?: {
+        surface?: 'derived' | 'all';
+    };
+    changes?: {
+        surface?: 'derived' | 'all';
+    };
+    activities?: {
+        surface?: 'derived' | 'all';
+    };
+    display?: {
+        depth?: number | null;
+        collapsed?: string[];
+    };
+}
+export interface FGCACanonSources {
+    elements: unknown[];
+    relations: unknown[];
+}
+/**
+ * Returns true when the parsed view document uses the canon-projection form
+ * (`view_config` key present, no inline `factors[]` / `goals[]` arrays).
+ * Used by the preview to decide whether to run the resolver or fall back to
+ * direct `parseCanonicalFGCA` on the inline document.
+ */
+export declare function isFGCAViewDoc(parsed: unknown): boolean;
+/**
+ * Assemble a flat canonical FGCA document from the canon element store,
+ * filtered by the view document's `view_config`.  The return value is ready
+ * to pass to `parseCanonicalFGCA`.
+ *
+ * Cross-reference fields (`goal.factors[]`, `change.goals[]`,
+ * `activity.changes[]`) are carried from the canon elements unchanged; the
+ * resolver decides which elements to include, not how they are shaped.
+ */
+export declare function resolveFGCA(viewDoc: unknown, sources: FGCACanonSources): Record<string, unknown>;