@transitrix/diagrams 1.11.0 → 1.12.0

package/dist/activities/validate.js

@@ -199,8 +199,9 @@ export function validateActivities(input) {
             }
         }
         // ACT-011: warn if no duration (duration_days is accepted as an alias)
+        // Network view is unaffected; this is only about CPM/Gantt rendering.
         if ((act.duration === undefined || act.duration === null) && (act.duration_days === undefined || act.duration_days === null)) {
-            warnings.push({ code: 'ACT-011', message: `Activity "${id}" has no duration — cannot participate in CPM analysis`, path });
+            warnings.push({ code: 'ACT-011', message: `Activity "${id}" has no duration — Gantt view and CPM analysis will exclude it. Network view is unaffected.`, path });
         }
     }
     if (errors.length > 0)
@@ -269,7 +270,9 @@ export function validateActivities(input) {
             }
         }
     }
-    // ACT-013: orphan activities (warning only)
+    // ACT-013: orphan activities (warning only). An activity is structurally orphan
+    // if it has no connections to the rest of the graph. Valid connections are:
+    // predecessors, successors, parent, or goals (direct or via delivers_changes).
     const successorIds = new Set();
     for (const a of doc.activities) {
         for (const pred of (a.predecessors ?? []))
@@ -280,10 +283,11 @@ export function validateActivities(input) {
         const hasSuccessors = successorIds.has(a.id);
         const hasGoals = Array.isArray(a.goals) && a.goals.length > 0;
         const hasPredecessors = Array.isArray(a.predecessors) && a.predecessors.length > 0;
-        if (doc.activities.length > 1 && !hasSuccessors && !hasGoals && !hasPredecessors) {
+        const hasParent = typeof a.parent === 'string' && a.parent.length > 0;
+        if (doc.activities.length > 1 && !hasSuccessors && !hasGoals && !hasPredecessors && !hasParent) {
             warnings.push({
                 code: 'ACT-013',
-                message: `Activity "${a.id}" appears to be structurally orphan (no predecessors, successors, or goals)`,
+                message: `Activity "${a.id}" appears to be structurally orphan (no predecessors, successors, parent, or goals)`,
                 path: `activities[${i}]`,
             });
         }

package/dist/fgca/parse-canonical.d.ts

@@ -28,17 +28,29 @@ import type { ValidationResult } from '../validation-types.js';
 export interface CanonicalFGCAResult extends ValidationResult {
     /** On success, the internal-form FGCADoc derived from the canonical input. */
     parsed?: FGCADoc;
+    /** True when a goal-scoped projection should show the scope caption. */
+    scopeCaption?: boolean;
 }
 /** DGA mode (`view_config.layers.changes: off`) omits the Changes column. */
 export declare function isDgcaChangesLayerOff(input: unknown): boolean;
 /**
  * Validate canonical FGCA YAML and, on success, return an internal-form
  * `FGCADoc` ready for `buildFGCALayout`.
+ *
+ * @param input The FGCA document to parse
+ * @param outOfScopeGoalIds When a goal-scoped projection omits goals that exist
+ *        in the catalogue, pass their IDs here to suppress FGCA-011/FGCA-009 errors
+ *        for references to out-of-scope goals. When provided and non-empty, and at least
+ *        one action or change references an out-of-scope goal, `scopeCaption` is set true.
+ * @param outOfScopeFactorIds When a goal-scoped projection omits factors that exist
+ *        in the catalogue, pass their IDs here to suppress FGCA-008 errors.
  */
-export declare function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult;
+export declare function parseCanonicalFGCA(input: unknown, outOfScopeGoalIds?: Set<string> | null, outOfScopeFactorIds?: Set<string> | null): CanonicalFGCAResult;
 /** On success, the internal-form FGCADoc derived from canonical FGA input. */
 export interface CanonicalFGAResult extends ValidationResult {
     parsed?: FGCADoc;
+    /** True when a goal-scoped projection should show the scope caption. */
+    scopeCaption?: boolean;
 }
 /**
  * Canonical-form FGA parser + validator.
@@ -57,4 +69,4 @@ export interface CanonicalFGAResult extends ValidationResult {
  * the canonical FGA path is unit-testable and the library owns the single
  * canon shape — flat form only, no `fga:` wrapper.
  */
-export declare function parseCanonicalFGA(input: unknown): CanonicalFGAResult;
+export declare function parseCanonicalFGA(input: unknown, outOfScopeGoalIds?: Set<string> | null, outOfScopeFactorIds?: Set<string> | null): CanonicalFGAResult;

package/dist/fgca/parse-canonical.js

@@ -59,8 +59,16 @@ export function isDgcaChangesLayerOff(input) {
 /**
  * Validate canonical FGCA YAML and, on success, return an internal-form
  * `FGCADoc` ready for `buildFGCALayout`.
+ *
+ * @param input The FGCA document to parse
+ * @param outOfScopeGoalIds When a goal-scoped projection omits goals that exist
+ *        in the catalogue, pass their IDs here to suppress FGCA-011/FGCA-009 errors
+ *        for references to out-of-scope goals. When provided and non-empty, and at least
+ *        one action or change references an out-of-scope goal, `scopeCaption` is set true.
+ * @param outOfScopeFactorIds When a goal-scoped projection omits factors that exist
+ *        in the catalogue, pass their IDs here to suppress FGCA-008 errors.
  */
-export function parseCanonicalFGCA(input) {
+export function parseCanonicalFGCA(input, outOfScopeGoalIds, outOfScopeFactorIds) {
     const errors = [];
     const warnings = [];
     if (!input || typeof input !== 'object') {
@@ -173,8 +181,10 @@ export function parseCanonicalFGCA(input) {
     activities.forEach((el, i) => checkLayerElement(el, `activities[${i}]`, ACTION_OR_ACTIVITY_ID_RE, activityIds));
     if (errors.length > 0)
         return { valid: false, errors, warnings };
+    // Track if any out-of-scope goals/factors are referenced (for scope caption).
+    let hasOutOfScopeRef = false;
     // Cross-refs.
-    function checkRefArray(el, field, targets, refRe, code, path) {
+    function checkRefArray(el, field, targets, refRe, code, path, outOfScope) {
         const ref = el[field];
         if (ref === undefined || ref === null)
             return [];
@@ -192,6 +202,12 @@ export function parseCanonicalFGCA(input) {
                 errors.push({ code: 'FGCA-007', message: `${path}.${field}[] entry "${r}" does not match the expected grammar`, path });
                 continue;
             }
+            if (outOfScope?.has(r)) {
+                // Reference is out-of-scope: suppress error and mark that we found an out-of-scope reference (for caption).
+                hasOutOfScopeRef = true;
+                out.push(r);
+                continue;
+            }
             if (!targets.has(r)) {
                 errors.push({ code, message: `${path}.${field}[] references undeclared element "${r}"`, path });
                 continue;
@@ -208,7 +224,7 @@ export function parseCanonicalFGCA(input) {
         name: String(el['name'] ?? ''),
     }));
     const internalGoals = goals.map((el, i) => {
-        const refIds = checkRefArray(el, 'factors', factorIds, FACTOR_OR_DRIVER_ID_RE, 'FGCA-008', `goals[${i}]`);
+        const refIds = checkRefArray(el, 'factors', factorIds, FACTOR_OR_DRIVER_ID_RE, 'FGCA-008', `goals[${i}]`, outOfScopeFactorIds);
         return {
             id: String(el['id']),
             name: String(el['name'] ?? ''),
@@ -233,7 +249,7 @@ export function parseCanonicalFGCA(input) {
         }
     }
     const internalChanges = changes.map((el, i) => {
-        const goalRefs = checkRefArray(el, 'goals', goalIds, GOAL_ID_RE, 'FGCA-009', `changes[${i}]`);
+        const goalRefs = checkRefArray(el, 'goals', goalIds, GOAL_ID_RE, 'FGCA-009', `changes[${i}]`, outOfScopeGoalIds);
         // 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) {
@@ -253,7 +269,7 @@ export function parseCanonicalFGCA(input) {
         };
     });
     const internalActivities = activities.map((el, i) => {
-        const goalRefs = checkRefArray(el, 'goals', goalIds, GOAL_ID_RE, 'FGCA-011', `actions[${i}]`);
+        const goalRefs = checkRefArray(el, 'goals', goalIds, GOAL_ID_RE, 'FGCA-011', `actions[${i}]`, outOfScopeGoalIds);
         const typeVal = typeof el['type'] === 'string' ? el['type'] : undefined;
         return {
             id: String(el['id']),
@@ -292,7 +308,13 @@ export function parseCanonicalFGCA(input) {
         activities: internalActivities,
         hideChanges: isDgcaChangesLayerOff(raw),
     };
-    return { valid: true, errors, warnings, parsed };
+    return {
+        valid: true,
+        errors,
+        warnings,
+        parsed,
+        scopeCaption: (outOfScopeGoalIds?.size ?? 0) > 0 && hasOutOfScopeRef,
+    };
 }
 const FGA_DOC_ID_RE = /^(FGA|DGA)(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
 /**
@@ -312,7 +334,7 @@ const FGA_DOC_ID_RE = /^(FGA|DGA)(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
  * 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) {
+export function parseCanonicalFGA(input, outOfScopeGoalIds, outOfScopeFactorIds) {
     if (!input || typeof input !== 'object') {
         return { valid: false, errors: [{ code: 'FGA-001', message: 'document root is not an object' }], warnings: [] };
     }
@@ -339,7 +361,7 @@ export function parseCanonicalFGA(input) {
     // codes are remapped on the way out. FGCA-009 / 010 / 014 (changes-related)
     // are unreachable here because `changes` is empty.
     const synth = { ...raw, notation: 'dgca', id: 'DGCA-FROM-DGA-1', changes: [] };
-    const r = parseCanonicalFGCA(synth);
+    const r = parseCanonicalFGCA(synth, outOfScopeGoalIds, outOfScopeFactorIds);
     const remap = {
         'FGCA-001': 'FGA-001',
         'FGCA-002': 'FGA-002',
@@ -359,5 +381,6 @@ export function parseCanonicalFGA(input) {
         errors: r.errors.map((e) => ({ ...e, code: remapCode(e.code) })),
         warnings: r.warnings.map((w) => ({ ...w, code: remapCode(w.code) })),
         parsed: r.parsed,
+        scopeCaption: r.scopeCaption,
     };
 }

package/dist/fgca/resolver.js

@@ -122,6 +122,20 @@ export function resolveFGCA(viewDoc, sources) {
         selectedActivities = [...activityElems.values()].filter((a) => strArray(a[actionChangeLinkField(a)]).some((cid) => selectedChangeIds.has(cid)) ||
             strArray(a['goals']).some((gid) => selectedGoalIds.has(gid)));
     }
+    // Collect out-of-scope goals (exist in catalogue but not in selected set).
+    // Used by the validator to suppress errors for references to goals that exist
+    // but are outside the scope.
+    let outOfScopeGoalIds;
+    if (goalsFilter !== 'all') {
+        // Goal scope is restricted; collect goals that exist but aren't selected.
+        outOfScopeGoalIds = new Set([...goalElems.keys()].filter((id) => !selectedGoalIds.has(id)));
+    }
+    // Collect out-of-scope factors (exist in catalogue but not in selected set).
+    const selectedFactorIds = new Set(selectedFactors.map((f) => str(f['id'])).filter((x) => x !== undefined));
+    let outOfScopeFactorIds;
+    if (goalsFilter !== 'all') {
+        outOfScopeFactorIds = new Set([...factorElems.keys()].filter((id) => !selectedFactorIds.has(id)));
+    }
     return {
         notation: 'dgca',
         id: viewDoc['id'],
@@ -132,5 +146,7 @@ export function resolveFGCA(viewDoc, sources) {
         changes: selectedChanges,
         actions: selectedActivities,
         view_config: viewDoc['view_config'],
+        __outOfScopeGoalIds: outOfScopeGoalIds,
+        __outOfScopeFactorIds: outOfScopeFactorIds,
     };
 }

package/dist/webview/entry.js

@@ -113,22 +113,44 @@ function dispatchValidate(kind, doc) {
             return r;
         }
         case 'dgca': {
-            const v = parseCanonicalFGCA(doc);
+            const meta = (doc ?? {});
+            const outOfScopeGoalIds = meta['__outOfScopeGoalIds'] instanceof Set
+                ? meta['__outOfScopeGoalIds']
+                : Array.isArray(meta['__outOfScopeGoalIds'])
+                    ? new Set(meta['__outOfScopeGoalIds'])
+                    : undefined;
+            const outOfScopeFactorIds = meta['__outOfScopeFactorIds'] instanceof Set
+                ? meta['__outOfScopeFactorIds']
+                : Array.isArray(meta['__outOfScopeFactorIds'])
+                    ? new Set(meta['__outOfScopeFactorIds'])
+                    : undefined;
+            const v = parseCanonicalFGCA(doc, outOfScopeGoalIds, outOfScopeFactorIds);
             const r = emptyResult(kind, v.valid ? 'ok' : 'error');
             r.errors.push(...v.errors);
             r.warnings.push(...v.warnings);
             if (v.valid && v.parsed) {
-                r.svg = renderFgcaSvg(v.parsed, { variant: 'dgca' });
+                r.svg = renderFgcaSvg(v.parsed, { variant: 'dgca', scopeCaption: v.scopeCaption });
             }
             return r;
         }
         case 'dga': {
-            const v = parseCanonicalFGA(doc);
+            const meta = (doc ?? {});
+            const outOfScopeGoalIds = meta['__outOfScopeGoalIds'] instanceof Set
+                ? meta['__outOfScopeGoalIds']
+                : Array.isArray(meta['__outOfScopeGoalIds'])
+                    ? new Set(meta['__outOfScopeGoalIds'])
+                    : undefined;
+            const outOfScopeFactorIds = meta['__outOfScopeFactorIds'] instanceof Set
+                ? meta['__outOfScopeFactorIds']
+                : Array.isArray(meta['__outOfScopeFactorIds'])
+                    ? new Set(meta['__outOfScopeFactorIds'])
+                    : undefined;
+            const v = parseCanonicalFGA(doc, outOfScopeGoalIds, outOfScopeFactorIds);
             const r = emptyResult(kind, v.valid ? 'ok' : 'error');
             r.errors.push(...v.errors);
             r.warnings.push(...v.warnings);
             if (v.valid && v.parsed) {
-                r.svg = renderFgcaSvg(v.parsed, { variant: 'dga' });
+                r.svg = renderFgcaSvg(v.parsed, { variant: 'dga', scopeCaption: v.scopeCaption });
             }
             return r;
         }

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

@@ -41,6 +41,8 @@ export interface RenderFgcaOptions {
     entryCurvature?: number;
     nodeSizePreset?: NodeSizePreset;
     layoutOptions?: Parameters<typeof layoutFGCAPreview>[1];
+    /** Show scope caption when goal-scoped projection omits goals that reference out-of-scope goals. */
+    scopeCaption?: boolean;
 }
 export declare function renderFgcaSvg(doc: FGCADoc, options?: RenderFgcaOptions): string;
 export {};

package/dist/webview/render-fgca.js

@@ -66,7 +66,7 @@ export function renderFgcaBody(columns, nodes, edges, curvature, entryCurvature,
     return `${headerSvg}\n${nodeSvg}\n${edgeSvg}`;
 }
 export function renderFgcaSvg(doc, options = {}) {
-    const { variant = 'dgca', title = '', curvature = DEFAULT_EDGE_CURVATURE, entryCurvature, nodeSizePreset = 'normal', layoutOptions, } = options;
+    const { variant = 'dgca', title = '', curvature = DEFAULT_EDGE_CURVATURE, entryCurvature, nodeSizePreset = 'normal', layoutOptions, scopeCaption = false, } = options;
     const hideChanges = variant === 'dga' || doc.hideChanges === true;
     const nodeSize = resolveDgcaNodeSize(parseNodeSizePreset(nodeSizePreset));
     const { nodes, edges, columns, width, height } = layoutFGCAPreview(doc, {
@@ -85,8 +85,13 @@ export function renderFgcaSvg(doc, options = {}) {
     const titleSvg = title
         ? `<text class="text-header" x="${PAD}" y="${PAD - 6}">${escXml(title)}</text>`
         : '';
+    const captionSvg = scopeCaption
+        ? `<text class="text-caption" x="${PAD}" y="${height + 16}">${escXml('This diagram is shown for the selected goal scope. Actions on it may also serve goals outside that scope.')}</text>`
+        : '';
     const embedCss = generateSvgEmbedCss('transitrix');
-    return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">
+    // Calculate final height including caption if present
+    const finalHeight = scopeCaption ? height + 24 : height;
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${finalHeight}" viewBox="0 0 ${width} ${finalHeight}">
 <style>${embedCss}</style>
 <defs>
   <marker id="arrow" markerWidth="8" markerHeight="8" refX="8" refY="3" orient="auto">
@@ -95,5 +100,6 @@ export function renderFgcaSvg(doc, options = {}) {
 </defs>
 ${titleSvg}
 ${body}
+${captionSvg}
 </svg>`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transitrix/diagrams",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "type": "module",
   "description": "Shared rendering, validation, and pure mutations for Transitrix custom diagram formats.",
   "license": "MIT",
@@ -55,12 +55,12 @@
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.4",
+    "@types/react-dom": "^19.2.5",
     "jsdom": "^29.1.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "reactflow": "^11.11.4",
     "typescript": "^5.0.0",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   }
 }

package/src/activities/validate.ts

@@ -216,8 +216,9 @@ export function validateActivities(input: unknown): ActivityValidationResult {
     }
 
     // ACT-011: warn if no duration (duration_days is accepted as an alias)
+    // Network view is unaffected; this is only about CPM/Gantt rendering.
     if ((act.duration === undefined || act.duration === null) && (act.duration_days === undefined || act.duration_days === null)) {
-      warnings.push({ code: 'ACT-011', message: `Activity "${id}" has no duration — cannot participate in CPM analysis`, path });
+      warnings.push({ code: 'ACT-011', message: `Activity "${id}" has no duration — Gantt view and CPM analysis will exclude it. Network view is unaffected.`, path });
     }
   }
 
@@ -292,7 +293,9 @@ export function validateActivities(input: unknown): ActivityValidationResult {
     }
   }
 
-  // ACT-013: orphan activities (warning only)
+  // ACT-013: orphan activities (warning only). An activity is structurally orphan
+  // if it has no connections to the rest of the graph. Valid connections are:
+  // predecessors, successors, parent, or goals (direct or via delivers_changes).
   const successorIds = new Set<string>();
   for (const a of doc.activities) {
     for (const pred of (a.predecessors ?? [])) successorIds.add(pred);
@@ -302,10 +305,11 @@ export function validateActivities(input: unknown): ActivityValidationResult {
     const hasSuccessors = successorIds.has(a.id);
     const hasGoals = Array.isArray(a.goals) && a.goals.length > 0;
     const hasPredecessors = Array.isArray(a.predecessors) && a.predecessors.length > 0;
-    if (doc.activities.length > 1 && !hasSuccessors && !hasGoals && !hasPredecessors) {
+    const hasParent = typeof a.parent === 'string' && a.parent.length > 0;
+    if (doc.activities.length > 1 && !hasSuccessors && !hasGoals && !hasPredecessors && !hasParent) {
       warnings.push({
         code: 'ACT-013',
-        message: `Activity "${a.id}" appears to be structurally orphan (no predecessors, successors, or goals)`,
+        message: `Activity "${a.id}" appears to be structurally orphan (no predecessors, successors, parent, or goals)`,
         path: `activities[${i}]`,
       });
     }

package/src/fgca/parse-canonical.ts

@@ -41,6 +41,8 @@ import { actionChangeLinkField } from './action-change-ids.js';
 export interface CanonicalFGCAResult extends ValidationResult {
   /** On success, the internal-form FGCADoc derived from the canonical input. */
   parsed?: FGCADoc;
+  /** True when a goal-scoped projection should show the scope caption. */
+  scopeCaption?: boolean;
 }
 
 // Canonical ID grammars per IDS_AND_REFERENCES.md §1. The TYPE prefix
@@ -79,8 +81,20 @@ export function isDgcaChangesLayerOff(input: unknown): boolean {
 /**
  * Validate canonical FGCA YAML and, on success, return an internal-form
  * `FGCADoc` ready for `buildFGCALayout`.
+ *
+ * @param input The FGCA document to parse
+ * @param outOfScopeGoalIds When a goal-scoped projection omits goals that exist
+ *        in the catalogue, pass their IDs here to suppress FGCA-011/FGCA-009 errors
+ *        for references to out-of-scope goals. When provided and non-empty, and at least
+ *        one action or change references an out-of-scope goal, `scopeCaption` is set true.
+ * @param outOfScopeFactorIds When a goal-scoped projection omits factors that exist
+ *        in the catalogue, pass their IDs here to suppress FGCA-008 errors.
  */
-export function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult {
+export function parseCanonicalFGCA(
+  input: unknown,
+  outOfScopeGoalIds?: Set<string> | null,
+  outOfScopeFactorIds?: Set<string> | null,
+): CanonicalFGCAResult {
   const errors: ValidationError[] = [];
   const warnings: ValidationWarning[] = [];
 
@@ -204,6 +218,9 @@ export function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult {
 
   if (errors.length > 0) return { valid: false, errors, warnings };
 
+  // Track if any out-of-scope goals/factors are referenced (for scope caption).
+  let hasOutOfScopeRef = false;
+
   // Cross-refs.
   function checkRefArray(
     el: Record<string, unknown>,
@@ -212,6 +229,7 @@ export function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult {
     refRe: RegExp,
     code: string,
     path: string,
+    outOfScope?: Set<string> | null,
   ): string[] {
     const ref = el[field];
     if (ref === undefined || ref === null) return [];
@@ -229,6 +247,12 @@ export function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult {
         errors.push({ code: 'FGCA-007', message: `${path}.${field}[] entry "${r}" does not match the expected grammar`, path });
         continue;
       }
+      if (outOfScope?.has(r)) {
+        // Reference is out-of-scope: suppress error and mark that we found an out-of-scope reference (for caption).
+        hasOutOfScopeRef = true;
+        out.push(r);
+        continue;
+      }
       if (!targets.has(r)) {
         errors.push({ code, message: `${path}.${field}[] references undeclared element "${r}"`, path });
         continue;
@@ -247,7 +271,7 @@ export function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult {
   }));
 
   const internalGoals: GoalItem[] = goals.map((el, i) => {
-    const refIds = checkRefArray(el!, 'factors', factorIds, FACTOR_OR_DRIVER_ID_RE, 'FGCA-008', `goals[${i}]`);
+    const refIds = checkRefArray(el!, 'factors', factorIds, FACTOR_OR_DRIVER_ID_RE, 'FGCA-008', `goals[${i}]`, outOfScopeFactorIds);
     return {
       id: String(el!['id']),
       name: String(el!['name'] ?? ''),
@@ -275,7 +299,7 @@ export function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult {
   }
 
   const internalChanges: BdnChangeWithActivities[] = changes.map((el, i) => {
-    const goalRefs = checkRefArray(el!, 'goals', goalIds, GOAL_ID_RE, 'FGCA-009', `changes[${i}]`);
+    const goalRefs = checkRefArray(el!, 'goals', goalIds, GOAL_ID_RE, 'FGCA-009', `changes[${i}]`, outOfScopeGoalIds);
     // 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) {
@@ -296,7 +320,7 @@ export function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult {
   });
 
   const internalActivities: ActivityItem[] = activities.map((el, i) => {
-    const goalRefs = checkRefArray(el!, 'goals', goalIds, GOAL_ID_RE, 'FGCA-011', `actions[${i}]`);
+    const goalRefs = checkRefArray(el!, 'goals', goalIds, GOAL_ID_RE, 'FGCA-011', `actions[${i}]`, outOfScopeGoalIds);
     const typeVal = typeof el!['type'] === 'string' ? el!['type'] : undefined;
     return {
       id: String(el!['id']),
@@ -337,7 +361,13 @@ export function parseCanonicalFGCA(input: unknown): CanonicalFGCAResult {
     hideChanges: isDgcaChangesLayerOff(raw),
   };
 
-  return { valid: true, errors, warnings, parsed };
+  return {
+    valid: true,
+    errors,
+    warnings,
+    parsed,
+    scopeCaption: (outOfScopeGoalIds?.size ?? 0) > 0 && hasOutOfScopeRef,
+  };
 }
 
 const FGA_DOC_ID_RE = /^(FGA|DGA)(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
@@ -345,6 +375,8 @@ const FGA_DOC_ID_RE = /^(FGA|DGA)(-[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;
+  /** True when a goal-scoped projection should show the scope caption. */
+  scopeCaption?: boolean;
 }
 
 /**
@@ -364,7 +396,11 @@ export interface CanonicalFGAResult extends ValidationResult {
  * 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 {
+export function parseCanonicalFGA(
+  input: unknown,
+  outOfScopeGoalIds?: Set<string> | null,
+  outOfScopeFactorIds?: Set<string> | null,
+): CanonicalFGAResult {
   if (!input || typeof input !== 'object') {
     return { valid: false, errors: [{ code: 'FGA-001', message: 'document root is not an object' }], warnings: [] };
   }
@@ -392,7 +428,7 @@ export function parseCanonicalFGA(input: unknown): CanonicalFGAResult {
   // codes are remapped on the way out. FGCA-009 / 010 / 014 (changes-related)
   // are unreachable here because `changes` is empty.
   const synth = { ...raw, notation: 'dgca', id: 'DGCA-FROM-DGA-1', changes: [] };
-  const r = parseCanonicalFGCA(synth);
+  const r = parseCanonicalFGCA(synth, outOfScopeGoalIds, outOfScopeFactorIds);
   const remap: Record<string, string> = {
     'FGCA-001': 'FGA-001',
     'FGCA-002': 'FGA-002',
@@ -412,5 +448,6 @@ export function parseCanonicalFGA(input: unknown): CanonicalFGAResult {
     errors: r.errors.map((e) => ({ ...e, code: remapCode(e.code) })),
     warnings: r.warnings.map((w) => ({ ...w, code: remapCode(w.code) })),
     parsed: r.parsed,
+    scopeCaption: r.scopeCaption,
   };
 }

package/src/fgca/resolver.ts

@@ -158,6 +158,28 @@ export function resolveFGCA(
     );
   }
 
+  // Collect out-of-scope goals (exist in catalogue but not in selected set).
+  // Used by the validator to suppress errors for references to goals that exist
+  // but are outside the scope.
+  let outOfScopeGoalIds: Set<string> | undefined;
+  if (goalsFilter !== 'all') {
+    // Goal scope is restricted; collect goals that exist but aren't selected.
+    outOfScopeGoalIds = new Set(
+      [...goalElems.keys()].filter((id) => !selectedGoalIds.has(id)),
+    );
+  }
+
+  // Collect out-of-scope factors (exist in catalogue but not in selected set).
+  const selectedFactorIds = new Set(
+    selectedFactors.map((f) => str(f['id'])).filter((x): x is string => x !== undefined),
+  );
+  let outOfScopeFactorIds: Set<string> | undefined;
+  if (goalsFilter !== 'all') {
+    outOfScopeFactorIds = new Set(
+      [...factorElems.keys()].filter((id) => !selectedFactorIds.has(id)),
+    );
+  }
+
   return {
     notation: 'dgca',
     id: viewDoc['id'],
@@ -168,5 +190,7 @@ export function resolveFGCA(
     changes: selectedChanges,
     actions: selectedActivities,
     view_config: viewDoc['view_config'],
+    __outOfScopeGoalIds: outOfScopeGoalIds,
+    __outOfScopeFactorIds: outOfScopeFactorIds,
   };
 }

package/src/webview/entry.ts

@@ -187,22 +187,44 @@ function dispatchValidate(kind: NotationKind, doc: unknown): RenderResult {
       return r;
     }
     case 'dgca': {
-      const v = parseCanonicalFGCA(doc);
+      const meta = (doc ?? {}) as Record<string, unknown>;
+      const outOfScopeGoalIds = meta['__outOfScopeGoalIds'] instanceof Set
+        ? (meta['__outOfScopeGoalIds'] as Set<string>)
+        : Array.isArray(meta['__outOfScopeGoalIds'])
+          ? new Set(meta['__outOfScopeGoalIds'] as string[])
+          : undefined;
+      const outOfScopeFactorIds = meta['__outOfScopeFactorIds'] instanceof Set
+        ? (meta['__outOfScopeFactorIds'] as Set<string>)
+        : Array.isArray(meta['__outOfScopeFactorIds'])
+          ? new Set(meta['__outOfScopeFactorIds'] as string[])
+          : undefined;
+      const v = parseCanonicalFGCA(doc, outOfScopeGoalIds, outOfScopeFactorIds);
       const r = emptyResult(kind, v.valid ? 'ok' : 'error');
       r.errors.push(...v.errors);
       r.warnings.push(...v.warnings);
       if (v.valid && v.parsed) {
-        r.svg = renderFgcaSvg(v.parsed, { variant: 'dgca' });
+        r.svg = renderFgcaSvg(v.parsed, { variant: 'dgca', scopeCaption: v.scopeCaption });
       }
       return r;
     }
     case 'dga': {
-      const v = parseCanonicalFGA(doc);
+      const meta = (doc ?? {}) as Record<string, unknown>;
+      const outOfScopeGoalIds = meta['__outOfScopeGoalIds'] instanceof Set
+        ? (meta['__outOfScopeGoalIds'] as Set<string>)
+        : Array.isArray(meta['__outOfScopeGoalIds'])
+          ? new Set(meta['__outOfScopeGoalIds'] as string[])
+          : undefined;
+      const outOfScopeFactorIds = meta['__outOfScopeFactorIds'] instanceof Set
+        ? (meta['__outOfScopeFactorIds'] as Set<string>)
+        : Array.isArray(meta['__outOfScopeFactorIds'])
+          ? new Set(meta['__outOfScopeFactorIds'] as string[])
+          : undefined;
+      const v = parseCanonicalFGA(doc, outOfScopeGoalIds, outOfScopeFactorIds);
       const r = emptyResult(kind, v.valid ? 'ok' : 'error');
       r.errors.push(...v.errors);
       r.warnings.push(...v.warnings);
       if (v.valid && v.parsed) {
-        r.svg = renderFgcaSvg(v.parsed, { variant: 'dga' });
+        r.svg = renderFgcaSvg(v.parsed, { variant: 'dga', scopeCaption: v.scopeCaption });
       }
       return r;
     }

package/src/webview/render-fgca.ts

@@ -110,6 +110,8 @@ export interface RenderFgcaOptions {
   entryCurvature?: number;
   nodeSizePreset?: NodeSizePreset;
   layoutOptions?: Parameters<typeof layoutFGCAPreview>[1];
+  /** Show scope caption when goal-scoped projection omits goals that reference out-of-scope goals. */
+  scopeCaption?: boolean;
 }
 
 export function renderFgcaSvg(doc: FGCADoc, options: RenderFgcaOptions = {}): string {
@@ -120,6 +122,7 @@ export function renderFgcaSvg(doc: FGCADoc, options: RenderFgcaOptions = {}): st
     entryCurvature,
     nodeSizePreset = 'normal',
     layoutOptions,
+    scopeCaption = false,
   } = options;
   const hideChanges = variant === 'dga' || doc.hideChanges === true;
   const nodeSize = resolveDgcaNodeSize(parseNodeSizePreset(nodeSizePreset));
@@ -144,9 +147,16 @@ export function renderFgcaSvg(doc: FGCADoc, options: RenderFgcaOptions = {}): st
     ? `<text class="text-header" x="${PAD}" y="${PAD - 6}">${escXml(title)}</text>`
     : '';
 
+  const captionSvg = scopeCaption
+    ? `<text class="text-caption" x="${PAD}" y="${height + 16}">${escXml('This diagram is shown for the selected goal scope. Actions on it may also serve goals outside that scope.')}</text>`
+    : '';
+
   const embedCss = generateSvgEmbedCss('transitrix');
 
-  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">
+  // Calculate final height including caption if present
+  const finalHeight = scopeCaption ? height + 24 : height;
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${finalHeight}" viewBox="0 0 ${width} ${finalHeight}">
 <style>${embedCss}</style>
 <defs>
   <marker id="arrow" markerWidth="8" markerHeight="8" refX="8" refY="3" orient="auto">
@@ -155,5 +165,6 @@ export function renderFgcaSvg(doc: FGCADoc, options: RenderFgcaOptions = {}): st
 </defs>
 ${titleSvg}
 ${body}
+${captionSvg}
 </svg>`;
 }