@transitrix/diagrams 1.6.0 → 1.7.6

package/src/compliance/impact.ts

@@ -10,6 +10,7 @@
 import type { AssertionStatus } from '../assertion/types.js';
 import type { ComplianceCanon } from './classify.js';
 import { buildComplianceIndex } from './reverse-index.js';
+import type { CanonCatalog } from '../typed-id.js';
 import type { ComplianceIndex, IndexAssertion, IndexRequirement, ObjectDetailInput, ObjectDetailDef, DeadlineStatus } from './types.js';
 
 /** Filter selecting REQUIREMENTs by codex source (jurisdiction / regime keys
@@ -75,13 +76,78 @@ export interface ImpactColumn {
   subjectType: 'product' | 'process' | 'capability';
 }
 
-/** A structural validation finding emitted by the matrix builder. */
 export interface ImpactFinding {
   code: string;
   severity: 'error' | 'warning';
   message: string;
 }
 
+/**
+ * Repo-scope cross-reference checks for a parsed compliance-impact view config
+ * (#518 Phase C3). Surfaces unresolved subject, obligation, and regime ids before
+ * `buildImpactMatrix` runs.
+ */
+export function collectImpactViewResolutionFindings(
+  config: ImpactViewConfig,
+  catalog: CanonCatalog,
+  complianceCanon: ComplianceCanon,
+): ImpactFinding[] {
+  const findings: ImpactFinding[] = [];
+  const codexIds = new Set(complianceCanon.codex.map((c) => c.id));
+
+  const subjectChecks: Array<{
+    ids: string[] | undefined;
+    expectedType: string;
+    path: string;
+  }> = [
+    { ids: config.subjects.products, expectedType: 'PRODUCT', path: 'subjects.products' },
+    { ids: config.subjects.processes, expectedType: 'PROCESS', path: 'subjects.processes' },
+    { ids: config.subjects.capabilities, expectedType: 'CAPABILITY', path: 'subjects.capabilities' },
+  ];
+
+  for (const { ids, expectedType, path } of subjectChecks) {
+    for (const id of ids ?? []) {
+      const t = catalog.typeOf(id);
+      if (t === undefined) {
+        findings.push({
+          code: 'COMPIMP-REF',
+          severity: 'error',
+          message: `${path}: "${id}" does not resolve to an admitted artefact.`,
+        });
+      } else if (t !== expectedType) {
+        findings.push({
+          code: 'COMPIMP-REF',
+          severity: 'error',
+          message: `${path}: "${id}" resolves to ${t}, not ${expectedType}.`,
+        });
+      }
+    }
+  }
+
+  for (const id of config.obligations.include ?? []) {
+    const t = catalog.typeOf(id);
+    if (t === undefined || t !== 'REQUIREMENT') {
+      findings.push({
+        code: 'COMPIMP-REF',
+        severity: 'error',
+        message: `obligations.include: "${id}" does not resolve to an admitted REQUIREMENT.`,
+      });
+    }
+  }
+
+  for (const id of config.obligations.filter?.derived_from_codex ?? []) {
+    if (!codexIds.has(id)) {
+      findings.push({
+        code: 'COMPIMP-REF',
+        severity: 'error',
+        message: `obligations.filter.derived_from_codex: "${id}" does not resolve to an admitted codex artefact.`,
+      });
+    }
+  }
+
+  return findings;
+}
+
 /**
  * Grouping options for matrix columns.
  *

package/src/compliance/index.ts

@@ -5,15 +5,22 @@ export { buildGapReport } from './gap-report.js';
 export type { GapReport, GapReportOptions } from './gap-report.js';
 export { emptyCanon, ingestComplianceDoc } from './classify.js';
 export type { ComplianceCanon, ComplianceProduct, ComplianceCodexDoc } from './classify.js';
+export {
+  admitDocumentToCatalog,
+  buildComplianceScan,
+  catalogFromMap,
+} from './canon-catalog.js';
+export type { ComplianceScanResult, ScannedYamlDoc } from './canon-catalog.js';
 export { renderComplianceMarkdown } from './markdown.js';
 export type { ReportScope, MarkdownOptions } from './markdown.js';
 export { renderComplianceHtml, renderImpactMatrixHtml } from './html.js';
 export type { HtmlOptions, ImpactMatrixHtmlOptions } from './html.js';
-export { buildImpactMatrix, renderImpactMarkdown, parseImpactViewConfig, COMPLIANCE_IMPACT_DEFAULTS, extractObjectDetails, extractProcessFlowTasks, mergeStageTaskDetails, computeDeadlineStatus } from './impact.js';
+export { buildImpactMatrix, renderImpactMarkdown, parseImpactViewConfig, collectImpactViewResolutionFindings, COMPLIANCE_IMPACT_DEFAULTS, extractObjectDetails, extractProcessFlowTasks, mergeStageTaskDetails, computeDeadlineStatus } from './impact.js';
 export type {
   ImpactCell,
   ImpactColumn,
   ImpactEmptyCellLabels,
+  ImpactFinding,
   ImpactGrouping,
   ImpactMatrix,
   ImpactObligationFilter,
@@ -31,6 +38,7 @@ export {
 export {
   parseCoverageMetricConfig,
   buildCoverageMatrix,
+  collectCoverageViewResolutionFindings,
 } from './coverage-metric.js';
 export type {
   CoverageMetricConfig,
@@ -40,6 +48,7 @@ export type {
   CoverageMetricThresholds,
   CoverageMatrix,
   CoverageRow,
+  CoverageViewFinding,
   ParseCoverageMetricResult,
   RagStatus,
 } from './coverage-metric.js';

package/src/constraint/__tests__/example.test.ts

@@ -0,0 +1,19 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { validateConstraint } from '../validate.js';
+
+const dir = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../../../../tests/fixtures/notation-corpus/constraint',
+);
+
+describe('constraint worked example (notation-corpus)', () => {
+  it('validates CONSTRAINT-GDPR-RESIDENCY-1.yaml without error', () => {
+    const data = yaml.load(readFileSync(path.join(dir, 'CONSTRAINT-GDPR-RESIDENCY-1.yaml'), 'utf-8'));
+    const v = validateConstraint(data);
+    expect(v.valid, JSON.stringify(v.errors)).toBe(true);
+  });
+});

package/src/constraint/__tests__/validate.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest';
+import { validateConstraint } from '../validate.js';
+import type { CanonCatalog } from '../../typed-id.js';
+
+function valid(): Record<string, unknown> {
+  return {
+    notation: 'constraint',
+    id: 'CONSTRAINT-GDPR-RESIDENCY-1',
+    name: 'EU customer personal data must be stored within EU/EEA jurisdictions',
+    statement: 'Personal data of EU customers MUST NOT be persisted outside EU / EEA jurisdictions.',
+    status: 'active',
+    zone: 'canon',
+    admitted_at: '2026-05-29',
+    admitted_by: 'v.korobeinikov',
+    gate_checks: { uniqueness: 'pass', consistency: 'pass', completeness: 'pass' },
+    valid_from: '2018-05-25',
+    valid_to: null,
+    severity: 'mandatory',
+    owner_role: 'ROLE-DPO-1',
+    applies_to: ['APPLICATION-CRM-1'],
+  };
+}
+
+const codes = (input: unknown, opts?: Parameters<typeof validateConstraint>[1]): string[] =>
+  validateConstraint(input, opts).errors.map((e) => e.code);
+
+describe('validateConstraint — positive', () => {
+  it('accepts a well-formed constraint', () => {
+    const r = validateConstraint(valid());
+    expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+  });
+});
+
+describe('validateConstraint — CONST-001', () => {
+  it('flags missing required fields and wrong notation', () => {
+    const r = valid();
+    delete r.statement;
+    expect(codes(r)).toContain('CONST-001');
+    expect(codes({ ...valid(), notation: 'requirement' })).toContain('CONST-001');
+    expect(codes({ ...valid(), id: 'CONSTRAINT-001' })).toContain('CONST-001');
+  });
+});
+
+describe('validateConstraint — CONST-002/003', () => {
+  it('flags invalid status and severity', () => {
+    expect(codes({ ...valid(), status: 'enabled' })).toContain('CONST-002');
+    expect(codes({ ...valid(), severity: 'critical' })).toContain('CONST-003');
+  });
+});
+
+describe('validateConstraint — CONST-004/005 (catalog)', () => {
+  it('flags unresolved applies_to and owner_role with catalog', () => {
+    const catalog: CanonCatalog = { typeOf: () => undefined };
+    expect(codes(valid(), { catalog })).toContain('CONST-004');
+    expect(codes(valid(), { catalog })).toContain('CONST-005');
+  });
+
+  it('does not flag CONST-004 without catalog for well-formed applies_to', () => {
+    expect(codes(valid())).not.toContain('CONST-004');
+  });
+
+  it('resolves applies_to when catalogue admits the target', () => {
+    const catalog: CanonCatalog = {
+      typeOf: (id) => (id === 'APPLICATION-CRM-1' ? 'APPLICATION' : id === 'ROLE-DPO-1' ? 'ROLE' : undefined),
+    };
+    expect(validateConstraint(valid(), { catalog }).valid).toBe(true);
+  });
+});

package/src/constraint/index.ts

@@ -0,0 +1,4 @@
+export { CONSTRAINT_STATUSES, CONSTRAINT_SEVERITIES } from './types.js';
+export type { ConstraintStatus, ConstraintSeverity } from './types.js';
+export { validateConstraint } from './validate.js';
+export type { ConstraintValidateOptions } from './validate.js';

package/src/constraint/types.ts

@@ -0,0 +1,5 @@
+export const CONSTRAINT_STATUSES = ['active', 'proposed', 'deprecated', 'retired'] as const;
+export type ConstraintStatus = (typeof CONSTRAINT_STATUSES)[number];
+
+export const CONSTRAINT_SEVERITIES = ['mandatory', 'recommended', 'advisory'] as const;
+export type ConstraintSeverity = (typeof CONSTRAINT_SEVERITIES)[number];

package/src/constraint/validate.ts

@@ -0,0 +1,131 @@
+// CONSTRAINT validator — methodology ELEMENT_PRIMITIVES.md §7.13 (sibling to
+// 15-requirement.md). Implements CONST-001..005 for the compliance suite (#518 C4).
+
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+import { typeOfId, isCanonicalIdOfType, type CanonCatalog } from '../typed-id.js';
+import { CONSTRAINT_STATUSES, CONSTRAINT_SEVERITIES } from './types.js';
+
+export interface ConstraintValidateOptions {
+  /** When provided, CONST-004/005 enforce artefact existence for cross-refs. */
+  catalog?: CanonCatalog;
+}
+
+const REQUIRED_FIELDS = [
+  'notation',
+  'name',
+  'statement',
+  'status',
+  'zone',
+  'admitted_at',
+  'admitted_by',
+  'gate_checks',
+  'valid_from',
+] as const;
+
+export function validateConstraint(
+  input: unknown,
+  options: ConstraintValidateOptions = {},
+): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    errors.push({ code: 'CONST-001', message: 'Constraint must be a YAML mapping.' });
+    return { valid: false, errors, warnings };
+  }
+  const c = input as Record<string, unknown>;
+
+  if (!isCanonicalIdOfType(c.id, 'CONSTRAINT')) {
+    errors.push({
+      code: 'CONST-001',
+      message: `id "${String(c.id)}" must match CONSTRAINT-[<middle>-]<INTEGER>.`,
+      path: 'id',
+    });
+  }
+  if (c.notation !== 'constraint') {
+    errors.push({ code: 'CONST-001', message: 'notation must be the fixed value "constraint".', path: 'notation' });
+  }
+  for (const f of REQUIRED_FIELDS) {
+    if (f === 'notation') continue;
+    if (f === 'gate_checks') {
+      if (c.gate_checks === null || typeof c.gate_checks !== 'object') {
+        errors.push({ code: 'CONST-001', message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
+      }
+      continue;
+    }
+    const v = c[f];
+    if (typeof v !== 'string' || v.trim() === '') {
+      errors.push({ code: 'CONST-001', message: `${f} is required.`, path: f });
+    }
+  }
+  if (c.zone !== 'canon') {
+    errors.push({ code: 'CONST-001', message: 'zone must be "canon" for a CONSTRAINT.', path: 'zone' });
+  }
+  if (!('valid_to' in c) || !(typeof c.valid_to === 'string' || c.valid_to === null)) {
+    errors.push({ code: 'CONST-001', message: 'valid_to is required (an ISO date string or null).', path: 'valid_to' });
+  }
+
+  const status = typeof c.status === 'string' ? c.status.trim() : '';
+  if (status && !(CONSTRAINT_STATUSES as readonly string[]).includes(status)) {
+    errors.push({
+      code: 'CONST-002',
+      message: `status must be one of ${CONSTRAINT_STATUSES.join(', ')}.`,
+      path: 'status',
+    });
+  }
+
+  if (c.severity !== undefined) {
+    const severity = typeof c.severity === 'string' ? c.severity.trim() : '';
+    if (!severity || !(CONSTRAINT_SEVERITIES as readonly string[]).includes(severity)) {
+      errors.push({
+        code: 'CONST-003',
+        message: `severity must be one of ${CONSTRAINT_SEVERITIES.join(', ')}.`,
+        path: 'severity',
+      });
+    }
+  }
+
+  if (c.applies_to !== undefined) {
+    if (!Array.isArray(c.applies_to)) {
+      errors.push({ code: 'CONST-001', message: 'applies_to must be a list of typed IDs.', path: 'applies_to' });
+    } else {
+      c.applies_to.forEach((ref, i) => {
+        const type = typeOfId(ref);
+        if (!type) {
+          errors.push({
+            code: 'CONST-004',
+            message: `applies_to[${i}] "${String(ref)}" is not a resolvable typed ID.`,
+            path: `applies_to[${i}]`,
+          });
+          return;
+        }
+        if (options.catalog && options.catalog.typeOf(ref as string) === undefined) {
+          errors.push({
+            code: 'CONST-004',
+            message: `applies_to[${i}] "${String(ref)}" does not resolve to an admitted artefact.`,
+            path: `applies_to[${i}]`,
+          });
+        }
+      });
+    }
+  }
+
+  if (c.owner_role !== undefined) {
+    const role = c.owner_role;
+    if (typeof role !== 'string' || !isCanonicalIdOfType(role, 'ROLE')) {
+      errors.push({
+        code: 'CONST-005',
+        message: `owner_role "${String(role)}" must be a typed ROLE id.`,
+        path: 'owner_role',
+      });
+    } else if (options.catalog && options.catalog.typeOf(role) === undefined) {
+      errors.push({
+        code: 'CONST-005',
+        message: `owner_role "${role}" does not resolve to an admitted artefact.`,
+        path: 'owner_role',
+      });
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/fgca/__tests__/parse-canonical.test.ts

@@ -35,6 +35,31 @@ describe('parseCanonicalFGCA', () => {
     expect(r.parsed?.activities).toHaveLength(1);
   });
 
+  it('accepts ACTION-* ids (methodology 1.0) alongside legacy ACTIVITY-*', () => {
+    const r = parseCanonicalFGCA({
+      ...VALID,
+      actions: [
+        { id: 'ACTION-CRM-EU-1', name: 'CRM rollout', changes: ['CHANGE-1'] },
+        { id: 'ACTIVITY-2', name: 'Legacy workstream', changes: ['CHANGE-1'] },
+      ],
+    });
+    expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+    expect(r.parsed?.activities.map((a) => a.id)).toEqual(['ACTION-CRM-EU-1', 'ACTIVITY-2']);
+  });
+
+  it('defaults changes to [] when view_config.layers.changes is off (DGA-in-dgca)', () => {
+    const r = parseCanonicalFGCA({
+      ...VALID,
+      changes: undefined,
+      view_config: { layers: { changes: 'off' } },
+      actions: [
+        { id: 'ACTION-DISCOVERY-1', name: 'Gap assessment', goals: ['GOAL-1'] },
+      ],
+    });
+    expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+    expect(r.parsed?.changes).toEqual([]);
+  });
+
   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');
@@ -198,6 +223,15 @@ describe('parseCanonicalFGA', () => {
     expect(r.parsed?.activities).toHaveLength(1);
   });
 
+  it('accepts ACTION-* ids in FGA mode', () => {
+    const r = parseCanonicalFGA({
+      ...VALID_FGA,
+      actions: [{ id: 'ACTION-GDPR-DSR-WORKFLOW-1', name: 'DSR workflow', goals: ['GOAL-1'] }],
+    });
+    expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+    expect(r.parsed?.activities[0].id).toBe('ACTION-GDPR-DSR-WORKFLOW-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.

package/src/fgca/parse-canonical.ts

@@ -6,7 +6,7 @@
  *
  * - 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`).
+ *   `GOAL-RET-1`, `CHANGE-1`, `ACTION-ONBOARD-1` (legacy `ACTIVITY-*` accepted).
  * - Plural canonical-direction cross-references: `goal.factors`,
  *   `change.goals`, `activity.changes`, `activity.goals`.
  * - Per-notation validation codes `FGCA-001 … FGCA-015`.
@@ -50,7 +50,8 @@ 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+$/;
+// ACTION is canonical since methodology 1.0; ACTIVITY accepted for legacy docs.
+const ACTION_OR_ACTIVITY_ID_RE = /^(ACTION|ACTIVITY)(-[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+$/;
 
@@ -63,6 +64,15 @@ function asObjectArray(v: unknown): Array<Record<string, unknown>> | null {
   return v.map((el) => (el && typeof el === 'object' ? (el as Record<string, unknown>) : null) as Record<string, unknown>);
 }
 
+/** DGA mode (`view_config.layers.changes: off`) may omit the changes layer. */
+function isChangesLayerOff(raw: Record<string, unknown>): boolean {
+  const vc = raw['view_config'];
+  if (!vc || typeof vc !== 'object') return false;
+  const layers = (vc as Record<string, unknown>)['layers'];
+  if (!layers || typeof layers !== 'object') return false;
+  return (layers as Record<string, unknown>)['changes'] === 'off';
+}
+
 
 /**
  * Validate canonical FGCA YAML and, on success, return an internal-form
@@ -114,7 +124,10 @@ export function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult {
 
   const factorsRaw = asObjectArray(raw['factors']);
   const goalsRaw = asObjectArray(raw['goals']);
-  const changesRaw = asObjectArray(raw['changes']);
+  let changesRaw = asObjectArray(raw['changes']);
+  if (changesRaw === null && raw['changes'] === undefined && isChangesLayerOff(raw)) {
+    changesRaw = [];
+  }
   const activitiesRaw = asObjectArray(raw['actions']);
   if (activitiesRaw === null && 'activities' in raw) {
     errors.push({ code: 'FGCA-004', message: '"activities" key is not accepted — rename to "actions"', path: 'actions' });
@@ -177,7 +190,7 @@ export function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult {
   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));
+  activities.forEach((el, i) => checkLayerElement(el, `activities[${i}]`, ACTION_OR_ACTIVITY_ID_RE, activityIds));
 
   if (errors.length > 0) return { valid: false, errors, warnings };
 

package/src/goals/GoalNode.tsx

@@ -1,6 +1,7 @@
 import React, { memo, useState } from 'react';
 import { Handle, Position } from 'reactflow';
 import type { Factor, Goal } from './types.js';
+import { displayGoalId } from './parse-canonical.js';
 import type { ThemeTokens } from './theme.js';
 
 const NODE_WIDTH = 250;
@@ -23,6 +24,7 @@ export interface GoalNodeData {
   onAddChild: (parentId: number, parentLevel: number) => void;
   onDelete: (id: number) => void;
   onToggleCollapse: (id: number) => void;
+  onFactorClick?: (factor: Factor) => void;
 }
 
 const GoalNode = memo(({ data }: { data: GoalNodeData }) => {
@@ -91,7 +93,7 @@ const GoalNode = memo(({ data }: { data: GoalNodeData }) => {
           {goal.name}
         </div>
         <div style={{ fontSize: 10, color: theme.cardMetaColor, marginTop: 2 }}>
-          ID: {goal.id} | Lvl: {goal.level}
+          ID: {displayGoalId(goal)} | Lvl: {goal.level}
           {goal.tag ? ` | #${goal.tag}` : ''}
         </div>
       </div>
@@ -130,6 +132,10 @@ const GoalNode = memo(({ data }: { data: GoalNodeData }) => {
           {(openPanel === 'positive' ? positive : negative).map((f) => (
             <div
               key={f.id}
+              onClick={(e) => {
+                e.stopPropagation();
+                data.onFactorClick?.(f);
+              }}
               style={{
                 background: openPanel === 'positive' ? '#f0fdf4' : '#fef2f2',
                 border: `1px solid ${openPanel === 'positive' ? '#bbf7d0' : '#fecaca'}`,
@@ -138,6 +144,7 @@ const GoalNode = memo(({ data }: { data: GoalNodeData }) => {
                 padding: '4px 6px',
                 fontSize: 10,
                 textAlign: 'left',
+                cursor: data.onFactorClick ? 'pointer' : 'default',
               }}
             >
               <div style={{ fontWeight: 700 }}>{f.name}</div>

package/src/goals/GoalTreeView.tsx

@@ -12,7 +12,7 @@ import ReactFlow, {
   type NodeDragHandler,
 } from 'reactflow';
 import 'reactflow/dist/style.css';
-import type { Goal, GoalTree, GoalTreeLayout, LayoutOptions } from './types.js';
+import type { Factor, Goal, GoalTree, GoalTreeLayout, LayoutOptions } from './types.js';
 import { layoutGoalTree } from './layout.js';
 import { reparent, addChild, deleteWithDescendants, moveToBacklog, restoreFromBacklog } from './mutations.js';
 import type { ThemeTokens } from './theme.js';
@@ -28,9 +28,11 @@ export interface GoalTreeViewProps {
   theme?: ThemeTokens;
   readOnly?: boolean;
   showBacklog?: boolean;
+  defaultBacklogOpen?: boolean;
   showMiniMap?: boolean;
   onChange?: (event: GoalTreeChange) => void;
   onEditRequest?: (goal: Goal) => void;
+  onFactorClick?: (factor: Factor) => void;
 }
 
 export type GoalTreeChange =
@@ -99,13 +101,16 @@ function GoalTreeViewInner({
   theme: themeProp,
   readOnly = false,
   showBacklog = false,
+  defaultBacklogOpen = true,
   showMiniMap = false,
   onChange,
   onEditRequest,
+  onFactorClick,
 }: GoalTreeViewProps): React.ReactElement {
   const theme = useMemo(() => resolveTheme(themeProp), [themeProp]);
   const [collapsedIds, setCollapsedIds] = useState<Set<number>>(new Set());
   const [hoveredId, setHoveredId] = useState<number | null>(null);
+  const [isBacklogOpen, setIsBacklogOpen] = useState(defaultBacklogOpen);
 
   const { canvas: canvasGoals, backlog: backlogGoals } = useMemo(
     () => partitionCanvasAndBacklog(tree.goals),
@@ -179,9 +184,10 @@ function GoalTreeViewInner({
         onAddChild,
         onDelete: onDeleteNode,
         onToggleCollapse,
+        onFactorClick,
       },
     }));
-  }, [layout.nodes, theme, readOnly, hoveredId, collapsedIds, onAddChild, onDeleteNode, onToggleCollapse]);
+  }, [layout.nodes, theme, readOnly, hoveredId, collapsedIds, onAddChild, onDeleteNode, onToggleCollapse, onFactorClick]);
 
   const buildEdges = useCallback((): Edge[] => {
     return layout.edges.map((e) => ({
@@ -286,38 +292,66 @@ function GoalTreeViewInner({
     <div style={{ display: 'flex', width: '100%', height: '100%' }}>
       {showBacklogPanel && (
         <div
-          data-goaltree-backlog-zone
+          {...(isBacklogOpen ? { 'data-goaltree-backlog-zone': true } : {})}
           style={{
-            width: 220,
+            width: isBacklogOpen ? 220 : 28,
             flexShrink: 0,
             borderRight: '1px solid #e2e8f0',
-            padding: 10,
-            overflowY: 'auto',
             background: '#f8fafc',
+            display: 'flex',
+            flexDirection: 'column',
+            position: 'relative',
           }}
         >
-          <div style={{ fontWeight: 700, fontSize: 12, color: '#334155', marginBottom: 8 }}>Backlog</div>
-          {backlogGoals.map((goal) => (
-            <div
-              key={goal.id}
-              draggable={!readOnly}
-              onDragStart={(e) => onBacklogItemDragStart(e, goal.id)}
-              onDoubleClick={() => onEditRequest?.(goal)}
-              title="Drag onto a canvas card to set its parent"
-              style={{
-                padding: 8,
-                marginBottom: 6,
-                background: '#ffffff',
-                border: '1px solid #cbd5e1',
-                borderRadius: 6,
-                fontSize: 11,
-                cursor: readOnly ? 'default' : 'grab',
-              }}
-            >
-              <div style={{ fontWeight: 600 }}>{goal.name}</div>
-              <div style={{ color: '#64748b' }}>Level: {goal.level}</div>
+          <button
+            type="button"
+            aria-label={isBacklogOpen ? 'Collapse backlog' : 'Expand backlog'}
+            title={isBacklogOpen ? 'Collapse backlog' : 'Expand backlog'}
+            onClick={() => setIsBacklogOpen((v) => !v)}
+            style={{
+              alignSelf: 'flex-end',
+              margin: '6px 6px 0 6px',
+              width: 16,
+              height: 16,
+              border: '1px solid #cbd5e1',
+              borderRadius: 4,
+              background: '#ffffff',
+              color: '#64748b',
+              fontSize: 10,
+              lineHeight: '14px',
+              padding: 0,
+              cursor: 'pointer',
+              flexShrink: 0,
+            }}
+          >
+            {isBacklogOpen ? '◀' : '▶'}
+          </button>
+          {isBacklogOpen && (
+            <div style={{ padding: '4px 10px 10px', overflowY: 'auto', flex: 1 }}>
+              <div style={{ fontWeight: 700, fontSize: 12, color: '#334155', marginBottom: 8 }}>Backlog</div>
+              {backlogGoals.map((goal) => (
+                <div
+                  key={goal.id}
+                  draggable={!readOnly}
+                  onDragStart={(e) => onBacklogItemDragStart(e, goal.id)}
+                  onDoubleClick={() => onEditRequest?.(goal)}
+                  title="Drag onto a canvas card to set its parent"
+                  style={{
+                    padding: 8,
+                    marginBottom: 6,
+                    background: '#ffffff',
+                    border: '1px solid #cbd5e1',
+                    borderRadius: 6,
+                    fontSize: 11,
+                    cursor: readOnly ? 'default' : 'grab',
+                  }}
+                >
+                  <div style={{ fontWeight: 600 }}>{goal.name}</div>
+                  <div style={{ color: '#64748b' }}>Level: {goal.level}</div>
+                </div>
+              ))}
             </div>
-          ))}
+          )}
         </div>
       )}