qgraphflow 0.0.6 → 0.0.7

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

@@ -0,0 +1,271 @@
+import { affectedRouteIds } from './route-clearance.js';
+import { compactCandidates } from './layout-compaction.js';
+import { layoutWeights, LAYOUT_VERSION, currentLayout } from './layout-policy.js';
+import { routeOrthogonal } from './orthogonal-routing.js';
+import { auditLayoutQuality, requireDiagramQuality } from './layout-quality.js';
+import { graphBounds, occupiedBox } from './edge-routing.js';
+import { diagramTypeOf, getDiagram, canvasBudgetFor } from './diagrams/registry.js';
+import { layoutTargets, layoutLimits } from './layout-spacing.js';
+import { groupHeadingLayout } from './text-layout.js';
+import { isArchitectureOverview } from './view-identity.js';
+import { spreadParticipants } from './sequence-executions.js';
+import { preservesTemplateOrder } from './layout-templates.js';
+
+export const REFINE_BUDGET = 60;
+export const MAX_LOCAL_SHIFT = 156;
+const stable = (a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+
+export function layoutMetrics(graph, audit = auditLayoutQuality(graph)) {
+  const routes = [...audit.routes.values()], bounds = graphBounds(graph, audit.routes), count = Math.max(1, routes.length);
+  const content = graph.nodes.reduce((sum, n) => { const b = occupiedBox(n, diagramTypeOf(graph)); return sum + b.width * b.height; }, 0), unit = Math.sqrt(content / Math.max(1, graph.nodes.length));
+  const length = routes.reduce((sum, r) => sum + r.points.slice(1).reduce((s, p, i) => s + Math.abs(p.x - r.points[i].x) + Math.abs(p.y - r.points[i].y), 0), 0);
+  const bends = routes.reduce((sum, r) => sum + Math.max(0, r.points.length - 2), 0), crossings = audit.crossings.reduce((sum, item) => sum + item.measured, 0);
+  const canvas=canvasBudgetFor(diagramTypeOf(graph)),aspectRatio=bounds.width/Math.max(1,bounds.height),aspectPenalty=canvas?Math.abs(aspectRatio-canvas.width/canvas.height):0;
+  return { errors: audit.errors.length, aspectRatio, aspectPenalty, area: bounds.width * bounds.height, length, bends, crossings, cost: bounds.width * bounds.height / content + length / (count * unit) + layoutWeights.bends * bends / count + layoutWeights.crossings * crossings / count };
+}
+const better = (a, b) => a.errors < b.errors || a.errors === b.errors && (a.cost < b.cost - .001 || Math.abs(a.cost-b.cost)<.001 && a.aspectPenalty < b.aspectPenalty - .001);
+
+function scopeIds(graph, focusId) {
+  if (!focusId) return new Set(graph.nodes.map(n => n.id));
+  return new Set([focusId, ...graph.edges.filter(e => e.source === focusId || e.target === focusId).flatMap(e => [e.source, e.target])]);
+}
+function preservesOrder(before, after) {
+  if (!preservesTemplateOrder(before, after)) return false;
+  const sequence = getDiagram(diagramTypeOf(before)).sequence;
+  const axis = sequence ? 'x' : before.layout?.direction === 'right' ? 'y' : 'x';
+  for (const a of before.nodes) for (const b of before.nodes) {
+    if (a.id >= b.id || a.groupId !== b.groupId || a.layout?.order === undefined || b.layout?.order === undefined) continue;
+    const na = after.nodes.find(n => n.id === a.id), nb = after.nodes.find(n => n.id === b.id);
+    if ((a.position[axis] - b.position[axis]) * (na.position[axis] - nb.position[axis]) < 0) return false;
+  }
+  if (['flowchart', 'state'].includes(diagramTypeOf(before))) for (const e of before.edges) {
+    const a = before.nodes.find(n => n.id === e.source), b = before.nodes.find(n => n.id === e.target);
+    if (a.id === b.id) continue;
+    const na = after.nodes.find(n => n.id === a.id), nb = after.nodes.find(n => n.id === b.id);
+    if (a.position.x === b.position.x && b.position.y > a.position.y && nb.position.y <= na.position.y) return false;
+    if (b.position.x > a.position.x && b.position.y < a.position.y && (nb.position.x <= na.position.x || nb.position.y >= na.position.y)) return false;
+  }
+  if (sequence) {
+    const ordered = [...before.nodes].sort((a, b) => a.position.x - b.position.x || stable(a, b));
+    for (let i = 1; i < ordered.length; i++) if (after.nodes.find(n => n.id === ordered[i].id).position.x <= after.nodes.find(n => n.id === ordered[i - 1].id).position.x) return false;
+  }
+  return true;
+}
+
+// A wider participant header pushes every later participant right, then the message spans are restored (the same
+// constraints compileSequence uses). Whatever stands at or right of a participant's old left edge moves with it, so a
+// fragment frame spanning that cut stretches and the horizontal bound still applies.
+function repairSequenceRow(input) {
+  const graph = structuredClone(input), limits = layoutLimits(getDiagram('sequence'));
+  const nodes = [...graph.nodes].sort((a, b) => a.position.x - b.position.x || stable(a, b)), cuts = nodes.map(node => node.position.x);
+  for (let i = 1; i < nodes.length; i++) {
+    const shift = nodes[i - 1].position.x + nodes[i - 1].size.width + limits.nodeGap - nodes[i].position.x;
+    if (shift > 0) for (let j = i; j < nodes.length; j++) nodes[j].position.x += shift;
+  }
+  spreadParticipants(graph, nodes);
+  const moved = nodes.map((node, i) => node.position.x - cuts[i]);
+  if (moved.some(delta => delta > MAX_LOCAL_SHIFT)) return null;
+  const follow = x => x + (moved[cuts.findLastIndex(cut => cut <= x)] ?? 0);
+  for (const group of graph.groups ?? []) { const right = follow(group.position.x + group.size.width); group.position.x = follow(group.position.x); group.size.width = right - group.position.x; }
+  for (const edge of graph.edges) {
+    if (edge.route?.via) edge.route.via = edge.route.via.map(point => ({ ...point, x: follow(point.x) }));
+    if (edge.route?.labelAt) edge.route.labelAt = { ...edge.route.labelAt, x: follow(edge.route.labelAt.x) };
+  }
+  return graph;
+}
+
+// Expanding edited text may consume both adjacent gaps. Repair that small collision chain
+// together before routing; individual moves cannot pass the gate while another gap is invalid.
+function repairEditedGaps(input, focusId, laneAxis) {
+  const graph = structuredClone(input), type = diagramTypeOf(graph), diagram = getDiagram(type), limits = layoutLimits(diagram);
+  if (diagram.sequence) return repairSequenceRow(input);
+  const changed = new Set([focusId]), related = new Set([focusId]);
+  for (let size = 0; size !== related.size;) { size = related.size; for (const edge of graph.edges) if (related.has(edge.source) || related.has(edge.target)) { related.add(edge.source); related.add(edge.target); } }
+  for (let step = 0; step < graph.nodes.length * 2; step++) {
+    let moved = false;
+    for (const a of [...graph.nodes].sort(stable)) for (const b of graph.nodes) {
+      if (a.id >= b.id || !changed.has(a.id) && !changed.has(b.id)) continue;
+      const x = Math.max(a.position.x, b.position.x) - Math.min(a.position.x + a.size.width, b.position.x + b.size.width);
+      const y = Math.max(a.position.y, b.position.y) - Math.min(a.position.y + a.size.height, b.position.y + b.size.height);
+      if (Math.hypot(Math.max(0, x), Math.max(0, y)) >= limits.nodeGap) continue;
+      const axis = laneAxis === 'x' || ['flowchart', 'state', 'class'].includes(type) ? 'y' : laneAxis === 'y' ? 'x' : x <= 0 ? 'y' : 'x';
+      const dimension = axis === 'x' ? 'width' : 'height';
+      const first = a.position[axis] <= b.position[axis] ? a : b, last = first === a ? b : a;
+      const cut = last.position[axis], shift = first.position[axis] + first.size[dimension] + limits.nodeGap - cut;
+      // Grow a row/column gap as a unit, so siblings and following bands keep their alignment.
+      for (const item of graph.nodes.filter(node => node.groupId === last.groupId && (related.has(node.id) || Math.abs(node.position[axis] - cut) < .001) && node.position[axis] >= cut)) {
+        item.position[axis] += shift;
+        const origin = input.nodes.find(n => n.id === item.id).position;
+        if (Math.abs(item.position[axis] - origin[axis]) > MAX_LOCAL_SHIFT) return null;
+        changed.add(item.id);
+      }
+      moved = true;
+    }
+    if (!moved) break;
+  }
+  const groups = graph.groups ?? [], groupById = new Map(groups.map(group => [group.id, group]));
+  const inside = (id, parent) => {
+    for (let item = groupById.get(id), depth = 0; item && depth < groups.length; item = groupById.get(item.parentId), depth++) if (item.id === parent) return true;
+    return false;
+  };
+  // A growing foreign card can reach a neighbouring ownership frame. Move that entire frame, with its members,
+  // rather than leaving a member outside or changing ownership. This is bounded by the same operation origin.
+  for (const node of graph.nodes.filter(item => changed.has(item.id))) for (const group of groups) {
+    if (inside(node.groupId, group.id)) continue;
+    const overlapX = Math.min(node.position.x + node.size.width, group.position.x + group.size.width) - Math.max(node.position.x, group.position.x);
+    const overlapY = Math.min(node.position.y + node.size.height, group.position.y + group.size.height) - Math.max(node.position.y, group.position.y);
+    if (overlapX <= 0 || overlapY <= 0) continue;
+    const moves = ['x', 'y'].map(axis => {
+      const dimension = axis === 'x' ? 'width' : 'height';
+      const after = group.position[axis] + group.size[dimension] / 2 >= node.position[axis] + node.size[dimension] / 2;
+      return { axis, delta: after ? node.position[axis] + node.size[dimension] + limits.nodeGap - group.position[axis] : node.position[axis] - limits.nodeGap - group.position[axis] - group.size[dimension] };
+    }).sort((a, b) => Math.abs(a.delta) - Math.abs(b.delta));
+    const members = [...groups.filter(item => inside(item.id, group.id)), ...graph.nodes.filter(item => inside(item.groupId, group.id))];
+    const movement = moves.find(({axis, delta}) => members.every(item => {
+      const original = [...input.nodes, ...(input.groups ?? [])].find(old => old.id === item.id);
+      return item.position[axis] + delta >= 0 && Math.abs(item.position[axis] + delta - original.position[axis]) <= MAX_LOCAL_SHIFT;
+    }));
+    if (!movement) return null;
+    for (const item of members) { item.position[movement.axis] += movement.delta; if (graph.nodes.includes(item)) changed.add(item.id); }
+  }
+  expandOwnershipBounds(graph);
+  return graph;
+}
+
+function expandOwnershipBounds(graph) {
+  const limits = layoutLimits(getDiagram(diagramTypeOf(graph))), groups = graph.groups ?? [], done = new Set();
+  const expand = group => {
+    if (done.has(group.id)) return; done.add(group.id);
+    const children = groups.filter(g => g.parentId === group.id); children.forEach(expand);
+    const members = [...graph.nodes.filter(n => n.groupId === group.id), ...children];
+    if (!members.length) return;
+    const top = groupHeadingLayout(group).height + limits.groupHeadingGap, inset = limits.groupInset;
+    const left = Math.max(0, Math.min(group.position.x, ...members.map(n => n.position.x - inset)));
+    const upper = Math.max(0, Math.min(group.position.y, ...members.map(n => n.position.y - top)));
+    const right = Math.max(group.position.x + group.size.width, ...members.map(n => n.position.x + n.size.width + inset));
+    const lower = Math.max(group.position.y + group.size.height, ...members.map(n => n.position.y + n.size.height + inset));
+    group.position = { x: left, y: upper }; group.size = { width: right - left, height: lower - upper };
+  };
+  groups.forEach(expand);
+  return graph;
+}
+
+// Geometry only. Ranks, ownership, fields, evidence and sequence events stay authored.
+export function refineDiagramLayout(input, { focusId = null, move = true, evaluations = REFINE_BUDGET, passes = 3, laneAxis = null, growBoundaries = false, global = false, edgeIds: requestedEdges = null } = {}) {
+  laneAxis ??= /fold\d+c$/.test(input.layout?.strategy ?? '') ? 'x' : /fold\d+r?$/.test(input.layout?.strategy ?? '') ? 'y' : null;
+  const origin = structuredClone(input), ids = scopeIds(origin, focusId), attempts = [];
+  let best = structuredClone(input);
+  if (growBoundaries) expandOwnershipBounds(best);
+  if (growBoundaries && requestedEdges) requestedEdges = affectedRouteIds(origin, best, requestedEdges);
+  const strictEdgeIds = requestedEdges ? new Set(requestedEdges) : focusId ? new Set(best.edges.filter(e => ids.has(e.source) || ids.has(e.target)).map(e => e.id)) : new Set(best.edges.map(e => e.id));
+  let metrics = layoutMetrics(best, auditLayoutQuality(best, { strictEdgeIds })), routing, count = 0;
+  const evaluate = (candidate, movedId = null, full = false) => {
+    let edgeIds = !full && requestedEdges ? new Set(requestedEdges) : !full && focusId ? new Set(candidate.edges.filter(e => ids.has(e.source) || ids.has(e.target)).map(e => e.id)) : null;
+    if (!global && !full) edgeIds = affectedRouteIds(best, candidate, edgeIds ?? strictEdgeIds);
+    count++;
+    try {
+      if (global) {
+        const audit = auditLayoutQuality(candidate), score = layoutMetrics(candidate,audit);
+        // Empty-channel compression can preserve a legal path exactly. Keep that improvement before
+        // searching new ports; otherwise repair only paths made invalid by the geometry change.
+        if (!score.errors && better(score,metrics)) {
+          attempts.push({errors:0,cost:score.cost,routing:{termination:'preserved-clear-paths'}});
+          best=candidate; metrics=score; return true;
+        }
+        if (!score.errors && count>1) {
+          edgeIds=affectedRouteIds(best,candidate);
+          if(!edgeIds.size)return false;
+        }
+        if (score.errors) {
+          const affected = new Set(audit.diagnostics.filter(d=>d.severity==='error').flatMap(d=>d.elementIds));
+          edgeIds = new Set(candidate.edges.filter(e=>affected.has(e.id)).map(e=>e.id));
+        }
+      }
+      const routed = routeOrthogonal(candidate, { passes: movedId || global && count > 1 ? 1 : passes, edgeIds, accept: requireDiagramQuality });
+      const next = routed.graph, score = layoutMetrics(next, auditLayoutQuality(next, { strictEdgeIds: edgeIds ?? strictEdgeIds }));
+      attempts.push({ errors: score.errors, cost: score.cost, routing: routed.report });
+      if (better(score, metrics)) { for (const id of edgeIds ?? []) strictEdgeIds.add(id); best = next; metrics = score; routing = routed.report; return true; }
+    } catch (error) { attempts.push({ reason: error.routingReason ?? 'quality', elementIds: error.elementIds ?? [], routing: error.routingReport }); }
+    return false;
+  };
+  if (evaluations > 0) evaluate(best);
+  if (move && focusId && metrics.errors && count < evaluations && !isArchitectureOverview(input)) {
+    const repaired = repairEditedGaps(best, focusId, laneAxis);
+    if (repaired && preservesOrder(origin, repaired)) evaluate(repaired);
+  }
+  if (global && move && !isArchitectureOverview(input) && diagramTypeOf(input) !== 'sequence') {
+    let improved = true;
+    while (improved && count < evaluations) {
+      improved = false;
+      for (const candidate of compactCandidates(best)) {
+        if (count >= evaluations) break;
+        // Global row/subtree permutations are constrained by authored ranks/order and the type quality gate.
+        if (candidate.nodes.some(n => n.position.x < 0 || n.position.y < 0) || !['architecture', 'er'].includes(diagramTypeOf(input)) && !preservesOrder(origin,candidate)) continue;
+        const checked = auditLayoutQuality(candidate);
+        if (checked.diagnostics.some(d => d.severity === 'error' && (d.ruleId.startsWith('semantic.') || d.ruleId.startsWith('group.') || d.ruleId === 'spacing.nodes'))) continue;
+        if (evaluate(candidate, null, true)) { improved = true; break; }
+      }
+    }
+  }
+  // Presentation grids are realigned by their section planner, never nudged across slots.
+  if (move && !global && !isArchitectureOverview(input)) {
+    const diagram = getDiagram(diagramTypeOf(input)), target = layoutTargets(diagram).nodeGap;
+    let changed = true;
+    while (changed && count < evaluations) {
+      changed = false;
+      const problems = new Set(auditLayoutQuality(best).diagnostics.filter(d => d.severity === 'error').flatMap(d => d.elementIds));
+      const nodes = [...best.nodes].filter(n => ids.has(n.id)).sort((a, b) => Number(problems.has(b.id)) - Number(problems.has(a.id)) || stable(a, b));
+      for (const node of nodes) {
+        const neighbors = best.edges.filter(e => e.source === node.id || e.target === node.id).map(e => best.nodes.find(n => n.id === (e.source === node.id ? e.target : e.source))).filter(n => n.id !== node.id);
+        const adjacent = neighbors.length ? neighbors : best.nodes.filter(n => n.id !== node.id && n.groupId === node.groupId);
+        const here = node.position, anchor = origin.nodes.find(n => n.id === node.id).position, moves = [];
+        for (const other of [...adjacent].sort(stable)) for (const axis of diagram.sequence ? ['x'] : laneAxis ? [laneAxis === 'x' ? 'y' : 'x'] : ['flowchart', 'state', 'class'].includes(diagramTypeOf(input)) ? ['y'] : ['x', 'y']) {
+          const dimension = axis === 'x' ? 'width' : 'height', delta = other.position[axis] - here[axis];
+          const desired = delta > 0 ? other.position[axis] - node.size[dimension] - target : other.position[axis] + other.size[dimension] + target;
+          if (Math.abs(desired - here[axis]) > 1) moves.push({ axis, value: here[axis] + Math.sign(desired - here[axis]) * Math.min(32, Math.abs(desired - here[axis])) });
+        }
+        if (problems.size) for (const axis of diagram.sequence ? ['x'] : laneAxis ? [laneAxis === 'x' ? 'y' : 'x'] : ['flowchart', 'state', 'class'].includes(diagramTypeOf(input)) ? ['y'] : ['x', 'y']) for (const delta of [-32, 32]) moves.push({ axis, value: here[axis] + delta });
+        const seen = new Set();
+        for (const { axis, value } of moves) {
+          if (count >= evaluations) break;
+          const k = axis + ':' + value;
+          if (seen.has(k) || value < 0 || Math.abs(value - anchor[axis]) > MAX_LOCAL_SHIFT) continue; seen.add(k);
+          const candidate = structuredClone(best); candidate.nodes.find(n => n.id === node.id).position[axis] = value;
+          if (!preservesOrder(origin, candidate)) continue;
+          const checked = auditLayoutQuality(candidate);
+          if (checked.diagnostics.some(d => d.severity === 'error' && (d.ruleId.startsWith('semantic.') || d.ruleId.startsWith('group.') || d.ruleId === 'spacing.nodes'))) continue;
+          if (evaluate(candidate, node.id)) { changed = true; break; }
+        }
+        if (changed || count >= evaluations) break;
+      }
+    }
+  }
+  const report = { budget: evaluations, evaluations: count, termination: count >= evaluations ? 'evaluation-budget' : move ? 'no-improving-local-candidate' : 'routing-only', provenImpossible: false, routing, before: layoutMetrics(origin), after: metrics, attempts };
+  try { requireDiagramQuality(best, { strictEdgeIds }); }
+  catch (error) { throw Object.assign(error, { routingReport: { ...report, termination: 'no-valid-candidate' } }); }
+  const movedNodeIds = best.nodes.filter(n => { const a = origin.nodes.find(o => o.id === n.id); return a.position.x !== n.position.x || a.position.y !== n.position.y; }).map(n => n.id);
+  return { graph: best, movedNodeIds, report };
+}
+
+// When upgrading an older positioned graph, its valid corridors are a useful candidate too.
+// The same finite refinement budget is shared across this seed and the fresh template/layered seed.
+export function refineWithLegacySeed(fresh, input, options = {}) {
+  const seeds=[fresh];
+  if (!currentLayout(input) && diagramTypeOf(input)!=='sequence' && [...input.nodes,...(input.groups??[])].every(n=>n.position&&n.size)) {
+    const legacy=structuredClone(input);legacy.layout={...legacy.layout,version:LAYOUT_VERSION,strategy:legacy.layout?.strategy??'legacy-refined'};
+    seeds.push(legacy);
+  }
+  let remaining=options.evaluations??REFINE_BUDGET,best,last,used=0,selectedSeed=0;const reports=[];
+  for (const [index,seed] of seeds.entries()) {
+    const budget=Math.floor(remaining/(seeds.length-index));
+    try {
+      const result=refineDiagramLayout(seed,{...options,global:true,evaluations:budget});
+      remaining-=result.report.evaluations;used+=result.report.evaluations;reports.push(result.report);
+      if(!best||better(result.report.after,best.report.after)){best=result;selectedSeed=index;}
+    } catch(error) {
+      last=error;const count=error.routingReport?.evaluations??budget;remaining-=count;used+=count;reports.push(error.routingReport??{termination:'no-valid-candidate',evaluations:count});
+    }
+  }
+  if(!best)throw Object.assign(last??new Error('No valid refinement candidate'),{routingReport:{budget:options.evaluations??REFINE_BUDGET,evaluations:used,termination:'no-valid-candidate',seeds:reports}});
+  return {...best,report:{...best.report,budget:options.evaluations??REFINE_BUDGET,evaluations:used,selectedSeed,...(seeds.length>1?{seeds:reports}:{})}};
+}

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

@@ -0,0 +1,8 @@
+export const DEPLOYMENT_TIERS = Object.freeze(['external', 'application', 'infrastructure', 'data']);
+export function deploymentTierOf(node) {
+  if (node.layout?.tier) return DEPLOYMENT_TIERS.indexOf(node.layout.tier);
+  if (['external', 'actor', 'client'].includes(node.kind)) return 0;
+  if (node.kind === 'database') return 3;
+  if (['queue', 'cache'].includes(node.kind)) return 2;
+  return 1;
+}

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

@@ -1,12 +1,31 @@
 // Graph units: safety limits are shared by generation, editing and export.
 export const LAYOUT_LIMITS = Object.freeze({ nodeGap: 48, labelGap: 24, labelEdgeGap: 6, groupHeadingGap: 24, groupInset: 32, groupGap: 48, endpoint: 12, parallelGap: 24 });
 export const LAYOUT_TARGETS = Object.freeze({ nodeGap: 64, layerGap: 80, edgeNodeGap: 24, labelWidth: 320, headingWidth: 360 });
-// A finished diagram keeps its width/height ratio between 1/ASPECT_BAND (portrait) and ASPECT_BAND (landscape); the graph's
-// own shape decides which side. Type budgets only express a preferred orientation inside this band.
+// Compact component cards (architecture, deployment) stack closer and sit closer to their boundary; the target keeps 8 units
+// of drag room above the limit.
+const CARD_LIMITS = Object.freeze({ ...LAYOUT_LIMITS, nodeGap: 32, groupInset: 24, groupGap: 32 }), CARD_TARGETS = Object.freeze({ ...LAYOUT_TARGETS, nodeGap: 40, layerGap: 48 });
+export const layoutLimits = diagram => diagram?.cardLayout ? CARD_LIMITS : LAYOUT_LIMITS;
+export const layoutTargets = diagram => diagram?.cardLayout ? CARD_TARGETS : LAYOUT_TARGETS;
+// Aspect is advisory: it triggers folded candidates and breaks equal-cost ties. Safety and semantic rules remain hard limits.
 export const ASPECT_BAND = 1.6;
-// A shape within this factor of the band counts as acceptable: it triggers no fold, and among folds the fewest segments
-// within it win. Without the slack a one-percent overshoot could trigger a fold that costs far more than it fixes.
+// This slack avoids generating fold candidates for a negligible overshoot; every legal candidate uses the normalized score.
 export const ASPECT_SLACK = 1.1;
 // How far a width/height ratio sits outside the band, as a factor ≥ 1; 1 means inside. Callers compare it to two decimals,
 // so a shape within one percent of the band edge counts as inside.
 export const ratioExcess = ratio => Math.max(ratio / ASPECT_BAND, 1 / (ratio * ASPECT_BAND), 1);
+// First-screen zoom floor: fitting everything below it would shrink the 14/16/20px text under about 10px, so the Viewer opens
+// at this scale on the start of the reading flow instead (14/16/20px read as 10.5/12/15px).
+export const READABLE_ZOOM = .75;
+// Whole-view floor: a view that fits the screen at this zoom or more opens whole, its 20/16px text read as at least 9/7.2px
+// like a printed overview; a larger view opens at READABLE_ZOOM on the start of the reading flow.
+export const OVERVIEW_ZOOM = .45;
+// What "one screen" means for the size advisory: the reading rectangle of a 1440×900 window with both panels closed
+// (readingRect), and how many such screens a view may need at READABLE_ZOOM before generation suggests splitting it.
+export const OVERVIEW_AREA = Object.freeze({ width: 1392, height: 688 });
+export const MAX_SCREENS = 4;
+// Layered direction. ER, deployment, data flow and use case read left to right; architecture is laid out both ways and keeps the
+// result that shows the whole view on one OVERVIEW_AREA at the larger zoom. The compiler records its choice in layout.direction,
+// and a direction already there is kept.
+const RIGHT_TYPES = ['er', 'deployment', 'dataflow', 'usecase'];
+export const layeredDirections = type => type === 'architecture' ? ['down', 'right'] : type === 'deployment' ? ['down', 'right'] : [RIGHT_TYPES.includes(type) ? 'right' : 'down'];
+export const layeredDown = (type, layout) => (layout?.direction ?? layeredDirections(type)[0]) === 'down';

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

@@ -0,0 +1,298 @@
+import { deploymentTierOf } from './layout-semantics.js';
+import { viewTypeOf } from './view-identity.js';
+import { diagramTypeOf, getDiagram } from './diagrams/registry.js';
+import { minimumNodeSize } from './layout-measure.js';
+import { layoutLimits, layoutTargets, layeredDirections } from './layout-spacing.js';
+import { groupHeadingLayout, estimateLabelSize } from './text-layout.js';
+import { visibleEdgeLabel } from './edge-routing.js';
+
+const stable = (a, b) => (a.layout?.order ?? 0) - (b.layout?.order ?? 0) || a.id.localeCompare(b.id, 'en');
+const kinds = item => item.members.map(node => node.kind);
+const has = (item, values) => kinds(item).some(kind => values.includes(kind));
+const degree = (item, edges) => edges.filter(edge => item.ids.has(edge.source) || item.ids.has(edge.target)).length;
+
+// Strongly connected components stay together. Cycles never create unbounded ranks, and array order is not a hint.
+function layers(items, edges) {
+  const owner = new Map(items.flatMap((item, index) => [...item.ids].map(id => [id, index])));
+  const next = items.map(() => new Set());
+  for (const edge of edges) { const a = owner.get(edge.source), b = owner.get(edge.target); if (a !== undefined && b !== undefined && a !== b) next[a].add(b); }
+  let clock = 0;
+  const index = new Map(), low = new Map(), stack = [], active = new Set(), components = [];
+  function visit(id) {
+    index.set(id, clock); low.set(id, clock++); stack.push(id); active.add(id);
+    for (const target of next[id]) {
+      if (!index.has(target)) { visit(target); low.set(id, Math.min(low.get(id), low.get(target))); }
+      else if (active.has(target)) low.set(id, Math.min(low.get(id), index.get(target)));
+    }
+    if (low.get(id) === index.get(id)) { const part = []; let member; do { member = stack.pop(); active.delete(member); part.push(member); } while (member !== id); components.push(part); }
+  }
+  items.forEach((_, i) => { if (!index.has(i)) visit(i); });
+  const component = new Map(components.flatMap((part, i) => part.map(id => [id, i]))), rank = new Map();
+  function depth(id) {
+    if (rank.has(id)) return rank.get(id);
+    const parents = new Set();
+    next.forEach((targets, source) => { if (component.get(source) !== id && [...targets].some(target => component.get(target) === id)) parents.add(component.get(source)); });
+    const value = parents.size ? Math.max(...[...parents].map(depth)) + 1 : 0; rank.set(id, value); return value;
+  }
+  const rows = [];
+  items.forEach((item, i) => { const r = depth(component.get(i)); (rows[r] ??= []).push(item); });
+  return rows.filter(Boolean).map(row => row.sort(stable));
+}
+
+function grid(items, ratio = 1.45) {
+  if (!items.length) return [];
+  if (items.length <= 2) return [items];
+  const average = key => items.reduce((sum, item) => sum + item.size[key], 0) / items.length;
+  const columns = Math.max(1, Math.min(items.length, Math.round(Math.sqrt(items.length * average('height') * ratio / average('width')))));
+  return Array.from({ length: Math.ceil(items.length / columns) }, (_, i) => items.slice(i * columns, (i + 1) * columns));
+}
+
+function components(items, graph) {
+  const rows = layers(items, graph.edges);
+  if (rows.length === 1 && items.length > 5) return grid(rows[0]);
+  return rows.map(row => row.sort((a, b) => String(a.members[0]?.module ?? '').localeCompare(String(b.members[0]?.module ?? '')) || stable(a, b)));
+}
+// Feedback relationships are routed around the spine; they do not collapse its steps into one rank.
+function forwardEdges(graph) {
+  const seen = new Set(), active = new Set(), feedback = new Set();
+  const next = id => graph.edges.filter(edge => edge.source === id).sort(stable);
+  function visit(id) {
+    if (seen.has(id)) return;
+    seen.add(id); active.add(id);
+    for (const edge of next(id)) { if (active.has(edge.target)) feedback.add(edge.id); else visit(edge.target); }
+    active.delete(id);
+  }
+  const first = graph.layout?.primaryPath ?? graph.nodes.filter(node => ['initial', 'start'].includes(node.kind)).map(node => node.id);
+  [...first, ...[...graph.nodes].sort(stable).map(node => node.id)].forEach(visit);
+  return graph.edges.filter(edge => !feedback.has(edge.id));
+}
+function workflow(items, graph) {
+  const path = graph.layout?.primaryPath ?? [];
+  const rows = layers(items, forwardEdges(graph));
+  if (rows.length === 1 && items.length > 5) return grid(rows[0]);
+  return rows.map(row => row.sort((a, b) => {
+    const inPath = item => item.members.some(node => path.includes(node.id));
+    return Number(inPath(b)) - Number(inPath(a)) || stable(a, b);
+  }));
+}
+function entities(items, graph) {
+  // Put the most connected table first, then its neighbours; all fields determine actual cell dimensions.
+  const remaining = [...items].sort((a, b) => degree(b, graph.edges) - degree(a, graph.edges) || stable(a, b)), ordered = [];
+  while (remaining.length) {
+    const at = ordered.length ? remaining.findIndex(item => graph.edges.some(edge =>
+      item.ids.has(edge.source) && ordered.at(-1).ids.has(edge.target) || item.ids.has(edge.target) && ordered.at(-1).ids.has(edge.source))) : 0;
+    ordered.push(...remaining.splice(Math.max(0, at), 1));
+  }
+  return grid(ordered);
+}
+function deployment(items, graph) {
+  // Peers share a runtime tier; dependencies order peers without mixing data with applications.
+  const tiers = new Map();
+  for (const item of items) { const tier = Math.min(...item.members.map(deploymentTierOf)); tiers.set(tier, [...(tiers.get(tier) ?? []), item]); }
+  return [...tiers].sort(([a], [b]) => a - b).flatMap(([, peers]) => layers(peers, graph.edges));
+}
+function classes(items, graph) {
+  const hierarchy = graph.edges.filter(edge => ['inheritance', 'implementation'].includes(edge.kind)).map(edge => ({ source: edge.target, target: edge.source }));
+  const contracts = items.filter(item => hierarchy.some(edge => item.ids.has(edge.source) || item.ids.has(edge.target)));
+  const domain = items.filter(item => !contracts.includes(item));
+  // Keep each contract above its implementations, with associated domain classes beside that hierarchy.
+  const left = layers(contracts, hierarchy), right = layers(domain, graph.edges);
+  const contractBottom = Math.max(-1, ...left.map((row, i) => row.some(item => has(item, ['abstract', 'interface'])) ? i : -1));
+  const domainStart = contractBottom + 1;
+  return Array.from({ length: Math.max(left.length, domainStart + right.length) }, (_, i) => [...(left[i] ?? []), ...(right[i - domainStart] ?? [])]);
+}
+function lifecycle(items, graph) {
+  const initial = items.filter(item => has(item, ['initial'])), final = items.filter(item => has(item, ['final']));
+  const states = items.filter(item => !initial.includes(item) && !final.includes(item));
+  return [initial, ...layers(states, forwardEdges(graph)), final].filter(row => row.length);
+}
+function usecases(items, graph, variant = 0) {
+  const actors = items.filter(item => has(item, ['actor'])), subjects = items.filter(item => !actors.includes(item));
+  // At system scope, actors occupy a separate column outside the real boundary. Inside, use cases form a compact matrix.
+  return actors.length ? [actors.sort(stable), subjects.sort(stable)].filter(row => row.length) : variant >= 2 ? subjects.sort(stable).map(item => [item]) : entities(subjects, graph);
+}
+function dataflow(items, graph) {
+  const stores = items.filter(item => has(item, ['dataStore']));
+  const work = items.filter(item => !stores.includes(item));
+  // A store mediates data between writers and readers, but is not an extra processing stage.
+  const mediated = stores.flatMap(store => graph.edges.filter(edge => store.ids.has(edge.target)).flatMap(write => graph.edges.filter(edge => store.ids.has(edge.source) && edge.target !== write.source).map(read => ({ source: write.source, target: read.target }))));
+  const stages = layers(work, [...graph.edges, ...mediated]);
+  const stageOf = new Map(stages.flatMap((row, i) => row.flatMap(item => [...item.ids].map(id => [id, i]))));
+  for (const store of stores.sort(stable)) {
+    const adjacent = graph.edges.filter(edge => store.ids.has(edge.source) || store.ids.has(edge.target)).map(edge => stageOf.get(store.ids.has(edge.source) ? edge.target : edge.source)).filter(i => i !== undefined).sort((a, b) => a - b);
+    const at = adjacent.length ? adjacent[Math.floor(adjacent.length / 2)] : Math.max(0, stages.length - 1);
+    (stages[at] ??= []).push(store);
+  }
+  return stages;
+}
+
+export const LAYOUT_TEMPLATES = Object.freeze({
+  capabilities: { structure: 'capability-bands', existing: 'overview' },
+  engineering: { structure: 'engineering-layers', existing: 'overview' },
+  relations: { structure: 'component-clusters', arrange: components },
+  flowchart: { structure: 'workflow-spine', arrange: workflow },
+  sequence: { structure: 'lifelines', existing: 'sequence' },
+  er: { structure: 'entity-matrix', arrange: entities },
+  deployment: { structure: 'runtime-tiers', arrange: deployment },
+  class: { structure: 'contract-hierarchy', arrange: classes },
+  state: { structure: 'lifecycle-branches', arrange: lifecycle },
+  usecase: { structure: 'actor-system', arrange: usecases },
+  dataflow: { structure: 'process-store', arrange: dataflow }
+});
+export const templateOf = graph => LAYOUT_TEMPLATES[viewTypeOf(graph)];
+
+// A measured template supplies positions only. Routing and acceptance are the same as for ELK and browser edits.
+// No virtual groups, rank hints, inferred relationships or shortened text are persisted into the semantic model.
+export function templateDraft(input, variant = 0) {
+  const template = templateOf(input);
+  if (!template?.arrange || (viewTypeOf(input) !== 'deployment' && input.layout?.direction && !input.layout?.version && !input.layout?.strategy?.startsWith('template-'))) return null;
+  const linear = input.edges.length === input.nodes.length - 1 && input.nodes.every(node => input.edges.filter(edge => edge.source === node.id).length <= 1 && input.edges.filter(edge => edge.target === node.id).length <= 1);
+  if (linear && !['flowchart', 'class', 'state', 'deployment', 'dataflow', 'usecase'].includes(viewTypeOf(input))) return null;
+  const graph = structuredClone(input), type = diagramTypeOf(graph), diagram = getDiagram(type), limits = layoutLimits(diagram), target = layoutTargets(diagram);
+  graph.nodes.forEach(node => { node.size = minimumNodeSize(node, type, graph.meta.locale); });
+  graph.edges.forEach(edge => { delete edge.route; });
+  const allGroups = graph.groups ?? [];
+  function compose(parentId) {
+    const children = allGroups.filter(group => group.parentId === parentId).sort(stable).map(group => {
+      const body = compose(group.id), heading = groupHeadingLayout({ ...group, size: undefined });
+      const top = heading.height + limits.groupHeadingGap, pad = limits.groupInset;
+      group.size = { width: Math.max(heading.width + 2 * pad, body.width + 2 * pad), height: top + body.height + pad };
+      return { ...group, members: body.members, ids: new Set(body.members.map(node => node.id)), children: body.items, inset: { x: pad, y: top }, original: group };
+    });
+    const nodes = graph.nodes.filter(node => node.groupId === parentId).sort(stable).map(node => ({ ...node, members: [node], ids: new Set([node.id]), original: node }));
+    const items = [...children, ...nodes].sort(stable);
+    const ranked = items.length > 0 && items.every(item => item.members.length && item.members.every(node => node.layout?.rank !== undefined && node.layout.rank === item.members[0].layout.rank));
+    let rows = template.arrange(items, graph, variant);
+    if (ranked) {
+      const ranks = new Map();
+      for (const item of items) { const rank = item.members[0].layout.rank; ranks.set(rank, [...(ranks.get(rank) ?? []), item]); }
+      rows = [...ranks].sort(([a], [b]) => a - b).map(([, row]) => row.sort(stable));
+    }
+    if (variant >= 2) {
+      // Barycentric sweeps align siblings with their neighbours without changing bands or authored order.
+      const owner = new Map(items.flatMap(item => [...item.ids].map(id => [id, item])));
+      for (let sweep = 0; sweep < 4; sweep++) {
+        const positions = new Map(rows.flatMap(row => row.map((item, i) => [item.id, (i + .5) / row.length])));
+        for (const row of (sweep % 2 ? [...rows].reverse() : rows)) {
+          if (row.some(item => item.layout?.order !== undefined)) continue;
+          const score = item => {
+            const peers = graph.edges.flatMap(edge => {
+              const a = owner.get(edge.source), b = owner.get(edge.target);
+              return a === item && b && !row.includes(b) ? [b] : b === item && a && !row.includes(a) ? [a] : [];
+            });
+            return peers.length ? peers.reduce((sum, peer) => sum + positions.get(peer.id), 0) / peers.length : positions.get(item.id);
+          };
+          row.sort((a, b) => score(a) - score(b) || stable(a, b));
+        }
+      }
+    }
+    const sideways = type === 'architecture' && (input.layout?.direction ?? layeredDirections(type)[0]) === 'right' || type === 'dataflow' || type === 'usecase' && items.some(item => has(item, ['actor'])) || ranked && (input.layout?.direction ?? layeredDirections(type)[0]) === 'right';
+    const along = sideways ? 'x' : 'y', across = sideways ? 'y' : 'x', height = sideways ? 'width' : 'height', width = sideways ? 'height' : 'width';
+    // Shared column tracks and row baselines are measured once for the whole ownership scope.
+    const columnWidths = Array.from({ length: Math.max(0, ...rows.map(row => row.length)) }, (_, column) => Math.max(0, ...rows.map(row => row[column]?.size[width] ?? 0)));
+    const lateral = graph.edges.filter(edge => rows.some(row => row.some(item => item.ids.has(edge.source)) && row.some(item => item.ids.has(edge.target)) && !row.some(item => item.ids.has(edge.source) && item.ids.has(edge.target))));
+    const widestLabel = Math.max(0, ...lateral.map(edge => estimateLabelSize(visibleEdgeLabel(edge, type, graph.meta.locale))[width]));
+    const gap = Math.max(target.nodeGap, Math.min(widestLabel + 2 * limits.labelGap, 240)) + variant * 24;
+    const tracks = columnWidths.map((_, column) => columnWidths.slice(0, column).reduce((sum, size) => sum + size + gap, 0));
+    const extent = columnWidths.reduce((sum, size) => sum + size, 0) + Math.max(0, columnWidths.length - 1) * gap;
+    let cursor = 0;
+    for (const row of rows) {
+      const ids = new Set(row.flatMap(item => [...item.ids]));
+      const labels = graph.edges.filter(edge => ids.has(edge.source) || ids.has(edge.target)).map(edge => estimateLabelSize(visibleEdgeLabel(edge, type, graph.meta.locale)));
+      const multiplicities = type === 'class' && graph.edges.some(edge => (ids.has(edge.source) || ids.has(edge.target)) && (edge.sourceMultiplicity !== undefined || edge.targetMultiplicity !== undefined));
+      const corridor = Math.max(type === 'flowchart' ? 64 : target.layerGap, multiplicities ? 176 : type === 'usecase' && sideways ? Math.max(160, graph.edges.length * 24) : 0, ...labels.map(label => label[height] + 2 * limits.labelGap)) + variant * 24;
+      const rowHeight = Math.max(0, ...row.map(item => item.size[height]));
+      const centred = ['flowchart', 'state', 'usecase', 'dataflow'].includes(type);
+      row.forEach((item, column) => {
+        item.position = {
+          [along]: cursor + (centred ? (rowHeight - item.size[height]) / 2 : 0),
+          [across]: (type === 'architecture' ? row.slice(0,column).reduce((sum,peer)=>sum+peer.size[width]+gap,0) : tracks[column]) + (centred ? (columnWidths[column] - item.size[width]) / 2 : 0)
+        };
+      });
+      if (row.length === 1 && ['flowchart', 'class', 'state'].includes(type)) row[0].position[across] = (extent - row[0].size[width]) / 2;
+      cursor += rowHeight + corridor;
+    }
+    if (type === 'flowchart' && graph.layout?.primaryPath?.length) {
+      const path = new Set(graph.layout.primaryPath), primary = items.filter(item => item.members.some(node => path.has(node.id)));
+      const spineWidth = Math.max(0, ...primary.map(item => item.size.width));
+      for (const row of rows) {
+        let branchX = spineWidth + target.nodeGap;
+        for (const item of row) {
+          if (primary.includes(item)) item.position.x = (spineWidth - item.size.width) / 2;
+          else { item.position.x = branchX; branchX += item.size.width + target.nodeGap; }
+        }
+      }
+    }
+    const size = { width: Math.max(0, ...items.map(item => item.position.x + item.size.width)), height: Math.max(0, ...items.map(item => item.position.y + item.size.height)) };
+    return { ...size, items, members: items.flatMap(item => item.members) };
+  }
+  function place(items, origin) {
+    for (const item of items) {
+      const position = { x: origin.x + item.position.x, y: origin.y + item.position.y };
+      item.original.position = position;
+      if (item.children) place(item.children, { x: position.x + item.inset.x, y: position.y + item.inset.y });
+    }
+  }
+  const body = compose(undefined);
+  // External return corridors may extend above/left of the first node. The export bounds crop this origin.
+  const margin = Math.max(64, ...graph.edges.map(edge => estimateLabelSize(visibleEdgeLabel(edge, type, graph.meta.locale)).width + 64));
+  place(body.items, { x: margin, y: margin });
+  if (type === 'architecture' && variant >= 2) {
+    const axis = graph.layout?.direction === 'right' ? 'y' : 'x', cross = axis === 'x' ? 'y' : 'x';
+    const extent = axis === 'x' ? 'width' : 'height';
+    const rows = new Map();
+    for (const node of [...graph.nodes].sort(stable)) { const key = `${node.groupId}:${node.position[cross]}:${node.size[extent]}`; rows.set(key,[...(rows.get(key)??[]),node]); }
+    for (let sweep=0;sweep<2;sweep++) {
+      const positions=new Map(graph.nodes.map(node=>[node.id,node.position[axis]+node.size[extent]/2]));
+      for (const [,row] of [...rows].sort(([a],[b])=>a.localeCompare(b))) {
+      if(row.length<2 || row.some(node=>node.layout?.order!==undefined))continue;
+      const slots=row.map(node=>node.position[axis]).sort((a,b)=>a-b);
+      const score=node=>{ const peers=graph.edges.filter(e=>e.source===node.id||e.target===node.id).map(e=>graph.nodes.find(n=>n.id===(e.source===node.id?e.target:e.source))).filter(n=>n.groupId!==node.groupId);
+        return peers.length?peers.reduce((sum,n)=>sum+positions.get(n.id),0)/peers.length:positions.get(node.id); };
+      const scores=new Map(row.map(node=>[node.id,score(node)])); row.sort((a,b)=>scores.get(a.id)-scores.get(b.id)||stable(a,b));
+      row.forEach((node,i)=>{node.position[axis]=slots[i];});
+      }
+    }
+  }
+  if (type === 'usecase') {
+    const actors = graph.nodes.filter(node => node.kind === 'actor');
+    for (const actor of actors) {
+      const cases = graph.edges.filter(edge => edge.source === actor.id || edge.target === actor.id).map(edge => graph.nodes.find(node => node.id === (edge.source === actor.id ? edge.target : edge.source))).filter(node => node.kind === 'usecase');
+      if (cases.length) actor.position.y = cases.reduce((sum, node) => sum + node.position.y + node.size.height / 2, 0) / cases.length - actor.size.height / 2;
+    }
+    actors.sort((a, b) => a.position.y - b.position.y || stable(a, b));
+    for (let i = 1; i < actors.length; i++) actors[i].position.y = Math.max(actors[i].position.y, actors[i - 1].position.y + actors[i - 1].size.height + target.nodeGap);
+  }
+  graph.layout = { ...graph.layout, direction: type === 'usecase' ? 'right' : type === 'architecture' ? input.layout?.direction ?? layeredDirections(type)[0] : layeredDirections(type)[0] };
+  // Seed decision alternatives on opposite outlines; the orthogonal router preserves these semantic exits.
+  for (const node of graph.nodes.filter(node => ['decision', 'choice'].includes(node.kind))) {
+    const targetX = edge => { const target = graph.nodes.find(item => item.id === edge.target); return target.position.x + target.size.width / 2; };
+    const branches = graph.edges.filter(edge => edge.source === node.id && edge.target !== node.id).sort((a, b) => targetX(a) - targetX(b) || stable(a, b));
+    branches.forEach((edge, index) => {
+      const x = node.position.x + (index % 2 ? node.size.width + 12 : -12), y = node.position.y + node.size.height / 2;
+      edge.route = { via: [{ x, y }] };
+    });
+  }
+  return graph;
+}
+
+// Editing may move a node locally, but must not invert the relative bands/columns of a generated template.
+export function preservesTemplateOrder(before, after) {
+  if (diagramTypeOf(before) !== 'sequence') for (const a of before.nodes) for (const b of before.nodes) {
+    if (a.id >= b.id || a.groupId !== b.groupId) continue;
+    const na = after.nodes.find(node => node.id === a.id), nb = after.nodes.find(node => node.id === b.id);
+    for (const [axis, dimension] of [['x', 'width'], ['y', 'height']]) for (const fraction of [0, .5]) {
+      const delta = (left, right) => left.position[axis] + fraction * left.size[dimension] - right.position[axis] - fraction * right.size[dimension];
+      if (Math.abs(delta(a, b)) < .001 && Math.abs(delta(na, nb)) > .001) return false;
+    }
+  }
+  if (!before.layout?.strategy?.startsWith('template-')) return true;
+  const type = viewTypeOf(before), next = new Map(after.nodes.map(node => [node.id, node]));
+  const axis = ['usecase', 'dataflow'].includes(type) ? 'x' : 'y', extent = axis === 'x' ? 'width' : 'height';
+  for (const a of before.nodes) for (const b of before.nodes) {
+    if (type === 'deployment' && a.id !== b.id && a.groupId === b.groupId && a.position.y === b.position.y && next.get(a.id).position.y !== next.get(b.id).position.y) return false;
+    if (a.id === b.id || a.groupId !== b.groupId && !(type === 'usecase' && (a.kind === 'actor' || b.kind === 'actor'))) continue;
+    if (a.position[axis] + a.size[extent] <= b.position[axis] && next.get(a.id).position[axis] + next.get(a.id).size[extent] > next.get(b.id).position[axis]) return false;
+  }
+  return true;
+}

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

@@ -10,7 +10,7 @@ export function renderNode(node, type, offsetX = 0, offsetY = 0, palette, locale
   const content = definition.render({ ...node, appearance }, x, y, fill, stroke, palette, locale);
   // A soft ring behind the frame marks the business center or an explicit failure without touching the text.
   const halo = ring && !['actor', 'initial', 'final'].includes(node.kind) ? paint(definition.outline(node, x, y), { class: 'role-ring', fill: 'none', stroke: ring, 'stroke-width': 5 }) : '';
-  const description = [node.label, node.subtitle,
+  const description = [node.label, node.subtitle, ...(node.overviewText ?? []), ...(node.badges ?? []).map(badge => badge.label),
     ...(node.fields ?? []).map(field => `${field.key ? field.key + ' ' : ''}${field.name}: ${field.type}${field.nullable === undefined ? '' : ` (nullable: ${field.nullable})`}`),
     ...(node.attributes ?? []), ...(node.methods ?? [])].filter(Boolean).join('\n');
   return `<g data-diagram-node-id="${escapeXml(node.id)}" class="node-drawing${coreNode(node) && !definition.compartments ? ' core-node' : ''}"><title>${escapeXml(description)}</title>${halo}${content}</g>`;