qgraphflow 0.0.6 → 0.0.7

package/skills/q-flow/scripts/compile-layout.mjs

@@ -1,3 +1,7 @@
+import { routeOrthogonal, placeEdgeLabels } from '../assets/viewer/src/orthogonal-routing.js';
+import { refineDiagramLayout, refineWithLegacySeed, layoutMetrics } from '../assets/viewer/src/layout-refinement.js';
+import { isArchitectureOverview } from '../assets/viewer/src/view-identity.js';
+import { overviewSections, fitArchitectureOverview, overviewLayoutReports } from '../assets/viewer/src/architecture-overview.js';
 import { Worker } from 'node:worker_threads';
 import { createHash } from 'node:crypto';
 import { validateGraph, diagramTypeOf } from './validate-graph.mjs';
@@ -6,11 +10,13 @@ import { stateSymbolX } from '../assets/viewer/src/diagrams/state.js';
 import { minimumNodeSize } from '../assets/viewer/src/layout-measure.js';
 import { graphBounds, occupiedBox, visibleEdgeLabel, groupHeadingBoxes, segmentCrossesBox, createEdgeRoutes } from '../assets/viewer/src/edge-routing.js';
 import { groupHeadingLayout, estimateLabelSize } from '../assets/viewer/src/text-layout.js';
-import { ASPECT_SLACK, LAYOUT_LIMITS, LAYOUT_TARGETS, ratioExcess } from '../assets/viewer/src/layout-spacing.js';
+import { ASPECT_SLACK, LAYOUT_LIMITS, LAYOUT_TARGETS, OVERVIEW_AREA, layeredDirections, layeredDown, layoutLimits, layoutTargets, ratioExcess } from '../assets/viewer/src/layout-spacing.js';
 import { auditLayoutQuality, qualityFailure, requireDiagramQuality } from '../assets/viewer/src/layout-quality.js';
 import { compileSequence } from './compile-sequence.mjs';
+import { templateDraft, templateOf } from '../assets/viewer/src/layout-templates.js';
 
-export const LAYOUT_VERSION = 'adaptive-v2-elkjs-0.11.0';
+import { LAYOUT_VERSION } from '../assets/viewer/src/layout-policy.js';
+export { LAYOUT_VERSION };
 export const CANDIDATE_COUNT = 6;
 // Hang guard for one ELK solve, not a budget for a compile: a slow or busy machine only takes longer.
 export const LAYOUT_TIMEOUT_MS = 30_000;
@@ -19,21 +25,8 @@ export const LAYOUT_TIMEOUT_MS = 30_000;
 // the shape back within the slack win, so the graph's own shape decides between landscape and portrait. Ranked layouts and
 // branching state charts never fold.
 export const FOLD_MAX = 5;
-// Fixed-position ports keep the order their relations were created in, so edge order alone decides which relations cross at
-// a node. When the best candidates still have crossings, a bounded local search moves only the relations that cross: it
-// swaps their ports within a node side, swaps which branch of a decision leaves on which side, and swaps their lanes across
-// fold cuts. A move is kept only when the candidate scores better, so it is deterministic and never worse than the plain
-// result; it stops with no crossings, no gain, or when its evaluation budget is spent. The budget counts evaluations, never
-// time, so a slow or busy machine lays out the same graph the same way; only LAYOUT_TIMEOUT_MS can end a compile, and that
-// is an error, not a different layout.
-export const REFINE_CANDIDATES = 2;
+// Layout and route refinement share a deterministic evaluation budget, not a wall-clock cutoff.
 export const REFINE_EVALUATIONS = 60;
-// Candidates whose width/height ratio is within this factor of the accepted band rank equal on shape, so a crossing is never
-// traded for a slightly better aspect ratio; only a shape beyond it (a long strip) outranks the crossings, and only by a
-// whole SHAPE_STEP, so a strip does not take on crossings for a marginally better ratio.
-export const SHAPE_TIE = 1.3;
-export const SHAPE_STEP = .25;
-export const shapeRank = excess => excess <= SHAPE_TIE ? 1 : Math.ceil(excess / SHAPE_STEP) * SHAPE_STEP;
 const stable = items => [...items].sort((a, b) => (a.layout?.rank ?? 0) - (b.layout?.rank ?? 0) || (a.layout?.order ?? 0) - (b.layout?.order ?? 0) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
 const round = value => +value.toFixed(3);
 const box = item => ({ ...item.position, ...item.size });
@@ -46,7 +39,8 @@ function semanticDigest(graph, migration = []) {
   for (const item of [...model.nodes, ...(model.groups ?? [])]) { delete item.position; delete item.size; }
   for (const edge of model.edges) delete edge.route;
   for (const item of migration) delete [...model.nodes, ...(model.groups ?? [])].find(element => element.id === item.elementId)[item.field];
-  if (model.layout) { delete model.layout.version; delete model.layout.strategy; if (!Object.keys(model.layout).length) delete model.layout; }
+  for (const section of overviewSections(model)) { delete section.position; delete section.size; }
+  if (model.layout) { delete model.layout.version; delete model.layout.strategy; delete model.layout.direction; if (!Object.keys(model.layout).length) delete model.layout; }
   const canonical = value => Array.isArray(value) ? value.map(canonical) : value && typeof value === 'object' ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])])) : value;
   return createHash('sha256').update(JSON.stringify(canonical(model))).digest('hex');
 }
@@ -72,9 +66,11 @@ export function migrateOwnership(graph) {
   return migrated;
 }
 
+const compactArchitecture = graph => diagramTypeOf(graph) === 'architecture' && !graph.groups?.length && !graph.edges.some(edge => edge.source === edge.target) && graph.nodes.some(node => graph.edges.filter(edge => edge.source === node.id).length > 1);
+
 function elkInput(graph, candidate, hints = {}) {
-  const type = diagramTypeOf(graph), diagram = getDiagram(type), down = !['er', 'deployment', 'dataflow', 'usecase'].includes(type);
-  const spacing = LAYOUT_TARGETS.layerGap + [0, 16, 48][candidate % 3];
+  const type = diagramTypeOf(graph), diagram = getDiagram(type), down = (hints.direction ?? layeredDirections(type)[0]) === 'down';
+  const spacing = layoutTargets(diagram).layerGap + [0, 16, 48][candidate % 3];
   const portGap = candidate < 3 ? 24 : 48;
   const feedback = new Set();
   if (['flowchart', 'state'].includes(type)) {
@@ -96,7 +92,7 @@ function elkInput(graph, candidate, hints = {}) {
     'elk.edgeRouting': 'ORTHOGONAL', 'elk.hierarchyHandling': !graph.edges.length && !graph.groups?.length && !graph.nodes.some(node => node.layout?.rank !== undefined || type === 'state' && ['initial', 'final'].includes(node.kind)) ? 'SEPARATE_CHILDREN' : 'INCLUDE_CHILDREN',
     'elk.layered.crossingMinimization.strategy': 'LAYER_SWEEP', 'elk.layered.mergeEdges': 'false',
     'elk.layered.feedbackEdges': String(['flowchart', 'state'].includes(type)),
-    'elk.spacing.nodeNode': String(LAYOUT_TARGETS.nodeGap), 'elk.spacing.componentComponent': String(LAYOUT_TARGETS.nodeGap), 'elk.layered.spacing.nodeNodeBetweenLayers': String(spacing),
+    'elk.spacing.nodeNode': String(layoutTargets(diagram).nodeGap), 'elk.spacing.componentComponent': String(layoutTargets(diagram).nodeGap), 'elk.layered.spacing.nodeNodeBetweenLayers': String(spacing),
     'elk.spacing.portPort': '24',
     'elk.spacing.edgeEdge': String(portGap), 'elk.layered.spacing.edgeEdgeBetweenLayers': String(portGap),
     'elk.spacing.edgeNode': String(Math.max(LAYOUT_TARGETS.edgeNodeGap, diagram.endpointStub ?? LAYOUT_LIMITS.endpoint)), 'elk.layered.spacing.edgeNodeBetweenLayers': String(Math.max(LAYOUT_TARGETS.edgeNodeGap, diagram.endpointStub ?? LAYOUT_LIMITS.endpoint)), 'elk.spacing.edgeLabel': String(LAYOUT_LIMITS.labelGap), 'elk.spacing.labelNode': String(LAYOUT_LIMITS.labelGap),
@@ -105,10 +101,11 @@ function elkInput(graph, candidate, hints = {}) {
     ...(diagram.curvedSelfLoops ? { 'elk.spacing.nodeSelfLoop': '44' } : {})
   };
   const root = { id: '$root', layoutOptions: options, children: [], edges: [] };
+  const inset = layoutLimits(diagram).groupInset;
   const groups = new Map(stable(graph.groups ?? []).map(group => {
     const heading = groupHeadingLayout({ ...group, size: undefined });
     return [group.id, { id: `g:${group.id}`, children: [], layoutOptions: { ...options,
-      'elk.padding': `[top=${heading.height + LAYOUT_LIMITS.groupHeadingGap},left=32,bottom=32,right=32]`,
+      'elk.padding': `[top=${heading.height + LAYOUT_LIMITS.groupHeadingGap},left=${inset},bottom=${inset},right=${inset}]`,
       'elk.nodeSize.constraints': 'MINIMUM_SIZE', 'elk.nodeSize.minimum': `(${heading.width + 64},0)` } }];
   }));
   const ordered = items => hints.nodes ? [...items].sort((a, b) => hints.nodes.indexOf(a.id) - hints.nodes.indexOf(b.id)) : stable(items);
@@ -143,7 +140,7 @@ function elkInput(graph, candidate, hints = {}) {
     root.edges.push({ id: `e:${edge.id}`, sources: [ports[0]], targets: [ports[1]],
       layoutOptions: { 'elk.layered.priority.direction': String(feedback.has(edge.id) ? 1 : 100) },
       // Labels sit on their own line: ELK routes the edge through the label and reserves its size in the layer gap.
-      labels: label ? [{ text: label, ...size, layoutOptions: { 'elk.edgeLabels.placement': 'CENTER', 'elk.edgeLabels.inline': 'true' } }] : [] });
+      labels: label && !(compactArchitecture(graph) && candidate < 3) ? [{ text: label, ...size, layoutOptions: { 'elk.edgeLabels.placement': 'CENTER', 'elk.edgeLabels.inline': 'true' } }] : [] });
   }
   for (const node of nodes.values()) {
     for (const side of ['NORTH', 'EAST', 'SOUTH', 'WEST']) {
@@ -302,7 +299,7 @@ function foldSegments(graph, layers, breaks, { spacing, portGap, laneOrder }, do
     + Math.max(0, ...groups.filter(child => child.parentId === group.id && spread.get(child.id).size > 1).map(room));
   for (const group of groups.filter(group => spread.get(group.id).size > 1)) {
     const first = extents[Math.min(...spread.get(group.id))], last = extents[Math.max(...spread.get(group.id))];
-    first[C] -= room(group); first[cExtent] += room(group); last[cExtent] += LAYOUT_LIMITS.groupInset;
+    first[C] -= room(group); first[cExtent] += room(group); last[cExtent] += layoutLimits(getDiagram(diagramTypeOf(graph))).groupInset;
   }
   // Crossing edges take the channel right after the earlier of their two segments; lanes there are spaced for their labels.
   const crossing = laneOrder ? output.edges.filter(edge => !internal(edge)).sort((a, b) => laneOrder.indexOf(a.id) - laneOrder.indexOf(b.id)) : stable(output.edges.filter(edge => !internal(edge)));
@@ -324,7 +321,7 @@ function foldSegments(graph, layers, breaks, { spacing, portGap, laneOrder }, do
     if (edge.route?.labelAt) edge.route.labelAt = shift(edge.route.labelAt, d);
   }
   // A boundary inside one segment moves with it; a boundary spread over several is rebuilt around its members and children.
-  const inset = LAYOUT_LIMITS.groupInset, done = new Set();
+  const inset = layoutLimits(getDiagram(diagramTypeOf(graph))).groupInset, done = new Set();
   const place = group => {
     if (done.has(group.id)) return; done.add(group.id);
     const children = groups.filter(child => child.parentId === group.id); children.forEach(place);
@@ -387,7 +384,7 @@ function foldSegments(graph, layers, breaks, { spacing, portGap, laneOrder }, do
 function foldedVariants(graph, options) {
   const type = diagramTypeOf(graph);
   if (graph.nodes.some(node => node.layout?.rank !== undefined) || type === 'state' && !stateChain(graph)) return [];
-  const down = !['er', 'deployment', 'dataflow', 'usecase'].includes(type), bounds = graphBounds(graph);
+  const down = layeredDown(type, graph.layout), bounds = graphBounds(graph);
   // Cutting shortens the layer sequence: a top-down layout folds only when too tall, a left-to-right one only when too wide.
   if (down ? bounds.width >= bounds.height : bounds.height >= bounds.width) return [];
   const layers = layersOf(graph, down);
@@ -403,18 +400,10 @@ function foldedVariants(graph, options) {
 
 function candidateScore(graph, audit, index) {
   const bounds = graphBounds(graph, audit.routes), budget = canvasBudgetFor(diagramTypeOf(graph));
-  const routes = [...audit.routes.values()];
-  const length = routes.reduce((sum, route) => sum + route.points.slice(1).reduce((sum, point, i) => sum + Math.hypot(point.x - route.points[i].x, point.y - route.points[i].y), 0), 0);
-  const area = graph.nodes.reduce((sum, node) => { const box = occupiedBox(node, diagramTypeOf(graph)); return sum + box.width * box.height; }, 0);
-  const count = Math.max(1, routes.length), unit = Math.sqrt(area / graph.nodes.length);
-  const crossings = audit.crossings.reduce((sum, item) => sum + item.measured + 2 * item.repeated, 0);
-  const bends = routes.reduce((sum, route) => sum + route.points.length - 2, 0);
-  // Normalize by content, so a small routing improvement cannot justify unlimited whitespace.
-  const cost = bounds.width * bounds.height / area + length / (count * unit) + .25 * bends / count + 4 * crossings / count;
-  // Shapes of one rank compete on crossings, then on the exact distance from the band (every in-band shape scores 1), then
-  // on compactness; a better rank wins first. The type's budget ratio only breaks ties towards its preferred orientation.
+  const { cost, crossings } = layoutMetrics(graph, audit);
   const excess = +aspectExcess(graph, audit.routes).toFixed(2);
-  return [audit.errors.length, shapeRank(excess), crossings, excess, round(cost), budget ? Math.abs(bounds.width / bounds.height - budget.width / budget.height) : 0, index];
+  // The normalized objective is shared with Worker refinement. Aspect and stable candidate ID break ties.
+  return [audit.errors.length, cost, budget ? Math.abs(bounds.width / bounds.height - budget.width / budget.height) : excess, index];
 }
 const compare = (a, b) => { for (let i = 0; i < a.score.length; i++) if (a.score[i] !== b.score[i]) return a.score[i] - b.score[i]; return 0; };
 
@@ -438,6 +427,11 @@ export async function compileGraphLayout(input, { layout = 'auto', timeoutMs = L
     requireDiagramQuality(graph);
     return { graph, report: { version: LAYOUT_VERSION, mode: layout, migration, semantics: semanticReport(graph) } };
   }
+  if (isArchitectureOverview(graph)) {
+    let output;
+    try { output = fitArchitectureOverview(graph, requireDiagramQuality); } catch (error) { throw error.diagnostics ? error : Object.assign(qualityFailure(graph, 'geometry', error.message), { routingReport: error.routingReport }); }
+    return { graph: output, report: { version: LAYOUT_VERSION, mode: layout, template: { structure: templateOf(graph).structure, applied: true, fallback: null }, refinement: overviewLayoutReports.get(output), semantics: semanticReport(output) } };
+  }
   const sequence = getDiagram(diagramTypeOf(graph)).sequence;
   const worker = new Worker(new URL('../assets/layout-dist/worker.mjs', import.meta.url), { execArgv: [] });
   let pending, expired = false;
@@ -448,7 +442,6 @@ export async function compileGraphLayout(input, { layout = 'auto', timeoutMs = L
   const timeout = Math.min(LAYOUT_TIMEOUT_MS, Math.max(1, timeoutMs));
   const candidates = [];
   try {
-    const extras = new WeakMap();
     // Each solve has its own limit; the compile as a whole has none, so load can slow it but never fail it or change its result.
     const post = root => new Promise((resolve, reject) => {
       const timer = setTimeout(() => { expired = true; fail(new Error(`Layout exceeded ${timeout}ms for ${diagramTypeOf(graph)}`)); worker.terminate(); }, timeout);
@@ -456,6 +449,20 @@ export async function compileGraphLayout(input, { layout = 'auto', timeoutMs = L
       worker.postMessage(root);
     });
     const evaluate = (candidate, index, errors = []) => {
+      // New auto layouts obey tiers; preserve mode keeps legacy coordinates and their recorded version.
+      if (diagramTypeOf(candidate) === 'deployment') candidate.layout = { ...candidate.layout, version: LAYOUT_VERSION };
+      if (!sequence && !isArchitectureOverview(candidate)) {
+        candidate.layout = { ...candidate.layout, version: LAYOUT_VERSION };
+        try { placeEdgeLabels(candidate); } catch { /* Routing below must supply an inline corridor. */ }
+      }
+      let routeRefined = false;
+      if (!sequence && (compactArchitecture(candidate) || auditLayoutQuality(candidate).errors.length)) {
+        try {
+          const routed = routeOrthogonal(candidate, { passes: 1, accept: requireDiagramQuality }).graph;
+          const checked = auditLayoutQuality(routed), original = auditLayoutQuality(candidate);
+          if (!checked.errors.length && (original.errors.length || layoutMetrics(routed, checked).cost < layoutMetrics(candidate, original).cost)) { routeRefined = checked.crossings.reduce((s, c) => s + c.measured, 0) < original.crossings.reduce((s, c) => s + c.measured, 0); candidate = routed; }
+        } catch { /* A measured ELK route remains a valid candidate; bounded failures are reported by final refinement. */ }
+      }
       let audit = auditLayoutQuality(candidate);
       if (errors.length) audit = { ...audit, errors: [...errors, ...audit.errors] };
       // ELK can put a label at a legal point crossing. Slide only that label along its own nearest segment.
@@ -477,89 +484,65 @@ export async function compileGraphLayout(input, { layout = 'auto', timeoutMs = L
         }
         edge.route.labelAt = best;
       }
-      return { graph: candidate, errors: audit.errors, diagnostics: audit.diagnostics, score: candidateScore(candidate, audit, index), crossings: audit.crossings, excess: +aspectExcess(candidate, audit.routes).toFixed(2) };
+      return { graph: candidate, ...(routeRefined ? { refined: true } : {}), errors: audit.errors, diagnostics: audit.diagnostics, score: candidateScore(candidate, audit, index), crossings: audit.crossings, excess: +aspectExcess(candidate, audit.routes).toFixed(2) };
     };
     const finish = (index, layered, prepared, hints) => {
       const unfolded = { ...evaluate(layered, index), fold: 0, axis: null };
       // Fold only a shape beyond the band's slack; the unfolded result stays available as the fallback.
-      const variants = !sequence && unfolded.excess > ASPECT_SLACK
-        ? foldedVariants(layered, { spacing: LAYOUT_TARGETS.layerGap + [0, 16, 48][index % 3], stub: prepared.stub, portGap: prepared.portGap, laneOrder: hints.lanes }).map(variant => ({ ...evaluate(variant.graph, index, variant.errors), fold: variant.count, axis: variant.axis })) : [];
-      // Folding exists to fix the shape: among the folds the quality gate accepts within the fold slack of the band, the one
-      // with the fewest crossings wins, then the fewest segments; otherwise the nearest valid shape competes with the
-      // unfolded result.
-      const valid = variants.filter(variant => !variant.errors.length), within = valid.filter(variant => variant.excess <= ASPECT_SLACK);
-      const fold = within.length ? within.reduce((a, b) => b.score[2] < a.score[2] ? b : a) : valid.sort((a, b) => a.excess - b.excess || compare(a, b))[0];
+      const variants = !sequence && !(['class', 'deployment', 'state'].includes(diagramTypeOf(graph))) && (diagramTypeOf(graph) === 'er' || !templateOf(graph)?.arrange || graph.layout?.direction && !graph.layout?.version || graph.layout?.strategy?.includes('-fold')) && unfolded.excess > ASPECT_SLACK
+        ? foldedVariants(layered, { spacing: layoutTargets(getDiagram(diagramTypeOf(graph))).layerGap + [0, 16, 48][index % 3], stub: prepared.stub, portGap: prepared.portGap, laneOrder: hints.lanes }).map(variant => ({ ...evaluate(variant.graph, index, variant.errors), fold: variant.count, axis: variant.axis })) : [];
+      // Folded and continuous paths share the same objective.
+      const fold = variants.filter(variant => !variant.errors.length).sort(compare)[0];
       const chosen = fold && compare(fold, unfolded) < 0 ? fold : unfolded;
-      const candidate = { index, ...chosen, folds: variants.map(variant => ({ axis: variant.axis, count: variant.fold, errors: variant.errors, excess: variant.excess, score: variant.score })) };
-      extras.set(candidate, { layered, prepared, hints });
+      const candidate = { index, ...(hints.direction ? { direction: hints.direction } : {}), ...chosen, folds: variants.map(variant => ({ axis: variant.axis, count: variant.fold, errors: variant.errors, excess: variant.excess, score: variant.score })) };
       return candidate;
     };
     const solve = async (index, hints = {}) => {
       const prepared = sequence ? null : elkInput(graph, index, hints);
-      return finish(index, sequence ? compileSequence(graph, index) : applyElk(graph, await post(prepared.root), prepared), prepared, hints);
-    };
-    // Crossing-directed local search over port order, decision branch sides and fold lanes (see REFINE_EVALUATIONS).
-    const swapped = (list, i, j) => { const next = [...list]; [next[i], next[j]] = [next[j], next[i]]; return next; };
-    const refine = async base => {
-      let best = base, evaluations = 0;
-      const first = extras.get(base);
-      let hints = { ports: new Map(first.prepared.buckets), lanes: stable(graph.edges).map(edge => edge.id), sides: new Map(), nodes: graph.nodes.some(node => node.layout?.order !== undefined) ? undefined : stable(graph.nodes).map(node => node.id) };
-      if (['flowchart', 'state'].includes(diagramTypeOf(graph))) for (const node of stable(graph.nodes.filter(node => ['decision', 'choice'].includes(node.kind)))) {
-        const branches = stable(graph.edges.filter(edge => edge.source === node.id && edge.target !== node.id)).map(edge => edge.id);
-        if (branches.length >= 2) hints.sides.set(node.id, branches);
-      }
-      if (diagramTypeOf(graph) === 'usecase') for (const node of stable(graph.nodes.filter(node => node.kind === 'actor'))) {
-        const incident = stable(graph.edges.filter(edge => edge.source === node.id || edge.target === node.id)).map(edge => edge.id);
-        if (incident.length >= 2) hints.sides.set(node.id, incident);
-      }
-      while (best.score[2] && evaluations < REFINE_EVALUATIONS) {
-        const here = extras.get(best), crossing = [...new Set(best.crossings.flatMap(item => item.elementIds))].sort();
-        const moves = [];
-        for (const id of crossing) {
-          for (const [portId, role] of here.prepared.portRoles) {
-            if (role.edge.id !== id) continue;
-            const key = `n:${role.edge[role.role]}:${role.side}`, list = hints.ports.get(key) ?? [], at = list.indexOf(portId);
-            for (let other = 0; other < list.length; other++) if (other !== at) moves.push({ rerun: true, hints: { ...hints, ports: new Map(hints.ports).set(key, swapped(list, at, other)) } });
-          }
-          for (const [node, branches] of hints.sides) {
-            const at = branches.indexOf(id);
-            if (at >= 0) for (let other = 0; other < branches.length; other++) if (other !== at) moves.push({ rerun: true, hints: { ...hints, sides: new Map(hints.sides).set(node, swapped(branches, at, other)) } });
-          }
-        }
-        if (hints.nodes) {
-          const ends = [...new Set(graph.edges.filter(edge => crossing.includes(edge.id)).flatMap(edge => [edge.source, edge.target]))].sort();
-          for (const a of ends) for (const b of ends) if (a < b && graph.nodes.find(node => node.id === a).groupId === graph.nodes.find(node => node.id === b).groupId) moves.push({ rerun: true, hints: { ...hints, nodes: swapped(hints.nodes, hints.nodes.indexOf(a), hints.nodes.indexOf(b)) } });
-        }
-        if (best.fold) for (const a of crossing) for (const b of crossing) if (a < b) moves.push({ rerun: false, hints: { ...hints, lanes: swapped(hints.lanes, hints.lanes.indexOf(a), hints.lanes.indexOf(b)) } });
-        let improved = false;
-        for (const move of moves) {
-          if (evaluations >= REFINE_EVALUATIONS) break;
-          evaluations++;
-          let next;
-          try { next = move.rerun ? await solve(base.index, move.hints) : finish(base.index, here.layered, here.prepared, move.hints); }
-          catch (error) { if (expired) throw error; continue; }
-          if (compare(next, best) < 0) { best = Object.assign(next, { refined: true }); hints = move.hints; improved = true; break; }
-        }
-        if (!improved) break;
-      }
-      return best;
+      const layered = sequence ? compileSequence(graph, index) : applyElk(graph, await post(prepared.root), prepared);
+      if (hints.direction) layered.layout = { ...layered.layout, direction: hints.direction };
+      return finish(index, layered, prepared, hints);
     };
-    for (let index = 0; index < CANDIDATE_COUNT; index++) {
-      try { candidates.push(await solve(index)); }
+    // A recorded or authored layout.direction pins the direction, so a regenerated view keeps its orientation.
+    const directions = sequence ? [undefined] : graph.layout?.direction ? [graph.layout.direction] : layeredDirections(diagramTypeOf(graph));
+    for (const direction of directions) for (let index = 0; index < CANDIDATE_COUNT; index++) {
+      try { candidates.push(await solve(index, layeredDirections(diagramTypeOf(graph)).length > 1 ? { direction } : {})); }
       catch (error) {
         if (expired) throw error;
         candidates.push({ index, errors: [error.message], diagnostics: qualityFailure(graph, 'geometry', error.message).diagnostics, score: [Infinity, 0, 0, 0, 0, 0, 0, 0, index] });
       }
     }
     candidates.sort(compare);
-    if (!sequence) for (const base of candidates.filter(candidate => !candidate.errors.length && candidate.score[2] > 0).slice(0, REFINE_CANDIDATES)) {
-      candidates[candidates.indexOf(base)] = await refine(base);
+    const template = templateOf(graph), templateAttempts = [], templates = [];
+    if (template?.arrange) for (let variant = 0; variant < 4; variant++) {
+      const draft = templateDraft(graph, variant);
+      if (!draft) break;
+      draft.layout = { ...draft.layout, version: LAYOUT_VERSION, strategy: `template-${template.structure}-${variant}` };
+      try {
+        const routed = routeOrthogonal(draft, { passes: 3, accept: requireDiagramQuality });
+        routed.graph.layout.strategy = `template-${template.structure}-${variant}`;
+        const candidate = { ...evaluate(routed.graph, variant), index: variant };
+        templateAttempts.push({ variant, errors: candidate.errors, cost: layoutMetrics(candidate.graph).cost });
+        if (!candidate.errors.length) templates.push(candidate);
+      } catch (error) { templateAttempts.push({ variant, errors: [error.message] }); }
     }
-    candidates.sort(compare);
-    const best = candidates[0];
+    templates.sort(compare);
+    // All legal layered and template candidates compete on the same normalized objective.
+    const layered = candidates[0];
+    const requiredTemplate = Boolean(template?.arrange && templateDraft(graph) && ['deployment', 'class', 'state', 'usecase', 'dataflow'].includes(diagramTypeOf(graph)));
+    const semanticTemplates = templates.filter(candidate => !candidate.errors.length);
+    const preferred = semanticTemplates.find(candidate => layered.errors.length || compare(candidate, layered) < 0) ?? (!layered.errors.length ? null : semanticTemplates[0]);
+    if (requiredTemplate && !preferred && layered.errors.length) throw qualityFailure(graph, 'geometry', `Semantic template ${template.structure} could not be routed:\n- ${templateAttempts.flatMap(attempt => attempt.errors).join('\n- ')}`);
+    const semanticPreferred = graph.layout?.primaryPath?.length && semanticTemplates.length ? semanticTemplates[0] : preferred;
+    const useTemplate = Boolean(semanticPreferred);
+    const best = useTemplate ? semanticPreferred : layered;
     if (best.errors.length) throw Object.assign(qualityFailure(graph, 'geometry', `No valid layout candidate for ${diagramTypeOf(graph)}:\n- ${best.errors.join('\n- ')}`, best.diagnostics), { diagnosticGraph: best.graph, candidates: candidates.map(({ graph, ...item }) => item) });
-    best.graph.layout = { ...best.graph.layout, version: LAYOUT_VERSION, strategy: `${sequence ? 'sequence' : 'layered'}-${best.index}${best.fold ? `-fold${best.fold}${best.axis === 'columns' ? 'c' : ''}` : ''}` };
-    return { graph: best.graph, report: { version: LAYOUT_VERSION, mode: layout, candidateCount: CANDIDATE_COUNT, timeoutMs: timeout, selected: best.index, migration, semantics: semanticReport(best.graph), candidates: candidates.map(({ graph, ...item }) => item) } };
+    best.graph.layout = { ...best.graph.layout, strategy: `${useTemplate ? `template-${template.structure}` : sequence ? 'sequence' : 'layered'}-${best.index}${best.fold ? `-fold${best.fold}${best.axis === 'columns' ? 'c' : ''}` : ''}` };
+    const refined = refineWithLegacySeed(best.graph, graph, { global: true, evaluations: REFINE_EVALUATIONS, laneAxis: best.fold ? best.axis === 'columns' ? 'x' : 'y' : null });
+    best.graph = refined.graph;
+    best.graph.layout = { ...best.graph.layout, version: LAYOUT_VERSION };
+    requireDiagramQuality(best.graph);
+    return { graph: best.graph, report: { version: LAYOUT_VERSION, mode: layout, template: template && { structure: template.structure, applied: Boolean(useTemplate || sequence), fallback: useTemplate || sequence ? null : templates.length ? 'lower-normalized-cost' : graph.layout?.direction ? 'authored-direction' : 'routing-quality', attempts: templateAttempts }, refinement: refined.report, candidateCount: CANDIDATE_COUNT, timeoutMs: timeout, selected: best.index, ...(best.direction ? { direction: best.direction } : {}), migration, semantics: semanticReport(best.graph), candidates: candidates.map(({ graph, ...item }) => item) } };
   } catch (error) { throw error.phases ? error : qualityFailure(graph, 'geometry', error.message); }
   finally { await worker.terminate(); }
 }

package/skills/q-flow/scripts/compile-sequence.mjs

@@ -2,8 +2,8 @@ import { minimumNodeSize } from '../assets/viewer/src/layout-measure.js';
 import { sequenceHeaderHeight } from '../assets/viewer/src/diagrams/sequence.js';
 import { operandId, operandEdges, fragmentDepth, fragmentHeadingLayout } from '../assets/viewer/src/sequence-fragments.js';
 import { createEdgeRoutes } from '../assets/viewer/src/edge-routing.js';
-import { sequenceMessageLabel, sequenceExecutions } from '../assets/viewer/src/sequence-executions.js';
-import { edgeLabelLayout, layoutText } from '../assets/viewer/src/text-layout.js';
+import { sequenceMessageLabel, sequenceExecutions, spreadParticipants } from '../assets/viewer/src/sequence-executions.js';
+import { layoutText } from '../assets/viewer/src/text-layout.js';
 import { LAYOUT_LIMITS, LAYOUT_TARGETS } from '../assets/viewer/src/layout-spacing.js';
 
 export function compileSequence(input, candidate) {
@@ -13,7 +13,7 @@ export function compileSequence(input, candidate) {
   for (const edge of [...graph.edges].sort((a, b) => a.order - b.order)) for (const id of [edge.source, edge.target]) if (!firstSeen.has(id)) firstSeen.set(id, firstSeen.size);
   const ordered = graph.layout?.participantOrder ?? [...graph.nodes].sort((a, b) => (a.layout?.order ?? 0) - (b.layout?.order ?? 0) || (firstSeen.get(a.id) ?? Infinity) - (firstSeen.get(b.id) ?? Infinity) || (a.id < b.id ? -1 : 1)).map(node => node.id);
   const nodes = ordered.map(id => graph.nodes.find(node => node.id === id));
-  const spacing = LAYOUT_TARGETS.nodeGap + candidate * 8, gap = LAYOUT_LIMITS.labelGap + candidate * 4;
+  const spacing = 32 + candidate * 8, gap = 12 + candidate * 4;
   const guardText = (group, operand) => group.kind === 'par' ? operand.label : `${group.kind === 'loop' ? `${group.loop.min}..${group.loop.max} ` : ''}[${operand.guard}]`;
   const guardLayout = (group, operand) => layoutText(guardText(group, operand), LAYOUT_TARGETS.labelWidth, 14, 20);
   const bodyLayout = operand => layoutText(operand.body, LAYOUT_TARGETS.labelWidth, 16, 24);
@@ -22,24 +22,7 @@ export function compileSequence(input, candidate) {
     node.size = minimumNodeSize(node, 'sequence', graph.meta.locale); node.position = { x, y: 48 };
     x += node.size.width + spacing;
   }
-  // Difference constraints on the message's actual span; moving the suffix keeps
-  // unrelated neighboring gaps unchanged. Longer spans reuse existing space.
-  const constraints = [...graph.edges].sort((a, b) => Math.abs(ordered.indexOf(a.source) - ordered.indexOf(a.target)) - Math.abs(ordered.indexOf(b.source) - ordered.indexOf(b.target)) || a.order - b.order);
-  const selfCounts = new Map();
-  for (const edge of constraints) {
-    const left = Math.min(ordered.indexOf(edge.source), ordered.indexOf(edge.target));
-    let right = Math.max(ordered.indexOf(edge.source), ordered.indexOf(edge.target));
-    const label = edgeLabelLayout(sequenceMessageLabel(graph, edge));
-    let required = label.width + 64;
-    if (left === right) {
-      const ordinal = selfCounts.get(edge.source) ?? 0; selfCounts.set(edge.source, ordinal + 1);
-      right++; required += 48 + ordinal * 24;
-      if (right === nodes.length) continue;
-    }
-    const center = node => node.position.x + node.size.width / 2;
-    const extra = Math.max(0, required - (center(nodes[right]) - center(nodes[left])));
-    for (let i = right; i < nodes.length; i++) nodes[i].position.x += extra;
-  }
+  spreadParticipants(graph, nodes);
   // Provisional order-preserving times let the shared router measure actual
   // prefixes, activation offsets, wrapped labels and self calls.
   for (const edge of graph.edges) edge.route = { messageY: 200 + edge.order * 100 };

package/skills/q-flow/scripts/generate-viewer.mjs

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 
+import { viewIdOf } from '../assets/viewer/src/view-identity.js';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { parseArgs } from 'node:util';
-import { diagramTypeOf, graphsOf, printCompositionReview, readAndValidateGraph, verifySourceEvidence, layoutComposition } from './validate-graph.mjs';
+import { isDeepStrictEqual, parseArgs } from 'node:util';
+import { diagramTypeOf, graphsOf, printCompositionReview, printViewReview, readAndValidateGraph, verifySourceEvidence, layoutComposition } from './validate-graph.mjs';
 import { compileGraphLayout } from './compile-layout.mjs';
 import { requireDiagramQuality } from '../assets/viewer/src/layout-quality.js';
 import { pageWithGraph } from '../assets/viewer/src/session-graph.js';
@@ -38,7 +39,7 @@ export function writeOutputs(outputDir, contents, stale = []) {
 }
 
 // Every view is compiled before anything is judged, so one run names every failing view instead of the first one only.
-// A single failure is rethrown untouched; several are combined, their diagnostics concatenated and candidates keyed by type.
+// A single failure is rethrown untouched; several are combined, their diagnostics concatenated and candidates and routing reports keyed by view identity.
 export async function compileViews(graphs, compile) {
   const compiled = [], failures = [];
   for (const graph of graphs) {
@@ -50,8 +51,9 @@ export async function compileViews(graphs, compile) {
     throw Object.assign(new Error(failures.map(({ error }) => error.message).join('\n\n')), {
       phases: { semantic: { status: phase === 'semantic' ? 'failed' : 'passed' }, geometry: { status: phase === 'semantic' ? 'not-checked' : 'failed' }, rendering: { status: 'not-checked' } },
       diagnostics: failures.flatMap(({ error }) => error.diagnostics ?? []),
-      candidates: Object.fromEntries(failures.filter(({ error }) => error.candidates).map(({ graph, error }) => [diagramTypeOf(graph), error.candidates])),
-      failedViews: failures.map(({ graph }) => diagramTypeOf(graph))
+      candidates: Object.fromEntries(failures.filter(({ error }) => error.candidates).map(({ graph, error }) => [viewIdOf(graph), error.candidates])),
+      failedViews: failures.map(({ graph }) => viewIdOf(graph)),
+      routingReports: Object.fromEntries(failures.filter(({ error }) => error.routingReport).map(({ graph, error }) => [viewIdOf(graph), error.routingReport]))
     });
   }
   return compiled;
@@ -60,6 +62,7 @@ export async function compileViews(graphs, compile) {
 const USAGE = `Usage: node generate-viewer.mjs <graph.json> <output-directory> [options]
   --repo-root <dir>     verify every node source (file, line range, symbol) against this working tree
   --layout auto|preserve  auto (default) computes positions; preserve keeps authored geometry under the same gate
+  --view <view-id>      auto-layout only this view; repeat for several; all other views must pass preserve
   --force               replace existing index.html / graph.json / diagram*.svg in the output directory (needs approval)
   --verbose             print the full receipt (layout candidates, folds, diagnostics) instead of one summary line
   -h, --help            this text
@@ -67,7 +70,7 @@ Writes index.html, graph.json and one SVG per view (diagram.svg, or diagram-<n>-
 Success prints one JSON line; failure prints the failing elements with rule, measurement and remediation.`;
 
 async function main() {
-  const { positionals: positional, values } = parseArgs({ allowPositionals: true, options: { force: { type: 'boolean' }, 'repo-root': { type: 'string' }, layout: { type: 'string', default: 'auto' }, verbose: { type: 'boolean', default: false }, help: { type: 'boolean', short: 'h', default: false } } });
+  const { positionals: positional, values } = parseArgs({ allowPositionals: true, options: { force: { type: 'boolean' }, 'repo-root': { type: 'string' }, layout: { type: 'string', default: 'auto' }, view: { type: 'string', multiple: true }, verbose: { type: 'boolean', default: false }, help: { type: 'boolean', short: 'h', default: false } } });
   const force = values.force;
   if (values.help) { console.log(USAGE); process.exit(0); }
   if (positional.length !== 2) {
@@ -79,6 +82,10 @@ async function main() {
   const outputDir = path.resolve(outputArg);
   if (outputDir === path.parse(outputDir).root || outputDir === os.homedir()) throw new Error('Refusing broad output directory');
   const input = readAndValidateGraph(inputPath, { inputOnly: true });
+  const selected = new Set(values.view ?? []), views = graphsOf(input);
+  if (selected.size && values.layout !== 'auto') throw new Error('--view requires --layout auto');
+  const unknown = [...selected].filter(id => !views.some(graph => viewIdOf(graph) === id));
+  if (unknown.length) throw new Error(`Unknown view: ${unknown.join(', ')}; available views: ${views.map(viewIdOf).join(', ')}`);
   const sourceEvidence = verifySourceEvidence(input, values['repo-root']);
   const warnings = printCompositionReview(input, { print: false }); // already printed by the input validation step
   if (!fs.existsSync(shellPath)) throw new Error(`Viewer shell missing: ${shellPath}`);
@@ -93,9 +100,11 @@ async function main() {
   if (existing.length && !force) throw new Error(`Refusing to overwrite: ${existing.join(', ')}; rerun with --force after approval`);
   const shell = fs.readFileSync(shellPath, 'utf8');
   if (!shell.includes('__CODEGRAPH_FLOW_DATA__')) throw new Error('Viewer shell data marker is missing');
-  const compiled = await compileViews(graphsOf(input), item => compileGraphLayout(item, { layout: values.layout }));
+  const compiled = await compileViews(views, item => compileGraphLayout(item, { layout: selected.size && !selected.has(viewIdOf(item)) ? 'preserve' : values.layout }));
+  for (let i = 0; i < views.length; i++) if (selected.size && !selected.has(viewIdOf(views[i])) && !isDeepStrictEqual(compiled[i].graph, views[i])) throw new Error(`Unselected view ${viewIdOf(views[i])} requires migration; update it explicitly before changing this collection`);
   const quality = compiled.map(item => requireDiagramQuality(item.graph));
   const graph = Array.isArray(input.diagrams) ? { ...input, diagrams: compiled.map(item => item.graph) } : compiled[0].graph;
+  const oversized = printViewReview(graph, { print: true }); // geometry exists only now; the input review could not see it
   const contents = { 'index.html': pageWithGraph(shell, graph), 'graph.json': `${JSON.stringify(graph, null, 2)}\n` };
   for (const { name, svg } of diagramSvgFiles(graph)) contents[name] = svg;
   writeOutputs(outputDir, contents, svgs.filter(name => !Object.hasOwn(contents, name)));
@@ -109,7 +118,7 @@ async function main() {
     edges: graphs.reduce((sum, item) => sum + item.edges.length, 0),
     groups: graphs.reduce((sum, item) => sum + (item.groups?.length ?? 0), 0),
     semantic: { status: status('semantic') }, geometry: { status: status('geometry') }, rendering: { status: status('rendering') },
-    ...(warnings.length ? { warnings: warnings.length } : {})
+    ...(warnings.length + oversized.length ? { warnings: warnings.length + oversized.length } : {})
   };
   const detail = values.verbose ? { layoutComposition: graphs.map(layoutComposition), layout: compiled.map(item => item.report), quality } : {};
   console.log(JSON.stringify(graphs.length === 1 && !Object.hasOwn(graph, 'diagrams')
@@ -121,6 +130,6 @@ if (process.argv[1] && fs.existsSync(process.argv[1]) && fs.realpathSync(process
   await main();
 } catch (error) {
   console.error(error.message);
-  if (error.phases || error.candidates) console.error(JSON.stringify({ ...error.phases, ...(error.failedViews ? { failedViews: error.failedViews } : {}), diagnostics: error.diagnostics, candidates: error.candidates }));
+  if (error.phases || error.candidates) console.error(JSON.stringify({ ...error.phases, ...(error.failedViews ? { failedViews: error.failedViews } : {}), diagnostics: error.diagnostics, candidates: error.candidates, ...(error.routingReport ? { routingReport: error.routingReport } : {}), ...(error.routingReports ? { routingReports: error.routingReports } : {}) }));
   process.exit(1);
 }

package/skills/q-flow/scripts/validate-graph.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { overviewSections } from '../assets/viewer/src/architecture-overview.js';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -7,7 +8,7 @@ import { parseArgs } from 'node:util';
 import { auditGraphLayout, graphBounds } from '../assets/viewer/src/edge-routing.js';
 import { canvasBudgetFor, diagramTypeOf } from '../assets/viewer/src/diagrams/registry.js';
 import { ASPECT_BAND, ASPECT_SLACK, ratioExcess } from '../assets/viewer/src/layout-spacing.js';
-import { graphsOf, reviewComposition, validateGraphInput } from '../assets/viewer/src/graph-validation.js';
+import { graphsOf, needsSite, overviewWarnings, reviewComposition, validateGraphInput } from '../assets/viewer/src/graph-validation.js';
 import { requireDiagramQuality, qualityFailure } from '../assets/viewer/src/layout-quality.js';
 import { operandScopes } from '../assets/viewer/src/sequence-fragments.js';
 import { callsMissingExecutions } from '../assets/viewer/src/sequence-executions.js';
@@ -16,7 +17,7 @@ export { graphsOf, reviewComposition, validateGraph, validateGraphInput } from '
 
 const USAGE = `Usage: node validate-graph.mjs <graph.json> [options]
   --input-only          check semantics only (no geometry); use before generating
-  --repo-root <dir>     verify every node source (file, line range, symbol) against this working tree
+  --repo-root <dir>     verify every node source and edge site (file, line range, symbol) against this working tree
   --fix                 repair mechanical errors in place (sequence order numbering, opt/loop/par operand ids,
                         unambiguous replyTo, the callee activation bar of each answered sync call; with --repo-root,
                         anchor line re-anchoring to a symbol found once in its file); prints each change; writes back
@@ -26,7 +27,8 @@ const USAGE = `Usage: node validate-graph.mjs <graph.json> [options]
 Success prints one JSON line; failure prints the failing elements with rule, measurement and remediation.
 Composition warnings never fail the run; --input-only prints them in full, later steps only count them in the
 receipt. Fix module.missing, module.inconsistent and flowchart.process-branch; module.single-tone asks whether the
-steps really are one subsystem's work.`;
+steps really are one subsystem's work. view.oversized (a view needing over 4 screens at the readable zoom) needs the
+laid-out graph: generate-viewer.mjs prints it, output validation only counts it.`;
 
 export function readAndValidateGraph(inputPath, options = {}) {
   const absolute = path.resolve(inputPath);
@@ -51,10 +53,19 @@ export function readAndValidateGraph(inputPath, options = {}) {
 
 // Warnings only. The full lines print once per delivery — during input validation, where the author repairs the
 // graph; generation and output validation see the same facts again and carry only the count in their receipt.
+const printWarnings = warnings => {
+  for (const warning of warnings) console.warn(`Composition warning (${warning.diagramType}) ${warning.ruleId}: ${warning.message} — ${warning.remediation}`);
+  return warnings;
+};
 export function printCompositionReview(graph, { print = true } = {}) {
   const warnings = reviewComposition(graph);
-  if (print) for (const warning of warnings) console.warn(`Composition warning (${warning.diagramType}) ${warning.ruleId}: ${warning.message} — ${warning.remediation}`);
-  return warnings;
+  return print ? printWarnings(warnings) : warnings;
+}
+
+// The size advisory needs the laid-out graph: generation prints it once, the output check only counts it.
+export function printViewReview(graph, { print = false } = {}) {
+  const warnings = overviewWarnings(graph);
+  return print ? printWarnings(warnings) : warnings;
 }
 
 export function layoutComposition(graph) {
@@ -148,24 +159,24 @@ export function fixGraphFile(inputPath, { repoRoot, ...options } = {}) {
   return { changes, blocked, errors: [], written };
 }
 
-// Re-anchors a drifted node whose symbol occurs exactly once in its file; the range moves with it and keeps its span.
+// Re-anchors a drifted node source or edge site whose symbol occurs exactly once in its file; the range moves with it and keeps its span.
 // Several matches need a judgement about which one is the definition, so they are only reported.
 export function applyAnchorFixes(input, repoRoot) {
   const changes = [], blocked = [], { read } = sourceReader(repoRoot);
   for (const [index, graph] of graphsOf(input).entries()) {
     const prefix = Object.hasOwn(input, 'diagrams') ? `diagrams[${index}].` : '';
-    for (const node of Array.isArray(graph?.nodes) ? graph.nodes : []) {
-      const source = node?.source;
-      if (typeof source?.symbol !== 'string' || !Number.isInteger(source.lineStart)) continue;
+    for (const [kind, key, items] of [['node', 'source', graph?.nodes], ['edge', 'site', graph?.edges]]) for (const item of Array.isArray(items) ? items : []) {
+      const anchor = item?.[key];
+      if (typeof anchor?.symbol !== 'string' || !Number.isInteger(anchor.lineStart)) continue;
       let lines;
-      try { lines = read(source.file); } catch { continue; } // reported by the source evidence check
-      const term = symbolTerm(source.symbol), found = term ? symbolLines(lines, term) : [];
-      if (found.some(line => line >= source.lineStart && line <= (source.lineEnd ?? source.lineStart))) continue;
-      if (found.length !== 1) { blocked.push(`${prefix}node ${node.id}.source not re-anchored: "${term ?? source.symbol}" ${foundAt(found)}`); continue; }
-      const lineEnd = source.lineEnd === undefined ? undefined : Math.min(lines.length, found[0] + source.lineEnd - source.lineStart);
-      changes.push(`${prefix}node ${node.id}.source.lineStart ${source.lineStart} → ${found[0]}${lineEnd === undefined ? '' : `, lineEnd ${source.lineEnd} → ${lineEnd}`}`);
-      source.lineStart = found[0];
-      if (lineEnd !== undefined) source.lineEnd = lineEnd;
+      try { lines = read(anchor.file); } catch { continue; } // reported by the source evidence check
+      const term = symbolTerm(anchor.symbol), found = term ? symbolLines(lines, term) : [];
+      if (found.some(line => line >= anchor.lineStart && line <= (anchor.lineEnd ?? anchor.lineStart))) continue;
+      if (found.length !== 1) { blocked.push(`${prefix}${kind} ${item.id}.${key} not re-anchored: "${term ?? anchor.symbol}" ${foundAt(found)}`); continue; }
+      const lineEnd = anchor.lineEnd === undefined ? undefined : Math.min(lines.length, found[0] + anchor.lineEnd - anchor.lineStart);
+      changes.push(`${prefix}${kind} ${item.id}.${key}.lineStart ${anchor.lineStart} → ${found[0]}${lineEnd === undefined ? '' : `, lineEnd ${anchor.lineEnd} → ${lineEnd}`}`);
+      anchor.lineStart = found[0];
+      if (lineEnd !== undefined) anchor.lineEnd = lineEnd;
     }
   }
   return { changes, blocked };
@@ -207,10 +218,16 @@ function sourceReader(repoRoot) {
 }
 
 // Checks the explicitly selected working tree, not the revision named in sourceRef or the meaning of a claim.
+// `relations` counts the edges that should record a site, so a delivery can say how much of the diagram is traceable.
 export function verifySourceEvidence(input, repoRoot) {
-  const anchors = graphsOf(input).flatMap((graph, graphIndex) => graph.nodes.flatMap((node, nodeIndex) => node.source
-    ? [{ source: node.source, label: `diagrams[${graphIndex}].nodes[${nodeIndex}].source` }] : []));
-  const summary = { scope: 'working-tree', references: anchors.length, checked: 0, files: 0 };
+  const graphs = graphsOf(input), edges = graphs.flatMap(graph => graph.edges ?? []);
+  const anchors = graphs.flatMap((graph, graphIndex) => [
+    ...overviewSections(graph).flatMap(section => section.source ? [{ source: section.source, label: `diagrams[${graphIndex}].sections.${section.id}.source` }] : []),
+    ...graph.nodes.flatMap((node, nodeIndex) => (node.badges ?? []).flatMap((badge, i) => badge.source ? [{ source: badge.source, label: `diagrams[${graphIndex}].nodes[${nodeIndex}].badges[${i}].source` }] : [])),
+    ...graph.nodes.flatMap((node, nodeIndex) => node.source ? [{ source: node.source, label: `diagrams[${graphIndex}].nodes[${nodeIndex}].source` }] : []),
+    ...(graph.edges ?? []).flatMap((edge, edgeIndex) => edge.site ? [{ source: edge.site, label: `diagrams[${graphIndex}].edges[${edgeIndex}].site` }] : [])]);
+  const summary = { scope: 'working-tree', references: anchors.length, checked: 0, files: 0,
+    relations: { sited: edges.filter(edge => needsSite(edge) && edge.site).length, eligible: edges.filter(needsSite).length } };
   if (repoRoot === undefined) {
     if (anchors.length) console.warn('Source evidence not verified: pass --repo-root <repository-directory> to check files, line ranges and symbols.');
     return { ...summary, status: anchors.length ? 'skipped' : 'not-applicable', ...(anchors.length ? { reason: 'repository-root-not-provided' } : {}) };
@@ -254,7 +271,7 @@ if (process.argv[1] && fs.existsSync(process.argv[1]) && fs.realpathSync(process
     }
     const graph = readAndValidateGraph(positionals[0], { inputOnly: values['input-only'] });
     const sourceEvidence = verifySourceEvidence(graph, values['repo-root']);
-    const warnings = printCompositionReview(graph, { print: values['input-only'] });
+    const warnings = [...printCompositionReview(graph, { print: values['input-only'] }), ...(values['input-only'] ? [] : printViewReview(graph))];
     const graphs = graphsOf(graph);
     const totals = {
       nodes: graphs.reduce((sum, item) => sum + item.nodes.length, 0),