qgraphflow 0.0.6 → 0.0.7

package/skills/q-flow/assets/viewer/src/edge-routing.js

@@ -1,7 +1,10 @@
+import { alignedLayout } from './layout-policy.js';
+import { presentationGraph } from './presentation-graph.js';
 import { TYPOGRAPHY } from './visual-style.js';
-import { cardTextLayout, estimateLabelSize, edgeLabelLayout, groupHeadingLayout, labelRunsByLine } from './text-layout.js';
+import { overviewSections, hasOverviewContent, overviewCardLayout } from './architecture-overview.js';
+import { CARD, cardTextLayout, estimateLabelSize, edgeLabelLayout, groupHeadingLayout, labelRunsByLine, layoutText } from './text-layout.js';
 import { LAYOUT_LIMITS, LAYOUT_TARGETS } from './layout-spacing.js';
-import { diagramTypeOf, getDiagram } from './diagrams/registry.js';
+import { compactCards, diagramTypeOf, getDiagram } from './diagrams/registry.js';
 import { sequenceHeaderHeight } from './diagrams/sequence.js';
 import { actorTop } from './diagrams/usecase.js';
 import { stateSymbolX } from './diagrams/state.js';
@@ -41,7 +44,8 @@ export function cardinalityMarks(cardinality, point, neighbor) {
 }
 
 export function graphBounds(graph, routes = createEdgeRoutes(graph)) {
-  const items = [...(graph.groups ?? []), ...graph.nodes, ...sequenceExecutions(graph).map(item => ({ position: { x: item.x, y: item.y }, size: { width: item.width, height: item.height } }))];
+  graph = presentationGraph(graph);
+  const items = [...overviewSections(graph), ...(graph.groups ?? []), ...graph.nodes, ...sequenceExecutions(graph).map(item => ({ position: { x: item.x, y: item.y }, size: { width: item.width, height: item.height } }))];
   const points = [...routes.values()].flatMap(route => [...route.points, { x: route.labelBox.x, y: route.labelBox.y }, { x: route.labelBox.x + route.labelBox.width, y: route.labelBox.y + route.labelBox.height }]);
   for (const route of routes.values()) for (const label of route.endpointLabels ?? []) points.push({ x: label.labelBox.x, y: label.labelBox.y }, { x: label.labelBox.x + label.labelBox.width, y: label.labelBox.y + label.labelBox.height });
   if (getDiagram(graph.meta?.diagramType).cardinalities) for (const edge of graph.edges) {
@@ -57,7 +61,7 @@ export function graphBounds(graph, routes = createEdgeRoutes(graph)) {
   return { x, y, width: right - x, height: bottom - y };
 }
 
-function anchor(node, side, offset = 0, type = 'architecture') {
+export function nodeAnchor(node, side, offset = 0, type = 'architecture') {
   const custom = getDiagram(type)?.anchor;
   if (custom) return custom(node, side, offset);
   const middle = center(node);
@@ -140,8 +144,7 @@ function sidesFor(source, target) {
 }
 
 function waypointEndpoint(node, point, fallbackSide, type) {
-  const { x, y } = node.position;
-  const { width, height } = node.size;
+  const { x, y, width, height } = type === 'usecase' && node.kind === 'actor' ? routingBounds(node, type) : { ...node.position, ...node.size };
   const dx = Math.max(x - point.x, 0, point.x - x - width);
   const dy = Math.max(y - point.y, 0, point.y - y - height);
   const side = dx === 0 && dy === 0 ? fallbackSide
@@ -150,10 +153,19 @@ function waypointEndpoint(node, point, fallbackSide, type) {
   const middle = center(node);
   const limit = Math.max(0, (horizontal ? height : width) / 2 - LAYOUT_LIMITS.endpoint);
   const offset = Math.max(-limit, Math.min(limit, horizontal ? point.y - middle.y : point.x - middle.x));
-  return { side, point: anchor(node, side, ['decision', 'choice'].includes(node.kind) ? 0 : offset, type) };
+  return { side, point: nodeAnchor(node, side, ['decision', 'choice'].includes(node.kind) ? 0 : offset, type) };
 }
 
 function routePointsWithWaypoints(start, end, sourceSide, targetSide, waypoints, stub = LAYOUT_LIMITS.endpoint) {
+  const horizontal = start.y === end.y, vertical = start.x === end.x;
+  const opposite = { left: 'right', right: 'left', top: 'bottom', bottom: 'top' };
+  const direction = { left: -1, right: 1, top: -1, bottom: 1 };
+  const axis = horizontal ? 'x' : 'y', across = horizontal ? 'y' : 'x';
+  if ((horizontal && ['left', 'right'].includes(sourceSide) || vertical && ['top', 'bottom'].includes(sourceSide))
+    && opposite[sourceSide] === targetSide && (end[axis] - start[axis]) * direction[sourceSide] > 0
+    && waypoints.every((point, i) => point[across] === start[across]
+      && (point[axis] - (i ? waypoints[i - 1][axis] : start[axis])) * direction[sourceSide] >= 0
+      && (end[axis] - point[axis]) * direction[sourceSide] >= 0)) return [start, end];
   const points = [start, outward(start, sourceSide, stub)];
   // A shaped endpoint can sit inside its layout box. Turn at the real stub before joining its allocated channel.
   if (['left', 'right'].includes(sourceSide) && waypoints.length && points[1].y !== waypoints[0].y) points.push({ x: points[1].x, y: waypoints[0].y });
@@ -164,8 +176,8 @@ function routePointsWithWaypoints(start, end, sourceSide, targetSide, waypoints,
 }
 
 function routeBetween(source, target, sides, sourceOffset, targetOffset, stub = LAYOUT_LIMITS.endpoint, type = 'architecture') {
-  const start = anchor(source, sides.sourceSide, sourceOffset, type);
-  const end = anchor(target, sides.targetSide, targetOffset, type);
+  const start = nodeAnchor(source, sides.sourceSide, sourceOffset, type);
+  const end = nodeAnchor(target, sides.targetSide, targetOffset, type);
   const sourceStub = outward(start, sides.sourceSide, stub);
   const targetStub = outward(end, sides.targetSide, stub);
   const channelOffset = sourceOffset || targetOffset;
@@ -234,6 +246,7 @@ function routeSequenceEdge(edge, source, target, selfIndex, context) {
 }
 
 export function createEdgeRoutes(graph) {
+  graph = presentationGraph(graph);
   const type = diagramTypeOf(graph);
   const stub = getDiagram(type).endpointStub ?? LAYOUT_LIMITS.endpoint;
   const nodeById = new Map(graph.nodes.map(node => [node.id, node]));
@@ -283,8 +296,8 @@ export function createEdgeRoutes(graph) {
       const sourceEndpoint = waypoints?.length && waypointEndpoint(item.source, waypoints[0], 'right', type);
       const targetEndpoint = waypoints?.length && waypointEndpoint(item.target, waypoints.at(-1), 'right', type);
       const sourceSide = sourceEndpoint ? sourceEndpoint.side : 'right', targetSide = targetEndpoint ? targetEndpoint.side : 'right';
-      const start = sourceEndpoint ? sourceEndpoint.point : anchor(item.source, 'right', -16 - selfIndex * 12, type);
-      const end = targetEndpoint ? targetEndpoint.point : anchor(item.source, 'right', 16 + selfIndex * 12, type);
+      const start = sourceEndpoint ? sourceEndpoint.point : nodeAnchor(item.source, 'right', -16 - selfIndex * 12, type);
+      const end = targetEndpoint ? targetEndpoint.point : nodeAnchor(item.source, 'right', 16 + selfIndex * 12, type);
       route = {
         points: item.edge.route?.via?.length
           ? routePointsWithWaypoints(start, end, sourceSide, targetSide, item.edge.route.via, stub)
@@ -292,7 +305,7 @@ export function createEdgeRoutes(graph) {
         label,
         labelPoint: item.edge.route?.labelAt ?? { x: right + extent + 8 + labelSize.width / 2, y: middleY },
         sourceSide, targetSide,
-        curved: Boolean(getDiagram(type).curvedSelfLoops)
+        curved: Boolean(getDiagram(type).curvedSelfLoops) && !alignedLayout(graph)
       };
     } else {
       const waypoints = item.edge.route?.via;
@@ -344,7 +357,7 @@ function pointOnNodeSide(point, node, side, type) {
   if ((side === 'top' || side === 'bottom') && (point.x < bounds.x || point.x > bounds.x + bounds.width)) return false;
   const middle = center(node);
   const offset = side === 'left' || side === 'right' ? point.y - middle.y : point.x - middle.x;
-  const expected = anchor(node, side, offset, type);
+  const expected = nodeAnchor(node, side, offset, type);
   return Math.hypot(point.x - expected.x, point.y - expected.y) < 1e-7;
 }
 
@@ -360,7 +373,7 @@ export function segmentCrossesBox(start, end, box) {
   return false;
 }
 
-function routingBounds(node, type) {
+export function routingBounds(node, type) {
   if (type === 'state' && ['initial', 'final'].includes(node.kind)) {
     const radius = node.kind === 'initial' ? 12 : 13, middle = center(node);
     return { x: node.position.x + stateSymbolX(node) - radius, y: middle.y - radius, width: radius * 2, height: radius * 2 };
@@ -374,31 +387,37 @@ function routingBounds(node, type) {
   return occupiedBox(node, type);
 }
 
-function segmentCrossesNode(start, end, node, type) {
+export function segmentCrossesNode(start, end, node, type) {
   if (type === 'state' && ['initial', 'final'].includes(node.kind) && node.subtitle) {
     const area = getDiagram(type).textArea(node);
     if (segmentCrossesBox(start, end, { ...area, x: node.position.x + area.x, y: node.position.y + area.y })) return true;
   }
   const bounds = routingBounds(node, type);
   if (type === 'sequence') return segmentCrossesBox(start, end, bounds);
-  if (type === 'usecase' && node.kind === 'actor') return segmentCrossesBox(start, end, bounds);
+  if (type === 'usecase' && node.kind === 'actor') {
+    const cy = node.position.y + actorTop(node), cx = center(node).x;
+    const labelWidth = Math.min(node.size.width, layoutText(node.label, Infinity, 20).width * 1.15);
+    const subtitleWidth = node.subtitle ? Math.min(node.size.width, layoutText(node.subtitle, Infinity, 16).width * 1.15) : 0;
+    return segmentCrossesBox(start, end, bounds) || segmentCrossesBox(start, end, { x: cx - labelWidth / 2, y: cy + 78, width: labelWidth, height: 26 })
+      || subtitleWidth > 0 && segmentCrossesBox(start, end, { x: cx - subtitleWidth / 2, y: cy + 106, width: subtitleWidth, height: 24 });
+  }
   const middle = center(node);
   if (start.y === end.y) {
     if (start.y <= bounds.y || start.y >= bounds.y + bounds.height) return false;
     const offset = start.y - middle.y;
-    const left = anchor(node, 'left', offset, type).x, right = anchor(node, 'right', offset, type).x;
+    const left = nodeAnchor(node, 'left', offset, type).x, right = nodeAnchor(node, 'right', offset, type).x;
     return Math.max(Math.min(start.x, end.x), left) < Math.min(Math.max(start.x, end.x), right) - 1e-7;
   }
   if (start.x === end.x) {
     if (start.x <= bounds.x || start.x >= bounds.x + bounds.width) return false;
     const offset = start.x - middle.x;
-    const top = anchor(node, 'top', offset, type).y, bottom = anchor(node, 'bottom', offset, type).y;
+    const top = nodeAnchor(node, 'top', offset, type).y, bottom = nodeAnchor(node, 'bottom', offset, type).y;
     return Math.max(Math.min(start.y, end.y), top) < Math.min(Math.max(start.y, end.y), bottom) - 1e-7;
   }
   return false;
 }
 
-function groupBorders(group) {
+export function groupBorders(group) {
   const left = group.position.x;
   const right = left + group.size.width;
   const top = group.position.y;
@@ -421,7 +440,7 @@ export function groupHeadingBoxes(group) {
   return boxes;
 }
 
-function sharedSegmentLength(firstStart, firstEnd, secondStart, secondEnd) {
+export function sharedSegmentLength(firstStart, firstEnd, secondStart, secondEnd) {
   if (firstStart.y === firstEnd.y && secondStart.y === secondEnd.y && firstStart.y === secondStart.y) {
     return Math.max(0, Math.min(Math.max(firstStart.x, firstEnd.x), Math.max(secondStart.x, secondEnd.x))
       - Math.max(Math.min(firstStart.x, firstEnd.x), Math.min(secondStart.x, secondEnd.x)));
@@ -451,6 +470,7 @@ export function routeCrossings(first, firstPoints, second, secondPoints) {
 }
 
 export function auditGraphLayout(graph) {
+  graph = presentationGraph(graph);
   const type = diagramTypeOf(graph);
   const crossings = [];
   const routes = createEdgeRoutes(graph);
@@ -484,9 +504,10 @@ export function auditGraphLayout(graph) {
       if (route.points.some(p => p.y > Math.min(...[edge.source, edge.target].map(id => { const n = graph.nodes.find(n => n.id === id); return n.position.y + n.size.height; })))) fail('sequence.lifeline', [edge.id, edge.source, edge.target], `layout: sequence edge ${edge.id} exceeds its participant lifeline`);
     }
   }
+  const classicCard = getDiagram(type).cardLayout && !compactCards(graph);
   if (getDiagram(type).cardLayout) for (const node of graph.nodes) {
-    if (node.size.height < 100) continue;
-    const { minHeight } = cardTextLayout(node);
+    if (node.size.height < (classicCard ? 100 : CARD.minHeight)) continue;
+    const { minHeight } = type === 'architecture' && hasOverviewContent(node) ? overviewCardLayout(node) : cardTextLayout(node, graph.meta.locale, classicCard);
     if (node.size.height < minHeight) fail('text.card-height', [node.id], `layout: node ${node.id} text needs at least ${minHeight}px height at 20/16px; enlarge the node and check its route clearance`);
   }
   for (let left = 0; left < graph.nodes.length; left += 1) {

package/skills/q-flow/assets/viewer/src/export-svg.js

@@ -1,6 +1,8 @@
+import { presentationGraph } from './presentation-graph.js';
+import { overviewSections, sectionSvg } from './architecture-overview.js';
 import { createEdgeRoutes, graphBounds, pathFromRoute, cardinalityMarks } from './edge-routing.js';
 import { layoutText } from './text-layout.js';
-import { DIAGRAM_TYPES, diagramTypeOf, getDiagram, edgeMarkers, isDashed, labelRoleColors } from './diagrams/registry.js';
+import { DIAGRAM_TYPES, compactCards, diagramTypeOf, getDiagram, edgeMarkers, isDashed, labelRoleColors } from './diagrams/registry.js';
 import { renderNode } from './node-svg.js';
 import { text, fit, escapeXml, svgStyles, groupHeadingSvg, groupFrameSvg } from './diagrams/drawing.js';
 import { PALETTES, dataKinds, edgeColor, sequenceGroupColor, moduleColorMap, groupAppearanceMap, TYPOGRAPHY } from './visual-style.js';
@@ -8,6 +10,7 @@ import { RADIX_COLORS_NOTICE } from './radix-colors.js';
 import { sequencePairs, sequenceExecutions } from './sequence-executions.js';
 import { sequenceFragment, renderFragment, fragmentDepth, fragmentSurfaceAt } from './sequence-fragments.js';
 import { requireDiagramQuality } from './layout-quality.js';
+import { translate } from './i18n.js';
 
 function edgeMarker(edge, type, target, moduleColors, source, pair) {
   const { end } = edgeMarkers(edge, type);
@@ -46,8 +49,23 @@ function renderEdge(edge, route, type, offsetX, offsetY, palette, target, module
   return `<g data-diagram-edge-id="${escapeXml(edge.id)}"><path d="${pathFromRoute(route, offsetX, offsetY)}" fill="none" stroke="${stroke}" stroke-width="1.5"${dash}${edgeMarker(edge, type, target, moduleColors, source, pair)}${edgeStartMarker(edge, type)}/>${cardinalities}${background}${pairLine}${label ? route.labelLines.map((line, index) => text(labelX, labelY - labelSize.height / 2 + 3 + TYPOGRAPHY.body + index * TYPOGRAPHY.edgeLineHeight, route.labelRuns ? { runs: route.labelRuns[index], colors: labelRoleColors(type, palette) } : line, 'edge', ' text-anchor="middle"')).join('') : ''}${multiplicities}</g>`;
 }
 
+// meta.notes sit under the board, on the paper: a heading, then one bulleted paragraph per note. Same text the Viewer's
+// "Key points" card shows, so a diagram embedded in a README carries its findings.
+const NOTE = { indent: 20, line: 24, gap: 6, top: 12, afterHeading: 14, bottom: 18 };
+function notesBlock(notes, locale, left, top, width) {
+  const layouts = notes.map(note => layoutText(note, width - NOTE.indent, TYPOGRAPHY.body, NOTE.line));
+  let y = top + NOTE.top + NOTE.afterHeading;
+  const items = layouts.map(({ lines }) => {
+    const first = y + 17, markup = text(left, first, '•', 'body') + lines.map((line, i) => text(left + NOTE.indent, first + i * NOTE.line, line, 'body')).join('');
+    y += lines.length * NOTE.line + NOTE.gap;
+    return markup;
+  }).join('');
+  return { height: y - top + NOTE.bottom, svg: `<g data-notes="${notes.length}">${text(left, top + NOTE.top, translate(locale, 'Key points'), 'group')}${items}</g>` };
+}
+
 export function createDiagramSvg(graph, theme = 'light', moduleColors) {
   requireDiagramQuality(graph);
+  graph = presentationGraph(graph);
   const palette = PALETTES[theme] ?? PALETTES.light;
   moduleColors ??= moduleColorMap([graph], palette);
   const groupAppearances = groupAppearanceMap(graph.groups ?? [], palette);
@@ -62,21 +80,25 @@ export function createDiagramSvg(graph, theme = 'light', moduleColors) {
   const subtitleLayout = layoutText(graph.meta.subtitle ?? '', width - margin * 2, TYPOGRAPHY.small);
   const subtitleY = 66 + Math.max(0, titleLayout.lines.length - 1) * titleLayout.lineHeight;
   const header = Math.max(88, subtitleLayout.lines.length ? subtitleY + (subtitleLayout.lines.length - 1) * subtitleLayout.lineHeight + 22 : 43 + Math.max(0, titleLayout.lines.length - 1) * titleLayout.lineHeight + 24);
-  const height = bounds.height + margin * 2 + header;
+  const boardBottom = bounds.height + margin * 2 + header;
+  const notes = graph.meta.notes?.length ? notesBlock(graph.meta.notes, graph.meta.locale, margin, boardBottom, width - margin * 2) : { height: 0, svg: '' };
+  const height = boardBottom + notes.height;
   const offsetX = margin - bounds.x;
   const offsetY = margin + header - bounds.y;
   const fragments = new Map((graph.groups ?? []).map(group => [group.id, type === 'sequence' ? sequenceFragment(group, routes, graph.meta.locale, graph.groups ?? [], executions) : null]));
   const groups = [...(graph.groups ?? [])].sort((a, b) => fragmentDepth(a, graph.groups ?? []) - fragmentDepth(b, graph.groups ?? [])).map(group => renderGroup(group, offsetX, offsetY, fragments.get(group.id), groupAppearances.get(group.id)) + (type === 'sequence' ? renderFragment({ ...fragments.get(group.id), guards: [], bodies: [] }, group, offsetX, offsetY, palette.ink3, groupAppearances.get(group.id).fill) : '')).join('');
+  const sections = overviewSections(graph).map(section => sectionSvg(section, palette, offsetX, offsetY)).join('');
   const fragmentText = type === 'sequence' ? (graph.groups ?? []).map(group => renderFragment({ ...fragments.get(group.id), separators: [] }, group, offsetX, offsetY, palette.ink3, groupAppearances.get(group.id).fill)).join('') : '';
 
   const edges = graph.edges.map(edge => renderEdge(edge, routes.get(edge.id), type, offsetX, offsetY, palette, nodeById.get(edge.target), moduleColors, nodeById.get(edge.source), pairs.get(edge.id), type === 'sequence' && routes.get(edge.id).label ? fragmentSurfaceAt(routes.get(edge.id).labelBox, graph.groups ?? [], groupAppearances) : undefined)).join('');
-  const nodes = graph.nodes.map(node => renderNode({ ...node, executionRects: executions.filter(item => item.participantId === node.id).map(item => ({ ...item, x: item.x - node.position.x, y: item.y - node.position.y, color: sequenceGroupColor(pairs.get(item.start.edgeId), palette) ?? palette.edge })) }, type, offsetX, offsetY, palette, graph.meta.locale, moduleColors)).join('');
+  const classicCard = !compactCards(graph);
+  const nodes = graph.nodes.map(node => renderNode({ ...node, classicCard, executionRects: executions.filter(item => item.participantId === node.id).map(item => ({ ...item, x: item.x - node.position.x, y: item.y - node.position.y, color: sequenceGroupColor(pairs.get(item.start.edgeId), palette) ?? palette.edge })) }, type, offsetX, offsetY, palette, graph.meta.locale, moduleColors)).join('');
   const boardX = 24;
   const boardY = header;
   const boardWidth = width - 48;
-  const boardHeight = height - header - 24;
+  const boardHeight = boardBottom - header - 24;
 
-  return `<?xml version="1.0" encoding="UTF-8"?>\n<!-- Radix Colors\n${RADIX_COLORS_NOTICE}-->\n<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" data-graph-offset-x="${offsetX}" data-graph-offset-y="${offsetY}" role="img" aria-labelledby="title desc"><title id="title">${escapeXml(graph.meta.title)}</title><desc id="desc">${escapeXml(type)} diagram for ${escapeXml(graph.meta.sourceRef)}</desc><defs><filter id="node-shadow" x="-20%" y="-20%" width="140%" height="150%"><feDropShadow dx="0" dy="5" stdDeviation="7" flood-color="${palette.ink}" flood-opacity=".045"/></filter><marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10Z" fill="${palette.edge}"/></marker><marker id="arrow-module" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10Z" fill="context-stroke"/></marker><marker id="arrow-warn" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10Z" fill="${palette.warn}"/></marker><marker id="arrow-ok" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10Z" fill="${palette.accent}"/></marker><marker id="arrow-data" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10Z" fill="${palette.data}"/></marker><marker id="arrow-open" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M1 1L9 5L1 9" fill="none" stroke="context-stroke" stroke-width="1.5"/></marker><marker id="triangle" viewBox="0 0 12 12" refX="11" refY="6" markerWidth="9" markerHeight="9" orient="auto"><path d="M1 1L11 6L1 11Z" fill="${palette.surface}" stroke="context-stroke"/></marker><marker id="diamond-filled" viewBox="0 0 14 10" refX="1" refY="5" markerWidth="12" markerHeight="10" orient="auto"><path d="M1 5L7 1L13 5L7 9Z" fill="context-stroke"/></marker><marker id="diamond-open" viewBox="0 0 14 10" refX="1" refY="5" markerWidth="12" markerHeight="10" orient="auto"><path d="M1 5L7 1L13 5L7 9Z" fill="${palette.surface}" stroke="context-stroke"/></marker><style>${svgStyles(palette)}</style></defs><rect width="100%" height="100%" fill="${palette.paper}"/><rect x="${boardX}" y="${boardY}" width="${boardWidth}" height="${boardHeight}" rx="16" fill="${palette.surface}" stroke="${palette.rule}"/>${titleLayout.lines.map((line, index) => text(margin, 43 + index * titleLayout.lineHeight, line, 'heading')).join('')}${subtitleLayout.lines.map((line, index) => text(margin, subtitleY + index * subtitleLayout.lineHeight, line, 'meta')).join('')}${groups}${type === 'sequence' ? nodes + edges : edges + nodes}${fragmentText}</svg>\n`;
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<!-- Radix Colors\n${RADIX_COLORS_NOTICE}-->\n<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" data-graph-offset-x="${offsetX}" data-graph-offset-y="${offsetY}" role="img" aria-labelledby="title desc"><title id="title">${escapeXml(graph.meta.title)}</title><desc id="desc">${escapeXml(type)} diagram for ${escapeXml(graph.meta.sourceRef)}</desc><defs><filter id="node-shadow" x="-20%" y="-20%" width="140%" height="150%"><feDropShadow dx="0" dy="5" stdDeviation="7" flood-color="${palette.ink}" flood-opacity=".045"/></filter><marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10Z" fill="${palette.edge}"/></marker><marker id="arrow-module" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10Z" fill="context-stroke"/></marker><marker id="arrow-warn" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10Z" fill="${palette.warn}"/></marker><marker id="arrow-ok" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10Z" fill="${palette.accent}"/></marker><marker id="arrow-data" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10Z" fill="${palette.data}"/></marker><marker id="arrow-open" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M1 1L9 5L1 9" fill="none" stroke="context-stroke" stroke-width="1.5"/></marker><marker id="triangle" viewBox="0 0 12 12" refX="11" refY="6" markerWidth="9" markerHeight="9" orient="auto"><path d="M1 1L11 6L1 11Z" fill="${palette.surface}" stroke="context-stroke"/></marker><marker id="diamond-filled" viewBox="0 0 14 10" refX="1" refY="5" markerWidth="12" markerHeight="10" orient="auto"><path d="M1 5L7 1L13 5L7 9Z" fill="context-stroke"/></marker><marker id="diamond-open" viewBox="0 0 14 10" refX="1" refY="5" markerWidth="12" markerHeight="10" orient="auto"><path d="M1 5L7 1L13 5L7 9Z" fill="${palette.surface}" stroke="context-stroke"/></marker><style>${svgStyles(palette)}</style></defs><rect width="100%" height="100%" fill="${palette.paper}"/><rect x="${boardX}" y="${boardY}" width="${boardWidth}" height="${boardHeight}" rx="16" fill="${palette.surface}" stroke="${palette.rule}"/>${titleLayout.lines.map((line, index) => text(margin, 43 + index * titleLayout.lineHeight, line, 'heading')).join('')}${subtitleLayout.lines.map((line, index) => text(margin, subtitleY + index * subtitleLayout.lineHeight, line, 'meta')).join('')}${sections}${groups}${type === 'sequence' ? nodes + edges : edges + nodes}${fragmentText}${notes.svg}</svg>\n`;
 }
 
 // The generator and the Viewer's in-place save both write these files, so names and bytes come from one place: light

package/skills/q-flow/assets/viewer/src/graph-validation.js

@@ -1,10 +1,16 @@
+import { isArchitectureOverview } from './view-identity.js';
+import { DEPLOYMENT_TIERS } from './layout-semantics.js';
 import { SUPPORTED_LOCALES } from './i18n.js';
-import { auditGraphLayout } from './edge-routing.js';
+import { auditGraphLayout, graphBounds } from './edge-routing.js';
+import { MAX_SCREENS, OVERVIEW_AREA, READABLE_ZOOM, layeredDirections } from './layout-spacing.js';
 import { missingCallExecutions, validateExecutions } from './sequence-executions.js';
 import { validateOperands } from './sequence-fragments.js';
+import { viewIdOf } from './view-identity.js';
+import { validateOverview } from './architecture-overview.js';
 import { DIAGRAM_TYPES, diagramTypeOf, getDiagram } from './diagrams/registry.js';
 
 const EVIDENCE_KINDS = new Set(['source', 'code', 'config', 'schema', 'test', 'document', 'framework', 'inference']);
+export const MAX_NOTES = 6, MAX_NOTE_LENGTH = 120;
 const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value);
 
 function requireString(value, label, errors) {
@@ -15,6 +21,16 @@ function optionalString(value, label, errors) {
   if (value !== undefined && typeof value !== 'string') errors.push(`${label} must be a string`);
 }
 
+// A node `source` and an edge `site` share one anchor shape, so one check and one --repo-root verification serve both.
+function validateAnchor(anchor, label, errors) {
+  requireString(anchor.file, `${label}.file`, errors);
+  optionalString(anchor.symbol, `${label}.symbol`, errors);
+  if (!Number.isInteger(anchor.lineStart) || anchor.lineStart < 1) errors.push(`${label}.lineStart must be a positive integer`);
+  if (anchor.lineEnd !== undefined && (!Number.isInteger(anchor.lineEnd) || (Number.isInteger(anchor.lineStart) && anchor.lineEnd < anchor.lineStart))) {
+    errors.push(`${label}.lineEnd must be an integer at or after lineStart`);
+  }
+}
+
 function requireBox(item, label, errors, inputOnly = false) {
   for (const [group, keys] of [['position', ['x', 'y']], ['size', ['width', 'height']]]) {
     if (inputOnly && item[group] === undefined) continue;
@@ -46,6 +62,14 @@ function validateStringArray(value, label, errors) {
   }
 }
 
+// meta.notes: the findings a reader must see before opening any node; the Viewer and the SVG both draw them.
+function validateNotes(notes, errors) {
+  validateStringArray(notes, 'meta.notes', errors);
+  if (!Array.isArray(notes)) return;
+  if (notes.length > MAX_NOTES) errors.push(`meta.notes must have at most ${MAX_NOTES} items`);
+  notes.forEach((note, index) => { if (typeof note === 'string' && [...note].length > MAX_NOTE_LENGTH) errors.push(`meta.notes[${index}] exceeds ${MAX_NOTE_LENGTH} characters`); });
+}
+
 export function graphsOf(input) {
   return input && typeof input === 'object' && !Array.isArray(input) && Array.isArray(input.diagrams)
     ? input.diagrams
@@ -59,7 +83,10 @@ export function validateGraph(graph, { inputOnly = false, audit = true } = {}) {
   if (!isObject(graph.meta)) errors.push('meta must be an object');
   requireString(graph.meta?.title, 'meta.title', errors);
   requireString(graph.meta?.sourceRef, 'meta.sourceRef', errors);
+  if (graph.meta?.viewId !== undefined) requireString(graph.meta.viewId, 'meta.viewId', errors);
+  if (graph.meta?.architectureView !== undefined && ((graph.meta.diagramType ?? 'architecture') !== 'architecture' || !['relations', 'capabilities', 'engineering'].includes(graph.meta.architectureView))) errors.push('meta.architectureView is unsupported');
   for (const key of ['subtitle', 'scope']) optionalString(graph.meta?.[key], `meta.${key}`, errors);
+  validateNotes(graph.meta?.notes, errors);
   if (graph.meta?.locale !== undefined && !SUPPORTED_LOCALES.includes(graph.meta.locale)) errors.push('meta.locale is unsupported');
   const diagramType = diagramTypeOf(graph);
   if (!DIAGRAM_TYPES.includes(diagramType)) errors.push('meta.diagramType is unsupported');
@@ -85,13 +112,8 @@ export function validateGraph(graph, { inputOnly = false, audit = true } = {}) {
     nodeIds.add(node?.id);
     if (node.source !== undefined && !isObject(node.source)) errors.push(`${label}.source must be an object`);
     else if (node.source) {
-      requireString(node.source.file, `${label}.source.file`, errors);
-      optionalString(node.source.symbol, `${label}.source.symbol`, errors);
+      validateAnchor(node.source, `${label}.source`, errors);
       if (node.source.kind !== undefined && !EVIDENCE_KINDS.has(node.source.kind)) errors.push(`${label}.source.kind is unsupported`);
-      if (!Number.isInteger(node.source.lineStart) || node.source.lineStart < 1) errors.push(`${label}.source.lineStart must be a positive integer`);
-      if (node.source.lineEnd !== undefined && (!Number.isInteger(node.source.lineEnd) || (Number.isInteger(node.source.lineStart) && node.source.lineEnd < node.source.lineStart))) {
-        errors.push(`${label}.source.lineEnd must be an integer at or after lineStart`);
-      }
     }
     for (const key of ['facts', 'tags', 'attributes', 'methods']) validateStringArray(node[key], `${label}.${key}`, errors);
     if (node.fields !== undefined) {
@@ -131,6 +153,8 @@ export function validateGraph(graph, { inputOnly = false, audit = true } = {}) {
     requireString(edge?.target, `${label}.target`, errors);
     if (!rules.edgeKinds.includes(edge?.kind)) errors.push(`${label}.kind is unsupported for ${diagramType}`);
     if (!EVIDENCE_KINDS.has(edge?.evidence)) errors.push(`${label}.evidence is unsupported`);
+    if (edge.site !== undefined && !isObject(edge.site)) errors.push(`${label}.site must be an object`);
+    else if (edge.site) validateAnchor(edge.site, `${label}.site`, errors);
     if (typeof edge.id === 'string' && edgeIds.has(edge.id)) errors.push(`${label}.id duplicates ${edge.id}`);
     edgeIds.add(edge?.id);
     if (typeof edge.source === 'string' && !nodeIds.has(edge.source)) errors.push(`${label}.source does not name a node: ${edge.source}`);
@@ -150,6 +174,7 @@ export function validateGraph(graph, { inputOnly = false, audit = true } = {}) {
     if (diagramType === 'sequence' && !inputOnly && edge.route?.messageY === undefined) errors.push(`${label}.route.messageY is required for a positioned sequence message; regenerate with --layout auto`);
     rules.validateEdge?.(edge, label, errors, { requireString, sequenceOrders });
   }
+  if (errors.length === 0) errors.push(...validateOverview(graph, { inputOnly, validateAnchor, evidenceKinds: EVIDENCE_KINDS }));
   if (errors.length === 0) errors.push(...validateLayoutSemantics(graph));
   if (errors.length === 0) errors.push(...validateOperands(graph));
   if (errors.length === 0) errors.push(...validateExecutions(graph, { inputOnly }));
@@ -168,7 +193,8 @@ function validateLayoutSemantics(graph) {
     }
     if (node.layout !== undefined) {
       if (!isObject(node.layout)) errors.push(`node ${node.id}.layout must be an object`);
-      else for (const key of ['rank', 'order']) if (node.layout[key] !== undefined && (!Number.isInteger(node.layout[key]) || node.layout[key] < 0)) errors.push(`node ${node.id}.layout.${key} must be a non-negative integer`);
+      else if (node.layout.tier !== undefined && (type !== 'deployment' || !DEPLOYMENT_TIERS.includes(node.layout.tier))) errors.push(`node ${node.id}.layout.tier requires deployment and one of ${DEPLOYMENT_TIERS.join(', ')}`);
+      if (isObject(node.layout)) for (const key of ['rank', 'order']) if (node.layout[key] !== undefined && (!Number.isInteger(node.layout[key]) || node.layout[key] < 0)) errors.push(`node ${node.id}.layout.${key} must be a non-negative integer`);
     }
   }
   if (!sequence) for (const group of groups.values()) {
@@ -181,7 +207,9 @@ function validateLayoutSemantics(graph) {
     }
   }
   if (graph.layout !== undefined && !isObject(graph.layout)) errors.push('layout must be an object');
-  else for (const key of ['primaryPath', 'participantOrder']) {
+  else if (graph.layout?.direction !== undefined && !layeredDirections(type).includes(graph.layout.direction)) errors.push(`layout.direction must be one of ${layeredDirections(type).join(', ')} for ${type}`);
+  if (graph.layout?.overviewConnections !== undefined && (!isArchitectureOverview(graph) || !['within-category', 'all'].includes(graph.layout.overviewConnections))) errors.push('layout.overviewConnections requires an architecture overview and within-category or all');
+  if (isObject(graph.layout)) for (const key of ['primaryPath', 'participantOrder']) {
     const list = graph.layout?.[key];
     if (list === undefined) continue;
     if (!Array.isArray(list) || !list.length || list.some(id => typeof id !== 'string' || !nodes.has(id)) || new Set(list).size !== list.length) {
@@ -218,15 +246,20 @@ export function validateGraphInput(input, options = {}) {
   if (!input || typeof input !== 'object' || Array.isArray(input)) return ['graph must be an object'];
   const authored = graph => { const errors = validateGraph(graph, options); return errors.length ? errors : missingCallExecutions(graph); };
   if (!Object.hasOwn(input, 'diagrams')) return authored(input);
-  if (!Array.isArray(input.diagrams) || input.diagrams.length < 1 || input.diagrams.length > DIAGRAM_TYPES.length) {
-    return [`diagrams must contain between 1 and ${DIAGRAM_TYPES.length} graphs`];
+  if (!Array.isArray(input.diagrams) || input.diagrams.length < 1 || input.diagrams.length > 32) {
+    return [`diagrams must contain between 1 and 32 graphs`];
   }
 
   const errors = [];
-  const types = new Set();
+  const types = new Set(), viewIds = new Set();
+  const architectureCount = input.diagrams.filter(graph => diagramTypeOf(graph) === 'architecture').length;
   input.diagrams.forEach((graph, index) => {
     const type = diagramTypeOf(graph);
-    if (types.has(type)) errors.push(`diagrams[${index}].meta.diagramType duplicates ${type}`);
+    if (types.has(type) && type !== 'architecture') errors.push(`diagrams[${index}].meta.diagramType duplicates ${type}`);
+    if (type === 'architecture' && architectureCount > 1 && !graph?.meta?.viewId) errors.push(`diagrams[${index}].meta.viewId is required for repeated architecture views`);
+    const viewId = viewIdOf(graph);
+    if (viewIds.has(viewId)) errors.push(`diagrams[${index}].meta.viewId duplicates ${viewId}`);
+    viewIds.add(viewId);
     types.add(type);
     errors.push(...authored(graph).map(error => `diagrams[${index}].${error}`));
   });
@@ -240,6 +273,9 @@ export function validateGraphInput(input, options = {}) {
 const PLAIN_KINDS = new Set(['initial', 'final']);
 const OUTSIDER_KINDS = new Set(['external', 'actor', 'device']);
 const moduleOf = item => (typeof item?.module === 'string' && item.module.trim() ? item.module : undefined);
+// A relationship backed by repository material records the line that makes it hold; a sequence return follows its call.
+const SITE_EVIDENCE = new Set(['source', 'code', 'config', 'schema', 'test']);
+export const needsSite = edge => SITE_EVIDENCE.has(edge.evidence) && edge.kind !== 'return';
 
 export function reviewComposition(input) {
   if (validateGraphInput(input, { inputOnly: true }).length) return [];
@@ -249,7 +285,7 @@ export function reviewComposition(input) {
   // The same label across views is the same component: its module must be present everywhere and be the same one.
   const byLabel = new Map();
   for (const graph of graphs) for (const node of graph.nodes) if (typeof node.label === 'string' && !PLAIN_KINDS.has(node.kind)) {
-    byLabel.set(node.label, [...(byLabel.get(node.label) ?? []), { diagramType: diagramTypeOf(graph), id: node.id, module: moduleOf(node) }]);
+    byLabel.set(node.label, [...(byLabel.get(node.label) ?? []), { diagramType: diagramTypeOf(graph), viewId: viewIdOf(graph), id: node.id, module: moduleOf(node) }]);
   }
   for (const graph of graphs) {
     const diagramType = diagramTypeOf(graph);
@@ -260,7 +296,7 @@ export function reviewComposition(input) {
         `${plain.length === 1 ? 'node' : 'nodes'} ${plain.map(node => node.id).join(', ')} ${plain.length === 1 ? 'has' : 'have'} no module and render${plain.length === 1 ? 's' : ''} on the plain surface without identity`,
         'Give every ordinary node the module of the subsystem whose work it performs (a step: the subsystem that does the work; an external hub or broker: its channel); leave only true outsiders plain.');
       for (const node of graph.nodes) {
-        const elsewhere = (byLabel.get(node.label) ?? []).filter(item => item.diagramType !== diagramType && item.module && item.module !== moduleOf(node));
+        const elsewhere = (byLabel.get(node.label) ?? []).filter(item => item.viewId !== viewIdOf(graph) && item.module && item.module !== moduleOf(node));
         if (!elsewhere.length || PLAIN_KINDS.has(node.kind)) continue;
         const other = elsewhere[0];
         warn('module.inconsistent', [node.id], `node ${node.id} "${node.label}" ${moduleOf(node) ? `carries module "${moduleOf(node)}"` : 'has no module'} here but "${other.module}" in ${other.diagramType}`,
@@ -273,6 +309,11 @@ export function reviewComposition(input) {
         `${diagramType} gives all ${washed.length} nodes the module "${moduleOf(washed[0])}", so the wash tells the reader nothing`,
         'Check whether the steps really are one subsystem\'s work: a step performed by another subsystem (a store, a cache layer, a queue) takes that subsystem\'s module, start and end take the caller. If everything truly belongs to one subsystem, leave it.');
     }
+    // Advisory only once the graph has started recording sites, so a graph authored without them stays quiet.
+    const sited = graph.edges.filter(edge => edge.site), unsited = graph.edges.filter(edge => needsSite(edge) && !edge.site);
+    if (sited.length && unsited.length) warn('edge.site-missing', unsited.map(edge => edge.id),
+      `${unsited.length === 1 ? 'edge' : 'edges'} ${unsited.map(edge => edge.id).join(', ')} ${unsited.length === 1 ? 'has' : 'have'} repository evidence but no site, while ${sited.length} other ${sited.length === 1 ? 'edge records' : 'edges record'} one`,
+      'Add the line that makes the relationship hold (the call, write, foreign key or extends clause) as site, or mark the edge inference.');
     if (diagramType === 'flowchart') {
       const outgoing = new Map();
       for (const edge of graph.edges) outgoing.set(edge.source, (outgoing.get(edge.source) ?? 0) + 1);
@@ -284,3 +325,19 @@ export function reviewComposition(input) {
   }
   return warnings;
 }
+
+// Advisory that needs laid-out geometry, so a graph without positions reports nothing: at the readable zoom a reader sees
+// one OVERVIEW_AREA at a time, and a view that needs more than MAX_SCREENS of them is read by scrolling, not by looking.
+export function overviewWarnings(input) {
+  if (validateGraphInput(input, { inputOnly: true }).length) return [];
+  const warnings = [];
+  for (const graph of graphsOf(input)) {
+    if (!graph.nodes.length || !graph.nodes.every(node => node.position && node.size)) continue;
+    const { width, height } = graphBounds(graph), across = width * READABLE_ZOOM / OVERVIEW_AREA.width, down = height * READABLE_ZOOM / OVERVIEW_AREA.height;
+    if (across * down <= MAX_SCREENS) continue;
+    warnings.push({ ruleId: 'view.oversized', severity: 'warning', diagramType: diagramTypeOf(graph), elementIds: [],
+      message: `the view spans ${Math.round(width)}×${Math.round(height)} units, about ${(across * down).toFixed(1)} screens (${across.toFixed(1)} wide × ${down.toFixed(1)} tall) at the readable zoom ${READABLE_ZOOM}`,
+      remediation: 'Split it by phase or sub-flow into separate views that together cover the whole model, never dropping facts; keep one view only when the user asked for it.' });
+  }
+  return warnings;
+}