qgraphflow 0.0.6 → 0.0.7

package/skills/q-flow/assets/viewer/src/route-clearance.js

@@ -0,0 +1,144 @@
+import { layoutLimits } from './layout-spacing.js';
+import { getDiagram, diagramTypeOf } from './diagrams/registry.js';
+import { routingBounds, groupBorders, groupHeadingBoxes, createEdgeRoutes, occupiedBox, segmentCrossesBox } from './edge-routing.js';
+import { actorTop } from './diagrams/usecase.js';
+import { layoutText } from './text-layout.js';
+import { isArchitectureOverview } from './view-identity.js';
+
+export const clearanceLimits = graph => ({ node: isArchitectureOverview(graph) ? 6 : 12, preferred: isArchitectureOverview(graph) ? 8 : 24, boundary: 6 });
+const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+const pointDistance = (p, a, b) => {
+  const dx = b.x - a.x, dy = b.y - a.y, t = clamp(((p.x - a.x) * dx + (p.y - a.y) * dy) / (dx * dx + dy * dy || 1), 0, 1);
+  return Math.hypot(p.x - a.x - t * dx, p.y - a.y - t * dy);
+};
+function segmentDistance(a, b, c, d) {
+  const cross = (p, q, r) => (q.x - p.x) * (r.y - p.y) - (q.y - p.y) * (r.x - p.x);
+  if (cross(a, b, c) * cross(a, b, d) <= 0 && cross(c, d, a) * cross(c, d, b) <= 0
+    && Math.max(Math.min(a.x, b.x), Math.min(c.x, d.x)) <= Math.min(Math.max(a.x, b.x), Math.max(c.x, d.x))
+    && Math.max(Math.min(a.y, b.y), Math.min(c.y, d.y)) <= Math.min(Math.max(a.y, b.y), Math.max(c.y, d.y))) return 0;
+  return Math.min(pointDistance(a, c, d), pointDistance(b, c, d), pointDistance(c, a, b), pointDistance(d, a, b));
+}
+function boxDistance(a, b, r) {
+  return Math.hypot(Math.max(r.x - Math.max(a.x, b.x), Math.min(a.x, b.x) - r.x - r.width, 0), Math.max(r.y - Math.max(a.y, b.y), Math.min(a.y, b.y) - r.y - r.height, 0));
+}
+function ellipseDistance(a, b, r) {
+  const point = p => {
+    const x = Math.abs(p.x - r.cx), y = Math.abs(p.y - r.cy);
+    if ((x / r.rx) ** 2 + (y / r.ry) ** 2 <= 1+1e-12) return 0;
+    if (x===0) return Math.max(0,y-r.ry);
+    if (y===0) return Math.max(0,x-r.rx);
+    const distance = t => Math.hypot(x - r.rx * Math.cos(t), y - r.ry * Math.sin(t));
+    let lo = 0, hi = Math.PI / 2;
+    for (let i = 0; i < 32; i++) { const l = lo + (hi - lo) / 3, h = hi - (hi - lo) / 3; if (distance(l) < distance(h)) hi = h; else lo = l; }
+    return Math.min(distance(0), distance(Math.PI / 2), distance((lo + hi) / 2));
+  };
+  const h = a.y === b.y, fixed = h ? a.y - r.cy : a.x - r.cx, radius = h ? r.ry : r.rx, extent = h ? r.rx : r.ry, centre = h ? r.cx : r.cy;
+  const lower = Math.min(h ? a.x : a.y, h ? b.x : b.y), upper = Math.max(h ? a.x : a.y, h ? b.x : b.y);
+  if (Math.abs(fixed) <= radius) { const half = extent * Math.sqrt(1 - (fixed / radius) ** 2); if (lower <= centre + half && upper >= centre - half) return 0; }
+  if (lower <= centre && upper >= centre) return Math.max(0,Math.abs(fixed)-radius);
+  const first=point(a);return first===0?0:Math.min(first,point(b));
+}
+function cylinderDistance(a,b,node) {
+  const left=node.position.x+12,right=node.position.x+node.size.width-12,top=node.position.y+2,bottom=node.position.y+node.size.height-2,rx=(right-left)/2,cx=(left+right)/2;
+  const inside=p=>{if(p.x<left||p.x>right)return false;const inset=5*(1-Math.sqrt(Math.min(p.x-left,right-p.x)/rx))**2;return p.y>=top+inset&&p.y<=bottom-inset;};
+  if(inside(a)||inside(b)||inside({x:clamp(cx,Math.min(a.x,b.x),Math.max(a.x,b.x)),y:clamp((top+bottom)/2,Math.min(a.y,b.y),Math.max(a.y,b.y))}))return 0;
+  const curve=(x,y,sx,sy)=>{
+    const distance=t=>pointDistance({x:x+sx*rx*t*t,y:y+sy*5*(1-t)**2},a,b);
+    let lo=0,hi=1;
+    for(let i=0;i<32;i++){const l=lo+(hi-lo)/3,h=hi-(hi-lo)/3;if(distance(l)<distance(h))hi=h;else lo=l;}
+    return Math.min(distance(0),distance(1),distance((lo+hi)/2));
+  };
+  return Math.min(boxDistance(a,b,{x:left,y:top+5,width:right-left,height:bottom-top-10}),curve(left,top,1,1),curve(right,top,-1,1),curve(left,bottom,1,-1),curve(right,bottom,-1,-1));
+}
+function polygonDistance(a, b, points) {
+  const inside = p => { let result = false; for (let i = 0, j = points.length - 1; i < points.length; j = i++) {
+    const c = points[i], d = points[j];
+    if ((c.y > p.y) !== (d.y > p.y) && p.x < (d.x - c.x) * (p.y - c.y) / (d.y - c.y) + c.x) result = !result;
+  } return result; };
+  if (inside(a) || inside(b)) return 0;
+  return Math.min(...points.map((p, i) => segmentDistance(a, b, p, points[(i + 1) % points.length])));
+}
+// Compile once per node: the router checks many grid segments against the same visible geometry.
+const cache = new WeakMap();
+export function nodeClearance(node, type) {
+  const signature = JSON.stringify([type,node.position,node.size,node.kind,node.label,node.subtitle,node.overviewText,node.badges,node.overviewTone]);
+  const cached = cache.get(node); if (cached?.signature === signature) return cached.probe;
+  const diagram = getDiagram(type), { x, y } = node.position;
+  const outline = diagram.outline?.(node, x, y) ?? [];
+  const [tag, shape] = outline[0] ?? [];
+  let probe;
+  if (type === 'usecase' && node.kind === 'actor') {
+    const top = y + actorTop(node), cx = x + node.size.width / 2;
+    const body = [[{x:cx,y:top+24},{x:cx,y:top+53}],[{x:cx-20,y:top+35},{x:cx+20,y:top+35}],[{x:cx,y:top+53},{x:cx-17,y:top+76}],[{x:cx,y:top+53},{x:cx+17,y:top+76}]];
+    const text = [[node.label, 20, top + 78, 26], ...(node.subtitle ? [[node.subtitle, 16, top + 106, 24]] : [])].map(([label, font, ty, height]) => {
+      const width = Math.min(node.size.width, layoutText(label, Infinity, font).width * 1.15); return { x: cx - width / 2, y: ty, width, height };
+    });
+    probe = (a, b) => Math.min(Math.max(0, pointDistance({x:cx,y:top+13},a,b)-11), ...body.map(([c,d])=>segmentDistance(a,b,c,d)), ...text.map(r=>boxDistance(a,b,r)));
+  } else if (tag === 'path' && ['architecture','deployment'].includes(type) && node.kind === 'database') {
+    probe=(a,b)=>cylinderDistance(a,b,node);
+  } else if (tag === 'polygon') {
+    const points = shape.points.split(/\s+/).map(p => { const [x,y]=p.split(',').map(Number); return {x,y}; });
+    probe = (a,b) => polygonDistance(a,b,points);
+  } else if (tag === 'circle') probe = (a,b) => Math.max(0,pointDistance({x:shape.cx,y:shape.cy},a,b)-shape.r);
+  else if (tag === 'ellipse') probe = (a,b) => ellipseDistance(a,b,shape);
+  else {
+    // Path-based cards (cylinders, documents and open stores) also reserve their full text body.
+    const r = tag === 'rect' ? shape : routingBounds(node,type), radius = tag === 'rect' ? Math.min(shape.rx ?? 0,r.width/2,r.height/2) : 0;
+    const inner = {x:r.x+radius,y:r.y+radius,width:r.width-2*radius,height:r.height-2*radius};
+    probe = (a,b) => Math.max(0,boxDistance(a,b,inner)-radius);
+  }
+  if (type === 'state' && ['initial','final'].includes(node.kind) && node.subtitle) {
+    const base=probe, area=diagram.textArea(node), text={...area,x:x+area.x,y:y+area.y};
+    probe=(a,b)=>Math.min(base(a,b),boxDistance(a,b,text));
+  }
+  const geometryProbe=probe, points=new Map();
+  probe=(a,b)=>{
+    if(a.x!==b.x||a.y!==b.y)return geometryProbe(a,b);
+    const key=a.x+','+a.y;if(points.has(key))return points.get(key);
+    const distance=geometryProbe(a,b);if(points.size<1024)points.set(key,distance);return distance;
+  };
+  cache.set(node,{signature,probe}); return probe;
+}
+
+export function boundaryClearance(a,b,group) {
+  const h=a.y===b.y, axis=h?'x':'y', across=h?'y':'x';
+  return groupBorders(group).filter(([c,d])=>h===(c.y===d.y)).map(([c,d])=>({
+    distance:Math.abs(a[across]-c[across]),
+    length:Math.max(0,Math.min(Math.max(a[axis],b[axis]),Math.max(c[axis],d[axis]))-Math.max(Math.min(a[axis],b[axis]),Math.min(c[axis],d[axis])))
+  })).filter(item=>item.length>.001).sort((a,b)=>a.distance-b.distance)[0] ?? {distance:Infinity,length:0};
+}
+
+// Only the terminal segment may enter its own node's clearance band.
+export function clearanceProbe(graph, sourceId, targetId, sourcePoints = [], targetPoints = []) {
+  const type=diagramTypeOf(graph), limits=clearanceLimits(graph);
+  const entries=graph.nodes.map(node=>({node,probe:nodeClearance(node,type),bounds:routingBounds(node,type),terminals:[...(node.id===sourceId?sourcePoints:[]),...(node.id===targetId?targetPoints:[])]}));
+  return (a,b) => entries.some(({node,probe,bounds,terminals})=> {
+    if (boxDistance(a,b,bounds)>=limits.node && !(type==='usecase'&&node.kind==='actor') && !(type==='state'&&node.subtitle)) return false;
+    const endpoint=p=>terminals.some(t=>Math.abs(t.x-p.x)<.001&&Math.abs(t.y-p.y)<.001);
+    if (endpoint(a) && probe(b,b)+.001>=limits.node || endpoint(b) && probe(a,a)+.001>=limits.node) return false;
+    return probe(a,b)+.001<limits.node;
+  }) || (graph.groups??[]).some(group=>boundaryClearance(a,b,group).distance+.001<limits.boundary);
+}
+
+// Edits reserve a halo around changed visible geometry. A changed boundary affects only nearby lanes/headings.
+export function affectedRouteIds(before, after, seed = []) {
+  const ids = new Set(seed), type = diagramTypeOf(after), gap = clearanceLimits(after).node;
+  const changed = after.nodes.filter(node => JSON.stringify(node) !== JSON.stringify(before.nodes.find(old => old.id === node.id)));
+  const nodes = new Set(changed.map(node => node.id));
+  const obstacles = changed.map(node => { const r = occupiedBox(node, type); return { x:r.x-gap, y:r.y-gap, width:r.width+2*gap, height:r.height+2*gap }; });
+  const groups = (after.groups ?? []).filter(group => JSON.stringify(group) !== JSON.stringify(before.groups?.find(old => old.id === group.id)));
+  const routes = createEdgeRoutes(before), labelGap = layoutLimits(getDiagram(type)).labelGap;
+  const labelObstacles = [...changed.map(node => occupiedBox(node,type)), ...groups.flatMap(groupHeadingBoxes)];
+  const rectDistance = (a,b) => Math.hypot(Math.max(a.x-b.x-b.width,b.x-a.x-a.width,0),Math.max(a.y-b.y-b.height,b.y-a.y-a.height,0));
+  for (const edge of after.edges) {
+    const old = before.edges.find(item => item.id === edge.id), route = routes.get(edge.id);
+    if (nodes.has(edge.source) || nodes.has(edge.target) || JSON.stringify(edge) !== JSON.stringify(old)
+      || route && [...(route.label ? [route.labelBox] : []), ...(route.endpointLabels ?? []).map(label=>label.labelBox)].some(label=>labelObstacles.some(box=>rectDistance(label,box)<labelGap))
+      || route?.points.slice(1).some((b,i) => {
+        const a = route.points[i];
+        return obstacles.some(r => segmentCrossesBox(a,b,r)) || groups.some(group => boundaryClearance(a,b,group).distance < clearanceLimits(after).boundary
+          || groupHeadingBoxes(group).some(r => segmentCrossesBox(a,b,r)));
+      })) ids.add(edge.id);
+  }
+  return ids;
+}

package/skills/q-flow/assets/viewer/src/sequence-executions.js

@@ -1,4 +1,5 @@
 import { operandScopes } from './sequence-fragments.js';
+import { edgeLabelLayout } from './text-layout.js';
 
 // Pair numbers follow the calls' message order (C1 is the first call that gets a reply), not their id spelling.
 export function sequencePairs(graph) {
@@ -18,6 +19,27 @@ export function sequenceMessageLabel(graph, edge, pairs = sequencePairs(graph),
   return pair ? `${pair.label} · ${edge.label ?? ''}` : parallel ? edge.label ?? '' : `${String(edge.order).padStart(2, '0')} · ${edge.label ?? ''}`;
 }
 
+// Difference constraints on each message's actual span; moving the suffix keeps unrelated neighboring gaps unchanged.
+// It only widens, so it lays out a fresh row and repairs a placed one alike. `nodes` stand left to right.
+export function spreadParticipants(graph, nodes) {
+  const index = id => nodes.findIndex(node => node.id === id);
+  const constraints = [...graph.edges].sort((a, b) => Math.abs(index(a.source) - index(a.target)) - Math.abs(index(b.source) - index(b.target)) || a.order - b.order);
+  const selfCounts = new Map();
+  for (const edge of constraints) {
+    const left = Math.min(index(edge.source), index(edge.target));
+    let right = Math.max(index(edge.source), index(edge.target));
+    let required = edgeLabelLayout(sequenceMessageLabel(graph, edge)).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;
+  }
+}
+
 // Hand-edited or legacy data may lack route.messageY, or the whole route. Such a message is stacked by order below the
 // default headers so the page still opens; the layout check reports the missing coordinate and --layout auto writes it.
 const FALLBACK_TOP = 140, FALLBACK_STEP = 54;

package/skills/q-flow/assets/viewer/src/sequence-fragments.js

@@ -168,11 +168,29 @@ export function sequenceFragment(group, routes, locale, groups = [], executions
     const childFrames = children.filter(child => child.parentOperandId === operandId(operand, i)).map(child => ({ ...child.position, ...child.size, id: child.id }));
     const selected = operandEdges(group, operand, i, groups).map(id => routes.get(id)).filter(Boolean);
     const boxes = [...childFrames, ...selected.flatMap(route => [route.labelBox, ...segmentBoxes(route)])];
-    return { operand, selected, childFrames, boxes, top: Math.min(...boxes.map(box => box.y)), bottom: Math.max(...boxes.map(box => box.y + box.height)) };
+    const label = group.kind === 'par' ? operand.label : `${group.kind === 'loop' ? `${group.loop.min}..${group.loop.max} ` : ''}[${operand.guard}]`;
+    const width = Math.min(LAYOUT_TARGETS.labelWidth, Math.max(1, frame.width - 40));
+    const textHeight = layoutText(label, width, 14, 20).height + 16 + (operand.body ? layoutText(operand.body, width, 16, 24).height + 12 : 0);
+    return { operand, selected, childFrames, boxes, textHeight, top: Math.min(...boxes.map(box => box.y)), bottom: Math.max(...boxes.map(box => box.y + box.height)) };
   });
   for (let i = 1; i < sections.length; i++) {
     const previous = sections[i - 1], next = sections[i];
-    separators.push(Number.isFinite(previous.bottom) && Number.isFinite(next.top) ? (previous.bottom + next.top) / 2 : headingBottom + (bottom - headingBottom) * i / sections.length);
+    separators.push((previous.bottom + next.top) / 2);
+  }
+  for (let start = 0; start < sections.length; start++) {
+    if (sections[start].boxes.length) continue;
+    let end = start;
+    while (end + 1 < sections.length && !sections[end + 1].boxes.length) end++;
+    const before = sections[start - 1], after = sections[end + 1];
+    const low = before ? before.bottom : headingBottom, high = after ? after.top : bottom;
+    let used = before ? 4 : 0;
+    const total = used + sections.slice(start, end + 1).reduce((sum, section) => sum + section.textHeight, 0) + (after?.textHeight ?? 0);
+    if (before) separators[start - 1] = low + (high - low) * used / total;
+    for (let index = start; index <= end; index++) {
+      used += sections[index].textHeight;
+      if (index + 1 < sections.length) separators[index] = low + (high - low) * used / total;
+    }
+    start = end;
   }
   const members = new Set(group.operands.flatMap((operand, i) => operandEdges(group, operand, i, groups)));
   for (const [id, route] of routes) if (route.points.some(p => p.x >= frame.x && p.x <= frame.x + frame.width && p.y > frame.y && p.y < bottom) && !members.has(id)) errors.push(`layout: group ${group.id} omits enclosed message ${id}`);

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

@@ -1,4 +1,8 @@
-import { diagramTypeOf } from './diagrams/registry.js';
+import { viewIdOf } from './view-identity.js';
+import { cardText, diagramTypeOf, getDiagram } from './diagrams/registry.js';
+import { layoutLimits } from './layout-spacing.js';
+import { requireDiagramQuality } from './layout-quality.js';
+import { groupHeadingLayout } from './text-layout.js';
 
 // The generator embeds the graph as escaped JSON inside this script element; saving from the page rewrites the same
 // element, so the saved page reopens with its edits and the generator and the page never disagree about the encoding.
@@ -11,12 +15,13 @@ export function pageWithGraph(html, graph) {
 }
 
 export function graphInputWithEdits(input, drafts, currentGraph) {
-  const edited = graph => diagramTypeOf(graph) === diagramTypeOf(currentGraph) ? currentGraph : drafts.get(diagramTypeOf(graph)) ?? graph;
+  const edited = graph => viewIdOf(graph) === viewIdOf(currentGraph) ? currentGraph : drafts.get(viewIdOf(graph)) ?? graph;
   return Array.isArray(input.diagrams) ? { ...input, diagrams: input.diagrams.map(edited) } : currentGraph;
 }
 
 export function currentGraphFromFlow(graph, nodes, edges) {
   const nodeState = new Map(nodes.filter(node => node.type === 'diagram').map(node => [node.id, node]));
+  const groupState = new Map(nodes.filter(node => node.type === 'boundary').map(node => [node.id, node]));
   const edgeState = new Map(edges.map(edge => [edge.id, edge]));
   return {
     ...graph,
@@ -24,9 +29,14 @@ export function currentGraphFromFlow(graph, nodes, edges) {
       const current = nodeState.get(node.id);
       if (!current) return node;
       const text = { label: current.data.label };
+      for (const key of ['overviewText', 'badges']) if (Object.hasOwn(current.data, key)) text[key] = current.data[key];
       if (Object.hasOwn(current.data, 'subtitle')) text.subtitle = current.data.subtitle;
-      return { ...node, ...text, position: current.position };
+      return { ...node, ...text, position: current.position, size: current.data.size };
     }),
+    ...(graph.groups && { groups: graph.groups.map(group => {
+      const current = groupState.get(group.id);
+      return current ? { ...group, position: current.position, size: current.data.size } : group;
+    }) }),
     edges: graph.edges.map(edge => {
       const current = edgeState.get(edge.id);
       return current && Object.hasOwn(current.data, 'label') ? { ...edge, label: current.data.label } : edge;
@@ -41,3 +51,36 @@ export function constrainNodeChanges(changes, nodes, diagramType) {
     ? { ...change, position: { ...change.position, y: positions.get(change.id).y } }
     : change);
 }
+
+// The graph with the boxes (id -> { position, size }) of nodes and groups put in place.
+export function placed(graph, boxes) {
+  const place = item => boxes.has(item.id) ? { ...item, ...boxes.get(item.id) } : item;
+  return { ...graph, nodes: graph.nodes.map(place), ...(graph.groups && { groups: graph.groups.map(place) }) };
+}
+
+// A card keeps all of its text. When an edit leaves it too short it grows by the missing height around its centre, else
+// upward, else downward (a connection leaving its top or bottom edge needs the stub there clear), whichever the quality gate
+// accepts first, and the boundaries that own it grow just enough to keep their clearance. If none is accepted the centred
+// growth stays and the gate names what is left; Arrange only moves cards. `classic` is the card style the view already draws
+// (compactCards of the graph before the edit). Returns id -> { position, size } for every box that changed.
+export function fitCard(graph, id, classic) {
+  const type = diagramTypeOf(graph), diagram = getDiagram(type), node = graph.nodes.find(item => item.id === id);
+  const grow = diagram.cardLayout ? cardText(node, type, graph.meta.locale, classic).minHeight - node.size.height : 0;
+  if (grow <= 0) return new Map();
+  const { groupInset, groupHeadingGap } = layoutLimits(diagram), groups = new Map((graph.groups ?? []).map(group => [group.id, group]));
+  // `above` is the share of the extra height that goes over the card's top edge; each boundary then takes in its member's box.
+  const growth = above => {
+    let box = { position: { x: node.position.x, y: Math.max(0, node.position.y - grow * above) }, size: { width: node.size.width, height: node.size.height + grow } };
+    const boxes = new Map([[id, box]]);
+    for (let group = groups.get(node.groupId), depth = 0; group && depth < groups.size; group = groups.get(group.parentId), depth++) {
+      const { position, size } = group, top = groupHeadingLayout(group).height + groupHeadingGap;
+      const left = Math.max(0, Math.min(position.x, box.position.x - groupInset)), upper = Math.max(0, Math.min(position.y, box.position.y - top));
+      const right = Math.max(position.x + size.width, box.position.x + box.size.width + groupInset), lower = Math.max(position.y + size.height, box.position.y + box.size.height + groupInset);
+      boxes.set(group.id, box = { position: { x: left, y: upper }, size: { width: right - left, height: lower - upper } });
+    }
+    return boxes;
+  };
+  const accepted = boxes => { try { requireDiagramQuality(placed(graph, boxes)); return true; } catch { return false; } };
+  const options = [.5, 1, 0].map(growth);
+  return options.find(accepted) ?? options[0];
+}

package/skills/q-flow/assets/viewer/src/text-layout.js

@@ -1,4 +1,5 @@
-import { TYPOGRAPHY } from './visual-style.js';
+import { TYPOGRAPHY, kindLabels } from './visual-style.js';
+import { translate } from './i18n.js';
 import { LAYOUT_LIMITS, LAYOUT_TARGETS } from './layout-spacing.js';
 
 // Conservative system-font widths keep server-rendered SVG and browser labels in the same bounds.
@@ -79,11 +80,37 @@ export function layoutText(value, maxWidth, fontSize = TYPOGRAPHY.body, lineHeig
   return { lines, width: Math.ceil(Math.max(...lines.map(line => textWidth(line, fontSize)))), height: lines.length * lineHeight, lineHeight };
 }
 
-export function cardTextLayout(node) {
-  const width = node.size.width - 30;
-  const title = layoutText(node.label, width, TYPOGRAPHY.title, 26);
-  const subtitle = layoutText(node.subtitle ?? '', width, TYPOGRAPHY.body, 24);
-  return { title, subtitle, minHeight: 65 + title.height + subtitle.height };
+// Component card: the icon plate, the title and the kind tag share the first row; the subtitle and the source anchor (file
+// name and lines) follow in the same text column. The whole block is centred vertically in a taller card.
+export const CARD = Object.freeze({ pad: 14, plate: 24, textX: 48, tagGap: 8, tagPad: 8, titleLine: 26, subtitleLine: 24, sourceLine: 20, minHeight: 64, maxWidth: 360 });
+// The card shows where a component is defined (file name and first line); the quick look and Inspector give the full path and range.
+export const cardSourceText = node => node.source?.file ? `${node.source.file.split('/').at(-1)}:${node.source.lineStart}` : '';
+// A source line never wraps: a file name too long for the column keeps its start and end around an ellipsis.
+function oneLine(value, width, fontSize) {
+  const colon = value.lastIndexOf(':'), name = value.slice(0, colon), line = value.slice(colon);
+  for (let keep = name.length - 1; textWidth(value, fontSize) > width && keep > 4; keep--) value = `${name.slice(0, Math.ceil(keep / 2))}…${name.slice(name.length - Math.floor(keep / 2))}${line}`;
+  return value;
+}
+export const cardTag = (node, locale) => {
+  const value = translate(locale, kindLabels[node.kind] ?? node.kind);
+  // The stereotype style adds .6px letter spacing.
+  return { text: value, width: Math.ceil(textWidth(value, TYPOGRAPHY.small) + value.length * .6) + 2 * CARD.tagPad };
+};
+
+// classic: the card drawn before compact cards (kind row above a full-width title, no source line). Views whose stored
+// geometry predates compact cards keep it; see compactCards.
+// corner: extra room right of the kind tag for notation drawn in the card's top-right corner.
+export function cardTextLayout(node, locale, classic = false, corner = 0) {
+  if (classic) {
+    const title = layoutText(node.label, node.size.width - 30, TYPOGRAPHY.title, 26), subtitle = layoutText(node.subtitle ?? '', node.size.width - 30, TYPOGRAPHY.body, 24);
+    return { title, subtitle, minHeight: Math.max(100, 65 + title.height + subtitle.height) };
+  }
+  const tag = cardTag(node, locale), column = node.size.width - CARD.textX - CARD.pad;
+  const title = layoutText(node.label, column - tag.width - CARD.tagGap - corner, TYPOGRAPHY.title, CARD.titleLine);
+  const subtitle = layoutText(node.subtitle ?? '', column, TYPOGRAPHY.body, CARD.subtitleLine);
+  const source = layoutText(oneLine(cardSourceText(node), column, TYPOGRAPHY.small), column, TYPOGRAPHY.small, CARD.sourceLine);
+  const contentHeight = CARD.pad + title.height + (subtitle.height ? 4 + subtitle.height : 0) + (source.height ? 6 + source.height : 0) + CARD.pad;
+  return { title, subtitle, source, tag, contentHeight, minHeight: Math.max(CARD.minHeight, contentHeight) };
 }
 
 export function edgeLabelLayout(value, maxWidth = LAYOUT_TARGETS.labelWidth) {

package/skills/q-flow/assets/viewer/src/view-identity.js

@@ -0,0 +1,26 @@
+// Legacy collections use their unique diagram type as identity. Repeated architecture views require authored IDs.
+export const viewIdOf = graph => graph?.meta?.viewId ?? graph?.meta?.diagramType ?? 'architecture';
+export const architectureViewOf = graph => graph?.meta?.architectureView ?? 'relations';
+export const isArchitectureOverview = graph => (graph?.meta?.diagramType ?? 'architecture') === 'architecture' && architectureViewOf(graph) !== 'relations';
+export const architectureViewLabels = { relations: 'Component relationship architecture', capabilities: 'Platform capability architecture', engineering: 'Engineering layer architecture' };
+
+// Presentation types are independent templates, while the nine semantic JSON types remain compatible.
+export const VIEW_TYPES = Object.freeze([
+  { id: 'capabilities', type: 'architecture', label: architectureViewLabels.capabilities },
+  { id: 'engineering', type: 'architecture', label: architectureViewLabels.engineering },
+  { id: 'relations', type: 'architecture', label: architectureViewLabels.relations },
+  { id: 'flowchart', type: 'flowchart', label: 'Flowchart' },
+  { id: 'sequence', type: 'sequence', label: 'Sequence' },
+  { id: 'er', type: 'er', label: 'ER diagram' },
+  { id: 'deployment', type: 'deployment', label: 'Deployment' },
+  { id: 'class', type: 'class', label: 'Class diagram' },
+  { id: 'state', type: 'state', label: 'State diagram' },
+  { id: 'usecase', type: 'usecase', label: 'Use cases' },
+  { id: 'dataflow', type: 'dataflow', label: 'Data flow' }
+]);
+export const viewTypeOf = graph => (graph?.meta?.diagramType ?? 'architecture') === 'architecture' ? architectureViewOf(graph) : graph.meta.diagramType;
+export const viewTypeLabel = graph => VIEW_TYPES.find(view => view.id === viewTypeOf(graph))?.label ?? graph?.meta?.diagramType ?? architectureViewLabels.relations;
+export const compareViews = (a, b) => {
+  const rank = graph => { const index = VIEW_TYPES.findIndex(view => view.id === viewTypeOf(graph)); return index < 0 ? VIEW_TYPES.length : index; };
+  return rank(a) - rank(b);
+};

package/skills/q-flow/assets/viewer/src/visual-style.js

@@ -1,4 +1,5 @@
 import { IDENTITY, IDENTITY_SCALES, RADIX } from './radix-colors.js';
+import { overviewAppearance, overviewPalette } from './architecture-overview-theme.js';
 
 // Mix a color over a background: identity washes and headers stay tied to their chip color.
 export function mix(color, background, amount) {
@@ -14,21 +15,22 @@ const FLIGHT_SCALES = ['orange', 'blue', 'teal', 'violet', 'plum', 'indigo'];
 export const PALETTES = Object.fromEntries(Object.entries(RADIX).map(([theme, { neutral: n, accent: t, data: b, warn: a, guard: g }]) => [theme, {
   paper: n[1], surface: n[1], surface2: n[2],
   ink: n[12], ink2: n[11], ink3: n[11], rule: n[6], ruleSoft: n[4],
-  accent: t[11], accentSoft: t[2], ringCore: t[5],
-  data: b[11], warn: a[11], ringWarn: a[5], guard: g[11],
+  accent: theme === 'dark' ? '#67c4aa' : '#126b5a', accentSoft: t[2], ringCore: t[5],
+  data: theme === 'dark' ? '#d9b16c' : '#886019', warn: a[11], ringWarn: a[5], guard: g[11],
   badge: n[3], outline: theme === 'dark' ? n[10] : n[9],
   // Dark cards lift one step above the canvas so a plain card still reads as a surface.
   card: theme === 'dark' ? n[3] : n[1],
   groupFill: n[2], groupFillNested: theme === 'dark' ? mix(n[2], n[3], .5) : n[1], groupLine: n[5],
-  moduleTones: IDENTITY_SCALES.map(name => { const scale = IDENTITY[theme][name]; return { name, chip: scale[9], accent: scale[10], wash: mix(scale[9], theme === 'dark' ? n[3] : n[1], theme === 'dark' ? .09 : .05), header: mix(scale[9], n[2], theme === 'dark' ? .16 : .1) }; }),
+  moduleTones: (theme === 'dark' ? ['#80b5ea', '#67c4aa', '#bb9add', '#d9b16c', '#9eafa7'] : ['#3677bb', '#16816d', '#8c64ac', '#b27e2a', '#6a7c75']).map((color, index) => ({ name: ['blue', 'teal', 'purple', 'amber', 'sage'][index], chip: color, accent: color, wash: mix(color, theme === 'dark' ? n[3] : n[1], .09), header: mix(color, n[2], theme === 'dark' ? .16 : .09) })),
   // Lifecycle tones of a state card: the goal is green, an ended state Slate, a failed one Red, and in-flight states take
   // the ramp above. The body is step 3; the frame is step 11 on light cards and step 10 on dark ones, the first steps
   // that hold 3:1 against that body in each theme.
+  sequenceTones: IDENTITY_SCALES.map(name => IDENTITY[theme][name][10]),
   stateTones: (() => {
     const step = theme === 'dark' ? 10 : 11, scales = IDENTITY[theme], identity = name => ({ name, fill: scales[name][3], stroke: scales[name][step] });
     return { goal: identity('grass'), ended: { name: 'slate', fill: n[3], stroke: n[step] }, failed: { name: 'red', fill: a[3], stroke: a[step] }, flight: FLIGHT_SCALES.map(identity) };
   })(),
-  edge: theme === 'dark' ? n[10] : n[9],
+  edge: theme === 'dark' ? n[10] : '#747982',
   mask: theme === 'dark' ? 'rgba(17,17,19,.75)' : 'rgba(252,252,253,.75)',
   group: n[2]
 }]));
@@ -107,6 +109,7 @@ const STATE_TONE_LABELS = { goal: 'Core state', ended: 'Ended state', failed: 'F
 // Text never follows either: titles stay ink. A failure keeps its red frame over any module. A state in a state
 // diagram wears its lifecycle tone instead of the module's frame and wash; the ring and the module's lines stay.
 export function nodeAppearance(node, palette, moduleColors) {
+  if (node.overviewText !== undefined || node.badges !== undefined || node.overviewTone !== undefined) return overviewAppearance(node, palette);
   const tone = moduleColors?.get(node.module);
   const stateRole = node.kind === 'state' ? moduleColors?.stateTones?.get(node.id) : undefined;
   if (stateRole) {
@@ -125,9 +128,10 @@ export function nodeAppearance(node, palette, moduleColors) {
 }
 
 // Pairs walk the identity scales in order; the order itself keeps neighbouring pair numbers far apart in hue.
-export const sequenceGroupColor = (pair, palette) => pair ? palette.moduleTones[pair.index % palette.moduleTones.length].accent : undefined;
+export const sequenceGroupColor = (pair, palette) => pair ? palette.sequenceTones[pair.index % palette.sequenceTones.length] : undefined;
 
 export function edgeColor(edge, target, palette, moduleColors, source, pair) {
+  if (source?.overviewTone !== undefined) return overviewPalette(palette).edge;
   if (pair) return sequenceGroupColor(pair, palette);
   if (edge.kind === 'failure') return palette.warn;
   if (edge.kind === 'success') return palette.accent;
@@ -142,6 +146,10 @@ export function themeVariables(palette) {
   return Object.fromEntries([...Object.entries(tokens).map(([name, key]) => [`--${name}`, palette[key]]), ...Object.entries(sizes).map(([name, key]) => [`--${name}`, `${TYPOGRAPHY[key]}px`])]);
 }
 
+export const evidenceLabels = { source: 'Source code', code: 'Code', config: 'Configuration', schema: 'Schema', test: 'Test', document: 'Document', framework: 'Framework convention', inference: 'Inference' };
+// "file:start-end" for a node source or an edge site.
+export const anchorText = anchor => `${anchor.file}:${anchor.lineStart}${anchor.lineEnd ? `-${anchor.lineEnd}` : ''}`;
+
 export const kindLabels = {
   external: 'External', config: 'Configuration', framework: 'Framework', security: 'Security', service: 'Service', business: 'Business',
   data: 'Data', failure: 'Failure', system: 'System', component: 'Component', database: 'Database', start: 'Start', end: 'End',