@transitrix/diagrams 1.12.2 → 1.13.0

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

@@ -44,8 +44,13 @@ export declare function isDgcaChangesLayerOff(input: unknown): boolean;
  *        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.
+ * @param progressData Optional map of action ID to progress data (percent + computedAt timestamp).
+ *        Consumed from `__progressData` metadata field if provided there.
  */
-export declare function parseCanonicalFGCA(input: unknown, outOfScopeGoalIds?: Set<string> | null, outOfScopeFactorIds?: Set<string> | null): CanonicalFGCAResult;
+export declare function parseCanonicalFGCA(input: unknown, outOfScopeGoalIds?: Set<string> | null, outOfScopeFactorIds?: Set<string> | null, progressData?: Map<string, {
+    percent: number;
+    computedAt: string;
+}> | null): CanonicalFGCAResult;
 /** On success, the internal-form FGCADoc derived from canonical FGA input. */
 export interface CanonicalFGAResult extends ValidationResult {
     parsed?: FGCADoc;
@@ -69,4 +74,7 @@ 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, outOfScopeGoalIds?: Set<string> | null, outOfScopeFactorIds?: Set<string> | null): CanonicalFGAResult;
+export declare function parseCanonicalFGA(input: unknown, outOfScopeGoalIds?: Set<string> | null, outOfScopeFactorIds?: Set<string> | null, progressData?: Map<string, {
+    percent: number;
+    computedAt: string;
+}> | null): CanonicalFGAResult;

package/dist/fgca/parse-canonical.js

@@ -67,8 +67,10 @@ export function isDgcaChangesLayerOff(input) {
  *        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.
+ * @param progressData Optional map of action ID to progress data (percent + computedAt timestamp).
+ *        Consumed from `__progressData` metadata field if provided there.
  */
-export function parseCanonicalFGCA(input, outOfScopeGoalIds, outOfScopeFactorIds) {
+export function parseCanonicalFGCA(input, outOfScopeGoalIds, outOfScopeFactorIds, progressData) {
     const errors = [];
     const warnings = [];
     if (!input || typeof input !== 'object') {
@@ -271,11 +273,14 @@ export function parseCanonicalFGCA(input, outOfScopeGoalIds, outOfScopeFactorIds
     const internalActivities = activities.map((el, i) => {
         const goalRefs = checkRefArray(el, 'goals', goalIds, GOAL_ID_RE, 'FGCA-011', `actions[${i}]`, outOfScopeGoalIds);
         const typeVal = typeof el['type'] === 'string' ? el['type'] : undefined;
+        const actId = String(el['id']);
+        const progressVal = progressData?.get(actId);
         return {
-            id: String(el['id']),
+            id: actId,
             name: String(el['name'] ?? ''),
             goal_id: goalRefs.length > 0 ? goalRefs[0] : null,
             ...(typeVal !== undefined ? { type: typeVal } : {}),
+            ...(progressVal !== undefined ? { progress: progressVal } : {}),
         };
     });
     // FACTOR.references_constraint grammar check (FGCA-015).
@@ -334,7 +339,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, outOfScopeGoalIds, outOfScopeFactorIds) {
+export function parseCanonicalFGA(input, outOfScopeGoalIds, outOfScopeFactorIds, progressData) {
     if (!input || typeof input !== 'object') {
         return { valid: false, errors: [{ code: 'FGA-001', message: 'document root is not an object' }], warnings: [] };
     }
@@ -361,7 +366,7 @@ export function parseCanonicalFGA(input, outOfScopeGoalIds, outOfScopeFactorIds)
     // 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, outOfScopeGoalIds, outOfScopeFactorIds);
+    const r = parseCanonicalFGCA(synth, outOfScopeGoalIds, outOfScopeFactorIds, progressData);
     const remap = {
         'FGCA-001': 'FGA-001',
         'FGCA-002': 'FGA-002',

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

@@ -22,6 +22,10 @@ export interface FGCAPreviewActivity {
     id: number | string;
     name: string;
     goal_id?: number | string | null;
+    progress?: {
+        percent: number;
+        computedAt: string;
+    };
 }
 /** Structural input the preview layout needs — a subset of the parsed DGCA/DGA doc. */
 export interface FGCAPreviewDoc {
@@ -83,6 +87,13 @@ export interface FGCAPreviewNode {
     y: number;
     label: string;
     col: FGCAPreviewColumn;
+    type?: string;
+    progress?: {
+        percent: number;
+        computedAt: string;
+    };
+    /** Marks a synthesized node (e.g. virtual Change) vs. a real entity. */
+    virtual?: boolean;
 }
 export interface FGCAPreviewEdge {
     sx: number;

package/dist/fgca/preview-layout.js

@@ -232,11 +232,24 @@ export function layoutFGCAPreview(inputDoc, options = {}) {
         ? ['driver', 'goal', 'activity']
         : ['driver', 'goal', 'change', 'activity'];
     const changes = doc.changes ?? [];
+    const coveredActivities = new Set(changes.flatMap(c => c.activity_ids.map(String)));
+    // Synthesize virtual Change nodes for activities without a real Change.
+    // Each virtual node is 1:1 with one activity (not shared across activities).
+    const virtualChanges = [];
+    for (const a of doc.activities) {
+        if (a.goal_id != null && !coveredActivities.has(String(a.id))) {
+            const virtualId = `vchange_activity_${a.id}`;
+            virtualChanges.push({ id: virtualId, activityId: String(a.id), goalId: String(a.goal_id) });
+        }
+    }
     const colItems = {
         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 })),
+        change: [
+            ...changes.map(c => ({ id: `change_${c.id}`, label: c.name })),
+            ...virtualChanges.map(v => ({ id: v.id, label: '–', virtual: true })),
+        ],
+        activity: doc.activities.map(a => ({ id: `activity_${a.id}`, label: a.name, progress: a.progress })),
     };
     // Build predecessor map: for each node, which node IDs in the previous column
     // connect to it from the left. Used for barycenter crossing minimization.
@@ -248,13 +261,17 @@ export function layoutFGCAPreview(inputDoc, options = {}) {
         for (const c of changes) {
             predecessors.set(`change_${c.id}`, [`goal_${c.goal_id}`]);
         }
-        const coveredActs = new Set(changes.flatMap(c => c.activity_ids.map(String)));
+        for (const v of virtualChanges) {
+            predecessors.set(v.id, [`goal_${v.goalId}`]);
+        }
         for (const a of doc.activities) {
             const preds = changes
                 .filter(c => c.activity_ids.map(String).includes(String(a.id)))
                 .map(c => `change_${c.id}`);
-            if (a.goal_id != null && !coveredActs.has(String(a.id)))
-                preds.push(`goal_${a.goal_id}`);
+            const virtualChange = virtualChanges.find(v => v.activityId === String(a.id));
+            if (virtualChange) {
+                preds.push(virtualChange.id);
+            }
             predecessors.set(`activity_${a.id}`, preds);
         }
     }
@@ -295,7 +312,16 @@ export function layoutFGCAPreview(inputDoc, options = {}) {
         const items = ci === 0 ? colItems[col] : barycentricSort(colItems[col], yCenters);
         let y = FGCA_PAD + FGCA_HEADER_H + rowGap;
         for (const item of items) {
-            const node = { id: item.id, x, y, label: item.label, col };
+            const node = {
+                id: item.id,
+                x,
+                y,
+                label: item.label,
+                col,
+                type: item.type,
+                progress: item.progress,
+                virtual: item.virtual,
+            };
             nodes.push(node);
             nodeMap.set(item.id, node);
             yCenters.set(item.id, y + nodeHeight / 2);
@@ -334,12 +360,10 @@ export function layoutFGCAPreview(inputDoc, options = {}) {
         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}`);
-            }
-        }
+        for (const v of virtualChanges)
+            addEdge(`goal_${v.goalId}`, v.id);
+        for (const v of virtualChanges)
+            addEdge(v.id, `activity_${v.activityId}`);
     }
     const maxNodeBottom = nodes.reduce((m, n) => Math.max(m, n.y + nodeHeight), FGCA_PAD + FGCA_HEADER_H + rowGap + nodeHeight);
     const width = FGCA_PAD * 2 + cols.length * colStride - colGap;

package/dist/fgca/types.d.ts

@@ -24,6 +24,10 @@ export interface ActivityItem {
     activity_type_id?: number;
     /** Canonical values: initiative | programme | project | work_package. Unknown values pass through without error. */
     type?: string;
+    progress?: {
+        percent: number;
+        computedAt: string;
+    };
 }
 export interface ActivityTypeItem {
     id: number | string;

package/dist/theme/themes.js

@@ -1,4 +1,4 @@
-import { LAYER_COLORS, LEVEL_COLORS, MATURITY_COLORS, TREE_LEVEL_COLORS, TREE_MATURITY_COLORS, STRUCTURAL, BRAND_EMPHASIS, TYPOGRAPHY, CSS_VAR, getBaseResetCss, } from './tokens.js';
+import { LAYER_COLORS, LEVEL_COLORS, MATURITY_COLORS, TREE_LEVEL_COLORS, TREE_MATURITY_COLORS, VIRTUAL_ENTITY, STRUCTURAL, BRAND_EMPHASIS, TYPOGRAPHY, CSS_VAR, getBaseResetCss, } from './tokens.js';
 const TRANSITRIX_LIGHT = {
     bg: '#ffffff',
     bgSurface: '#f8fafc',
@@ -79,6 +79,7 @@ function diagramVars(variant) {
         `${CSS_VAR.layerGoal}:${lc.goal[variant]}`,
         `${CSS_VAR.layerChange}:${lc.change[variant]}`,
         `${CSS_VAR.layerActivity}:${lc.activity[variant]}`,
+        `${CSS_VAR.virtualEntity}:${VIRTUAL_ENTITY[variant]}`,
         `${CSS_VAR.nodeStroke}:${sc.nodeStroke[variant]}`,
         `${CSS_VAR.edgeStroke}:${sc.edgeStroke[variant]}`,
         `${CSS_VAR.textPrimary}:${sc.textPrimary[variant]}`,
@@ -133,6 +134,7 @@ function diagramClassCss() {
 .layer-goal{fill:var(${cv.layerGoal});}
 .layer-change{fill:var(${cv.layerChange});}
 .layer-activity{fill:var(${cv.layerActivity});}
+.layer-virtual{fill:var(${cv.virtualEntity});stroke-dasharray:4,3;}
 ${levelRules}
 .diagram-edge{stroke:var(${cv.edgeStroke});stroke-width:1.5;fill:none;}
 .arrow-fill{fill:var(${cv.edgeStroke});}

package/dist/theme/tokens.d.ts

@@ -70,6 +70,17 @@ export declare const LAYER_COLORS: {
         readonly hc: "#4ade80";
     };
 };
+/**
+ * Virtual/synthesized entity fill — used for placeholder nodes that represent
+ * absence (e.g. a synthesized Change box when an Action skips straight to its Goal).
+ * Pale neutral tint, distinctly muted from real entity colors; border dashed to
+ * signal non-reality.
+ */
+export declare const VIRTUAL_ENTITY: {
+    readonly light: "#f3f4f6";
+    readonly dark: "#2a3134";
+    readonly hc: "#e2e8f0";
+};
 /**
  * Level fill colors for Goals tree nodes — 8 slots, cycled by level index.
  * A single-hue petrol tint ramp (level-0 lightest/root → level-7 deepest);
@@ -241,6 +252,7 @@ export declare const CSS_VAR: {
     readonly layerGoal: "--ts-layer-goal";
     readonly layerChange: "--ts-layer-change";
     readonly layerActivity: "--ts-layer-activity";
+    readonly virtualEntity: "--ts-virtual-entity";
     readonly nodeStroke: "--ts-node-stroke";
     readonly edgeStroke: "--ts-edge-stroke";
     readonly textPrimary: "--ts-text-primary";

package/dist/theme/tokens.js

@@ -38,6 +38,17 @@ export const LAYER_COLORS = {
     change: { light: '#c7e5ef', dark: '#1a3842', hc: '#60a5fa' },
     activity: { light: '#b4e0ee', dark: '#1a414e', hc: '#4ade80' },
 };
+/**
+ * Virtual/synthesized entity fill — used for placeholder nodes that represent
+ * absence (e.g. a synthesized Change box when an Action skips straight to its Goal).
+ * Pale neutral tint, distinctly muted from real entity colors; border dashed to
+ * signal non-reality.
+ */
+export const VIRTUAL_ENTITY = {
+    light: '#f3f4f6',
+    dark: '#2a3134',
+    hc: '#e2e8f0',
+};
 /**
  * Level fill colors for Goals tree nodes — 8 slots, cycled by level index.
  * A single-hue petrol tint ramp (level-0 lightest/root → level-7 deepest);
@@ -158,6 +169,7 @@ export const CSS_VAR = {
     layerGoal: '--ts-layer-goal',
     layerChange: '--ts-layer-change',
     layerActivity: '--ts-layer-activity',
+    virtualEntity: '--ts-virtual-entity',
     nodeStroke: '--ts-node-stroke',
     edgeStroke: '--ts-edge-stroke',
     textPrimary: '--ts-text-primary',

package/dist/webview/entry.js

@@ -124,7 +124,10 @@ function dispatchValidate(kind, doc) {
                 : Array.isArray(meta['__outOfScopeFactorIds'])
                     ? new Set(meta['__outOfScopeFactorIds'])
                     : undefined;
-            const v = parseCanonicalFGCA(doc, outOfScopeGoalIds, outOfScopeFactorIds);
+            const progressData = meta['__progressData'] instanceof Map
+                ? meta['__progressData']
+                : undefined;
+            const v = parseCanonicalFGCA(doc, outOfScopeGoalIds, outOfScopeFactorIds, progressData);
             const r = emptyResult(kind, v.valid ? 'ok' : 'error');
             r.errors.push(...v.errors);
             r.warnings.push(...v.warnings);
@@ -145,7 +148,10 @@ function dispatchValidate(kind, doc) {
                 : Array.isArray(meta['__outOfScopeFactorIds'])
                     ? new Set(meta['__outOfScopeFactorIds'])
                     : undefined;
-            const v = parseCanonicalFGA(doc, outOfScopeGoalIds, outOfScopeFactorIds);
+            const progressData = meta['__progressData'] instanceof Map
+                ? meta['__progressData']
+                : undefined;
+            const v = parseCanonicalFGA(doc, outOfScopeGoalIds, outOfScopeFactorIds, progressData);
             const r = emptyResult(kind, v.valid ? 'ok' : 'error');
             r.errors.push(...v.errors);
             r.warnings.push(...v.warnings);

package/dist/webview/render-fgca.js

@@ -38,6 +38,7 @@ export function renderFgcaBody(columns, nodes, edges, curvature, entryCurvature,
     const nodeHeight = bodyOptions.nodeHeight ?? FGCA_NODE_H;
     const edgeStyle = bodyOptions.edgeStyle;
     const headerTruncate = Math.max(8, Math.floor((nodeWidth - 16) / 7));
+    const STALENESS_THRESHOLD_MS = 7 * 24 * 60 * 60 * 1000;
     const headerSvg = columns
         .map(({ col, x }) => `<text class="text-header" x="${x + nodeWidth / 2}" y="${PAD + HEADER_H / 2}" text-anchor="middle" dominant-baseline="central">${escXml(truncateLine(COL_LABELS[col], headerTruncate))}</text>`)
         .join('\n');
@@ -47,6 +48,7 @@ export function renderFgcaBody(columns, nodes, edges, curvature, entryCurvature,
     const nodeSvg = nodes
         .map((n) => {
         const entityId = n.id.slice(n.id.indexOf('_') + 1);
+        const nodeClass = n.virtual ? 'diagram-node layer-virtual' : `diagram-node layer-${n.col}`;
         const specs = layoutCenteredEntityText({
             boxX: n.x,
             boxY: n.y,
@@ -58,10 +60,29 @@ export function renderFgcaBody(columns, nodes, edges, curvature, entryCurvature,
             idMaxLines: 1,
         });
         const textSvg = emitCenteredTextSvg(specs, n.x + nodeWidth / 2, escXml);
+        const titleContent = `${escXml(n.label)} (${escXml(entityId)})`;
+        const typeBadge = n.type && n.col === 'activity'
+            ? `<text class="text-id" x="${n.x + nodeWidth - 6}" y="${n.y + 10}" text-anchor="end" dominant-baseline="hanging" font-size="10">${escXml(n.type)}</text>`
+            : '';
+        const progressBadge = n.progress && n.col === 'activity'
+            ? (() => {
+                const computedAt = new Date(n.progress.computedAt);
+                const now = new Date();
+                const isStale = now.getTime() - computedAt.getTime() > STALENESS_THRESHOLD_MS;
+                const className = isStale ? 'text-id' : 'text-id';
+                const opacity = isStale ? ' opacity="0.5"' : '';
+                return `<text class="${className}" x="${n.x + nodeWidth - 6}" y="${n.y + 22}" text-anchor="end" dominant-baseline="hanging" font-size="10"${opacity}>${escXml(n.progress.percent + '%')}</text>`;
+            })()
+            : '';
         return [
-            `<rect class="diagram-node layer-${n.col}" x="${n.x}" y="${n.y}" width="${nodeWidth}" height="${nodeHeight}" rx="8"/>`,
+            `<g>`,
+            `<title>${titleContent}</title>`,
+            `<rect class="${nodeClass}" x="${n.x}" y="${n.y}" width="${nodeWidth}" height="${nodeHeight}" rx="8"/>`,
             textSvg,
-        ].join('\n');
+            typeBadge,
+            progressBadge,
+            `</g>`,
+        ].filter(Boolean).join('\n');
     })
         .join('\n');
     return `${headerSvg}\n${nodeSvg}\n${edgeSvg}`;

package/dist/webview/render-goals.js

@@ -92,7 +92,12 @@ export function renderGoalsLayoutSvg(layout, options = {}) {
             idMaxLines: 1,
         });
         const textSvg = emitCenteredTextSvg(specs, x + n.width / 2, escXml);
+        const titleParts = [escXml(labelText), escXml(idText)];
+        if (n.data.level !== undefined)
+            titleParts.push(`level ${n.data.level}`);
+        const titleContent = titleParts.join(' — ');
         return `<g>
+  <title>${titleContent}</title>
   <rect class="diagram-node level-${level}" x="${x}" y="${y}" width="${n.width}" height="${n.height}" rx="${ENTITY_NODE_RX}"/>
   ${textSvg}
 </g>`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transitrix/diagrams",
-  "version": "1.12.2",
+  "version": "1.13.0",
   "type": "module",
   "description": "Shared rendering, validation, and pure mutations for Transitrix custom diagram formats.",
   "license": "MIT",

package/src/fgca/parse-canonical.ts

@@ -89,11 +89,14 @@ export function isDgcaChangesLayerOff(input: unknown): boolean {
  *        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.
+ * @param progressData Optional map of action ID to progress data (percent + computedAt timestamp).
+ *        Consumed from `__progressData` metadata field if provided there.
  */
 export function parseCanonicalFGCA(
   input: unknown,
   outOfScopeGoalIds?: Set<string> | null,
   outOfScopeFactorIds?: Set<string> | null,
+  progressData?: Map<string, { percent: number; computedAt: string }> | null,
 ): CanonicalFGCAResult {
   const errors: ValidationError[] = [];
   const warnings: ValidationWarning[] = [];
@@ -322,11 +325,14 @@ export function parseCanonicalFGCA(
   const internalActivities: ActivityItem[] = activities.map((el, i) => {
     const goalRefs = checkRefArray(el!, 'goals', goalIds, GOAL_ID_RE, 'FGCA-011', `actions[${i}]`, outOfScopeGoalIds);
     const typeVal = typeof el!['type'] === 'string' ? el!['type'] : undefined;
+    const actId = String(el!['id']);
+    const progressVal = progressData?.get(actId);
     return {
-      id: String(el!['id']),
+      id: actId,
       name: String(el!['name'] ?? ''),
       goal_id: goalRefs.length > 0 ? goalRefs[0] : null,
       ...(typeVal !== undefined ? { type: typeVal } : {}),
+      ...(progressVal !== undefined ? { progress: progressVal } : {}),
     };
   });
 
@@ -400,6 +406,7 @@ export function parseCanonicalFGA(
   input: unknown,
   outOfScopeGoalIds?: Set<string> | null,
   outOfScopeFactorIds?: Set<string> | null,
+  progressData?: Map<string, { percent: number; computedAt: string }> | null,
 ): CanonicalFGAResult {
   if (!input || typeof input !== 'object') {
     return { valid: false, errors: [{ code: 'FGA-001', message: 'document root is not an object' }], warnings: [] };
@@ -428,7 +435,7 @@ export function parseCanonicalFGA(
   // 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, outOfScopeGoalIds, outOfScopeFactorIds);
+  const r = parseCanonicalFGCA(synth, outOfScopeGoalIds, outOfScopeFactorIds, progressData);
   const remap: Record<string, string> = {
     'FGCA-001': 'FGA-001',
     'FGCA-002': 'FGA-002',

package/src/fgca/preview-layout.ts

@@ -33,6 +33,10 @@ export interface FGCAPreviewActivity {
   id: number | string;
   name: string;
   goal_id?: number | string | null;
+  progress?: {
+    percent: number;
+    computedAt: string;
+  };
 }
 
 /** Structural input the preview layout needs — a subset of the parsed DGCA/DGA doc. */
@@ -304,6 +308,13 @@ export interface FGCAPreviewNode {
   y: number;
   label: string;
   col: FGCAPreviewColumn;
+  type?: string;
+  progress?: {
+    percent: number;
+    computedAt: string;
+  };
+  /** Marks a synthesized node (e.g. virtual Change) vs. a real entity. */
+  virtual?: boolean;
 }
 export interface FGCAPreviewEdge {
   sx: number;
@@ -354,11 +365,26 @@ export function layoutFGCAPreview(
     ? ['driver', 'goal', 'activity']
     : ['driver', 'goal', 'change', 'activity'];
   const changes = doc.changes ?? [];
-  const colItems: Record<FGCAPreviewColumn, Array<{ id: string; label: string }>> = {
+  const coveredActivities = new Set(changes.flatMap(c => c.activity_ids.map(String)));
+
+  // Synthesize virtual Change nodes for activities without a real Change.
+  // Each virtual node is 1:1 with one activity (not shared across activities).
+  const virtualChanges: Array<{ id: string; activityId: string; goalId: string }> = [];
+  for (const a of doc.activities) {
+    if (a.goal_id != null && !coveredActivities.has(String(a.id))) {
+      const virtualId = `vchange_activity_${a.id}`;
+      virtualChanges.push({ id: virtualId, activityId: String(a.id), goalId: String(a.goal_id) });
+    }
+  }
+
+  const colItems: Record<FGCAPreviewColumn, Array<{ id: string; label: string; type?: string; progress?: { percent: number; computedAt: string }; virtual?: boolean }>> = {
     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 })),
+    change:   [
+      ...changes.map(c => ({ id: `change_${c.id}`, label: c.name })),
+      ...virtualChanges.map(v => ({ id: v.id, label: '–', virtual: true })),
+    ],
+    activity: doc.activities.map(a => ({ id: `activity_${a.id}`, label: a.name, progress: a.progress })),
   };
 
   // Build predecessor map: for each node, which node IDs in the previous column
@@ -371,12 +397,17 @@ export function layoutFGCAPreview(
     for (const c of changes) {
       predecessors.set(`change_${c.id}`, [`goal_${c.goal_id}`]);
     }
-    const coveredActs = new Set(changes.flatMap(c => c.activity_ids.map(String)));
+    for (const v of virtualChanges) {
+      predecessors.set(v.id, [`goal_${v.goalId}`]);
+    }
     for (const a of doc.activities) {
       const preds = changes
         .filter(c => c.activity_ids.map(String).includes(String(a.id)))
         .map(c => `change_${c.id}`);
-      if (a.goal_id != null && !coveredActs.has(String(a.id))) preds.push(`goal_${a.goal_id}`);
+      const virtualChange = virtualChanges.find(v => v.activityId === String(a.id));
+      if (virtualChange) {
+        preds.push(virtualChange.id);
+      }
       predecessors.set(`activity_${a.id}`, preds);
     }
   } else {
@@ -398,9 +429,9 @@ export function layoutFGCAPreview(
   // Nodes with no predecessors sort last (Infinity barycenter) so they don't
   // displace connected nodes.
   function barycentricSort(
-    items: Array<{ id: string; label: string }>,
+    items: Array<{ id: string; label: string; type?: string; progress?: { percent: number; computedAt: string }; virtual?: boolean }>,
     yCenters: Map<string, number>,
-  ): Array<{ id: string; label: string }> {
+  ): Array<{ id: string; label: string; type?: string; progress?: { percent: number; computedAt: string }; virtual?: boolean }> {
     return [...items].sort((a, b) => {
       const pA = (predecessors.get(a.id) ?? []).map(p => yCenters.get(p) ?? 0).filter(v => v > 0);
       const pB = (predecessors.get(b.id) ?? []).map(p => yCenters.get(p) ?? 0).filter(v => v > 0);
@@ -422,7 +453,16 @@ export function layoutFGCAPreview(
     const items = ci === 0 ? colItems[col] : barycentricSort(colItems[col], yCenters);
     let y = FGCA_PAD + FGCA_HEADER_H + rowGap;
     for (const item of items) {
-      const node: FGCAPreviewNode = { id: item.id, x, y, label: item.label, col };
+      const node: FGCAPreviewNode = {
+        id: item.id,
+        x,
+        y,
+        label: item.label,
+        col,
+        type: item.type,
+        progress: item.progress,
+        virtual: item.virtual,
+      };
       nodes.push(node);
       nodeMap.set(item.id, node);
       yCenters.set(item.id, y + nodeHeight / 2);
@@ -457,12 +497,8 @@ export function layoutFGCAPreview(
   } 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}`);
-      }
-    }
+    for (const v of virtualChanges) addEdge(`goal_${v.goalId}`, v.id);
+    for (const v of virtualChanges) addEdge(v.id, `activity_${v.activityId}`);
   }
 
   const maxNodeBottom = nodes.reduce(

package/src/fgca/types.ts

@@ -25,6 +25,10 @@ export interface ActivityItem {
   activity_type_id?: number;
   /** Canonical values: initiative | programme | project | work_package. Unknown values pass through without error. */
   type?: string;
+  progress?: {
+    percent: number;
+    computedAt: string;
+  };
 }
 
 export interface ActivityTypeItem {

package/src/theme/themes.ts

@@ -4,6 +4,7 @@ import {
   MATURITY_COLORS,
   TREE_LEVEL_COLORS,
   TREE_MATURITY_COLORS,
+  VIRTUAL_ENTITY,
   STRUCTURAL,
   BRAND_EMPHASIS,
   TYPOGRAPHY,
@@ -97,6 +98,7 @@ function diagramVars(variant: 'light' | 'dark' | 'hc'): string {
     `${CSS_VAR.layerGoal}:${lc.goal[variant]}`,
     `${CSS_VAR.layerChange}:${lc.change[variant]}`,
     `${CSS_VAR.layerActivity}:${lc.activity[variant]}`,
+    `${CSS_VAR.virtualEntity}:${VIRTUAL_ENTITY[variant]}`,
     `${CSS_VAR.nodeStroke}:${sc.nodeStroke[variant]}`,
     `${CSS_VAR.edgeStroke}:${sc.edgeStroke[variant]}`,
     `${CSS_VAR.textPrimary}:${sc.textPrimary[variant]}`,
@@ -155,6 +157,7 @@ function diagramClassCss(): string {
 .layer-goal{fill:var(${cv.layerGoal});}
 .layer-change{fill:var(${cv.layerChange});}
 .layer-activity{fill:var(${cv.layerActivity});}
+.layer-virtual{fill:var(${cv.virtualEntity});stroke-dasharray:4,3;}
 ${levelRules}
 .diagram-edge{stroke:var(${cv.edgeStroke});stroke-width:1.5;fill:none;}
 .arrow-fill{fill:var(${cv.edgeStroke});}

package/src/theme/tokens.ts

@@ -42,6 +42,18 @@ export const LAYER_COLORS = {
   activity: { light: '#b4e0ee', dark: '#1a414e', hc: '#4ade80' },
 } as const;
 
+/**
+ * Virtual/synthesized entity fill — used for placeholder nodes that represent
+ * absence (e.g. a synthesized Change box when an Action skips straight to its Goal).
+ * Pale neutral tint, distinctly muted from real entity colors; border dashed to
+ * signal non-reality.
+ */
+export const VIRTUAL_ENTITY = {
+  light: '#f3f4f6',
+  dark:  '#2a3134',
+  hc:    '#e2e8f0',
+} as const;
+
 /**
  * Level fill colors for Goals tree nodes — 8 slots, cycled by level index.
  * A single-hue petrol tint ramp (level-0 lightest/root → level-7 deepest);
@@ -188,6 +200,7 @@ export const CSS_VAR = {
   layerGoal:        '--ts-layer-goal',
   layerChange:      '--ts-layer-change',
   layerActivity:    '--ts-layer-activity',
+  virtualEntity:    '--ts-virtual-entity',
   nodeStroke:       '--ts-node-stroke',
   edgeStroke:       '--ts-edge-stroke',
   textPrimary:      '--ts-text-primary',

package/src/webview/entry.ts

@@ -198,7 +198,10 @@ function dispatchValidate(kind: NotationKind, doc: unknown): RenderResult {
         : Array.isArray(meta['__outOfScopeFactorIds'])
           ? new Set(meta['__outOfScopeFactorIds'] as string[])
           : undefined;
-      const v = parseCanonicalFGCA(doc, outOfScopeGoalIds, outOfScopeFactorIds);
+      const progressData = meta['__progressData'] instanceof Map
+        ? (meta['__progressData'] as Map<string, { percent: number; computedAt: string }>)
+        : undefined;
+      const v = parseCanonicalFGCA(doc, outOfScopeGoalIds, outOfScopeFactorIds, progressData);
       const r = emptyResult(kind, v.valid ? 'ok' : 'error');
       r.errors.push(...v.errors);
       r.warnings.push(...v.warnings);
@@ -219,7 +222,10 @@ function dispatchValidate(kind: NotationKind, doc: unknown): RenderResult {
         : Array.isArray(meta['__outOfScopeFactorIds'])
           ? new Set(meta['__outOfScopeFactorIds'] as string[])
           : undefined;
-      const v = parseCanonicalFGA(doc, outOfScopeGoalIds, outOfScopeFactorIds);
+      const progressData = meta['__progressData'] instanceof Map
+        ? (meta['__progressData'] as Map<string, { percent: number; computedAt: string }>)
+        : undefined;
+      const v = parseCanonicalFGA(doc, outOfScopeGoalIds, outOfScopeFactorIds, progressData);
       const r = emptyResult(kind, v.valid ? 'ok' : 'error');
       r.errors.push(...v.errors);
       r.warnings.push(...v.warnings);

package/src/webview/render-fgca.ts

@@ -63,6 +63,7 @@ export function renderFgcaBody(
   const nodeHeight = bodyOptions.nodeHeight ?? FGCA_NODE_H;
   const edgeStyle = bodyOptions.edgeStyle;
   const headerTruncate = Math.max(8, Math.floor((nodeWidth - 16) / 7));
+  const STALENESS_THRESHOLD_MS = 7 * 24 * 60 * 60 * 1000;
 
   const headerSvg = columns
     .map(({ col, x }) =>
@@ -80,6 +81,7 @@ export function renderFgcaBody(
   const nodeSvg = nodes
     .map((n) => {
       const entityId = n.id.slice(n.id.indexOf('_') + 1);
+      const nodeClass = n.virtual ? 'diagram-node layer-virtual' : `diagram-node layer-${n.col}`;
       const specs = layoutCenteredEntityText({
         boxX: n.x,
         boxY: n.y,
@@ -91,10 +93,29 @@ export function renderFgcaBody(
         idMaxLines: 1,
       });
       const textSvg = emitCenteredTextSvg(specs, n.x + nodeWidth / 2, escXml);
+      const titleContent = `${escXml(n.label)} (${escXml(entityId)})`;
+      const typeBadge = n.type && n.col === 'activity'
+        ? `<text class="text-id" x="${n.x + nodeWidth - 6}" y="${n.y + 10}" text-anchor="end" dominant-baseline="hanging" font-size="10">${escXml(n.type)}</text>`
+        : '';
+      const progressBadge = n.progress && n.col === 'activity'
+        ? (() => {
+            const computedAt = new Date(n.progress.computedAt);
+            const now = new Date();
+            const isStale = now.getTime() - computedAt.getTime() > STALENESS_THRESHOLD_MS;
+            const className = isStale ? 'text-id' : 'text-id';
+            const opacity = isStale ? ' opacity="0.5"' : '';
+            return `<text class="${className}" x="${n.x + nodeWidth - 6}" y="${n.y + 22}" text-anchor="end" dominant-baseline="hanging" font-size="10"${opacity}>${escXml(n.progress.percent + '%')}</text>`;
+          })()
+        : '';
       return [
-        `<rect class="diagram-node layer-${n.col}" x="${n.x}" y="${n.y}" width="${nodeWidth}" height="${nodeHeight}" rx="8"/>`,
+        `<g>`,
+        `<title>${titleContent}</title>`,
+        `<rect class="${nodeClass}" x="${n.x}" y="${n.y}" width="${nodeWidth}" height="${nodeHeight}" rx="8"/>`,
         textSvg,
-      ].join('\n');
+        typeBadge,
+        progressBadge,
+        `</g>`,
+      ].filter(Boolean).join('\n');
     })
     .join('\n');
 

package/src/webview/render-goals.ts

@@ -124,7 +124,11 @@ export function renderGoalsLayoutSvg(layout: GoalTreeLayout, options: RenderGoal
         idMaxLines: 1,
       });
       const textSvg = emitCenteredTextSvg(specs, x + n.width / 2, escXml);
+      const titleParts = [escXml(labelText), escXml(idText)];
+      if (n.data.level !== undefined) titleParts.push(`level ${n.data.level}`);
+      const titleContent = titleParts.join(' — ');
       return `<g>
+  <title>${titleContent}</title>
   <rect class="diagram-node level-${level}" x="${x}" y="${y}" width="${n.width}" height="${n.height}" rx="${ENTITY_NODE_RX}"/>
   ${textSvg}
 </g>`;