@transitrix/diagrams 1.0.0

package/src/fgca/nodes/FGCAGoalNode.tsx

@@ -0,0 +1,72 @@
+import React, { memo } from "react";
+import { Handle, Position } from "reactflow";
+
+const NODE_WIDTH = 250;
+const NODE_HEIGHT = 80;
+const DEFAULT_BG = "var(--ts-layer-goal)";
+
+export interface FGCAGoalNodeProps {
+  data: {
+    id: number;
+    name: string;
+    level?: number;
+    bgColor?: string;
+    borderColor?: string;
+    borderWidth?: number;
+  };
+  isConnectable?: boolean;
+}
+
+const FGCAGoalNode = memo(({ data, isConnectable }: FGCAGoalNodeProps) => {
+  const level = data.level ?? 0;
+  const bg = data.bgColor ?? DEFAULT_BG;
+
+  return (
+    <div
+      style={{
+        background: bg,
+        width: NODE_WIDTH,
+        height: NODE_HEIGHT,
+        padding: "6px 8px",
+        fontSize: "12px",
+        borderColor: data.borderColor ?? "var(--ts-node-stroke)",
+        borderWidth: data.borderWidth ?? 1,
+        borderStyle: "solid",
+        borderRadius: "0.75rem",
+        boxShadow: "0 1px 4px rgba(0,0,0,0.12)",
+        display: "flex",
+        flexDirection: "column",
+        justifyContent: "center",
+        alignItems: "center",
+        textAlign: "center",
+        color: "var(--ts-text-primary)",
+      }}
+    >
+      <Handle type="target" position={Position.Left} isConnectable={false} style={{ background: "var(--ts-node-stroke)" }} />
+      <Handle type="source" position={Position.Right} isConnectable={isConnectable} style={{ background: "var(--ts-node-stroke)" }} />
+      <div
+        style={{
+          fontWeight: 600,
+          lineHeight: 1.2,
+          overflow: "hidden",
+          display: "-webkit-box",
+          WebkitLineClamp: 2,
+          WebkitBoxOrient: "vertical",
+          wordBreak: "break-word",
+          padding: "0 4px",
+          width: "100%",
+        }}
+        title={data.name}
+      >
+        {data.name}
+      </div>
+      <div style={{ fontSize: "10px", color: "var(--ts-text-secondary)", marginTop: 2 }}>
+        G-{String(data.id).padStart(4, "0")} | Lvl: {level}
+      </div>
+    </div>
+  );
+});
+
+FGCAGoalNode.displayName = "FGCAGoalNode";
+
+export default FGCAGoalNode;

package/src/fgca/parse-canonical.ts

@@ -0,0 +1,400 @@
+/**
+ * Canonical-form FGCA parser + validator.
+ *
+ * Accepts the methodology's canonical FGCA YAML shape (see
+ * `transitrix/methodology` `notations/02-fgca.md`):
+ *
+ * - Flat top-level arrays, no `fgca:` wrapper.
+ * - Typed string IDs per `IDS_AND_REFERENCES.md` (`FACTOR-1`,
+ *   `GOAL-RET-1`, `CHANGE-1`, `ACTIVITY-ONBOARD-1`).
+ * - Plural canonical-direction cross-references: `goal.factors`,
+ *   `change.goals`, `activity.changes`, `activity.goals`.
+ * - Per-notation validation codes `FGCA-001 … FGCA-015`.
+ *
+ * Returns the validation result plus, on success, an internal `FGCADoc`
+ * representation built from the canonical input — string IDs are kept
+ * as strings; the existing `buildFGCALayout` consumes `id: number`
+ * historically but the layout code only uses IDs as opaque keys, so
+ * string IDs work fine.
+ *
+ * Strategy hub #63: this lives at the input boundary so the library's
+ * internal types (currently using DSM-API form — numeric IDs and
+ * singular cross-refs) can stay where they are. A follow-up task can
+ * unify the internal types with the canonical form across all sister
+ * modules.
+ */
+
+import type {
+  ActivityItem,
+  BdnChangeWithActivities,
+  FactorItem,
+  GoalItem,
+} from './types.js';
+import type { FGCADoc } from './validate.js';
+import type {
+  ValidationError,
+  ValidationWarning,
+  ValidationResult,
+} from '../validation-types.js';
+
+export interface CanonicalFGCAResult extends ValidationResult {
+  /** On success, the internal-form FGCADoc derived from the canonical input. */
+  parsed?: FGCADoc;
+}
+
+// Canonical ID grammars per IDS_AND_REFERENCES.md §1. The TYPE prefix
+// 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 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 CONSTRAINT_ID_RE = /^CONSTRAINT(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+
+function isNonEmptyString(v: unknown): v is string {
+  return typeof v === 'string' && v.trim().length > 0;
+}
+
+function asObjectArray(v: unknown): Array<Record<string, unknown>> | null {
+  if (!Array.isArray(v)) return null;
+  return v.map((el) => (el && typeof el === 'object' ? (el as Record<string, unknown>) : null) as Record<string, unknown>);
+}
+
+interface InternalIdMap {
+  /** Canonical typed-string ID → internal numeric ID for layout consumption. */
+  toInternal: Map<string, number>;
+}
+
+/**
+ * Validate canonical FGCA YAML and, on success, return an internal-form
+ * `FGCADoc` ready for `buildFGCALayout`.
+ */
+export function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (!input || typeof input !== 'object') {
+    return {
+      valid: false,
+      errors: [{ code: 'FGCA-001', message: 'document root is not an object' }],
+      warnings,
+    };
+  }
+
+  const raw = input as Record<string, unknown>;
+
+  if ('notation' in raw && raw['notation'] !== 'fgca') {
+    return {
+      valid: false,
+      errors: [
+        {
+          code: 'FGCA-001',
+          message: `notation must be "fgca", got "${String(raw['notation'])}"`,
+        },
+      ],
+      warnings,
+    };
+  }
+
+  // FGCA-002 — document id (optional in v1.4 per the canonical spec? — spec
+  // says required; absence is FGCA-002).
+  if (raw['id'] !== undefined) {
+    if (!isNonEmptyString(raw['id']) || !FGCA_DOC_ID_RE.test(raw['id'])) {
+      errors.push({
+        code: 'FGCA-002',
+        message: `id "${String(raw['id'])}" must match FGCA-[<middle>-]<INTEGER>`,
+      });
+    }
+  } else {
+    errors.push({ code: 'FGCA-002', message: 'document id is required' });
+  }
+
+  if (!isNonEmptyString(raw['name'])) {
+    errors.push({ code: 'FGCA-003', message: 'name is required' });
+  }
+
+  const factorsRaw = asObjectArray(raw['factors']);
+  const goalsRaw = asObjectArray(raw['goals']);
+  const changesRaw = asObjectArray(raw['changes']);
+  const activitiesRaw = asObjectArray(raw['activities']);
+
+  if (factorsRaw === null) errors.push({ code: 'FGCA-004', message: 'factors must be an array', path: 'factors' });
+  if (goalsRaw === null) errors.push({ code: 'FGCA-004', message: 'goals must be an array', path: 'goals' });
+  if (changesRaw === null) errors.push({ code: 'FGCA-004', message: 'changes must be an array', path: 'changes' });
+  if (activitiesRaw === null) errors.push({ code: 'FGCA-004', message: 'activities must be an array', path: 'activities' });
+
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  // From here we know all four arrays exist.
+  const factors = factorsRaw!;
+  const goals = goalsRaw!;
+  const changes = changesRaw!;
+  const activities = activitiesRaw!;
+
+  // Per-layer ID maps + duplicate detection. (FGCA-006: unique within a layer.)
+  const factorIds = new Set<string>();
+  const goalIds = new Set<string>();
+  const changeIds = new Set<string>();
+  const activityIds = new Set<string>();
+
+  function checkLayerElement(
+    el: Record<string, unknown> | null,
+    path: string,
+    idRe: RegExp,
+    seen: Set<string>,
+  ): { id: string; name: string } | null {
+    if (!el) {
+      errors.push({ code: 'FGCA-005', message: `${path} must be an object`, path });
+      return null;
+    }
+    const id = el['id'];
+    const name = el['name'];
+    if (!isNonEmptyString(id)) {
+      errors.push({ code: 'FGCA-005', message: `${path}.id is required`, path });
+      return null;
+    }
+    if (!isNonEmptyString(name)) {
+      errors.push({ code: 'FGCA-005', message: `${path}.name is required`, path });
+    }
+    if (!idRe.test(id)) {
+      errors.push({
+        code: 'FGCA-007',
+        message: `${path}.id "${id}" does not match the canonical grammar for its layer`,
+        path,
+      });
+      return null;
+    }
+    if (seen.has(id)) {
+      errors.push({ code: 'FGCA-006', message: `Duplicate id "${id}"`, path });
+    } else {
+      seen.add(id);
+    }
+    return { id, name: isNonEmptyString(name) ? name : '' };
+  }
+
+  factors.forEach((el, i) => checkLayerElement(el, `factors[${i}]`, FACTOR_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));
+
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  // Cross-refs.
+  function checkRefArray(
+    el: Record<string, unknown>,
+    field: string,
+    targets: Set<string>,
+    refRe: RegExp,
+    code: string,
+    path: string,
+  ): string[] {
+    const ref = el[field];
+    if (ref === undefined || ref === null) return [];
+    if (!Array.isArray(ref)) {
+      errors.push({ code: 'FGCA-007', message: `${path}.${field} must be an array of IDs`, path });
+      return [];
+    }
+    const out: string[] = [];
+    for (const r of ref) {
+      if (!isNonEmptyString(r)) {
+        errors.push({ code: 'FGCA-007', message: `${path}.${field}[] entries must be non-empty strings`, path });
+        continue;
+      }
+      if (!refRe.test(r)) {
+        errors.push({ code: 'FGCA-007', message: `${path}.${field}[] entry "${r}" does not match the expected grammar`, path });
+        continue;
+      }
+      if (!targets.has(r)) {
+        errors.push({ code, message: `${path}.${field}[] references undeclared element "${r}"`, path });
+        continue;
+      }
+      out.push(r);
+    }
+    return out;
+  }
+
+  // Build internal id-maps (canonical string ID → internal sequential number).
+  const idMap: InternalIdMap = { toInternal: new Map() };
+  const allCanonicalIds = [...factorIds, ...goalIds, ...changeIds, ...activityIds];
+  allCanonicalIds.forEach((id, i) => idMap.toInternal.set(id, i + 1));
+
+  function intId(canonical: string): number {
+    const n = idMap.toInternal.get(canonical);
+    if (n === undefined) {
+      // Shouldn't happen — we built the map from the same sets.
+      throw new Error(`internal: canonical id "${canonical}" not mapped`);
+    }
+    return n;
+  }
+
+  // Layer entries (internal form).
+  const internalFactors: FactorItem[] = factors.map((el) => ({
+    id: intId(String(el!['id'])),
+    name: String(el!['name'] ?? ''),
+  }));
+
+  const internalGoals: GoalItem[] = goals.map((el, i) => {
+    const refIds = checkRefArray(el!, 'factors', factorIds, FACTOR_ID_RE, 'FGCA-008', `goals[${i}]`);
+    return {
+      id: intId(String(el!['id'])),
+      name: String(el!['name'] ?? ''),
+      factor: refIds.map((r) => ({ id: intId(r) })),
+    };
+  });
+
+  // Build a reverse mapping: which changes does each activity reference (via
+  // canonical activity.changes)? Used to populate the internal `change.activity_ids`.
+  const activityChangesByCanonicalActivityId = new Map<string, string[]>();
+  activities.forEach((el, i) => {
+    const refIds = checkRefArray(el!, 'changes', changeIds, CHANGE_ID_RE, 'FGCA-010', `activities[${i}]`);
+    activityChangesByCanonicalActivityId.set(String(el!['id']), refIds);
+  });
+
+  // For each change, find the activities that reference it.
+  const activitiesForChange = new Map<string, string[]>();
+  for (const [actId, changeIdsForAct] of activityChangesByCanonicalActivityId.entries()) {
+    for (const cid of changeIdsForAct) {
+      const arr = activitiesForChange.get(cid) ?? [];
+      arr.push(actId);
+      activitiesForChange.set(cid, arr);
+    }
+  }
+
+  const internalChanges: BdnChangeWithActivities[] = changes.map((el, i) => {
+    const goalRefs = checkRefArray(el!, 'goals', goalIds, GOAL_ID_RE, 'FGCA-009', `changes[${i}]`);
+    // Internal `change.goal_id` is singular; canonical `change.goals` is plural.
+    // First goal wins for the singular field; warn (not error) if multiple.
+    if (goalRefs.length > 1) {
+      warnings.push({
+        code: 'FGCA-009',
+        message: `changes[${i}].goals lists ${goalRefs.length} goals; the internal layout uses the first one (${goalRefs[0]}). Multi-goal changes are not lossy for the canonical spec — only the layout linearises them.`,
+        path: `changes[${i}].goals`,
+      });
+    }
+    const canonicalChangeId = String(el!['id']);
+    const linkedActivityIds = activitiesForChange.get(canonicalChangeId) ?? [];
+    return {
+      id: intId(canonicalChangeId),
+      name: String(el!['name'] ?? ''),
+      goal_id: goalRefs.length > 0 ? intId(goalRefs[0]) : 0,
+      activity_ids: linkedActivityIds.map((aid) => intId(aid)),
+    };
+  });
+
+  const internalActivities: ActivityItem[] = activities.map((el, i) => {
+    const goalRefs = checkRefArray(el!, 'goals', goalIds, GOAL_ID_RE, 'FGCA-011', `activities[${i}]`);
+    return {
+      id: intId(String(el!['id'])),
+      name: String(el!['name'] ?? ''),
+      goal_id: goalRefs.length > 0 ? intId(goalRefs[0]) : null,
+    };
+  });
+
+  // FACTOR.references_constraint grammar check (FGCA-015).
+  factors.forEach((el, i) => {
+    const rc = el!['references_constraint'];
+    if (rc === undefined || rc === null) return;
+    if (!Array.isArray(rc)) {
+      errors.push({ code: 'FGCA-015', message: `factors[${i}].references_constraint must be an array of IDs`, path: `factors[${i}].references_constraint` });
+      return;
+    }
+    for (const r of rc) {
+      if (typeof r !== 'string' || !CONSTRAINT_ID_RE.test(r)) {
+        errors.push({
+          code: 'FGCA-015',
+          message: `factors[${i}].references_constraint[] entry "${String(r)}" must match CONSTRAINT-[<middle>-]<INTEGER>`,
+          path: `factors[${i}].references_constraint`,
+        });
+      }
+    }
+  });
+
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  const parsed: FGCADoc = {
+    notation: 'fgca',
+    spec_version: typeof raw['spec_version'] === 'string' ? (raw['spec_version'] as string) : undefined,
+    factors: internalFactors,
+    goals: internalGoals,
+    changes: internalChanges,
+    activities: internalActivities,
+  };
+
+  return { valid: true, errors, warnings, parsed };
+}
+
+const FGA_DOC_ID_RE = /^FGA(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+
+/** On success, the internal-form FGCADoc derived from canonical FGA input. */
+export interface CanonicalFGAResult extends ValidationResult {
+  parsed?: FGCADoc;
+}
+
+/**
+ * Canonical-form FGA parser + validator.
+ *
+ * FGA is the canonical FGCA chain minus the `changes[]` layer — flat
+ * top-level `factors[]` + `goals[]` + `activities[]`, with `activity.goals[]`
+ * linking activities straight to goals (no intermediate change). It reuses
+ * `parseCanonicalFGCA` by injecting an empty `changes` array and remapping
+ * the FGCA-NNN codes to the FGA-NNN registry (`notations/03-fga.md`,
+ * FGA-001..011). The resulting internal `FGCADoc` carries `activity.goal_id`,
+ * which is exactly what the renderer needs to draw goal → activity edges —
+ * the field whose absence produced the "FGA nodes render, no edges" bug
+ * (transitrix/methodology#65 / vkgeorgia/strategy#65).
+ *
+ * Lives beside `parseCanonicalFGCA` (rather than inline in the extension) so
+ * the canonical FGA path is unit-testable and the library owns the single
+ * canon shape — flat form only, no `fga:` wrapper.
+ */
+export function parseCanonicalFGA(input: unknown): CanonicalFGAResult {
+  if (!input || typeof input !== 'object') {
+    return { valid: false, errors: [{ code: 'FGA-001', message: 'document root is not an object' }], warnings: [] };
+  }
+  const raw = input as Record<string, unknown>;
+  if ('notation' in raw && raw['notation'] !== 'fga') {
+    return {
+      valid: false,
+      errors: [{ code: 'FGA-001', message: `notation must be "fga", got "${String(raw['notation'])}"` }],
+      warnings: [],
+    };
+  }
+  if (raw['id'] === undefined) {
+    return { valid: false, errors: [{ code: 'FGA-002', message: 'document id is required' }], warnings: [] };
+  }
+  if (typeof raw['id'] !== 'string' || !FGA_DOC_ID_RE.test(raw['id'])) {
+    return {
+      valid: false,
+      errors: [{ code: 'FGA-002', message: `id "${String(raw['id'])}" must match FGA-[<middle>-]<INTEGER>` }],
+      warnings: [],
+    };
+  }
+
+  // Forward to the FGCA parser with synthetic FGCA notation + doc id + empty
+  // 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 r = parseCanonicalFGCA(synth);
+  const remap: Record<string, string> = {
+    'FGCA-001': 'FGA-001',
+    'FGCA-002': 'FGA-002',
+    'FGCA-003': 'FGA-003',
+    'FGCA-004': 'FGA-004',
+    'FGCA-005': 'FGA-005',
+    'FGCA-006': 'FGA-006',
+    'FGCA-007': 'FGA-007',
+    'FGCA-008': 'FGA-008',
+    'FGCA-011': 'FGA-009',
+    'FGCA-012': 'FGA-010',
+    'FGCA-015': 'FGA-007',
+  };
+  const remapCode = (c: string): string => remap[c] ?? c;
+  return {
+    valid: r.valid,
+    errors: r.errors.map((e) => ({ ...e, code: remapCode(e.code) })),
+    warnings: r.warnings.map((w) => ({ ...w, code: remapCode(w.code) })),
+    parsed: r.parsed,
+  };
+}

package/src/fgca/preview-layout.ts

@@ -0,0 +1,217 @@
+// Pure column-layout geometry for the static FGCA / FGA previews.
+//
+// This is the layout the Studio extension's `fgca-preview.ts` renders to SVG
+// (NOT the ReactFlow `buildFGCALayout` in `./layout.ts`, which targets the
+// interactive web UI). It lives here — rather than inline in the extension —
+// so the gap geometry is unit-testable: the extension has no test harness.
+//
+// No React, no DOM, no vscode. Safe to call in Node.js or a test environment.
+
+import type { Scope } from '../scope.js';
+
+export type FGCAPreviewColumn = 'factor' | 'goal' | 'change' | 'activity';
+
+export interface FGCAPreviewFactor {
+  id: number | string;
+  name: string;
+}
+export interface FGCAPreviewGoal {
+  id: number | string;
+  name: string;
+  level?: number;
+  factor?: Array<{ id: number | string }>;
+}
+export interface FGCAPreviewChange {
+  id: number | string;
+  name: string;
+  goal_id: number | string;
+  activity_ids: Array<number | string>;
+}
+export interface FGCAPreviewActivity {
+  id: number | string;
+  name: string;
+  goal_id?: number | string | null;
+}
+
+/** Structural input the preview layout needs — a subset of the parsed FGCA/FGA doc. */
+export interface FGCAPreviewDoc {
+  factors: FGCAPreviewFactor[];
+  goals: FGCAPreviewGoal[];
+  changes?: FGCAPreviewChange[];
+  activities: FGCAPreviewActivity[];
+}
+
+export interface FGCAPreviewLayoutOptions {
+  /** FGA hides the Changes column and links Goal → Activity directly. */
+  hideChanges?: boolean;
+  /** Horizontal gap (px) between columns. Default matches the historical hardcoded value. */
+  colGap?: number;
+  /** Vertical gap (px) between stacked nodes within a column. Default matches the historical hardcoded value. */
+  rowGap?: number;
+  /** Trim to a level cap or a single root goal (vkgeorgia/strategy#77). Defaults to 'all'. */
+  scope?: Scope;
+}
+
+/**
+ * Trims an FGCA/FGA doc to a scope (vkgeorgia/strategy#77).
+ *
+ * FGCA/FGA goals are flat (no parent_id), so:
+ *   - 'level' → goals with `(level ?? 0) <= maxLevel`.
+ *   - 'root'  → the single goal whose id matches `rootGoalId` (empty when absent).
+ *
+ * Factors, changes and activities are then kept only when they touch a visible
+ * goal: a factor referenced by a visible goal, a change whose `goal_id` is
+ * visible, an activity bound to a visible goal directly or via a visible
+ * change. Pure and exported so an access-control layer can reuse it.
+ */
+export function selectScopedFGCA(doc: FGCAPreviewDoc, scope: Scope): FGCAPreviewDoc {
+  if (scope.mode === 'all') return doc;
+
+  const visibleGoals =
+    scope.mode === 'level'
+      ? doc.goals.filter(g => (g.level ?? 0) <= scope.maxLevel)
+      : doc.goals.filter(g => String(g.id) === scope.rootGoalId);
+
+  const visibleGoalIds = new Set(visibleGoals.map(g => g.id));
+
+  const changes = doc.changes ?? [];
+  const visibleChanges = changes.filter(c => visibleGoalIds.has(c.goal_id));
+  const activityIdsViaChange = new Set(visibleChanges.flatMap(c => c.activity_ids));
+
+  const visibleActivities = doc.activities.filter(
+    a => (a.goal_id != null && visibleGoalIds.has(a.goal_id)) || activityIdsViaChange.has(a.id),
+  );
+
+  const factorIds = new Set(visibleGoals.flatMap(g => (g.factor ?? []).map(f => f.id)));
+  const visibleFactors = doc.factors.filter(f => factorIds.has(f.id));
+
+  return {
+    factors: visibleFactors,
+    goals: visibleGoals,
+    changes: doc.changes === undefined ? undefined : visibleChanges,
+    activities: visibleActivities,
+  };
+}
+
+export interface FGCAPreviewNode {
+  id: string;
+  x: number;
+  y: number;
+  label: string;
+  col: FGCAPreviewColumn;
+}
+export interface FGCAPreviewEdge {
+  sx: number;
+  sy: number;
+  tx: number;
+  ty: number;
+}
+/** Per-column header anchor — lets the renderer draw column headers without recomputing the stride. */
+export interface FGCAPreviewColumnPos {
+  col: FGCAPreviewColumn;
+  x: number;
+}
+export interface FGCAPreviewLayout {
+  nodes: FGCAPreviewNode[];
+  edges: FGCAPreviewEdge[];
+  columns: FGCAPreviewColumnPos[];
+  width: number;
+  height: number;
+}
+
+// Fixed node + frame geometry. Only the inter-node gaps are user-configurable
+// (vkgeorgia/strategy#75); node size and padding stay constant.
+export const FGCA_NODE_W = 220;
+export const FGCA_NODE_H = 72;
+export const FGCA_HEADER_H = 32;
+export const FGCA_PAD = 20;
+export const FGCA_DEFAULT_COL_GAP = 160;
+export const FGCA_DEFAULT_ROW_GAP = 20;
+
+export function layoutFGCAPreview(
+  inputDoc: FGCAPreviewDoc,
+  options: FGCAPreviewLayoutOptions = {},
+): FGCAPreviewLayout {
+  const {
+    hideChanges = false,
+    colGap = FGCA_DEFAULT_COL_GAP,
+    rowGap = FGCA_DEFAULT_ROW_GAP,
+    scope = { mode: 'all' },
+  } = options;
+
+  // Trim to scope first; everything below lays out the visible subset only.
+  const doc = selectScopedFGCA(inputDoc, scope);
+
+  const colStride = FGCA_NODE_W + colGap;
+  const cols: FGCAPreviewColumn[] = hideChanges
+    ? ['factor', 'goal', 'activity']
+    : ['factor', 'goal', 'change', 'activity'];
+  const changes = doc.changes ?? [];
+  const colItems: Record<FGCAPreviewColumn, Array<{ id: string; label: string }>> = {
+    factor:   doc.factors.map(f => ({ id: `factor_${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 })),
+  };
+
+  const nodeMap = new Map<string, FGCAPreviewNode>();
+  const nodes: FGCAPreviewNode[] = [];
+  const columns: FGCAPreviewColumnPos[] = [];
+
+  for (let ci = 0; ci < cols.length; ci++) {
+    const col = cols[ci];
+    const x = FGCA_PAD + ci * colStride;
+    columns.push({ col, x });
+    let y = FGCA_PAD + FGCA_HEADER_H + rowGap;
+    for (const item of colItems[col]) {
+      const node: FGCAPreviewNode = { id: item.id, x, y, label: item.label, col };
+      nodes.push(node);
+      nodeMap.set(item.id, node);
+      y += FGCA_NODE_H + rowGap;
+    }
+  }
+
+  const edges: FGCAPreviewEdge[] = [];
+  function addEdge(sourceId: string, targetId: string): void {
+    const s = nodeMap.get(sourceId);
+    const t = nodeMap.get(targetId);
+    if (!s || !t) return;
+    edges.push({ sx: s.x + FGCA_NODE_W, sy: s.y + FGCA_NODE_H / 2, tx: t.x, ty: t.y + FGCA_NODE_H / 2 });
+  }
+
+  for (const g of doc.goals) {
+    for (const f of (g.factor ?? [])) addEdge(`factor_${f.id}`, `goal_${g.id}`);
+  }
+  if (hideChanges) {
+    const connectedViaChange = new Set<number | string>();
+    for (const c of changes) {
+      for (const aid of c.activity_ids) {
+        addEdge(`goal_${c.goal_id}`, `activity_${aid}`);
+        connectedViaChange.add(aid);
+      }
+    }
+    for (const a of doc.activities) {
+      if (a.goal_id != null && !connectedViaChange.has(a.id)) {
+        addEdge(`goal_${a.goal_id}`, `activity_${a.id}`);
+      }
+    }
+  } else {
+    for (const c of changes) addEdge(`goal_${c.goal_id}`, `change_${c.id}`);
+    for (const c of changes) for (const aid of c.activity_ids) addEdge(`change_${c.id}`, `activity_${aid}`);
+    const coveredActivities = new Set(changes.flatMap(c => c.activity_ids));
+    for (const a of doc.activities) {
+      if (a.goal_id != null && !coveredActivities.has(a.id)) {
+        addEdge(`goal_${a.goal_id}`, `activity_${a.id}`);
+      }
+    }
+  }
+
+  const maxNodeBottom = nodes.reduce(
+    (m, n) => Math.max(m, n.y + FGCA_NODE_H),
+    FGCA_PAD + FGCA_HEADER_H + rowGap + FGCA_NODE_H,
+  );
+  const width = FGCA_PAD * 2 + cols.length * colStride - colGap;
+  const height = maxNodeBottom + FGCA_PAD;
+
+  return { nodes, edges, columns, width, height };
+}