qgraphflow 0.0.6

package/skills/q-flow/assets/viewer/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "qgraphflow-viewer",
+  "private": true,
+  "version": "0.0.6",
+  "type": "module",
+  "scripts": {
+    "build": "node build-layout.mjs && vite build",
+    "dev": "vite"
+  },
+  "dependencies": {
+    "@xyflow/react": "12.11.5",
+    "d3-force": "3.0.0",
+    "react": "19.2.8",
+    "react-dom": "19.2.8"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "6.1.1",
+    "elkjs": "0.11.0",
+    "vite": "8.2.2",
+    "vite-plugin-singlefile": "2.3.3"
+  }
+}

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

@@ -0,0 +1,43 @@
+import { genericCard } from './card.js';
+import { cylinder, polygonAnchor, rectAnchor, roundedRectAnchor, rectangle, HEXAGON, polygon } from './drawing.js';
+
+const OCTAGON = [[.06, 0], [.94, 0], [1, .16], [1, .84], [.94, 1], [.06, 1], [0, .84], [0, .16]];
+const SLANT = [[.08, 0], [1, 0], [.92, 1], [0, 1]];
+
+export function architectureOutline(node, x, y) {
+  const { width: w, height: h } = node.size;
+  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.
+  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' }]];
+  return base;
+}
+
+const anchor = (node, side, offset) => {
+  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);
+  if (node.kind === 'config') return polygonAnchor(node, side, offset, SLANT);
+  if (node.kind === 'business') return roundedRectAnchor(node, side, offset, Math.min(28, node.size.height / 2));
+  if (node.kind === 'database') return rectAnchor(node, side, offset, { left: 12, right: 12, top: 2, bottom: 2 });
+  return rectAnchor(node, side, offset);
+};
+
+const contentInset = node => ['external', 'config', 'failure'].includes(node.kind) ? Math.min(28, node.size.width * .08) : 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,
+  cardLayout: true, contentInset,
+};

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

@@ -0,0 +1,21 @@
+import { translate } from '../i18n.js';
+import { cardTextLayout, text, coreNode, dataKinds, kindLabels, 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 } });
+  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>`;
+}

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

@@ -0,0 +1,52 @@
+import { translate } from '../i18n.js';
+import { text, fit, TYPOGRAPHY, nodeMetrics, rectangle, paint } from './drawing.js';
+import { estimateLabelSize } from '../text-layout.js';
+
+const outline = (node, x, y) => rectangle(node, x, y, 9);
+
+function classNode(node, x, y, fill, stroke, palette) {
+  const attributes = node.attributes ?? [];
+  const methods = node.methods ?? [];
+  const { classHeaderHeight: header, classRowHeight: rowHeight } = nodeMetrics(node);
+  const attributeHeight = attributes.length ? attributes.length * rowHeight + 13 : 30;
+  const attrY = y + header;
+  const methodY = attrY + attributeHeight;
+  const stereotype = node.kind === 'interface' ? '«interface»' : node.kind === 'abstract' ? '«abstract»' : '';
+  const textWidth = node.size.width - 26;
+  const attrText = attributes.map((item, index) => text(x + 13, attrY + 6 + rowHeight / 2 + TYPOGRAPHY.body * .35 + index * rowHeight, fit(item, textWidth), 'member')).join('');
+  const methodText = methods.map((item, index) => text(x + 13, methodY + 6 + rowHeight / 2 + TYPOGRAPHY.body * .35 + index * rowHeight, fit(item, textWidth), 'member')).join('');
+  return `<g filter="url(#node-shadow)">${paint(outline(node, x, y), { fill: palette.surface2, stroke, 'stroke-width': node.appearance?.moduleColor || node.appearance?.ring ? 1.5 : 1 })}<path d="M${x + 9} ${y}H${x + node.size.width - 9}Q${x + node.size.width} ${y} ${x + node.size.width} ${y + 9}V${attrY}H${x}V${y + 9}Q${x} ${y} ${x + 9} ${y}Z" fill="${node.appearance?.header ?? fill}"/><rect x="${x + 1}" y="${methodY}" width="${node.size.width - 2}" height="${Math.max(0, node.size.height - header - attributeHeight - 1)}" fill="${palette.group}"/>${stereotype ? text(x + 13, y + 24, stereotype, 'stereotype') : ''}${text(x + 13, y + (stereotype ? 50 : TYPOGRAPHY.classHeader / 2 + 7), fit(node.label, textWidth), 'shape-title')}${node.subtitle ? text(x + 13, y + header - 10, fit(node.subtitle, textWidth), 'body') : ''}<path d="M${x} ${attrY}H${x + node.size.width}M${x} ${methodY}H${x + node.size.width}" stroke="${palette.rule}"/>${attrText}${methodText}</g>`;
+}
+
+
+export default {
+  dashedKinds: ['implementation', 'dependency'],
+  id: 'class', label: 'Class diagram',
+  nodeKinds: ["class", "interface", "abstract"],
+  groupKinds: [],
+  edgeKinds: ["association", "inheritance", "implementation", "composition", "aggregation", "dependency"],
+  render: classNode, outline, compartments: true,
+  undirected: ['association', 'composition', 'aggregation'],
+  markers: { inheritance: { end: 'triangle' }, implementation: { end: 'triangle' }, composition: { start: 'diamond-filled' }, aggregation: { start: 'diamond-open' }, dependency: { end: 'arrow-open' } },
+  edgeLabel: (edge, locale) => edge.label ?? (['composition', 'aggregation', 'inheritance', 'implementation'].includes(edge.kind) ? translate(locale, edge.kind) : ''),
+  validateEdge(edge, label, errors) {
+    for (const role of ['source', 'target']) {
+      const value = edge[`${role}Multiplicity`];
+      if (value === undefined) continue;
+      const range = typeof value === 'string' && /^(\d+)(?:\.\.(\d+|\*))?$/.exec(value);
+      if (value !== '*' && (!range || range[2] && range[2] !== '*' && Number(range[2]) < Number(range[1]))) errors.push(`${label}.${role}Multiplicity must be *, a non-negative integer, or an ascending range`);
+      if (['inheritance', 'implementation', 'dependency'].includes(edge.kind)) errors.push(`${label}.${role}Multiplicity is only supported on associations, aggregation and composition`);
+    }
+  },
+  endpointLabels(edge, points) {
+    return ['source', 'target'].flatMap(role => {
+      const label = edge[`${role}Multiplicity`];
+      if (label === undefined) return [];
+      const point = role === 'source' ? points[0] : points.at(-1), neighbor = role === 'source' ? points[1] : points.at(-2), size = estimateLabelSize(label, Infinity);
+      const horizontal = point.y === neighbor.y, direction = Math.sign(horizontal ? neighbor.x - point.x : neighbor.y - point.y);
+      const center = horizontal ? { x: point.x + direction * (24 + size.width / 2), y: point.y - 6 - size.height / 2 }
+        : { x: point.x + 6 + size.width / 2, y: point.y + direction * (24 + size.height / 2) };
+      return [{ role, label, labelPoint: center, labelBox: { x: center.x - size.width / 2, y: center.y - size.height / 2, ...size } }];
+    });
+  },
+};

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

@@ -0,0 +1,19 @@
+import { centeredTitle, rectangle, paint, rectAnchor, roundedRectAnchor } from './drawing.js';
+
+const outline = (node, x, y) => node.kind === 'dataStore'
+  ? [['path', { d: `M${x + node.size.width} ${y}H${x}V${y + node.size.height}H${x + node.size.width}M${x + 12} ${y}V${y + node.size.height}` }]]
+  : rectangle(node, x, y, node.kind === 'process' ? 24 : 10);
+const textArea = node => ({ width: node.size.width - 32, height: node.size.height - 20 });
+function dataflowNode(node, x, y, fill, stroke) {
+  const area = textArea(node);
+  return `<g class="shape-label">${paint(outline(node, x, y), { fill, stroke, 'stroke-width': 1.2 })}${centeredTitle(x + node.size.width / 2, y + node.size.height / 2, node.label, area.width, area.height, node.subtitle)}</g>`;
+}
+
+export default {
+  id: 'dataflow', label: 'Data flow',
+  nodeKinds: ["external", "process", "dataStore"],
+  groupKinds: ["ownership", "external"],
+  edgeKinds: ["data"],
+  render: dataflowNode, outline, textArea,
+  anchor: (node, side, offset) => node.kind === 'process' ? roundedRectAnchor(node, side, offset, 24) : rectAnchor(node, side, offset),
+};

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

@@ -0,0 +1,41 @@
+import { genericCard } from './card.js';
+import { cylinder, polygonAnchor, rectAnchor, roundedRectAnchor, rectangle, HEXAGON, polygon } from './drawing.js';
+
+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.
+  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' }]
+  ];
+  if (node.kind === 'node') return [...polygon(node, x, y, CUBE), ['path', { d: `M${x} ${y + h * .1}L${x + w * .94} ${y + h * .1}L${x + w} ${y}M${x + w * .94} ${y + h * .1}V${y + h}`, fill: 'none' }]];
+  if (node.kind === 'container') return [...rectangle(node, x, y, 10), ['rect', { x: x + w - 30, y: y + 13, width: 16, height: 11, rx: 2, fill: 'none' }], ['rect', { x: x + w - 34, y: y + 17, width: 16, height: 11, rx: 2, fill: 'none' }]];
+  if (node.kind === 'artifact') return [['path', { d: `M${x} ${y}H${x + w - 28}L${x + w} ${y + 28}V${y + h}H${x}Z` }], ['path', { d: `M${x + w - 28} ${y}V${y + 28}H${x + w}`, fill: 'none' }]];
+  if (node.kind === 'database') return cylinder(node, x, y);
+  if (node.kind === 'external') return polygon(node, x, y, HEXAGON);
+  if (node.kind === 'service') return rectangle(node, x, y, 16);
+  return rectangle(node, x, y, 10);
+}
+
+const anchor = (node, side, offset) => {
+  if (node.kind === 'device') return rectAnchor(node, side, offset, { left: 16, right: 16, top: 0, bottom: 0 });
+  if (node.kind === 'node') return polygonAnchor(node, side, offset, CUBE);
+  if (node.kind === 'database') return rectAnchor(node, side, offset, { left: 12, right: 12, top: 2, bottom: 2 });
+  if (node.kind === 'external') return polygonAnchor(node, side, offset, HEXAGON);
+  if (node.kind === 'service') return roundedRectAnchor(node, side, offset, 16);
+  return rectAnchor(node, side, offset);
+};
+
+const contentInset = node => node.kind === 'external' ? Math.min(28, node.size.width * .08) : node.kind === 'device' ? 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,
+};

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

@@ -0,0 +1,174 @@
+import { cardTextLayout, layoutText, groupHeadingLayout } from '../text-layout.js';
+import { TYPOGRAPHY, isCore as coreNode, dataKinds, kindLabels, nodeMetrics } from '../visual-style.js';
+export { cardTextLayout, layoutText, TYPOGRAPHY, coreNode, dataKinds, kindLabels, nodeMetrics };
+
+export function groupHeadingSvg(group, x = 0, y = 0) {
+  return groupHeadingLayout(group).lines.map((line, i) => text(x + 16, y + 26 + i * 22, line, 'group')).join('');
+}
+
+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"/>`;
+}
+
+export function escapeXml(value = '') {
+  return String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+}
+
+
+export function fit(value, width) {
+  return { value: String(value ?? ''), width };
+}
+
+
+export function text(x, y, value, className, extra = '') {
+  const fitted = value && typeof value === 'object' && 'width' in value;
+  const fontSize = Number(extra.match(/font-size:([\d.]+)px/)?.[1]) || {
+    title: TYPOGRAPHY.title, 'shape-title': TYPOGRAPHY.title, 'participant-title': TYPOGRAPHY.title,
+    body: TYPOGRAPHY.body, 'field-name': TYPOGRAPHY.body, 'field-type': TYPOGRAPHY.body,
+    member: TYPOGRAPHY.body, 'entity-title': TYPOGRAPHY.title
+  }[className] || TYPOGRAPHY.small;
+  if (value && typeof value === 'object' && 'runs' in value) {
+    const spans = value.runs.map(run => { const color = value.colors[run.role]; return color ? `<tspan style="fill:${color}">${escapeXml(run.text)}</tspan>` : escapeXml(run.text); }).join('');
+    return `<text x="${x}" y="${y}" class="${className}"${extra}>${spans}</text>`;
+  }
+  let content = fitted ? value.value : value;
+  if (fitted && layoutText(content, Infinity, fontSize).width > value.width) {
+    const available = Math.max(0, value.width - layoutText('…', Infinity, fontSize).width);
+    content = available ? (layoutText(content, available, fontSize).lines[0] ?? '') + '…' : '…';
+  }
+  return `<text x="${x}" y="${y}" class="${className}"${extra}>${escapeXml(content)}</text>`;
+}
+
+
+export function centeredTitle(cx, cy, value, width, height = Infinity, subtitle = '') {
+  if (width <= 0 || height <= 0) return '';
+  const title = layoutText(value, width, TYPOGRAPHY.title, 29);
+  const body = layoutText(subtitle, width, TYPOGRAPHY.body, 23.2);
+  const titleCount = Math.min(title.lines.length, Math.max(1, Math.floor(height / title.lineHeight)));
+  const bodyCount = Math.min(body.lines.length, Math.max(0, Math.floor((height - titleCount * title.lineHeight - 5) / body.lineHeight)));
+  const usedHeight = titleCount * title.lineHeight + (bodyCount ? 5 + bodyCount * body.lineHeight : 0);
+  const top = cy - usedHeight / 2;
+  const lines = (layout, count, y, className) => layout.lines.slice(0, count).map((line, index) =>
+    text(cx, y + index * layout.lineHeight, line + (index === count - 1 && count < layout.lines.length ? '…' : ''), className, ' text-anchor="middle"')).join('');
+  const markup = lines(title, titleCount, top + 22, 'shape-title')
+    + lines(body, bodyCount, top + titleCount * title.lineHeight + 5 + 18, 'body');
+  // Legacy tiny symbols may be shorter than one title line; only their text is scaled to the available height.
+  const scale = Math.min(1, height / usedHeight);
+  return scale < 1 ? `<g transform="translate(${cx} ${cy}) scale(${scale}) translate(${-cx} ${-cy})">${markup}</g>` : markup;
+}
+
+
+// Geometry is declared once by each diagram and painted by both node rendering and selection.
+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
+// 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;
+  return [
+    ['path', { d: `M${x + 12} ${top}Q${x + 12} ${y + 2} ${x + w / 2} ${y + 2}T${x + w - 12} ${top}V${bottom}Q${x + w - 12} ${y + h - 2} ${x + w / 2} ${y + h - 2}T${x + 12} ${bottom}Z` }],
+    ['ellipse', { cx: x + w / 2, cy: top, rx: w / 2 - 12, ry, fill: 'none' }]
+  ];
+};
+export const HEXAGON = [[.08, 0], [.92, 0], [1, .5], [.92, 1], [.08, 1], [0, .5]];
+export const polygon = (node, x, y, points) => [['polygon', { points: points.map(([px, py]) => `${x + px * node.size.width},${y + py * node.size.height}`).join(' ') }]];
+export const diamond = (node, x, y) => [['polygon', { points: `${x + node.size.width / 2},${y} ${x + node.size.width},${y + node.size.height / 2} ${x + node.size.width / 2},${y + node.size.height} ${x},${y + node.size.height / 2}` }]];
+export const actor = (node, x, y) => {
+  const cx = x + node.size.width / 2;
+  return [['circle', { cx, cy: y + 13, r: 11 }], ['path', { d: `M${cx} ${y + 24}v29M${cx - 20} ${y + 35}h40M${cx} ${y + 53}l-17 23M${cx} ${y + 53}l17 23`, fill: 'none' }]];
+};
+
+const nodeCenter = node => ({ x: node.position.x + node.size.width / 2, y: node.position.y + node.size.height / 2 });
+export function rectAnchor(node, side, offset = 0, inset = 0) {
+  const middle = nodeCenter(node);
+  const values = typeof inset === 'number' ? { left: inset, right: inset, top: inset, bottom: inset } : { left: 0, right: 0, top: 0, bottom: 0, ...inset };
+  if (side === 'left' || side === 'right') return {
+    x: node.position.x + (side === 'left' ? values.left : node.size.width - values.right),
+    y: middle.y + offset
+  };
+  return {
+    x: middle.x + offset,
+    y: node.position.y + (side === 'top' ? values.top : node.size.height - values.bottom)
+  };
+}
+
+export function roundedRectAnchor(node, side, offset = 0, radius = 10) {
+  const { x, y } = node.position, { width, height } = node.size;
+  const middle = nodeCenter(node), r = Math.max(0, Math.min(radius, width / 2, height / 2));
+  if (side === 'left' || side === 'right') {
+    const py = middle.y + offset;
+    if (py < y || py > y + height) return rectAnchor(node, side, offset);
+    const circleY = py < y + r ? y + r : py > y + height - r ? y + height - r : py;
+    const curve = Math.sqrt(Math.max(0, r * r - (py - circleY) ** 2));
+    return { x: side === 'left' ? x + r - curve : x + width - r + curve, y: py };
+  }
+  const px = middle.x + offset;
+  if (px < x || px > x + width) return rectAnchor(node, side, offset);
+  const circleX = px < x + r ? x + r : px > x + width - r ? x + width - r : px;
+  const curve = Math.sqrt(Math.max(0, r * r - (px - circleX) ** 2));
+  return { x: px, y: side === 'top' ? y + r - curve : y + height - r + curve };
+}
+
+export function ellipseAnchor(node, side, offset = 0, insetX = 0, insetY = 0) {
+  const middle = nodeCenter(node), rx = Math.max(1, node.size.width / 2 - insetX), ry = Math.max(1, node.size.height / 2 - insetY);
+  if (side === 'left' || side === 'right') {
+    const py = middle.y + offset;
+    if (Math.abs(offset) > ry) return rectAnchor(node, side, offset);
+    const dx = rx * Math.sqrt(Math.max(0, 1 - ((py - middle.y) / ry) ** 2));
+    return { x: middle.x + (side === 'left' ? -dx : dx), y: py };
+  }
+  const px = middle.x + offset;
+  if (Math.abs(offset) > rx) return rectAnchor(node, side, offset);
+  const dy = ry * Math.sqrt(Math.max(0, 1 - ((px - middle.x) / rx) ** 2));
+  return { x: px, y: middle.y + (side === 'top' ? -dy : dy) };
+}
+
+export function polygonAnchor(node, side, offset = 0, normalizedPoints) {
+  const points = normalizedPoints.map(([px, py]) => ({ x: node.position.x + px * node.size.width, y: node.position.y + py * node.size.height }));
+  const middle = nodeCenter(node);
+  const horizontal = side === 'left' || side === 'right';
+  const fixed = horizontal ? middle.y + offset : middle.x + offset;
+  const hits = [];
+  for (let index = 0; index < points.length; index += 1) {
+    const a = points[index], b = points[(index + 1) % points.length];
+    const first = horizontal ? a.y : a.x, second = horizontal ? b.y : b.x;
+    if (fixed < Math.min(first, second) || fixed > Math.max(first, second) || first === second) continue;
+    const ratio = (fixed - first) / (second - first);
+    hits.push((horizontal ? a.x : a.y) + ratio * ((horizontal ? b.x : b.y) - (horizontal ? a.x : a.y)));
+  }
+  if (!hits.length) return rectAnchor(node, side, offset);
+  const value = side === 'left' || side === 'top' ? Math.min(...hits) : Math.max(...hits);
+  return horizontal ? { x: value, y: fixed } : { x: fixed, y: value };
+}
+
+export function actorAnchor(node, side, offset = 0, top = 0) {
+  const cx = node.position.x + node.size.width / 2, y = node.position.y + top;
+  if (side === 'left') return { x: cx - 20, y: y + 35 };
+  if (side === 'right') return { x: cx + 20, y: y + 35 };
+  if (side === 'top') return { x: cx, y: y + 2 };
+  return { x: cx + Math.sign(offset || 1) * Math.min(17, Math.abs(offset)), y: y + 76 };
+}
+
+export function svgStyles(palette, scope = '') {
+  return `${scope}.heading{font:650 24px -apple-system,BlinkMacSystemFont,"PingFang SC",sans-serif;fill:${palette.ink};letter-spacing:-.5px}
+${scope}.meta{font:400 ${TYPOGRAPHY.small}px -apple-system,BlinkMacSystemFont,"PingFang SC",sans-serif;fill:${palette.ink3}}
+${scope}.group{font:650 ${TYPOGRAPHY.small}px -apple-system,BlinkMacSystemFont,"PingFang SC",sans-serif;fill:${palette.ink2};letter-spacing:.4px}
+${scope}[data-diagram-group-id]>.group{fill:${palette.ink2}}
+${scope}.group-kind{font:600 ${TYPOGRAPHY.small}px ui-monospace,monospace;fill:${palette.ink2};letter-spacing:.7px}
+${scope}.stereotype{font:600 ${TYPOGRAPHY.small}px -apple-system,BlinkMacSystemFont,"PingFang SC",sans-serif;fill:${palette.ink3};letter-spacing:.6px}
+${scope}.title,${scope}.participant-title{font:650 ${TYPOGRAPHY.title}px -apple-system,BlinkMacSystemFont,"PingFang SC",sans-serif;fill:${palette.ink}}
+${scope}.shape-title{font:650 ${TYPOGRAPHY.title}px -apple-system,BlinkMacSystemFont,"PingFang SC",sans-serif;fill:${palette.ink}}
+${scope}.body{font:400 ${TYPOGRAPHY.body}px -apple-system,BlinkMacSystemFont,"PingFang SC",sans-serif;fill:${palette.ink2}}
+${scope}.edge,${scope}.cardinality{font:500 ${TYPOGRAPHY.body}px -apple-system,BlinkMacSystemFont,"PingFang SC",sans-serif;fill:${palette.ink2}}
+${scope}.edge-bg{fill:${palette.surface};stroke:none}
+${scope}.field-key{font:700 ${TYPOGRAPHY.small}px ui-monospace,monospace;fill:${palette.accent}}
+${scope}.field-name{font:500 ${TYPOGRAPHY.body}px ui-monospace,monospace;fill:${palette.ink2}}
+${scope}.entity-title{font:650 ${TYPOGRAPHY.title}px -apple-system,BlinkMacSystemFont,"PingFang SC",sans-serif;fill:${palette.ink}}
+${scope}.entity-meta{font:500 ${TYPOGRAPHY.small}px -apple-system,BlinkMacSystemFont,"PingFang SC",sans-serif;fill:${palette.ink2}}
+${scope}.member{font:500 ${TYPOGRAPHY.body}px ui-monospace,monospace;fill:${palette.ink2}}
+${scope}.field-type{font:400 ${TYPOGRAPHY.body}px ui-monospace,monospace;fill:${palette.ink3}}
+`;
+}

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

@@ -0,0 +1,34 @@
+import { translate } from '../i18n.js';
+import { text, fit, layoutText, TYPOGRAPHY, nodeMetrics, rectangle, paint } from './drawing.js';
+
+const outline = (node, x, y) => rectangle(node, x, y, 9);
+
+function erNode(node, x, y, fill, stroke, palette, locale) {
+  const { erHeaderHeight: header, erRowHeight: rowHeight, erFontSize: fontSize } = nodeMetrics(node);
+  const subtitle = fit(node.subtitle ?? translate(locale, 'Entity'), node.size.width - 60);
+  const subtitleFont = node.subtitle ? TYPOGRAPHY.body : TYPOGRAPHY.small;
+  const rows = node.fields.map((field, index) => {
+    const rowY = y + header + index * rowHeight;
+    const baseline = rowY + rowHeight / 2 + fontSize * .35;
+    const typeWidth = Math.min(node.size.width * .55, layoutText(field.type, Infinity, fontSize).width);
+    return `${field.key === 'FK' ? `<rect x="${x + 1}" y="${rowY}" width="${node.size.width - 2}" height="${rowHeight}" fill="${palette.surface}"/>` : ''}${index ? `<path d="M${x} ${rowY}H${x + node.size.width}" stroke="${palette.ruleSoft}"/>` : ''}${field.key ? text(x + 10, baseline - 1, field.key, 'field-key', ` style="fill:${field.key === 'FK' ? palette.accent : palette.data}"`) : ''}${text(x + 45, baseline, fit(field.name, Math.max(1, node.size.width - 62 - typeWidth)), 'field-name', ` style="font-size:${fontSize}px"`)}${text(x + node.size.width - 10, baseline - 1, fit(field.type, typeWidth), 'field-type', ` text-anchor="end" style="font-size:${fontSize}px"`)}`;
+  }).join('');
+  return `<g filter="url(#node-shadow)">${paint(outline(node, x, y), { fill: palette.surface2, stroke, 'stroke-width': node.appearance?.moduleColor || node.appearance?.ring ? 1.5 : 1 })}<path d="M${x + 9} ${y}H${x + node.size.width - 9}Q${x + node.size.width} ${y} ${x + node.size.width} ${y + 9}V${y + header}H${x}V${y + 9}Q${x} ${y} ${x + 9} ${y}Z" fill="${node.appearance?.header ?? fill}"/><path d="M${x} ${y + header}H${x + node.size.width}" stroke="${palette.rule}"/>${text(x + 13, y + header * .43, fit(node.label, node.size.width - 26), 'entity-title', ` style="font-size:${Math.min(TYPOGRAPHY.title, header * .38)}px;fill:${palette.ink}"`)}${text(x + 13, y + header * .78, subtitle, 'entity-meta', ` style="font-size:${Math.min(subtitleFont, header * .23)}px;fill:${palette.ink2}"`)}${text(x + node.size.width - 13, y + header * .78, String(node.fields.length).padStart(2, '0'), 'entity-meta', ` text-anchor="end" style="font-size:${Math.min(subtitleFont, header * .23)}px;fill:${palette.ink2}"`)}${rows}</g>`;
+}
+
+
+export default {
+  id: 'er', label: 'ER diagram',
+  nodeKinds: ["entity"],
+  groupKinds: [],
+  edgeKinds: ["relationship"],
+  render: erNode, outline,
+  compartments: true, cardinalities: true, endpointStub: 28,
+  undirected: ['relationship'],
+  validateNode(node, label, errors) {
+    if (!Array.isArray(node?.fields) || node.fields.length === 0) errors.push(`${label}.fields must be a non-empty array for er`);
+  },
+  validateEdge(edge, label, errors) {
+    for (const field of ['sourceCardinality', 'targetCardinality']) if (!['1', '0..1', '*', '1..*', '0..*'].includes(edge?.[field])) errors.push(`${label}.${field} is unsupported`);
+  },
+};

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

@@ -0,0 +1,37 @@
+import { translate } from '../i18n.js';
+import { centeredTitle, rectangle, diamond, paint, polygonAnchor, rectAnchor, roundedRectAnchor } from './drawing.js';
+
+export const FLOW_SLANT = .12;
+const outline = (node, x, y) => {
+  if (node.kind === 'decision') return diamond(node, x, y);
+  if (['input', 'output'].includes(node.kind)) return [['polygon', { points: `${x + node.size.width * FLOW_SLANT},${y} ${x + node.size.width},${y} ${x + node.size.width * (1 - FLOW_SLANT)},${y + node.size.height} ${x},${y + node.size.height}` }]];
+  return rectangle(node, x, y, ['start', 'end'].includes(node.kind) ? node.size.height / 2 : 10);
+};
+const anchor = (node, side, offset) => {
+  if (node.kind === 'decision') return polygonAnchor(node, side, offset, [[.5, 0], [1, .5], [.5, 1], [0, .5]]);
+  if (['input', 'output'].includes(node.kind)) return polygonAnchor(node, side, offset, [[FLOW_SLANT, 0], [1, 0], [1 - FLOW_SLANT, 1], [0, 1]]);
+  if (['start', 'end'].includes(node.kind)) return roundedRectAnchor(node, side, offset, node.size.height / 2);
+  return rectAnchor(node, side, offset);
+};
+
+const textArea = node => {
+  const { width: w, height: h } = node.size;
+  const inset = ['input', 'output'].includes(node.kind) ? w * FLOW_SLANT + 12 : ['start', 'end'].includes(node.kind) ? Math.min(h / 2, w / 4) : 18;
+  return { width: node.kind === 'decision' ? w / 2 - 8 : w - inset * 2, height: node.kind === 'decision' ? h / 2 - 8 : h - 12 };
+};
+function flowNode(node, x, y, fill, stroke) {
+  const { width: w, height: h } = node.size, area = textArea(node);
+  const label = centeredTitle(x + w / 2, y + h / 2, node.label, area.width, area.height, node.subtitle);
+  const inner = node.kind === 'subprocess' ? `<path d="M ${x + 11} ${y}V ${y + h}M ${x + w - 11} ${y}V ${y + h}" stroke="${stroke}"/>` : '';
+  return `<g class="shape-label">${paint(outline(node, x, y), { fill, stroke, 'stroke-width': 1.2 })}${inner}${label}</g>`;
+}
+
+
+export default {
+  id: 'flowchart', label: 'Flowchart',
+  nodeKinds: ["start", "end", "process", "decision", "input", "output", "subprocess"],
+  groupKinds: [],
+  edgeKinds: ["flow", "yes", "no", "success", "failure"],
+  render: flowNode, outline, anchor, textArea,
+  edgeLabel: (edge, locale) => edge.label ?? (['yes', 'no'].includes(edge.kind) ? translate(locale, edge.kind) : ''),
+};

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

@@ -0,0 +1,28 @@
+import architecture from './architecture.js';
+import flowchart from './flowchart.js';
+import sequence from './sequence.js';
+import er from './er.js';
+import deployment from './deployment.js';
+import classDiagram from './class.js';
+import state from './state.js';
+import usecase from './usecase.js';
+import dataflow from './dataflow.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];
+export const DIAGRAM_TYPES = DIAGRAMS.map(diagram => diagram.id);
+export const diagramLabels = Object.fromEntries(DIAGRAMS.map(diagram => [diagram.id, diagram.label]));
+const byId = new Map(DIAGRAMS.map(diagram => [diagram.id, diagram]));
+if (byId.size !== DIAGRAMS.length) throw new Error('Duplicate diagram type');
+export const diagramTypeOf = graph => graph?.meta?.diagramType ?? 'architecture';
+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 };
+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));
+
+// Diagrams whose labels carry roles (a state transition's trigger, guard and effect) name the palette color of each role.
+export const labelRoleColors = (type, palette) => Object.fromEntries(Object.entries(getDiagram(type)?.labelRoleColors ?? {}).map(([role, key]) => [role, palette[key]]));
+
+export const edgeMarkers = (edge, type) => ({ start: null, end: hasArrow(edge, type) ? 'arrow' : null, ...getDiagram(type).markers?.[edge.kind] });

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

@@ -0,0 +1,38 @@
+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;
+
+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 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>`;
+}
+
+export default {
+  dashedKinds: ['return'],
+  markers: { async: { end: 'arrow-open' }, return: { end: 'arrow-open' } },
+  id: 'sequence', label: 'Sequence',
+  nodeKinds: ["actor", "participant", "external", "service", "database"],
+  groupKinds: ["alt", "opt", "loop", "par"],
+  edgeKinds: ["sync", "async", "return"],
+  render: sequenceNode, outline,
+  sequence: true,
+  selectionHeight: sequenceHeaderHeight,
+  edgeLabel: edge => `${String(edge.order).padStart(2, '0')} · ${edge.label ?? ''}`,
+  validateEdge(edge, label, errors, { requireString, sequenceOrders }) {
+    if (!Number.isInteger(edge?.order) || edge.order < 1) errors.push(`${label}.order must be a positive integer for sequence`);
+    else if (sequenceOrders.has(edge.order)) errors.push(`${label}.order duplicates ${edge.order}`);
+    else sequenceOrders.add(edge.order);
+    requireString(edge?.label, `${label}.label`, errors);
+  },
+};

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

@@ -0,0 +1,91 @@
+import { centeredTitle, rectangle, diamond, paint, ellipseAnchor, polygonAnchor, rectAnchor, text, layoutText, TYPOGRAPHY } from './drawing.js';
+
+export const stateSymbolX = node => node.subtitle ? 14 : node.size.width / 2;
+
+// UML state actions: a state may list what it does on entry, while it is active (do) and on exit, below a divider.
+export const STATE_ACTIONS = ['entry', 'do', 'exit'];
+const ACTION = { side: 16, pad: 8, line: 20, keyWidth: 64 };
+export function stateActivities(node) {
+  const rows = node.kind === 'state' ? STATE_ACTIONS.filter(key => typeof node[key] === 'string' && node[key].trim())
+    .map(key => ({ key, lines: layoutText(node[key], node.size.width - 2 * ACTION.side - ACTION.keyWidth, TYPOGRAPHY.small, ACTION.line).lines })) : [];
+  return { rows, height: rows.length ? rows.reduce((sum, row) => sum + row.lines.length, 0) * ACTION.line + 2 * ACTION.pad : 0 };
+}
+export const STATE_ACTION_INSET = 2 * ACTION.side + ACTION.keyWidth;
+// The action list sits in the bottom compartment; the title keeps the compartment above it.
+export const activityArea = node => {
+  const { height } = stateActivities(node);
+  return height ? { x: ACTION.side, y: node.size.height - height, width: node.size.width - 2 * ACTION.side, height } : null;
+};
+
+const outline = (node, x, y) => {
+  if (['initial', 'final'].includes(node.kind)) return [['circle', { cx: x + stateSymbolX(node), cy: y + node.size.height / 2, r: node.kind === 'initial' ? 12 : 13 }]];
+  return node.kind === 'choice' ? diamond(node, x, y) : rectangle(node, x, y, 12);
+};
+const anchor = (node, side, offset) => {
+  if (['initial', 'final'].includes(node.kind)) {
+    const radius = node.kind === 'initial' ? 12 : 13;
+    const shift = stateSymbolX(node) - node.size.width / 2;
+    const circle = { ...node, position: { ...node.position, x: node.position.x + shift } };
+    return ellipseAnchor(circle, side, offset - (['top', 'bottom'].includes(side) ? shift : 0), node.size.width / 2 - radius, node.size.height / 2 - radius);
+  }
+  return node.kind === 'choice' ? polygonAnchor(node, side, offset, [[.5, 0], [1, .5], [.5, 1], [0, .5]]) : rectAnchor(node, side, offset);
+};
+const textArea = node => {
+  if (['initial', 'final'].includes(node.kind) && node.subtitle) return { x: 42, y: 8, width: node.size.width - 50, height: node.size.height - 16 };
+  const actions = stateActivities(node).height;
+  const area = { width: node.kind === 'choice' ? node.size.width / 2 - 8 : node.size.width - 24, height: node.kind === 'choice' ? node.size.height / 2 - 8 : node.size.height - 16 - actions };
+  return actions ? { x: 12, y: 8, ...area } : area;
+};
+
+function activityMarkup(node, x, y, stroke, palette) {
+  const { rows, height } = stateActivities(node);
+  if (!rows.length) return '';
+  const top = y + node.size.height - height;
+  let index = 0;
+  return `<path d="M${x} ${top}H${x + node.size.width}" fill="none" stroke="${stroke}" stroke-opacity=".35"/>${rows.map(row => row.lines.map((line, i) => {
+    const baseline = top + ACTION.pad + index++ * ACTION.line + 15;
+    return (i ? '' : text(x + ACTION.side, baseline, `${row.key} /`, 'field-key'))
+      + text(x + ACTION.side + ACTION.keyWidth, baseline, line, 'entity-meta', ` style="fill:${palette.ink}"`);
+  }).join('')).join('')}`;
+}
+
+function stateNode(node, x, y, fill, stroke, palette) {
+  const cx = x + node.size.width / 2, cy = y + node.size.height / 2;
+  if (['initial', 'final'].includes(node.kind)) {
+    const area = textArea(node), final = node.kind === 'final';
+    return `<g class="state-dot">${paint(outline(node, x, y), { fill: final ? palette.surface : stroke, stroke, 'stroke-width': 1 })}${final ? `<circle cx="${x + stateSymbolX(node)}" cy="${cy}" r="8" fill="${stroke}"/>` : ''}</g>${node.subtitle ? centeredTitle(x + area.x + area.width / 2, cy, node.label, area.width, area.height, node.subtitle) : ''}`;
+  }
+  const area = textArea(node), titleY = y + (node.size.height - stateActivities(node).height) / 2;
+  return `<g class="shape-label">${paint(outline(node, x, y), { fill, stroke, 'stroke-width': 1.2 })}${centeredTitle(cx, titleY, node.label, area.width, area.height, node.subtitle)}${activityMarkup(node, x, y, stroke, palette)}</g>`;
+}
+
+// Trigger, [guard] and / effect are told apart by color; the label string is these parts joined by single spaces.
+const labelParts = edge => [
+  { text: edge.label, role: 'trigger' },
+  ...(edge.guard ? [{ text: `[${edge.guard}]`, role: 'guard' }] : []),
+  ...(edge.action ? [{ text: `/ ${edge.action}`, role: 'effect' }] : [])
+].filter(part => part.text);
+
+export default {
+  id: 'state', label: 'State diagram',
+  nodeKinds: ["initial", "state", "final", "choice"],
+  groupKinds: [],
+  edgeKinds: ["transition"],
+  render: stateNode, outline, anchor, textArea, activityArea,
+  curvedSelfLoops: true,
+  markers: { transition: { end: 'arrow-open' } },
+  edgeLabel: edge => labelParts(edge).map(part => part.text).join(' '),
+  edgeLabelParts: labelParts,
+  labelRoleColors: { trigger: 'ink', guard: 'guard' },
+  legend: { neutral: 'State', core: 'Core state', goal: 'Core state', ended: 'Ended state', failed: 'Failed state', flight: 'In-progress state: warm to cool as it advances', solid: 'Transition' },
+  validateNode(node, label, errors) {
+    for (const key of STATE_ACTIONS) {
+      if (node?.[key] === undefined) continue;
+      if (typeof node[key] !== 'string' || !node[key].trim()) errors.push(`${label}.${key} must be a non-empty string`);
+      else if (node.kind !== 'state') errors.push(`${label}.${key} is only supported on state nodes`);
+    }
+  },
+  validateEdge(edge, label, errors) {
+    for (const field of ['guard', 'action']) if (edge?.[field] !== undefined && typeof edge[field] !== 'string') errors.push(`${label}.${field} must be a string`);
+  },
+};