qgraphflow 0.0.6

package/skills/q-flow/assets/viewer/src/i18n.js

@@ -0,0 +1,14 @@
+import messages from './i18n-messages.json' with { type: 'json' };
+
+// Interface strings are authored in English; every other language, including the default zh-CN, is a catalog.
+// Graphs without meta.locale keep rendering in Chinese, so existing pages do not change. Authored text and code
+// identifiers are never translated.
+export const DEFAULT_LOCALE = 'zh-CN';
+export const SUPPORTED_LOCALES = ['en', ...Object.keys(messages)];
+
+export function translate(locale, message, values = {}) {
+  const effective = locale ?? DEFAULT_LOCALE;
+  const catalog = Object.hasOwn(messages, effective) ? messages[effective] : undefined;
+  const template = catalog && Object.hasOwn(catalog, message) ? catalog[message] : message;
+  return template.replace(/\{(\w+)\}/g, (token, key) => Object.hasOwn(values, key) ? String(values[key]) : token);
+}

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

@@ -0,0 +1,55 @@
+import { getDiagram } from './diagrams/registry.js';
+import { sequenceHeaderHeight } from './diagrams/sequence.js';
+import { cardTextLayout, layoutText } from './text-layout.js';
+import { TYPOGRAPHY, kindLabels } from './visual-style.js';
+import { translate } from './i18n.js';
+import { STATE_ACTIONS, STATE_ACTION_INSET, stateActivities } from './diagrams/state.js';
+
+// System fonts vary: reserve width beyond the estimate, then verify actual glyphs in the browser.
+const singleLineWidth = (text, font) => Math.ceil(layoutText(String(text ?? '').replace(/\r?\n/g, ' '), Infinity, font).width * 1.15);
+const rounded = size => Object.fromEntries(Object.entries(size).map(([key, value]) => [key, Math.ceil(value)]));
+
+export function minimumNodeSize(node, type, locale = 'en') {
+  const diagram = getDiagram(type), title = singleLineWidth(node.label, TYPOGRAPHY.title), body = singleLineWidth(node.subtitle, TYPOGRAPHY.body);
+  if (type === 'state' && ['initial', 'final'].includes(node.kind)) {
+    if (!node.subtitle) return { width: 28, height: 28 };
+    const width = Math.max(title, body);
+    return rounded({ width: width + 50, height: Math.max(80, layoutText(node.label, width, TYPOGRAPHY.title, 29).height + 5 + layoutText(node.subtitle, width, TYPOGRAPHY.body, 23.2).height + 16) });
+  }
+  if (type === 'state' && STATE_ACTIONS.some(key => node.kind === 'state' && typeof node[key] === 'string' && node[key].trim())) {
+    // Title compartment (at least 72) above the action compartment, whose height follows the width it wraps at.
+    const width = Math.max(240, Math.min(480, Math.max(Math.max(title, body) + 60, ...STATE_ACTIONS.filter(key => node[key]).map(key => singleLineWidth(node[key], TYPOGRAPHY.small) + STATE_ACTION_INSET))));
+    const heading = layoutText(node.label, width - 24, TYPOGRAPHY.title, 29), subtitle = layoutText(node.subtitle, width - 24, TYPOGRAPHY.body, 23.2);
+    return rounded({ width, height: Math.max(72, heading.height + (subtitle.height ? 5 + subtitle.height : 0) + 16) + stateActivities({ ...node, size: { width, height: 0 } }).height });
+  }
+  if (diagram.sequence || node.kind === 'actor') return { width: Math.max(160, title + 28, body + 28), height: diagram.sequence ? sequenceHeaderHeight(node) + 48 : 104 + (node.subtitle ? 24 : 0) };
+  if (diagram.cardinalities) {
+    const fields = node.fields.map(field => {
+      const name = singleLineWidth(field.name, TYPOGRAPHY.body), type = singleLineWidth(field.type, TYPOGRAPHY.body);
+      return Math.max(name + type + 74, type / .55);
+    });
+    return rounded({ width: Math.max(240, title + 26, body + 60, ...fields), height: Math.max(TYPOGRAPHY.erHeader / .4, TYPOGRAPHY.erHeader + node.fields.length * TYPOGRAPHY.erRow) });
+  }
+  if (diagram.compartments) {
+    const attributes = node.attributes ?? [], methods = node.methods ?? [];
+    return rounded({ width: Math.max(240, title + 26, body + 26, ...[...attributes, ...methods].map(value => singleLineWidth(value, TYPOGRAPHY.body) + 26)),
+      height: TYPOGRAPHY.classHeader + (node.subtitle ? 24 : 0) + (attributes.length ? attributes.length * TYPOGRAPHY.classRow + 13 : 30) + (methods.length ? methods.length * TYPOGRAPHY.classRow + 13 : 30) });
+  }
+  const size = { width: Math.max(240, Math.min(480, Math.max(title, body) + 60)), height: 100 };
+  if (diagram.cardLayout) {
+    const inset = diagram.contentInset?.({ ...node, size }) ?? 0;
+    size.width = Math.max(size.width, singleLineWidth(translate(locale, kindLabels[node.kind] ?? node.kind), TYPOGRAPHY.small) + 70 + 2 * inset);
+    size.height = Math.max(100, cardTextLayout({ ...node, size: { ...size, width: size.width - 2 * (diagram.contentInset?.({ ...node, size }) ?? 0) } }).minHeight);
+    return rounded(size);
+  }
+  const textArea = diagram.textArea ?? (node => ({ width: node.size.width - 36, height: node.size.height - 20 }));
+  // All supported safety regions grow monotonically with height. Bounded expansion also handles diamond/ellipse insets.
+  for (let i = 0; i < 16; i++) {
+    const area = textArea({ ...node, size });
+    const titleText = layoutText(node.label, area.width, TYPOGRAPHY.title, 29), subtitle = layoutText(node.subtitle, area.width, TYPOGRAPHY.body, 23.2);
+    const required = titleText.height + (subtitle.height ? 5 + subtitle.height : 0);
+    if (area.height >= required) return rounded(size);
+    size.height += Math.ceil((required - area.height) * 2 + 2);
+  }
+  throw new Error(`Cannot measure full text for ${type} node ${node.id}`);
+}

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

@@ -0,0 +1,164 @@
+import { auditGraphLayout, boxDistance, occupiedBox, graphBounds, segmentCrossesBox } from './edge-routing.js';
+import { diagramTypeOf, getDiagram } from './diagrams/registry.js';
+import { cardTextLayout, layoutText, groupHeadingLayout } from './text-layout.js';
+import { LAYOUT_LIMITS } from './layout-spacing.js';
+import { minimumNodeSize } from './layout-measure.js';
+import { validateGraph } from './graph-validation.js';
+
+const bounds = item => ({ ...item.position, ...item.size });
+const contains = (a, b) => b.x >= a.x && b.y >= a.y && b.x + b.width <= a.x + a.width && b.y + b.height <= a.y + a.height;
+const overlap = (a, b) => a.x < b.x + b.width && b.x < a.x + a.width && a.y < b.y + b.height && b.y < a.y + a.height;
+const segments = route => route.points.slice(1).map((end, i) => [route.points[i], end]);
+
+export function qualityFailure(graph, phase, message, diagnostics = []) {
+  if (!diagnostics.length) diagnostics = (String(message).includes('\n- ') ? String(message).split('\n- ').slice(1) : [String(message)]).map(detail => {
+    const elements = ['nodes', 'edges', 'groups'].flatMap(key => (Array.isArray(graph?.[key]) ? graph[key] : []).filter((item, index) => item && typeof item === 'object' && (
+      detail.includes(`${key}[${index}]`) || new RegExp(`(^|[^\\w.-])${String(item.id).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}($|[^\\w.-])`).test(detail))));
+    return { ruleId: `${phase}.invalid`, severity: 'error', diagramType: diagramTypeOf(graph),
+      elementIds: elements.map(item => item.id), measured: detail, required: `Valid ${phase} content and complete notation`,
+      bounds: elements.filter(item => item.position && item.size).map(item => ({ ...item.position, ...item.size })),
+      remediation: phase === 'semantic' ? 'Correct the reported input field or reference before layout.' : 'Correct the identified content or geometry and retry without removing semantic facts.' };
+  });
+  return Object.assign(new Error(String(message)), { diagnostics, phases: {
+    semantic: { status: phase === 'semantic' ? 'failed' : 'passed' },
+    geometry: { status: phase === 'semantic' ? 'not-checked' : phase === 'geometry' ? 'failed' : 'passed' },
+    rendering: { status: phase === 'rendering' ? 'failed' : 'not-checked' }
+  } });
+}
+
+export function requireDiagramQuality(graph) {
+  const semantic = validateGraph(graph, { inputOnly: true });
+  const geometry = semantic.length ? [] : validateGraph(graph, { audit: false });
+  const audit = semantic.length || geometry.length ? null : auditLayoutQuality(graph);
+  const errors = [...semantic, ...geometry, ...(audit?.errors ?? [])];
+  const phases = { semantic: { status: semantic.length ? 'failed' : 'passed' }, geometry: { status: semantic.length ? 'not-checked' : errors.length ? 'failed' : 'passed' }, rendering: { status: 'not-checked' } };
+  if (errors.length) throw qualityFailure(graph, semantic.length ? 'semantic' : 'geometry', `Diagram quality failed:\n- ${errors.join('\n- ')}`, audit?.diagnostics ?? []);
+  return { ...phases, diagnostics: audit.diagnostics };
+}
+
+export function auditLayoutQuality(graph) {
+  const legacy = auditGraphLayout(graph), type = diagramTypeOf(graph), diagram = getDiagram(type), limits = LAYOUT_LIMITS;
+  const diagnostics = [...legacy.diagnostics, ...legacy.crossings];
+  const issue = (ruleId, ids, measured, required, boxes, remediation) => diagnostics.push({ ruleId, severity: 'error', diagramType: type, elementIds: ids, measured, required, bounds: boxes, remediation });
+  const nodeBoxes = new Map(graph.nodes.map(node => [node.id, occupiedBox(node, type)]));
+  const nodeById = new Map(graph.nodes.map(node => [node.id, node]));
+  if (!diagram.sequence) {
+    const ranked = graph.nodes.flatMap(first => graph.nodes.filter(second => first.layout?.rank !== undefined && second.layout?.rank !== undefined && first.layout.rank < second.layout.rank).map(second => [first, second]));
+    let primaryPath = graph.layout?.primaryPath ?? [];
+    if (type === 'flowchart' && !primaryPath.length && graph.edges.length === graph.nodes.length - 1) {
+      const next = new Map(graph.nodes.map(node => [node.id, graph.edges.filter(edge => edge.source === node.id)]));
+      const starts = graph.nodes.filter(node => !graph.edges.some(edge => edge.target === node.id));
+      if (starts.length === 1 && [...next.values()].every(edges => edges.length <= 1)) {
+        const path = [], seen = new Set();
+        for (let id = starts[0].id; id && !seen.has(id); id = next.get(id)[0]?.target) { path.push(id); seen.add(id); }
+        // Only a complete simple chain has an unambiguous main path; never guess among branches or cycles.
+        if (path.length === graph.nodes.length) primaryPath = path;
+      }
+    }
+    const primary = ['flowchart', 'state'].includes(type) ? primaryPath.slice(1).map((id, i) => [nodeById.get(primaryPath[i]), nodeById.get(id)]) : [];
+    const decisions = ['flowchart', 'state'].includes(type) ? graph.nodes.filter(node => ['decision', 'choice'].includes(node.kind)).map(node => {
+      const branches = graph.edges.filter(edge => edge.source === node.id && edge.target !== node.id);
+      return { node, branches, sides: new Set(branches.map(edge => legacy.routes.get(edge.id).sourceSide)) };
+    }).filter(item => item.branches.length >= 2) : [];
+    const vertical = !['er', 'deployment', 'dataflow', 'usecase'].includes(type);
+    const coordinate = vertical ? 'y' : 'x', dimension = vertical ? 'height' : 'width';
+    // A layout folded into top-down columns continues at the top of the next column: a successor that sits entirely to the
+    // right of its predecessor keeps the notation's reading direction; a path or hierarchy step must also start higher.
+    const continues = (earlier, later, higher) => later.position.x - earlier.position.x - earlier.size.width + .001 >= limits.nodeGap && (!higher || later.position.y < earlier.position.y);
+    for (const [first, second] of ranked) {
+      const distance = second.position[coordinate] - first.position[coordinate] - first.size[dimension];
+      if (distance + .001 < limits.nodeGap) issue('semantic.rank', [first.id, second.id], distance, limits.nodeGap, [nodeBoxes.get(first.id), nodeBoxes.get(second.id)], 'Keep declared ranks in separate layers along the reading direction.');
+    }
+    if (vertical && graph.nodes.length > 5 && Math.max(...graph.nodes.map(node => node.position.y)) < Math.min(...graph.nodes.map(node => node.position.y + node.size.height))) issue('semantic.single-row', graph.nodes.map(node => node.id), 1, 'multiple rows', [...nodeBoxes.values()], 'Arrange responsibility layers or wrap peer nodes; tiny y offsets do not create another row.');
+    if (type === 'class') for (const edge of graph.edges.filter(edge => ['inheritance', 'implementation'].includes(edge.kind))) {
+      const child = nodeById.get(edge.source), parent = nodeById.get(edge.target), distance = child.position.y - parent.position.y - parent.size.height;
+      if (distance + .001 < limits.nodeGap && !continues(parent, child, true)) issue('semantic.class-hierarchy', [edge.id, parent.id, child.id], distance, limits.nodeGap, [nodeBoxes.get(parent.id), nodeBoxes.get(child.id)], 'Place the parent class or interface above its child or implementation, or continue the hierarchy at the top of the next column.');
+    }
+    if (type === 'state') for (const symbol of graph.nodes.filter(node => ['initial', 'final'].includes(node.kind))) {
+      for (const state of graph.nodes.filter(node => !['initial', 'final'].includes(node.kind))) {
+        const distance = symbol.kind === 'initial' ? state.position.y - symbol.position.y - symbol.size.height : symbol.position.y - state.position.y - state.size.height;
+        const continued = symbol.kind === 'initial' ? continues(symbol, state, false) : continues(state, symbol, false);
+        if (distance + .001 < limits.nodeGap && !continued) issue('semantic.state-endpoint', [symbol.id, state.id], distance, limits.nodeGap, [nodeBoxes.get(symbol.id), nodeBoxes.get(state.id)], 'Keep initial symbols above the lifecycle and final symbols below it; a column fold continues the lifecycle at the top of the next column.');
+      }
+    }
+    for (const [source, target] of primary) {
+      const distance = target.position[coordinate] - source.position[coordinate] - source.size[dimension];
+      if (distance + .001 < limits.nodeGap && !continues(source, target, true)) issue('semantic.primary-path', [source.id, target.id], distance, limits.nodeGap, [nodeBoxes.get(source.id), nodeBoxes.get(target.id)], 'Keep the declared or unambiguous main path directed downwards; a column fold continues it at the top of the next column.');
+    }
+    for (const { node, branches, sides } of decisions) {
+      if (!['left', 'right'].every(side => sides.has(side))) issue('semantic.branch-sides', [node.id, ...branches.map(edge => edge.id)], [...sides], ['left', 'right'], [nodeBoxes.get(node.id)], 'Give alternatives separate left and right corridors while retaining their real targets and merges.');
+    }
+  }
+  for (let i = 0; i < graph.nodes.length; i++) {
+    const node = graph.nodes[i], rect = nodeBoxes.get(node.id), minimum = minimumNodeSize(node, type, graph.meta.locale);
+    if (diagram.cardLayout) {
+      const inset = diagram.contentInset?.(node) ?? 0, required = Math.max(100, cardTextLayout({ ...node, size: { ...node.size, width: node.size.width - inset * 2 } }).minHeight);
+      if (node.size.height < required) issue('text.node-height', [node.id], node.size.height, required, [rect], 'Increase height to keep full title and subtitle at 20/16px.');
+    } else if (diagram.textArea && node.kind !== 'actor' && !['initial', 'final'].includes(node.kind)) {
+      const area = diagram.textArea(node), title = layoutText(node.label, area.width, 20, 29), body = layoutText(node.subtitle, area.width, 16, 23.2), required = title.height + (body.height ? body.height + 5 : 0);
+      if (area.width <= 0 || area.height < required) issue('text.shape-safe-area', [node.id], area, { width: 1, height: required }, [rect], 'Enlarge the shape safety region to contain all text.');
+    } else if (node.size.width < minimum.width || node.size.height < minimum.height) issue('text.node-size', [node.id], node.size, minimum, [rect], 'Increase dimensions for complete headers, members and fields.');
+    for (const other of graph.nodes.slice(i + 1)) {
+      const otherBox = nodeBoxes.get(other.id), distance = boxDistance(rect, otherBox);
+      if (distance + .001 < limits.nodeGap) issue('spacing.nodes', [node.id, other.id], distance, limits.nodeGap, [rect, otherBox], 'Separate the visible node outlines.');
+    }
+  }
+  const labels = graph.edges.flatMap(edge => {
+    const route = legacy.routes.get(edge.id);
+    return [...(route.label ? [{ id: edge.id, box: route.labelBox }] : []), ...(route.endpointLabels ?? []).map(label => ({ id: edge.id, role: label.role, box: label.labelBox }))];
+  });
+  for (let i = 0; i < labels.length; i++) {
+    const label = labels[i];
+    for (const [id, rect] of nodeBoxes) {
+      const distance = boxDistance(label.box, rect);
+      if (distance + .001 < limits.labelGap) issue('spacing.label-node', [label.id, id], distance, limits.labelGap, [label.box, rect], 'Move the label away from the node.');
+    }
+    for (const other of labels.slice(i + 1)) {
+      const distance = boxDistance(label.box, other.box);
+      if (distance + .001 < limits.labelGap) issue('spacing.labels', [label.id, other.id], distance, limits.labelGap, [label.box, other.box], 'Separate complete label bounds.');
+    }
+    const margin = limits.labelEdgeGap;
+    for (const edge of graph.edges) if (edge.id !== label.id) {
+      const expanded = { x: label.box.x - margin, y: label.box.y - margin, width: label.box.width + 2 * margin, height: label.box.height + 2 * margin };
+      if (segments(legacy.routes.get(edge.id)).some(([a, b]) => segmentCrossesBox(a, b, expanded))) issue('spacing.label-edge', [label.id, edge.id], '<6', margin, [label.box], 'Reserve a clear label area away from other relations.');
+    }
+  }
+  for (let i = 0; i < graph.edges.length; i++) {
+    const edge = graph.edges[i], route = legacy.routes.get(edge.id), parts = segments(route);
+    if (!diagram.sequence) for (const [point, neighbor, hint] of [[route.points[0], route.points[1], edge.route?.via?.[0]], [route.points.at(-1), route.points.at(-2), edge.route?.via?.at(-1)]]) {
+      const distance = Math.hypot(point.x - neighbor.x, point.y - neighbor.y), required = diagram.endpointStub ?? limits.endpoint;
+      const length = hint && distance ? Math.min(distance, ((hint.x - point.x) * (neighbor.x - point.x) + (hint.y - point.y) * (neighbor.y - point.y)) / distance) : distance;
+      if (length + .001 < required) issue('route.endpoint-stub', [edge.id], length, required, [{ ...point, width: 0, height: 0 }], 'Reserve a straight outward segment for the endpoint symbol.');
+    }
+    for (const other of graph.edges.slice(i + 1)) {
+      const otherRoute = legacy.routes.get(other.id), found = [];
+      for (const [a, b] of parts) for (const [c, d] of segments(otherRoute)) {
+        const horizontal = a.y === b.y;
+        if (horizontal !== (c.y === d.y)) continue;
+        const axis = horizontal ? 'x' : 'y', across = horizontal ? 'y' : 'x';
+        const shared = Math.min(Math.max(a[axis], b[axis]), Math.max(c[axis], d[axis])) - Math.max(Math.min(a[axis], b[axis]), Math.min(c[axis], d[axis]));
+        const separation = Math.abs(a[across] - c[across]);
+        if (shared <= .001 || separation + .001 >= limits.parallelGap) continue;
+        const terminals = (e, r) => [{ id: e.source, point: r.points[0] }, { id: e.target, point: r.points.at(-1) }];
+        const initialShared = separation < .001 && shared <= limits.endpoint && terminals(edge, route).some(left => terminals(other, otherRoute).some(right => left.id === right.id && left.point.x === right.point.x && left.point.y === right.point.y && (left.point === a || left.point === b) && (right.point === c || right.point === d)));
+        if (!initialShared) found.push({ x: Math.min(a.x, b.x, c.x, d.x), y: Math.min(a.y, b.y, c.y, d.y), width: Math.max(a.x, b.x, c.x, d.x) - Math.min(a.x, b.x, c.x, d.x), height: Math.max(a.y, b.y, c.y, d.y) - Math.min(a.y, b.y, c.y, d.y), separation, shared });
+      }
+      if (found.length) issue('route.parallel-channels', [edge.id, other.id], Math.min(...found.map(item => item.separation)), limits.parallelGap, found, `Separate parallel channels; only the initial ${limits.endpoint}px at one common port may overlap.`);
+    }
+  }
+  if (!diagram.sequence) {
+    const groups = graph.groups ?? [], byId = new Map(groups.map(group => [group.id, group]));
+    const belongs = (node, group) => { let id = node.groupId; const seen = new Set(); while (id && !seen.has(id)) { if (id === group.id) return true; seen.add(id); id = byId.get(id)?.parentId; } return false; };
+    for (let i = 0; i < groups.length; i++) {
+      const group = groups[i], rect = bounds(group), inset = limits.groupInset, top = groupHeadingLayout(group).height + limits.groupHeadingGap;
+      const inner = { x: rect.x + inset, y: rect.y + top, width: rect.width - 2 * inset, height: rect.height - top - inset };
+      const members = [...graph.nodes.filter(node => node.groupId === group.id), ...groups.filter(child => child.parentId === group.id)];
+      for (const member of members) if (!contains(inner, bounds(member))) issue('group.member-inset', [group.id, member.id], bounds(member), inner, [rect, bounds(member)], 'Expand the owning boundary to preserve heading and side clearance.');
+      for (const node of graph.nodes) if (!belongs(node, group) && overlap(rect, nodeBoxes.get(node.id))) issue('group.unowned-node', [group.id, node.id], node.groupId ?? null, 'outside', [rect, nodeBoxes.get(node.id)], 'Keep nodes outside boundaries they do not belong to.');
+      for (const other of groups.slice(i + 1)) if (group.parentId === other.parentId && boxDistance(rect, bounds(other)) + .001 < limits.groupGap) issue('group.sibling-gap', [group.id, other.id], boxDistance(rect, bounds(other)), limits.groupGap, [rect, bounds(other)], 'Separate sibling boundaries.');
+    }
+  }
+  // Existing shape/fragment/marker checks stay blocking; new rules carry structured locations above.
+  const errors = [...diagnostics.filter(item => item.severity === 'error').map(item => `${item.ruleId}: ${item.elementIds.join(', ')} (${JSON.stringify(item.measured)}; required ${JSON.stringify(item.required)})`)];
+  return { ...legacy, errors, diagnostics, bounds: graphBounds(graph, legacy.routes) };
+}

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

@@ -0,0 +1,12 @@
+// 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.
+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.
+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);

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

@@ -0,0 +1,28 @@
+import { getDiagram } from './diagrams/registry.js';
+import { escapeXml, coreNode, paint } from './diagrams/drawing.js';
+import { nodeAppearance } from './visual-style.js';
+
+export function renderNode(node, type, offsetX = 0, offsetY = 0, palette, locale, moduleColors) {
+  const definition = getDiagram(type);
+  if (!definition) throw new Error(`Unsupported diagram type: ${type}`);
+  const appearance = nodeAppearance(node, palette, moduleColors), { fill, stroke, ring } = appearance;
+  const x = node.position.x + offsetX, y = node.position.y + offsetY;
+  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,
+    ...(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>`;
+}
+
+export function renderSelection(node, type) {
+  const definition = getDiagram(type);
+  return { markup: paint(definition.outline(node, 0, 0)), height: definition.selectionHeight?.(node) ?? node.size.height };
+}
+
+export function renderMiniMapNode(node, type, x, y, width, height, fill, stroke, strokeWidth) {
+  const definition = getDiagram(type);
+  const scaled = { ...node, position: { x, y }, size: { width, height } };
+  return paint(definition.outline(scaled, x, y), { fill, stroke, 'stroke-width': strokeWidth });
+}

package/skills/q-flow/assets/viewer/src/radix-colors.js

@@ -0,0 +1,47 @@
+// Selected Radix Colors scales, copied verbatim from @radix-ui/colors@3.0.0: https://github.com/radix-ui/colors
+// neutral = slate, accent = iris, data = cyan, warn = red, guard = amber (light and dark variants; index 0 is a placeholder, steps 1–12).
+// MIT notice is retained in generated HTML and SVG.
+export const RADIX = {
+  light: {
+    neutral: [null, "#fcfcfd", "#f9f9fb", "#f0f0f3", "#e8e8ec", "#e0e1e6", "#d9d9e0", "#cdced6", "#b9bbc6", "#8b8d98", "#80838d", "#60646c", "#1c2024"],
+    accent: [null, "#fdfdff", "#f8f8ff", "#f0f1fe", "#e6e7ff", "#dadcff", "#cbcdff", "#b8baf8", "#9b9ef0", "#5b5bd6", "#5151cd", "#5753c6", "#272962"],
+    data: [null, "#fafdfe", "#f2fafb", "#def7f9", "#caf1f6", "#b5e9f0", "#9ddde7", "#7dcedc", "#3db9cf", "#00a2c7", "#0797b9", "#107d98", "#0d3c48"],
+    warn: [null, "#fffcfc", "#fff7f7", "#feebec", "#ffdbdc", "#ffcdce", "#fdbdbe", "#f4a9aa", "#eb8e90", "#e5484d", "#dc3e42", "#ce2c31", "#641723"],
+    guard: [null, "#fefdfb", "#fefbe9", "#fff7c2", "#ffee9c", "#fbe577", "#f3d673", "#e9c162", "#e2a336", "#ffc53d", "#ffba18", "#ab6400", "#4f3422"],
+  },
+  dark: {
+    neutral: [null, "#111113", "#18191b", "#212225", "#272a2d", "#2e3135", "#363a3f", "#43484e", "#5a6169", "#696e77", "#777b84", "#b0b4ba", "#edeef0"],
+    accent: [null, "#13131e", "#171625", "#202248", "#262a65", "#303374", "#3d3e82", "#4a4a95", "#5958b1", "#5b5bd6", "#6e6ade", "#b1a9ff", "#e0dffe"],
+    data: [null, "#0b161a", "#101b20", "#082c36", "#003848", "#004558", "#045468", "#12677e", "#11809c", "#00a2c7", "#23afd0", "#4ccce6", "#b6ecf7"],
+    warn: [null, "#191111", "#201314", "#3b1219", "#500f1c", "#611623", "#72232d", "#8c333a", "#b54548", "#e5484d", "#ec5d5e", "#ff9592", "#ffd1d9"],
+    guard: [null, "#16120c", "#1d180f", "#302008", "#3f2700", "#4d3000", "#5c3d05", "#714f19", "#8f6424", "#ffc53d", "#ffd60a", "#ffca16", "#ffe7b3"],
+  },
+};
+
+// Eight identity scales for `module` colors, in the order call/return pairs cycle through them so neighbours differ most.
+// visual-style.js reads step 9 for icon chips and washes, step 10 for card frames and relationship lines.
+export const IDENTITY_SCALES = ['blue', 'orange', 'teal', 'crimson', 'violet', 'grass', 'plum', 'indigo'];
+export const IDENTITY = {
+  light: {
+    blue: [null, "#fbfdff", "#f4faff", "#e6f4fe", "#d5efff", "#c2e5ff", "#acd8fc", "#8ec8f6", "#5eb1ef", "#0090ff", "#0588f0", "#0d74ce", "#113264"],
+    orange: [null, "#fefcfb", "#fff7ed", "#ffefd6", "#ffdfb5", "#ffd19a", "#ffc182", "#f5ae73", "#ec9455", "#f76b15", "#ef5f00", "#cc4e00", "#582d1d"],
+    teal: [null, "#fafefd", "#f3fbf9", "#e0f8f3", "#ccf3ea", "#b8eae0", "#a1ded2", "#83cdc1", "#53b9ab", "#12a594", "#0d9b8a", "#008573", "#0d3d38"],
+    crimson: [null, "#fffcfd", "#fef7f9", "#ffe9f0", "#fedce7", "#facedd", "#f3bed1", "#eaacc3", "#e093b2", "#e93d82", "#df3478", "#cb1d63", "#621639"],
+    violet: [null, "#fdfcfe", "#faf8ff", "#f4f0fe", "#ebe4ff", "#e1d9ff", "#d4cafe", "#c2b5f5", "#aa99ec", "#6e56cf", "#654dc4", "#6550b9", "#2f265f"],
+    grass: [null, "#fbfefb", "#f5fbf5", "#e9f6e9", "#daf1db", "#c9e8ca", "#b2ddb5", "#94ce9a", "#65ba74", "#46a758", "#3e9b4f", "#2a7e3b", "#203c25"],
+    plum: [null, "#fefcff", "#fdf7fd", "#fbebfb", "#f7def8", "#f2d1f3", "#e9c2ec", "#deade3", "#cf91d8", "#ab4aba", "#a144af", "#953ea3", "#53195d"],
+    indigo: [null, "#fdfdfe", "#f7f9ff", "#edf2fe", "#e1e9ff", "#d2deff", "#c1d0ff", "#abbdf9", "#8da4ef", "#3e63dd", "#3358d4", "#3a5bc7", "#1f2d5c"],
+  },
+  dark: {
+    blue: [null, "#0d1520", "#111927", "#0d2847", "#003362", "#004074", "#104d87", "#205d9e", "#2870bd", "#0090ff", "#3b9eff", "#70b8ff", "#c2e6ff"],
+    orange: [null, "#17120e", "#1e160f", "#331e0b", "#462100", "#562800", "#66350c", "#7e451d", "#a35829", "#f76b15", "#ff801f", "#ffa057", "#ffe0c2"],
+    teal: [null, "#0d1514", "#111c1b", "#0d2d2a", "#023b37", "#084843", "#145750", "#1c6961", "#207e73", "#12a594", "#0eb39e", "#0bd8b6", "#adf0dd"],
+    crimson: [null, "#191114", "#201318", "#381525", "#4d122f", "#5c1839", "#6d2545", "#873356", "#b0436e", "#e93d82", "#ee518a", "#ff92ad", "#fdd3e8"],
+    violet: [null, "#14121f", "#1b1525", "#291f43", "#33255b", "#3c2e69", "#473876", "#56468b", "#6958ad", "#6e56cf", "#7d66d9", "#baa7ff", "#e2ddfe"],
+    grass: [null, "#0e1511", "#141a15", "#1b2a1e", "#1d3a24", "#25482d", "#2d5736", "#366740", "#3e7949", "#46a758", "#53b365", "#71d083", "#c2f0c2"],
+    plum: [null, "#181118", "#201320", "#351a35", "#451d47", "#512454", "#5e3061", "#734079", "#92549c", "#ab4aba", "#b658c4", "#e796f3", "#f4d4f4"],
+    indigo: [null, "#11131f", "#141726", "#182449", "#1d2e62", "#253974", "#304384", "#3a4f97", "#435db1", "#3e63dd", "#5472e4", "#9eb1ff", "#d6e1ff"],
+  },
+};
+
+export const RADIX_COLORS_NOTICE = "MIT License\n\nCopyright (c) 2021-2022 Modulz\nCopyright (c) 2022-Present WorkOS\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n";

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

@@ -0,0 +1,140 @@
+import { operandScopes } from './sequence-fragments.js';
+
+// Pair numbers follow the calls' message order (C1 is the first call that gets a reply), not their id spelling.
+export function sequencePairs(graph) {
+  if (graph.meta.diagramType !== 'sequence') return new Map();
+  const orderOf = new Map(graph.edges.map(edge => [edge.id, edge.order]));
+  const calls = [...new Set(graph.edges.map(edge => edge.replyTo).filter(Boolean))].sort((a, b) => (orderOf.get(a) ?? Infinity) - (orderOf.get(b) ?? Infinity) || (a < b ? -1 : a > b ? 1 : 0));
+  const indices = new Map(calls.map((id, index) => [id, index]));
+  return new Map(graph.edges.filter(edge => indices.has(edge.replyTo ?? edge.id)).map(edge => {
+    const callId = edge.replyTo ?? edge.id, index = indices.get(callId);
+    return [edge.id, { callId, index, label: `${edge.replyTo ? '↩ ' : ''}C${index + 1}` }];
+  }));
+}
+
+export function sequenceMessageLabel(graph, edge, pairs = sequencePairs(graph), scopes = operandScopes(graph)) {
+  const pair = pairs.get(edge.id);
+  const parallel = (graph.groups ?? []).some(group => group.kind === 'par' && (scopes.get(edge.id) ?? '').split('/').some(segment => segment.startsWith(encodeURIComponent(group.id) + ':')));
+  return pair ? `${pair.label} · ${edge.label ?? ''}` : parallel ? edge.label ?? '' : `${String(edge.order).padStart(2, '0')} · ${edge.label ?? ''}`;
+}
+
+// Hand-edited or legacy data may lack route.messageY, or the whole route. Such a message is stacked by order below the
+// default headers so the page still opens; the layout check reports the missing coordinate and --layout auto writes it.
+const FALLBACK_TOP = 140, FALLBACK_STEP = 54;
+export const sequenceEndpointY = (edge, at) => (edge.route?.messageY ?? FALLBACK_TOP + edge.order * FALLBACK_STEP) + (at === 'receive' && edge.source === edge.target ? 30 : 0);
+
+export function validateExecutions(graph, { inputOnly = false } = {}) {
+  const errors = [], edges = new Map(graph.edges.map(edge => [edge.id, edge]));
+  const sequence = graph.meta.diagramType === 'sequence';
+  if (!sequence) {
+    if (graph.executions !== undefined || graph.edges.some(edge => edge.replyTo !== undefined)) errors.push('executions and replyTo are only supported for sequence');
+    return errors;
+  }
+  if (!inputOnly) {
+    const ordered = [...graph.edges].sort((a, b) => a.order - b.order);
+    for (let i = 1; i < ordered.length; i++) if (sequenceEndpointY(ordered[i], 'send') <= sequenceEndpointY(ordered[i - 1], 'send')) errors.push(`edge ${ordered[i].id}.route.messageY must preserve message order after ${ordered[i - 1].id}`);
+  }
+  const scopes = operandScopes(graph), returned = new Set();
+  for (const edge of graph.edges) {
+    if (edge.replyTo === undefined) continue;
+    const call = edges.get(edge.replyTo), prefix = `edge ${edge.id}.replyTo ${String(edge.replyTo)}`;
+    if (edge.kind !== 'return' || typeof edge.replyTo !== 'string' || !call || !['sync', 'async'].includes(call.kind)) errors.push(`${prefix} must reference a sync or async call from a return`);
+    else {
+      if (call.order >= edge.order) errors.push(`${prefix} must precede its return`);
+      if (call.source !== edge.target || call.target !== edge.source) errors.push(`${prefix} endpoints must be reversed`);
+      if (scopes.get(call.id) !== scopes.get(edge.id)) errors.push(`${prefix} must stay in the same operand scope`);
+    }
+    if (returned.has(edge.replyTo)) errors.push(`${prefix} has a duplicate return`);
+    returned.add(edge.replyTo);
+  }
+  if (graph.executions === undefined) return errors;
+  if (!Array.isArray(graph.executions)) return [...errors, 'executions must be an array'];
+  const ids = new Map(), intervals = new Map(), anchors = new Map();
+  for (const execution of graph.executions) {
+    if (!execution || typeof execution !== 'object' || Array.isArray(execution)) { errors.push('execution must be an object'); continue; }
+    const prefix = `execution ${String(execution.id)}`;
+    if (typeof execution.id !== 'string' || !execution.id.trim()) errors.push(`${prefix} needs a non-empty id`);
+    if (ids.has(execution.id)) errors.push(`${prefix} duplicate id`);
+    ids.set(execution.id, execution);
+    if (!graph.nodes.some(node => node.id === execution.participantId)) errors.push(`${prefix} unknown participant ${String(execution.participantId)}`);
+    const ys = [];
+    for (const role of ['start', 'end']) {
+      const endpoint = execution[role], edge = edges.get(endpoint?.edgeId);
+      if (!edge || !['send', 'receive'].includes(endpoint?.at)) { errors.push(`${prefix}.${role} invalid endpoint ${String(endpoint?.edgeId)}`); continue; }
+      if (edge[endpoint.at === 'send' ? 'source' : 'target'] !== execution.participantId) errors.push(`${prefix}.${role} endpoint ${edge.id} does not belong to participant ${execution.participantId}`);
+      // Semantic ordering must not depend on coordinates or legacy message spacing.
+      ys.push(inputOnly ? edge.order * 2 + Number(endpoint.at === 'receive' && edge.source === edge.target) : sequenceEndpointY(edge, endpoint.at));
+      const key = `${edge.id}:${endpoint.at}`;
+      if (anchors.has(key)) errors.push(`${prefix}.${role} ambiguous endpoint ${key} with execution ${anchors.get(key)}`);
+      anchors.set(key, execution.id);
+    }
+    if (ys.length === 2) {
+      if (ys[0] >= ys[1]) errors.push(`${prefix} start must precede end`);
+      if (scopes.get(execution.start.edgeId) !== scopes.get(execution.end.edgeId)) errors.push(`${prefix} endpoints must stay in the same operand scope`);
+      intervals.set(execution.id, ys);
+    }
+  }
+  for (const execution of ids.values()) {
+    if (execution.parentId !== undefined) {
+      const parent = ids.get(execution.parentId);
+      if (!parent) errors.push(`execution ${execution.id} unknown parent ${String(execution.parentId)}`);
+      else {
+        if (parent.participantId !== execution.participantId) errors.push(`execution ${execution.id} parent ${parent.id} belongs to another participant`);
+        const a = intervals.get(parent.id), b = intervals.get(execution.id);
+        if (a && b && (b[0] < a[0] || b[1] > a[1])) errors.push(`execution ${execution.id} exceeds parent ${parent.id}`);
+        const parentScope = scopes.get(parent.start?.edgeId) ?? '', childScope = scopes.get(execution.start?.edgeId) ?? '';
+        if (parentScope && childScope !== parentScope && !childScope.startsWith(parentScope + '/')) errors.push(`execution ${execution.id} is outside parent ${parent.id} operand scope`);
+      }
+    }
+    const seen = new Set([execution.id]); let parent = ids.get(execution.parentId);
+    while (parent) {
+      if (seen.has(parent.id)) { errors.push(`execution ${execution.id} parent cycle at ${parent.id}`); break; }
+      seen.add(parent.id); parent = ids.get(parent.parentId);
+    }
+  }
+  const list = [...ids.values()];
+  const ancestor = (a, b) => { const seen = new Set(); let parent = ids.get(b.parentId); while (parent && !seen.has(parent.id)) { if (parent.id === a.id) return true; seen.add(parent.id); parent = ids.get(parent.parentId); } return false; };
+  for (let i = 0; i < list.length; i++) for (const other of list.slice(i + 1)) {
+    const item = list[i], a = intervals.get(item.id), b = intervals.get(other.id);
+    if (a && b && item.participantId === other.participantId && !ancestor(item, other) && !ancestor(other, item) && a[0] < b[1] && b[0] < a[1]) errors.push(`executions ${item.id} and ${other.id} overlap without nesting`);
+  }
+  return errors;
+}
+
+// Authoring rule for the CLI, not the Viewer: an answered sync call needs a bar on its callee from the call's receive
+// to the reply's send. Legacy sequences have no replyTo, so they are never asked for one; async pairs need no bar. Two
+// answered calls to one callee that interleave (the second opens inside the first and closes after it) cannot be drawn,
+// since bars on one participant nest or stay apart, so neither is asked for one.
+export function callsMissingExecutions(graph) {
+  if (graph.meta?.diagramType !== 'sequence') return [];
+  const edges = new Map(graph.edges.map(edge => [edge.id, edge])), bars = graph.executions ?? [];
+  const at = (anchor, edgeId, side) => anchor?.edgeId === edgeId && anchor.at === side;
+  const pairs = graph.edges.filter(reply => edges.get(reply.replyTo)?.kind === 'sync').map(reply => ({ call: edges.get(reply.replyTo), reply }));
+  const crosses = (a, b) => a.call.order < b.call.order && b.call.order < a.reply.order && a.reply.order < b.reply.order;
+  return pairs.filter(pair => !pairs.some(other => other.call.target === pair.call.target && (crosses(pair, other) || crosses(other, pair)))
+    && !bars.some(bar => bar.participantId === pair.call.target && at(bar.start, pair.call.id, 'receive') && at(bar.end, pair.reply.id, 'send')));
+}
+
+export const missingCallExecutions = graph => callsMissingExecutions(graph)
+  .map(({ call, reply }) => `edge ${call.id} sync call answered by ${reply.id} needs an execution on ${call.target} from ${call.id} receive to ${reply.id} send; --fix adds it`);
+
+// Geometry is shared by routing, the participant SVG, exports and bounds.
+export function sequenceExecutions(graph) {
+  if (graph.meta.diagramType !== 'sequence') return [];
+  const items = graph.executions ?? [], edges = new Map(graph.edges.map(edge => [edge.id, edge])), scopes = operandScopes(graph);
+  return items.map(item => {
+    let depth = 0, parent = items.find(other => other.id === item.parentId);
+    const seen = new Set([item.id]);
+    while (parent && !seen.has(parent.id)) { seen.add(parent.id); depth++; parent = items.find(other => other.id === parent.parentId); }
+    const node = graph.nodes.find(node => node.id === item.participantId);
+    const y = sequenceEndpointY(edges.get(item.start.edgeId), item.start.at);
+    return { ...item, depth, scope: scopes.get(item.start.edgeId) ?? '', x: node.position.x + node.size.width / 2 - 8 + depth * 8, y, width: 16, height: sequenceEndpointY(edges.get(item.end.edgeId), item.end.at) - y };
+  });
+}
+
+export function executionAt(executions, participantId, edge, at, y, scope = '') {
+  const candidates = executions.filter(item => item.participantId === participantId);
+  const bound = candidates.find(item => [item.start, item.end].some(anchor => anchor.edgeId === edge.id && anchor.at === at));
+  if (bound) return bound;
+  return candidates.filter(item => y >= item.y && y <= item.y + item.height && (!item.scope || scope === item.scope || scope.startsWith(item.scope + '/'))).sort((a, b) => b.depth - a.depth)[0];
+}