qgraphflow 0.0.6 → 0.0.7

package/skills/q-flow/assets/viewer/src/architecture-overview.js

@@ -0,0 +1,340 @@
+import { affectedRouteIds } from './route-clearance.js';
+import { LAYOUT_VERSION } from './layout-policy.js';
+import { presentationGraph, mergePresentationEdges } from './presentation-graph.js';
+import { routeOrthogonal } from './orthogonal-routing.js';
+import { layoutText } from './text-layout.js';
+import { isArchitectureOverview } from './view-identity.js';
+import { OVERVIEW, OVERVIEW_TONES, overviewPalette } from './architecture-overview-theme.js';
+
+export const overviewSections = graph => {
+  const walk = (sections, depth = 0) => (Array.isArray(sections) && depth <= 16 ? sections : []).filter(section => section && typeof section === 'object').flatMap(section => [section, ...walk((Array.isArray(section.items) ? section.items : []).filter(item => item?.mode), depth + 1)]);
+  return walk(graph.layout?.sections);
+};
+const object = value => value && typeof value === 'object' && !Array.isArray(value);
+const strings = value => Array.isArray(value) && value.every(item => typeof item === 'string' && item.trim());
+export const hasOverviewContent = node => node.overviewText !== undefined || node.badges !== undefined || node.overviewTone !== undefined;
+
+export function validateOverview(graph, { inputOnly = true, validateAnchor, evidenceKinds } = {}) {
+  const errors = [], overview = isArchitectureOverview(graph);
+  const tone = (value, path) => { if (value !== undefined && !OVERVIEW_TONES.includes(value)) errors.push(`${path} is unsupported`); };
+  const anchor = (source, path) => {
+    if (!object(source)) errors.push(`${path} must be an object`);
+    else { validateAnchor?.(source, path, errors); if (source.kind !== undefined && !evidenceKinds?.has(source.kind)) errors.push(`${path}.kind is unsupported`); }
+  };
+  for (const node of graph.nodes ?? []) {
+    tone(node.overviewTone, `node ${node.id}.overviewTone`);
+    if (node.overviewAccent !== undefined && typeof node.overviewAccent !== 'boolean') errors.push(`node ${node.id}.overviewAccent must be boolean`);
+    if (node.overviewText !== undefined && !strings(node.overviewText)) errors.push(`node ${node.id}.overviewText must contain non-empty strings`);
+    if (node.badges !== undefined) {
+      if (!Array.isArray(node.badges)) errors.push(`node ${node.id}.badges must be an array`);
+      else for (const [i, badge] of node.badges.entries()) {
+        const path = `node ${node.id}.badges[${i}]`;
+        if (!object(badge) || typeof badge.label !== 'string' || !badge.label.trim() || !['status', 'version', 'requirement'].includes(badge.role) || !evidenceKinds?.has(badge.evidence)) errors.push(`${path} needs label, role (status/version/requirement) and evidence`);
+        if (badge?.source !== undefined) anchor(badge.source, `${path}.source`);
+      }
+    }
+  }
+  if (!overview) {
+    if (graph.layout?.sections !== undefined) errors.push('layout.sections requires an architecture overview');
+    return errors;
+  }
+  if (!Array.isArray(graph.layout?.sections) || !graph.layout.sections.length) return [...errors, 'architecture overview requires non-empty layout.sections'];
+  const nodeMap = new Map(graph.nodes.map(node => [node.id, node]));
+  const groups = new Map((graph.groups ?? []).map(group => [group.id, group]));
+  const seen = new Set(), sectionIds = new Set(), referencedGroups = new Set();
+  const addNode = id => { if (!nodeMap.has(id)) errors.push(`section nodeId does not name a node: ${id}`); else if (seen.has(id)) errors.push(`section repeats node ${id}`); else seen.add(id); };
+  const addGroup = (id, ancestry = new Set()) => {
+    if (!groups.has(id)) { errors.push(`section groupId does not name a group: ${id}`); return; }
+    if (ancestry.has(id) || referencedGroups.has(id)) { errors.push(`section repeats or cycles group ${id}`); return; }
+    referencedGroups.add(id); const path = new Set([...ancestry, id]);
+    graph.nodes.filter(node => node.groupId === id).forEach(node => addNode(node.id));
+    [...groups.values()].filter(group => group.parentId === id).forEach(group => addGroup(group.id, path));
+  };
+  const visit = (section, depth = 0) => {
+    if (!object(section) || depth > 16) { errors.push('invalid section or nesting exceeds 16 levels'); return; }
+    if (typeof section.id !== 'string' || !section.id.trim() || sectionIds.has(section.id) || nodeMap.has(section.id) || groups.has(section.id)) errors.push(`section.id must be unique: ${section.id}`);
+    sectionIds.add(section.id);
+    if (!['stack', 'grid', 'row', 'note'].includes(section.mode)) errors.push(`section ${section.id}.mode is unsupported`);
+    if (typeof section.title !== 'string' || !section.title.trim()) errors.push(`section ${section.id}.title is required`);
+    tone(section.tone, `section ${section.id}.tone`);
+    if (section.frame !== undefined && !['solid', 'dashed', 'none'].includes(section.frame)) errors.push(`section ${section.id}.frame is unsupported`);
+    if (section.columns !== undefined && (!Number.isInteger(section.columns) || section.columns < 1 || section.columns > 16 || section.mode !== 'grid')) errors.push(`section ${section.id}.columns requires a grid and an integer from 1 to 16`);
+    if (section.weights !== undefined && (section.mode !== 'row' || !Array.isArray(section.weights) || section.weights.length !== section.items?.length || section.weights.some(weight => !Number.isFinite(weight) || weight <= 0))) errors.push(`section ${section.id}.weights requires a row and one positive finite weight per item`);
+    if (section.text !== undefined && !strings(section.text)) errors.push(`section ${section.id}.text must contain non-empty strings`);
+    if (section.source !== undefined) anchor(section.source, `section ${section.id}.source`);
+    if (section.detailOf !== undefined && !nodeMap.has(section.detailOf)) errors.push(`section ${section.id}.detailOf does not name a node`);
+    if (!inputOnly && (!object(section.position) || !object(section.size) || !Number.isFinite(section.position.x) || !Number.isFinite(section.position.y) || section.position.x < 0 || section.position.y < 0 || !Number.isFinite(section.size.width) || !Number.isFinite(section.size.height) || section.size.width <= 0 || section.size.height <= 0)) errors.push(`section ${section.id} requires finite geometry`);
+    if (section.mode === 'note') {
+      if (!strings(section.text) || !section.text.length || (section.items?.length ?? 0)) errors.push(`note ${section.id} requires text and no items`);
+    } else if (!Array.isArray(section.items) || !section.items.length) errors.push(`section ${section.id}.items must be non-empty`);
+    for (const item of Array.isArray(section.items) ? section.items : []) {
+      if (!object(item)) { errors.push(`section ${section.id} item must be an object`); continue; }
+      const refs = ['nodeId', 'groupId', 'mode'].filter(key => Object.hasOwn(item, key));
+      if (refs.length !== 1) errors.push(`section ${section.id} item needs exactly one nodeId, groupId or nested section`);
+      else if (item.nodeId !== undefined) addNode(item.nodeId);
+      else if (item.groupId !== undefined) addGroup(item.groupId);
+      else visit(item, depth + 1);
+    }
+  };
+  graph.layout.sections.forEach(section => visit(section));
+  for (const id of nodeMap.keys()) if (!seen.has(id)) errors.push(`overview node ${id} is missing from sections`);
+  return errors;
+}
+
+export function overviewCardLayout(node, width = node.size.width) {
+  const p = node.overviewTone === 'plain' ? 0 : OVERVIEW.cardPadding, inner = width - p * 2, badges = [];
+  const badgeWidth = node.badges?.length ? Math.min(inner * .45, Math.max(...node.badges.map(badge => layoutText(badge.label, inner * .45 - 16, OVERVIEW.badge, OVERVIEW.badgeLine).width + 16))) : 0;
+  let badgeY = p;
+  for (const badge of node.badges ?? []) {
+    const label = layoutText(badge.label, badgeWidth - 16, OVERVIEW.badge, OVERVIEW.badgeLine), w = Math.max(48, label.width + 16), h = label.height + 6;
+    badges.push({ ...badge, x: width - p - w, y: badgeY, width: w, height: h, lines: label.lines }); badgeY += h + 6;
+  }
+  const title = layoutText(node.label, inner - (badgeWidth ? badgeWidth + 10 : 0), OVERVIEW.title, OVERVIEW.titleLine);
+  const lines = title.lines.map((text, i) => ({ text, x: p, y: p + OVERVIEW.title + i * OVERVIEW.titleLine, role: 'title' }));
+  const inlineSubtitle = node.subtitle && title.lines.length === 1 && layoutText(node.subtitle, Infinity, OVERVIEW.body, OVERVIEW.bodyLine).width + title.width + 12 <= inner - (badgeWidth ? badgeWidth + 10 : 0);
+  if (inlineSubtitle) lines.push({ text: node.subtitle, x: p + title.width + 12, y: p + OVERVIEW.title, role: 'body' });
+  let cursor = Math.max(p + title.height, badges.length ? badgeY - 6 : 0);
+  const paragraphs = width > 1000 ? [(node.overviewText ?? []).join(' ')] : node.overviewText ?? [];
+  for (const paragraph of [inlineSubtitle ? '' : node.subtitle, ...paragraphs].filter(Boolean)) {
+    cursor += 6; const content = layoutText(paragraph, inner, OVERVIEW.body, OVERVIEW.bodyLine);
+    lines.push(...content.lines.map((text, i) => ({ text, x: p, y: cursor + OVERVIEW.body + i * OVERVIEW.bodyLine, role: 'body' }))); cursor += content.height;
+  }
+  return { lines, badges, minHeight: cursor + p };
+}
+
+const sectionPadding = section => section.frame === 'none' ? 0 : OVERVIEW.padding;
+const sectionContentHeight = (section, width) => {
+  const inner = width - sectionPadding(section) * 2;
+  return sectionPadding(section) + layoutText(section.title, inner, OVERVIEW.sectionTitle, OVERVIEW.sectionLine).height + (section.text ?? []).reduce((sum, paragraph) => sum + 8 + layoutText(paragraph, inner, OVERVIEW.body, OVERVIEW.bodyLine).height, 0);
+};
+
+// A title occupies its measured lines, not an invisible wall across the whole band.
+// Routing and geometry checks share these boxes with the section's SVG typography.
+export function sectionTextBoxes(section) {
+  if (section.mode === 'note') return [{ ...section.position, ...section.size }];
+  const p = sectionPadding(section), x = section.position.x + p, width = section.size.width - p * 2;
+  const title = layoutText(section.title, width, OVERVIEW.sectionTitle, OVERVIEW.sectionLine);
+  const boxes = title.lines.map((line, i) => ({ x, y: section.position.y + p + i * OVERVIEW.sectionLine,
+    width: layoutText(line, Infinity, OVERVIEW.sectionTitle, OVERVIEW.sectionLine).width, height: OVERVIEW.sectionLine }));
+  let cursor = section.position.y + p + title.height;
+  for (const paragraph of section.text ?? []) {
+    cursor += 8;
+    const body = layoutText(paragraph, width, OVERVIEW.body, OVERVIEW.bodyLine);
+    boxes.push(...body.lines.map((line, i) => ({ x, y: cursor + i * OVERVIEW.bodyLine,
+      width: layoutText(line, Infinity, OVERVIEW.body, OVERVIEW.bodyLine).width, height: OVERVIEW.bodyLine })));
+    cursor += body.height;
+  }
+  return boxes;
+}
+
+// The same synchronous layout runs in Node and in the offline Viewer. Sections are presentation, never ownership.
+export function layoutArchitectureOverview(input, { width = OVERVIEW.width, gap = OVERVIEW.cardGap, gaps = {}, bandGaps = {} } = {}) {
+  const graph = structuredClone(input), nodes = new Map(graph.nodes.map(node => [node.id, node]));
+  const groups = new Map((graph.groups ?? []).map(group => [group.id, group]));
+  const nodeHeight = (node, w) => overviewCardLayout(node, w).minHeight;
+  const groupSection = id => { const group = groups.get(id); return { id, title: group.label, mode: 'grid', group: true, items: [...(graph.groups ?? []).filter(child => child.parentId === id).map(child => ({ groupId: child.id })), ...graph.nodes.filter(node => node.groupId === id).map(node => ({ nodeId: node.id }))] }; };
+  const idsOf = item => item.nodeId ? [item.nodeId] : (item.groupId ? groupSection(item.groupId) : item).items?.flatMap(idsOf) ?? [];
+  const measure = (item, w) => {
+    if (item.nodeId) return { item, width: w, height: nodeHeight(nodes.get(item.nodeId), w) };
+    const section = item.groupId ? groupSection(item.groupId) : item, p = sectionPadding(section), localGap = gaps[section.id] ?? gap;
+    const top = sectionContentHeight(section, w) + (section.mode === 'note' ? 0 : 24);
+    if (section.mode === 'note') return { item: section, width: w, height: top + p };
+    const columns = section.mode === 'row' ? section.items.length : section.mode === 'grid' ? Math.min(section.items.length, section.columns ?? Math.max(1, Math.floor((w - p * 2 + localGap) / (300 + localGap)))) : 1;
+    const rows = [];
+    for (let i = 0; i < section.items.length; i += columns) {
+      const items = section.items.slice(i, i + columns), weights = section.mode === 'row' && section.weights || items.map(() => 1), total = weights.reduce((sum, weight) => sum + weight, 0);
+      const available = w - p * 2 - localGap * (items.length - 1);
+      const row = items.map((child, j) => measure(child, available * weights[j] / total)), height = Math.max(...row.map(child => child.height));
+      // Inventory rows align both edges; parallel regions share a full-height support boundary.
+      for (const child of row) if (section.mode === 'grid' && child.item.nodeId || section.mode === 'row') child.height = height;
+      rows.push(row);
+    }
+    // Labeled dependencies need a small explicit connector lane. Unconnected inventory grids retain reference spacing.
+    const owned = new Set(idsOf(section)), connected = graph.edges.some(edge => owned.has(edge.source) && owned.has(edge.target));
+    const rowGap = connected ? Math.max(localGap, OVERVIEW.connectedGap) : localGap;
+    return { item: section, width: w, height: top + rows.reduce((sum, row) => sum + Math.max(...row.map(child => child.height)), 0) + rowGap * Math.max(0, rows.length - 1) + p, top, rows, rowGap, gap: localGap, padding: p };
+  };
+  const place = (plan, x, y) => {
+    if (plan.item.nodeId) { const node = nodes.get(plan.item.nodeId); node.position = { x, y }; node.size = { width: plan.width, height: plan.height }; return; }
+    const section = plan.item; section.position = { x, y }; section.size = { width: plan.width, height: plan.height };
+    if (section.group) Object.assign(groups.get(section.id), { position: section.position, size: section.size });
+    let rowY = y + plan.top;
+    for (const row of plan.rows ?? []) { let columnX = x + plan.padding; for (const child of row) { place(child, columnX, rowY); columnX += child.width + plan.gap; } rowY += Math.max(...row.map(child => child.height)) + plan.rowGap; }
+  };
+  const minimumWidth = item => {
+    if (item.nodeId) return 300;
+    const section = item.groupId ? groupSection(item.groupId) : item, p = sectionPadding(section), localGap = gaps[section.id] ?? gap;
+    if (section.mode === 'note') return 300 + p * 2;
+    const sizes = section.items.map(minimumWidth);
+    if (section.mode === 'row') {
+      const weights = section.weights ?? sizes.map(() => 1);
+      return p * 2 + Math.max(...sizes.map((size, i) => size / weights[i])) * weights.reduce((sum, weight) => sum + weight, 0) + gap * (sizes.length - 1);
+    }
+    if (section.columns) return p * 2 + Math.min(section.columns, section.items.length) * 176 + gap * (Math.min(section.columns, section.items.length) - 1);
+    return p * 2 + Math.max(...sizes);
+  };
+  width = Math.max(width, ...graph.layout.sections.map(minimumWidth));
+  let y = OVERVIEW.margin;
+  for (const section of graph.layout.sections) { const plan = measure(section, width); place(plan, OVERVIEW.margin, y); y += plan.height + Math.max(bandGaps[section.id] ?? gap, OVERVIEW.bandGap); }
+  const bounds = group => {
+    const children = [...graph.nodes.filter(node => node.groupId === group.id), ...(graph.groups ?? []).filter(child => child.parentId === group.id).map(child => { bounds(child); return child; })];
+    if (!children.length) throw new Error(`Empty ownership group ${group.id}`);
+    const x = Math.min(...children.map(child => child.position.x)) - OVERVIEW.padding, y = Math.min(...children.map(child => child.position.y)) - layoutText(group.label, width, 20, 26).height - OVERVIEW.padding;
+    const right = Math.max(...children.map(child => child.position.x + child.size.width)) + OVERVIEW.padding, bottom = Math.max(...children.map(child => child.position.y + child.size.height)) + OVERVIEW.padding;
+    group.position = { x: Math.max(0, x), y: Math.max(0, y) }; group.size = { width: right - group.position.x, height: bottom - group.position.y };
+  };
+  for (const group of graph.groups ?? []) if (!group.parentId && !overviewSections(graph).some(section => section.items?.some(item => item.groupId === group.id))) bounds(group);
+  graph.layout.version = LAYOUT_VERSION; graph.layout.direction = 'down'; graph.layout.strategy = 'architecture-overview-v2';
+  for (const edge of graph.edges) delete edge.route;
+  return routeOverview(graph);
+}
+
+// Local maintenance keeps every existing slot and the legacy version. Oversized edits fail the same
+// quality gate as drags, so the Viewer can retain the last valid canvas and the user's text draft.
+export function maintainArchitectureOverview(input, reference, accept) {
+  const graph = structuredClone(input);
+  for (const node of graph.nodes) {
+    const old = reference.nodes.find(item => item.id === node.id);
+    if (JSON.stringify(node) !== JSON.stringify(old)) node.size.height = Math.max(node.size.height, overviewCardLayout(node).minHeight);
+  }
+  const installSlots = (oldIds, newIds) => {
+    if (oldIds.join('\0') === newIds.join('\0')) return;
+    const slots = oldIds.map(id => reference.nodes.find(node => node.id === id));
+    newIds.forEach((id,i) => { const node = graph.nodes.find(node => node.id === id); node.position = { ...slots[i].position }; });
+  };
+  for (const section of overviewSections(graph)) {
+    const old = overviewSections(reference).find(item => item.id === section.id);
+    if (old) installSlots((old.items ?? []).filter(item => item.nodeId).map(item => item.nodeId), (section.items ?? []).filter(item => item.nodeId).map(item => item.nodeId));
+  }
+  for (const group of graph.groups ?? []) installSlots(reference.nodes.filter(n=>n.groupId===group.id).map(n=>n.id),graph.nodes.filter(n=>n.groupId===group.id).map(n=>n.id));
+  const edgeIds = affectedRouteIds(reference, graph);
+  const routed = routeOrthogonal(presentationGraph(graph), { edgeIds, passes: 2, accept });
+  graph.edges = mergePresentationEdges(graph, routed.graph);
+  accept(graph, { strictEdgeIds: edgeIds });
+  return graph;
+}
+
+export const overviewLayoutReports = new WeakMap();
+export function fitArchitectureOverview(input, accept) {
+  const gaps = {}, bandGaps = {}, attempts = [];
+  let last;
+  for (let evaluation = 0; evaluation < 60; evaluation++) {
+    try {
+      const graph = layoutArchitectureOverview(input, { gaps, bandGaps });
+      accept(graph);
+      overviewLayoutReports.set(graph, { evaluations: evaluation + 1, budget: 60, gaps: { ...gaps }, bandGaps: { ...bandGaps }, attempts, termination: 'valid-local-spacing', provenImpossible: false });
+      return graph;
+    } catch (error) {
+      last = error;
+      const ids = new Set([...(error.elementIds ?? []), ...(error.diagnostics ?? []).flatMap(d => d.elementIds)]);
+      for (const edge of input.edges) if (ids.has(edge.id)) { ids.add(edge.source); ids.add(edge.target); }
+      const all = overviewSections(input);
+      const descendants = section => (section.items ?? []).flatMap(item => item.nodeId ? [item.nodeId] : item.groupId ? input.nodes.filter(n => n.groupId === item.groupId).map(n => n.id) : descendants(item));
+      const affected = all.filter(section => descendants(section).some(id => ids.has(id)));
+      const leaves = affected.filter(section => !affected.some(child => child !== section && (section.items ?? []).includes(child)));
+      if (!leaves.length) throw error;
+      let changed = false;
+      for (const section of leaves) {
+        const before = gaps[section.id] ?? OVERVIEW.cardGap;
+        if (before >= 200) continue;
+        gaps[section.id] = before + 16; changed = true;
+      }
+      // Only the corridor following a source band grows; unrelated card grids keep their gap.
+      for (const section of input.layout.sections) if (descendants(section).some(id => ids.has(id))) {
+        const before = bandGaps[section.id] ?? OVERVIEW.bandGap;
+        if (before < 200) { bandGaps[section.id] = before + 16; changed = true; }
+      }
+      attempts.push({ elementIds: [...ids], reason: error.routingReason ?? 'quality', gaps: { ...gaps }, bandGaps: { ...bandGaps } });
+      if (!changed) break;
+    }
+  }
+  throw Object.assign(last, { routingReport: { attempts, termination: 'local-spacing-budget', provenImpossible: false } });
+}
+
+export function reorderOverview(graph, id, position) {
+  const next = structuredClone(graph), target = next.nodes.find(node => node.id === id);
+  if (!target) return next;
+  const list = overviewSections(next).find(section => section.items?.some(item => item.nodeId === id));
+  if (list) {
+    const peers = list.items.filter(item => item.nodeId).map(item => next.nodes.find(node => node.id === item.nodeId));
+    const nearest = peers.sort((a, b) => Math.hypot(a.position.x - position.x, a.position.y - position.y) - Math.hypot(b.position.x - position.x, b.position.y - position.y))[0];
+    if (nearest && nearest.id !== id) { const from = list.items.findIndex(item => item.nodeId === id), to = list.items.findIndex(item => item.nodeId === nearest.id); list.items.splice(to, 0, list.items.splice(from, 1)[0]); }
+  } else if (target.groupId) {
+    const peers = next.nodes.filter(node => node.groupId === target.groupId), nearest = peers.sort((a, b) => Math.hypot(a.position.x - position.x, a.position.y - position.y) - Math.hypot(b.position.x - position.x, b.position.y - position.y))[0];
+    if (nearest && nearest.id !== id) { const from = next.nodes.findIndex(node => node.id === id), to = next.nodes.findIndex(node => node.id === nearest.id); next.nodes.splice(to, 0, next.nodes.splice(from, 1)[0]); }
+  }
+  return next;
+}
+
+const escape = value => String(value ?? '').replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+const svgText = (x, y, value, role, style = '') => `<text x="${x}" y="${y}" class="${role}"${style ? ` style="${style}"` : ''}>${escape(value)}</text>`;
+export function overviewCardSvg(node, x, y, palette) {
+  const colors = overviewPalette(palette), tone = colors[node.overviewTone ?? 'subtle'] ?? colors.subtle, layout = overviewCardLayout(node);
+  const plain = node.overviewTone === 'plain';
+  const gradientId = `overview-card-${[...node.id].map(c => c.codePointAt(0).toString(16)).join('-')}`;
+  const gradient = !plain && tone.band && node.size.width > 1000 ? `<defs><linearGradient id="${gradientId}"><stop stop-color="${tone.band[0]}"/><stop offset="1" stop-color="${tone.band[1]}"/></linearGradient></defs>` : '';
+  const frame = `<rect class="node-surface" x="${x}" y="${y}" width="${node.size.width}" height="${node.size.height}" rx="${OVERVIEW.cardRadius}" fill="${plain ? 'none' : gradient ? `url(#${gradientId})` : tone.fill}" stroke="${plain ? 'none' : tone.stroke}" stroke-width="1.5"/>`;
+  const accent = node.overviewAccent && tone.accent ? `<path d="M${x + 5} ${y + 10}V${y + node.size.height - 10}" stroke="${tone.accent}" stroke-width="5" stroke-linecap="round"/>` : '';
+  const text = layout.lines.map(line => svgText(x + line.x, y + line.y, line.text, line.role, `fill:${line.role === 'title' ? colors.ink : colors.body};font-size:${line.role === 'title' ? OVERVIEW.title : OVERVIEW.body}px;font-weight:${line.role === 'title' ? 700 : 400}`)).join('');
+  return gradient + frame + accent + text + layout.badges.map(badge => {
+    const done = /^(已实现|已完成|完成|implemented|ready|done|complete)$/i.test(badge.label), badgeTone = badge.role === 'version' ? { fill: tone.accent ?? colors.blue.accent, ink: colors.paper } : badge.role === 'status' && done || badge.role === 'requirement' && /^(必选|required|mandatory)$/i.test(badge.label) ? colors.success : colors.badge;
+    return `<g data-badge-role="${badge.role}"><rect x="${x + badge.x}" y="${y + badge.y}" width="${badge.width}" height="${badge.height}" rx="8" fill="${badgeTone.fill}"/>${badge.lines.map((line, i) => svgText(x + badge.x + 8, y + badge.y + 3 + OVERVIEW.badge + i * OVERVIEW.badgeLine, line, 'meta', `fill:${badgeTone.ink};font-size:${OVERVIEW.badge}px;font-weight:600`)).join('')}</g>`;
+  }).join('');
+}
+export function sectionSvg(section, palette, offsetX = 0, offsetY = 0) {
+  const colors = overviewPalette(palette), tone = colors[section.tone ?? 'white'] ?? colors.white;
+  const x = section.position.x + offsetX, y = section.position.y + offsetY, w = section.size.width, p = sectionPadding(section);
+  const heading = layoutText(section.title, w - p * 2, OVERVIEW.sectionTitle, OVERVIEW.sectionLine); let cursor = y + p + heading.height;
+  let body = '';
+  for (const paragraph of section.text ?? []) { cursor += 8; const lines = layoutText(paragraph, w - p * 2, OVERVIEW.body, OVERVIEW.bodyLine); body += lines.lines.map((line, i) => svgText(x + p, cursor + OVERVIEW.body + i * OVERVIEW.bodyLine, line, 'body', `fill:${colors.body};font-size:${OVERVIEW.body}px`)).join(''); cursor += lines.height; }
+  const gradientId = `overview-band-${[...section.id].map(c => c.codePointAt(0).toString(16)).join('-')}`;
+  const gradient = tone.band && section.frame !== 'none' ? `<defs><linearGradient id="${gradientId}"><stop stop-color="${tone.band[0]}"/><stop offset="1" stop-color="${tone.band[1]}"/></linearGradient></defs>` : '';
+  const frame = section.frame === 'none' ? '' : `<rect x="${x}" y="${y}" width="${w}" height="${section.size.height}" rx="${OVERVIEW.sectionRadius}" fill="${gradient ? `url(#${gradientId})` : tone.fill}" stroke="${tone.stroke}" stroke-width="1.5"${section.frame === 'dashed' ? ' stroke-dasharray="5 4"' : ''}/>`;
+  return `<g data-overview-section-id="${escape(section.id)}">${gradient}${frame}${heading.lines.map((line, i) => svgText(x + p, y + p + OVERVIEW.sectionTitle + i * OVERVIEW.sectionLine, line, 'title', `fill:${colors.ink};font-size:${OVERVIEW.sectionTitle}px;font-weight:700`)).join('')}${body}</g>`;
+}
+
+export function overviewGeometryErrors(graph, routes = new Map()) {
+  if (!isArchitectureOverview(graph)) return [];
+  const errors = [], sections = overviewSections(graph);
+  for (const section of sections) {
+    const required = sectionContentHeight(section, section.size.width) + sectionPadding(section);
+    if (section.size.height < required) errors.push(`section ${section.id} text is clipped`);
+    for (const item of Array.isArray(section.items) ? section.items : []) {
+      const child = item.nodeId ? graph.nodes.find(node => node.id === item.nodeId) : item.groupId ? graph.groups.find(group => group.id === item.groupId) : item;
+      if (child && (child.position.x < section.position.x + sectionPadding(section) || child.position.y < section.position.y + sectionContentHeight(section, section.size.width) + 24 || child.position.x + child.size.width > section.position.x + section.size.width - sectionPadding(section) + .01 || child.position.y + child.size.height > section.position.y + section.size.height - sectionPadding(section) + .01)) errors.push(`section ${section.id} does not contain ${child.id}`);
+    }
+  }
+  const itemBox = item => ({ ...item.position, ...item.size });
+  const overlaps = (a, b) => a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
+  const siblings = items => {
+    const resolved = items.map(item => item.nodeId ? graph.nodes.find(node => node.id === item.nodeId) : item.groupId ? (graph.groups ?? []).find(group => group.id === item.groupId) : item).filter(Boolean);
+    for (let i = 0; i < resolved.length; i++) for (const other of resolved.slice(i + 1)) if (overlaps(itemBox(resolved[i]), itemBox(other))) errors.push(`overview siblings ${resolved[i].id} and ${other.id} overlap`);
+  };
+  siblings(graph.layout.sections);
+  for (const section of sections) if (section.items) siblings(section.items);
+  const crosses = (a, b, rect) => {
+    let low = 0, high = 1;
+    for (const [axis, dimension] of [['x', 'width'], ['y', 'height']]) {
+      const delta = b[axis] - a[axis];
+      if (!delta) { if (a[axis] <= rect[axis] || a[axis] >= rect[axis] + rect[dimension]) return false; continue; }
+      const t1 = (rect[axis] - a[axis]) / delta, t2 = (rect[axis] + rect[dimension] - a[axis]) / delta;
+      low = Math.max(low, Math.min(t1, t2)); high = Math.min(high, Math.max(t1, t2));
+      if (low >= high) return false;
+    }
+    return high > 0 && low < 1;
+  };
+  for (const section of sections) {
+    for (const obstacle of sectionTextBoxes(section)) for (const [id, route] of routes) {
+      if (route.points.slice(1).some((point, i) => crosses(route.points[i], point, obstacle))) errors.push(`overview route ${id} crosses section ${section.id} text`);
+      if (route.label && overlaps(route.labelBox, obstacle)) errors.push(`overview label ${id} overlaps section ${section.id} text`);
+    }
+  }
+  return errors;
+}
+
+// Kept as a compatible entry point for older callers. All types use the shared router.
+export function routeOverview(graph) {
+  const result = routeOrthogonal(presentationGraph(graph), { passes: 3 });
+  graph.edges = mergePresentationEdges(graph, result.graph);
+  return graph;
+}

package/skills/q-flow/assets/viewer/src/diagrams/architecture.js

@@ -1,3 +1,4 @@
+import { hasOverviewContent, overviewCardSvg } from '../architecture-overview.js';
 import { genericCard } from './card.js';
 import { cylinder, polygonAnchor, rectAnchor, roundedRectAnchor, rectangle, HEXAGON, polygon } from './drawing.js';
 
@@ -6,14 +7,15 @@ const SLANT = [[.08, 0], [1, 0], [.92, 1], [0, 1]];
 
 export function architectureOutline(node, x, y) {
   const { width: w, height: h } = node.size;
+  if (hasOverviewContent(node)) return rectangle(node, x, y, 16);
   if (node.kind === 'external') return polygon(node, x, y, HEXAGON);
   if (node.kind === 'security') return rectangle(node, x, y, 22);
   if (node.kind === 'failure') return polygon(node, x, y, OCTAGON);
   if (node.kind === 'config') return polygon(node, x, y, SLANT);
   if (node.kind === 'business') return rectangle(node, x, y, Math.min(28, h / 2));
   const base = rectangle(node, x, y, ['service', 'component'].includes(node.kind) ? 16 : 10);
-  // Notation stays in the card margins: text starts at x + 15, the chip row at y + 13, and the last text baseline sits
-  // 21px above the bottom.
+  // Notation stays in the card margins: the icon plate starts 14px in, text 48px in, and the content block is centred
+  // vertically with 14px above and below.
   if (node.kind === 'data') return [...base, ['path', { d: `M${x + 10} ${y}V${y + h}M${x + w - 10} ${y}V${y + h}`, fill: 'none' }]];
   if (node.kind === 'database') return cylinder(node, x, y);
   if (node.kind === 'framework') return [...base, ['path', { d: `M${x + 16} ${y + 6}H${x + w - 16}M${x + 16} ${y + h - 6}H${x + w - 16}`, fill: 'none', 'stroke-dasharray': '7 5' }]];
@@ -21,6 +23,7 @@ export function architectureOutline(node, x, y) {
 }
 
 const anchor = (node, side, offset) => {
+  if (hasOverviewContent(node)) return roundedRectAnchor(node, side, offset, 16);
   if (node.kind === 'external') return polygonAnchor(node, side, offset, HEXAGON);
   if (node.kind === 'security') return roundedRectAnchor(node, side, offset, 22);
   if (node.kind === 'failure') return polygonAnchor(node, side, offset, OCTAGON);
@@ -30,14 +33,14 @@ const anchor = (node, side, offset) => {
   return rectAnchor(node, side, offset);
 };
 
-const contentInset = node => ['external', 'config', 'failure'].includes(node.kind) ? Math.min(28, node.size.width * .08) : 0;
+const contentInset = node => ['external', 'config', 'failure'].includes(node.kind) ? Math.min(28, node.size.width * .08) : node.kind === 'database' ? 12 : 0;
 
 export default {
   dashedKinds: ['framework', 'optional'],
   id: 'architecture', label: 'Architecture',
   nodeKinds: ["external", "config", "framework", "security", "service", "business", "data", "failure", "system", "component", "database"],
   groupKinds: ["runtime", "security", "ownership", "external"],
-  edgeKinds: ["request", "call", "data", "success", "failure", "framework", "optional", "depends"],
-  render: (node, ...args) => genericCard(node, ...args, architectureOutline, contentInset(node)), outline: architectureOutline, anchor,
+  edgeKinds: ["request", "call", "data", "success", "failure", "framework", "optional", "depends", "aggregates", "inherits", "provides"],
+  render: (node, x, y, fill, stroke, palette, locale) => hasOverviewContent(node) ? overviewCardSvg(node, x, y, palette, fill, stroke) : genericCard(node, x, y, fill, stroke, palette, locale, architectureOutline, contentInset(node)), outline: architectureOutline, anchor,
   cardLayout: true, contentInset,
 };

package/skills/q-flow/assets/viewer/src/diagrams/card.js

@@ -1,21 +1,39 @@
-import { translate } from '../i18n.js';
-import { cardTextLayout, text, coreNode, dataKinds, kindLabels, paint } from './drawing.js';
+import { CARD, cardTag } from '../text-layout.js';
+import { cardTextLayout, text, coreNode, dataKinds, paint } from './drawing.js';
 
-export function genericCard(node, x, y, fill, stroke, palette, locale, outline, contentInset = 0) {
-  const { title, subtitle } = cardTextLayout({ ...node, size: { ...node.size, width: node.size.width - contentInset * 2 } });
+export function genericCard(node, x, y, fill, stroke, palette, locale, outline, contentInset = 0, corner = 0) {
+  if (node.classicCard) return classicCard(node, x, y, fill, stroke, palette, locale, outline, contentInset);
+  const { title, subtitle, source, tag, contentHeight } = cardTextLayout({ ...node, size: { ...node.size, width: node.size.width - contentInset * 2 } }, locale, false, corner);
+  // Baselines sit 20/17/14px below the top of their 26/24/20px lines.
+  const left = x + contentInset, row = y + Math.max(0, (node.size.height - contentHeight) / 2) + CARD.pad, column = left + CARD.textX;
+  const subtitleTop = row + title.height + (subtitle.height ? 4 : 0), sourceTop = subtitleTop + subtitle.height + (source.height ? 6 : 0);
+  const titleText = title.lines.map((line, index) => text(column, row + 20 + index * title.lineHeight, line, 'title')).join('');
+  const subtitleText = subtitle.lines.map((line, index) => text(column, subtitleTop + 17 + index * subtitle.lineHeight, line, 'body')).join('');
+  const sourceText = source.lines.map((line, index) => text(column, sourceTop + 14 + index * source.lineHeight, line, 'meta')).join('');
+  const plate = { x: left + CARD.pad, y: row + (CARD.titleLine - CARD.plate) / 2 }, tagX = x + node.size.width - contentInset - CARD.pad - tag.width - corner;
+  return `<g filter="url(#node-shadow)">${frame(node, x, y, fill, stroke, outline)}${iconPlate(node, plate.x, plate.y, CARD.plate, palette)}<rect x="${tagX}" y="${row + 3}" width="${tag.width}" height="20" rx="6" fill="${palette.badge}"/>${text(tagX + tag.width / 2, row + 18, tag.text, 'stereotype', ' text-anchor="middle"')}${titleText}${subtitleText}${sourceText}</g>`;
+}
+
+const frame = (node, x, y, fill, stroke, outline) => paint(outline(node, x, y), { fill, stroke, 'stroke-width': node.appearance?.moduleColor || node.appearance?.ring ? 1.5 : 1 });
+
+// The icon plate is the identity chip: solid module color with a white glyph. Without a module it stays a quiet plate
+// whose glyph takes the role tone. Titles never change color.
+function iconPlate(node, x, y, size, palette) {
+  const chip = node.appearance?.chip;
+  const tone = chip ? '#ffffff' : coreNode(node) ? palette.accent : dataKinds.has(node.kind) ? palette.data : node.kind === 'failure' ? palette.warn : palette.ink2;
+  const inset = (size - 15) / 2;
+  return `<rect x="${x}" y="${y}" width="${size}" height="${size}" rx="7" fill="${chip ?? palette.badge}"/><svg x="${x + inset}" y="${y + inset}" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="${tone}" stroke-width="${chip ? 1.75 : 1.5}">${cardIcon(node)}</svg>`;
+}
+
+const cardIcon = node => dataKinds.has(node.kind) ? '<ellipse cx="12" cy="5" rx="8" ry="3"/><path d="M4 5v14c0 4 16 4 16 0V5M4 12c0 4 16 4 16 0"/>'
+  : ['external', 'actor'].includes(node.kind) ? '<rect x="6" y="2" width="12" height="20" rx="3"/><path d="M10 18h4"/>'
+  : ['security', 'config'].includes(node.kind) ? '<path d="m12 2 8 4v6c0 5-8 10-8 10S4 17 4 12V6Z"/><path d="m8 12 3 3 5-6"/>'
+  : '<rect x="4" y="4" width="16" height="16" rx="3"/><path d="M8 9h8M8 13h8M8 17h4"/>';
+
+// The card drawn before compact cards, kept for views whose stored geometry predates them (see compactCards).
+function classicCard(node, x, y, fill, stroke, palette, locale, outline, contentInset) {
+  const { title, subtitle } = cardTextLayout({ ...node, size: { ...node.size, width: node.size.width - contentInset * 2 } }, locale, true);
   const titleText = title.lines.map((line, index) => text(x + 15 + contentInset, y + 68 + index * title.lineHeight, line, 'title')).join('');
   const subtitleText = subtitle.lines.map((line, index) => text(x + 15 + contentInset, y + 68 + title.height + index * subtitle.lineHeight, line, 'body')).join('');
-  const core = coreNode(node);
-
-  // The icon plate is the identity chip: solid module color with a white glyph. Without a module it stays a quiet plate
-  // whose glyph takes the role tone. Titles never change color.
-  const chip = node.appearance?.chip, failure = node.kind === 'failure';
-  const tone = chip ? '#ffffff' : core ? palette.accent : dataKinds.has(node.kind) ? palette.data : failure ? palette.warn : palette.ink2;
-  const badge = chip ?? palette.badge;
-  const icon = dataKinds.has(node.kind) ? '<ellipse cx="12" cy="5" rx="8" ry="3"/><path d="M4 5v14c0 4 16 4 16 0V5M4 12c0 4 16 4 16 0"/>'
-    : ['external', 'actor'].includes(node.kind) ? '<rect x="6" y="2" width="12" height="20" rx="3"/><path d="M10 18h4"/>'
-    : ['security', 'config'].includes(node.kind) ? '<path d="m12 2 8 4v6c0 5-8 10-8 10S4 17 4 12V6Z"/><path d="m8 12 3 3 5-6"/>'
-    : '<rect x="4" y="4" width="16" height="16" rx="3"/><path d="M8 9h8M8 13h8M8 17h4"/>';
-  const frameWidth = node.appearance?.moduleColor || node.appearance?.ring ? 1.5 : 1;
-  return `<g filter="url(#node-shadow)">${paint(outline(node, x, y), { fill, stroke, 'stroke-width': frameWidth })}<rect x="${x + 15 + contentInset}" y="${y + 13}" width="25" height="25" rx="7" fill="${badge}"/><svg x="${x + 20 + contentInset}" y="${y + 18}" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="${tone}" stroke-width="${chip ? 1.75 : 1.5}">${icon}</svg>${text(x + 47 + contentInset, y + 29, translate(locale, kindLabels[node.kind] ?? node.kind), 'stereotype')}${titleText}${subtitleText}</g>`;
+  return `<g filter="url(#node-shadow)">${frame(node, x, y, fill, stroke, outline)}${iconPlate(node, x + 15 + contentInset, y + 13, 25, palette)}${text(x + 47 + contentInset, y + 29, cardTag(node, locale).text, 'stereotype')}${titleText}${subtitleText}</g>`;
 }

package/skills/q-flow/assets/viewer/src/diagrams/deployment.js

@@ -5,8 +5,8 @@ const CUBE = [[0, .1], [.06, 0], [1, 0], [1, .9], [.94, 1], [0, 1]];
 
 export function deploymentOutline(node, x, y) {
   const { width: w, height: h } = node.size;
-  // Notation stays clear of the card text: the stand sits under the last line, whose baseline is 21px above the bottom,
-  // and the container's stacked boxes take the top-right corner, opposite the chip.
+  // Notation stays clear of the card text: the stand sits under the 14px bottom padding, and the stacked boxes, the folded
+  // corner and the cube's side face keep the top-right corner, which cardCorner leaves free of the kind tag.
   if (node.kind === 'device') return [
     ['rect', { x: x + 16, y, width: w - 32, height: h, rx: 10 }],
     ['path', { d: `M${x + w / 2} ${y + h - 10}V${y + h - 5}M${x + w / 2 - 30} ${y + h - 5}H${x + w / 2 + 30}`, fill: 'none' }]
@@ -29,13 +29,15 @@ const anchor = (node, side, offset) => {
   return rectAnchor(node, side, offset);
 };
 
-const contentInset = node => node.kind === 'external' ? Math.min(28, node.size.width * .08) : node.kind === 'device' ? 12 : 0;
+// Right-hand room the kind tag leaves for the notation in the top-right corner.
+const cardCorner = node => ({ container: 24, artifact: 18, node: 20 })[node.kind] ?? 0;
+const contentInset = node => node.kind === 'external' ? Math.min(28, node.size.width * .08) : ['device', 'database'].includes(node.kind) ? 12 : 0;
 
 export default {
   id: 'deployment', label: 'Deployment',
   nodeKinds: ["device", "node", "container", "artifact", "service", "database", "external"],
   groupKinds: ["host", "network", "cluster", "namespace"],
   edgeKinds: ["deploy", "network", "depends"],
-  render: (node, ...args) => genericCard(node, ...args, deploymentOutline, contentInset(node)), outline: deploymentOutline, anchor,
-  cardLayout: true, contentInset,
+  render: (node, ...args) => genericCard(node, ...args, deploymentOutline, contentInset(node), cardCorner(node)), outline: deploymentOutline, anchor,
+  cardLayout: true, contentInset, cardCorner,
 };

package/skills/q-flow/assets/viewer/src/diagrams/drawing.js

@@ -8,7 +8,9 @@ export function groupHeadingSvg(group, x = 0, y = 0) {
 
 export function groupFrameSvg(group, appearance, x = 0, y = 0) {
   const radius = ['loop', 'par'].includes(group.kind) ? 5 : 14;
-  return `<rect class="boundary-frame" x="${x}" y="${y}" width="${group.size.width}" height="${group.size.height}" rx="${radius}" fill="${appearance.fill}" stroke="${appearance.stroke}" stroke-width="1"/>`;
+  // A security boundary is a trust line, drawn dashed like Archify's security groups and UML trust boundaries.
+  const dash = group.kind === 'security' ? ' stroke-dasharray="6 4"' : '';
+  return `<rect class="boundary-frame" x="${x}" y="${y}" width="${group.size.width}" height="${group.size.height}" rx="${radius}" fill="${appearance.fill}" stroke="${appearance.stroke}" stroke-width="1"${dash}/>`;
 }
 
 export function escapeXml(value = '') {
@@ -64,7 +66,8 @@ export function paint(outline, attributes = {}) {
   return outline.map(([tag, geometry]) => `<${tag}${Object.entries({ ...geometry, ...(Object.keys(attributes).length ? { class: 'node-surface' } : {}), ...attributes, ...(geometry.fill === undefined ? {} : { fill: geometry.fill }) }).map(([key, value]) => ` ${key}="${escapeXml(value)}"`).join('')}/>`).join('');
 }
 export const rectangle = (node, x, y, radius = 10, height = node.size.height) => [['rect', { x, y, width: node.size.width, height, rx: radius }]];
-// Flat caps keep the cylinder above the card's chip row (y + 13) and well below its last text baseline (h - 21); the
+// Flat caps (2–12px) stay above the card's 14px top padding and inside its 14px bottom padding; the walls stand 12px in,
+// so database cards inset their content by 12px. The
 // 2px top and bottom insets are where edges attach.
 export const cylinder = (node, x, y) => {
   const { width: w, height: h } = node.size, ry = 5, top = y + 2 + ry, bottom = y + h - 2 - ry;

package/skills/q-flow/assets/viewer/src/diagrams/registry.js

@@ -1,3 +1,4 @@
+import { hasOverviewContent, overviewCardLayout } from '../architecture-overview.js';
 import architecture from './architecture.js';
 import flowchart from './flowchart.js';
 import sequence from './sequence.js';
@@ -7,6 +8,7 @@ import classDiagram from './class.js';
 import state from './state.js';
 import usecase from './usecase.js';
 import dataflow from './dataflow.js';
+import { cardTextLayout } from '../text-layout.js';
 
 // Add a diagram module here; navigation, validation, drawing and exports use this same list.
 export const DIAGRAMS = [architecture, flowchart, sequence, er, deployment, classDiagram, state, usecase, dataflow];
@@ -19,6 +21,14 @@ export const getDiagram = (type = 'architecture') => byId.get(type);
 // Starting space budgets only; content bounds still determine the actual canvas and exports.
 export const canvasBudgetFor = type => getDiagram(type).sequence ? null
   : ['flowchart', 'state'].includes(type) ? { width: 1600, height: 2400 } : { width: 2400, height: 1600 };
+// Card text inside the inset margins of the node's outline.
+export const cardText = (node, type, locale, classic = false) => type === 'architecture' && hasOverviewContent(node) ? overviewCardLayout(node) : cardTextLayout({ ...node, size: { ...node.size, width: node.size.width - 2 * (getDiagram(type).contentInset?.(node) ?? 0) } }, locale, classic, getDiagram(type).cardCorner?.(node));
+// A view uses compact cards when every card fits them; geometry stored before compact cards keeps the classic cards until it
+// is laid out again, so preserved layouts stay valid and one view never mixes the two.
+export const compactCards = graph => {
+  const type = diagramTypeOf(graph);
+  return !getDiagram(type).cardLayout || graph.nodes.every(node => !node.size || node.size.height >= cardText(node, type, graph.meta?.locale).minHeight);
+};
 export const hasArrow = (edge, type) => !(getDiagram(type).undirected ?? []).includes(edge.kind);
 export const isDashed = (edge, type) => !(type === 'sequence' && edge.kind === 'sync') && (['framework', 'inference'].includes(edge.evidence) || (getDiagram(type).dashedKinds ?? []).includes(edge.kind));
 

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

@@ -1,21 +1,27 @@
+import { layoutText } from '../text-layout.js';
 import { translate } from '../i18n.js';
 import { text, fit, TYPOGRAPHY, kindLabels, rectangle, actor, paint, escapeXml } from './drawing.js';
 import { mix } from '../visual-style.js';
 
-const outline = (node, x, y) => node.kind === 'actor' ? actor(node, x, y) : rectangle(node, x, y, 7, TYPOGRAPHY.sequenceHeader);
-export const sequenceHeaderHeight = node => node.kind === 'actor' ? TYPOGRAPHY.sequenceActorHeader + (node.subtitle ? 22 : 0) : TYPOGRAPHY.sequenceHeader;
+const outline = (node, x, y) => node.kind === 'actor' ? actor(node, x, y) : rectangle(node, x, y, 7, sequenceHeaderHeight(node));
+export function sequenceHeaderHeight(node) {
+  const width = (node.size?.width ?? 280) - 28;
+  const titles = layoutText(node.label, width, 20, 26).lines.length;
+  const bodies = node.subtitle ? layoutText(node.subtitle, width, 16, 22).lines.length : 0;
+  return (node.kind === 'actor' ? TYPOGRAPHY.sequenceActorHeader + (node.subtitle ? 22 : 0) : TYPOGRAPHY.sequenceHeader) + Math.max(0, titles - 1) * 26 + Math.max(0, bodies - 1) * 22;
+}
 
 function sequenceNode(node, x, y, fill, stroke, palette, locale) {
   const cx = x + node.size.width / 2;
   const actorNode = node.kind === 'actor';
   const header = sequenceHeaderHeight(node);
   const head = paint(outline(node, x, y), { fill, stroke, 'stroke-width': 1.5 });
-  const label = actorNode
-    ? text(cx, y + 98, fit(node.label, node.size.width - 12), 'participant-title', ` text-anchor="middle" style="fill:${palette.ink}"`)
-    : text(cx, y + (node.subtitle ? 18 : 25), translate(locale, kindLabels[node.kind] ?? node.kind), 'stereotype', ' text-anchor="middle"') + text(cx, y + (node.subtitle ? 41 : 53), fit(node.label, node.size.width - 28), 'participant-title', ' text-anchor="middle"');
-  const subtitle = node.subtitle ? text(cx, y + (actorNode ? 120 : 63), fit(node.subtitle, node.size.width - 28), 'body', ' text-anchor="middle"') : '';
+  const titleLines = layoutText(node.label, node.size.width - 28, 20, 26).lines;
+  const titleY = y + (actorNode ? 98 : node.subtitle ? 44 : 53);
+  const label = (actorNode ? '' : text(cx, y + 20, translate(locale, kindLabels[node.kind] ?? node.kind), 'stereotype', ' text-anchor="middle"')) + titleLines.map((line, i) => text(cx, titleY + i * 26, line, 'participant-title', ' text-anchor="middle"')).join('');
+  const subtitle = node.subtitle ? layoutText(node.subtitle, node.size.width - 28, 16, 22).lines.map((line, i) => text(cx, titleY + (titleLines.length - 1) * 26 + (actorNode ? 28 : 22) + i * 22, line, 'body', ' text-anchor="middle"')).join('') : '';
   const executions = (node.executionRects ?? []).map(item => `<rect class="sequence-execution" data-execution-id="${escapeXml(item.id)}" x="${x + item.x}" y="${y + item.y}" width="${item.width}" height="${item.height}" fill="${mix(item.color, palette.surface, .14)}" stroke="${item.color}" stroke-width="1.5"/>`).join('');
-  return `<g><g class="sequence-head"><g class="${actorNode ? 'actor-figure' : 'participant-head'}">${head}</g>${label}${subtitle}</g><path class="lifeline" d="M ${cx} ${y + header}V ${y + node.size.height}" stroke="${palette.edge}" stroke-width="1" stroke-dasharray="4 6"/>${executions}</g>`;
+  return `<g><title>${escapeXml([node.label, node.subtitle].filter(Boolean).join(" · "))}</title><g class="sequence-head"><g class="${actorNode ? 'actor-figure' : 'participant-head'}">${head}</g>${label}${subtitle}</g><path class="lifeline" d="M ${cx} ${y + header}V ${y + node.size.height}" stroke="${palette.edge}" stroke-width="1" stroke-dasharray="4 6"/>${executions}</g>`;
 }
 
 export default {