qgraphflow 0.0.6

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

@@ -0,0 +1,208 @@
+import { layoutText } from './text-layout.js';
+import { LAYOUT_TARGETS } from './layout-spacing.js';
+import { translate } from './i18n.js';
+import { text, escapeXml } from './diagrams/drawing.js';
+
+export const intersects = (a, b, gap = 0) => a.x < b.x + b.width + gap && a.x + a.width > b.x - gap && a.y < b.y + b.height + gap && a.y + a.height > b.y - gap;
+export const segmentBoxes = route => route.points.slice(1).map((end, i) => {
+  const start = route.points[i];
+  return { x: Math.min(start.x, end.x) - 6, y: Math.min(start.y, end.y) - 6, width: Math.abs(end.x - start.x) + 12, height: Math.abs(end.y - start.y) + 12 };
+});
+
+export const operandId = (operand, index) => operand?.id ?? String(index);
+export function operandScopes(graph) {
+  const groups = new Map((graph.groups ?? []).map(group => [group.id, group]));
+  const result = new Map();
+  const prefix = (group, seen = new Set()) => {
+    if (!group.parentId || seen.has(group.id)) return '';
+    seen.add(group.id);
+    const parent = groups.get(group.parentId);
+    return parent ? prefix(parent, seen) + `${encodeURIComponent(parent.id)}:${encodeURIComponent(group.parentOperandId)}/` : '';
+  };
+  for (const group of groups.values()) if (Array.isArray(group.operands)) for (const [i, operand] of group.operands.entries()) {
+    for (const id of Array.isArray(operand?.edgeIds) ? operand.edgeIds : []) result.set(id, prefix(group) + `${encodeURIComponent(group.id)}:${encodeURIComponent(operandId(operand, i))}`);
+  }
+  return result;
+}
+
+export function operandEdges(group, operand, index, groups, seen = new Set()) {
+  if (seen.has(group.id)) return [];
+  const next = new Set(seen).add(group.id);
+  const children = groups.filter(child => child.parentId === group.id && child.parentOperandId === operandId(operand, index));
+  return [...(operand.edgeIds ?? []), ...children.flatMap(child => (child.operands ?? []).flatMap((item, i) => operandEdges(child, item, i, groups, next)))];
+}
+
+export function validateOperands(graph) {
+  const errors = [], edges = new Map(graph.edges.map(edge => [edge.id, edge]));
+  const groups = graph.groups ?? [], used = new Map();
+  for (const group of groups) {
+    const prefix = `group ${group.id}.operands`;
+    if (graph.meta.diagramType !== 'sequence') {
+      if (group.operands !== undefined || group.parentOperandId !== undefined || group.loop !== undefined) errors.push(`${prefix} is only supported for sequence`);
+      continue;
+    }
+    if (group.parentId !== undefined || group.parentOperandId !== undefined) {
+      const parent = groups.find(item => item.id === group.parentId);
+      if (!parent || !Array.isArray(parent.operands) || !parent.operands.some((item, i) => operandId(item, i) === group.parentOperandId)) errors.push(`group ${group.id} unknown parent operand ${group.parentId}/${group.parentOperandId}`);
+    }
+    const seen = new Set([group.id]); let parent = groups.find(item => item.id === group.parentId);
+    while (parent) {
+      if (seen.has(parent.id)) { errors.push(`group ${group.id} parent cycle at ${parent.id}`); break; }
+      seen.add(parent.id); parent = groups.find(item => item.id === parent.parentId);
+    }
+    if (group.operands === undefined && group.kind !== 'par' && group.loop === undefined && group.parentId === undefined) continue;
+    const multiple = ['alt', 'par'].includes(group.kind);
+    if (!Array.isArray(group.operands) || (multiple ? group.operands.length < 2 : group.operands.length !== 1)) {
+      errors.push(`${prefix} needs ${multiple ? 'at least two branches' : 'exactly one branch'}`); continue;
+    }
+    if (group.kind === 'loop') {
+      if (!Number.isInteger(group.loop?.min) || group.loop.min < 0 || !(group.loop?.max === '*' || Number.isInteger(group.loop?.max) && group.loop.max >= group.loop.min)) errors.push(`group ${group.id}.loop needs a non-negative min and max >= min (or *)`);
+    } else if (group.loop !== undefined) errors.push(`group ${group.id}.loop is only supported for loop`);
+    const ids = new Set();
+    for (const [i, operand] of group.operands.entries()) {
+      const label = `${prefix}[${i}] (${String(operand?.id ?? i)})`;
+      if (!operand || typeof operand !== 'object' || Array.isArray(operand)) { errors.push(`${label} must be an object`); continue; }
+      if (operand.id !== undefined && (typeof operand.id !== 'string' || !operand.id.trim())) errors.push(`${label}.id must be a non-empty string`);
+      if (group.kind !== 'alt' && operand.id === undefined) errors.push(`${label}.id is required`);
+      const id = operandId(operand, i);
+      if (ids.has(id)) errors.push(`${label} duplicate operand id`);
+      ids.add(id);
+      const field = group.kind === 'par' ? 'label' : 'guard';
+      if (typeof operand[field] !== 'string' || !operand[field].trim()) errors.push(`${label}.${field} must be a non-empty string`);
+      if (group.kind === 'alt' && operand.guard?.trim?.() === 'else' && i !== group.operands.length - 1) errors.push(`${label} else must be last and unique`);
+      if (operand.body !== undefined && (typeof operand.body !== 'string' || !operand.body.trim())) errors.push(`${label}.body must be a non-empty string`);
+      const children = groups.filter(child => child.parentId === group.id && child.parentOperandId === id);
+      if (!Array.isArray(operand.edgeIds) || !operand.edgeIds.length && !operand.body?.trim?.() && !children.length) { errors.push(`${label}.edgeIds must be an array with messages, body or a child fragment`); continue; }
+      for (const edgeId of operand.edgeIds) {
+        if (typeof edgeId !== 'string' || !edges.has(edgeId)) errors.push(`${label} unknown edge ${String(edgeId)}`);
+        if (used.has(edgeId)) errors.push(`${label} duplicate edge ${edgeId}, already in ${used.get(edgeId)}`);
+        used.set(edgeId, `${group.id}/${id}`);
+      }
+      // Recursive ranges are checked after malformed operands have been rejected.
+    }
+  }
+  if (errors.length) return errors;
+  for (const group of groups) {
+    let previous = -Infinity;
+    for (const [i, operand] of (group.operands ?? []).entries()) {
+      const orders = operandEdges(group, operand, i, groups).map(id => edges.get(id)?.order).filter(Number.isFinite);
+      if (orders.length && Math.min(...orders) <= previous) errors.push(`group ${group.id}.operands order ranges must be ordered and non-interleaving`);
+      if (orders.length) previous = Math.max(...orders);
+    }
+  }
+  return errors;
+}
+
+export function fragmentDepth(group, groups) {
+  let depth = 0, parent = groups.find(item => item.id === group.parentId);
+  const seen = new Set([group.id]);
+  while (parent && !seen.has(parent.id)) { seen.add(parent.id); depth++; parent = groups.find(item => item.id === parent.parentId); }
+  return depth;
+}
+
+// Text masks inside a fragment borrow the innermost frame's surface, so they blend in both themes.
+export function fragmentSurfaceAt(box, groups = [], appearances) {
+  const cx = box.x + box.width / 2, cy = box.y + box.height / 2;
+  const inside = groups.filter(group => group.position && group.size && cx >= group.position.x && cx <= group.position.x + group.size.width && cy >= group.position.y && cy <= group.position.y + group.size.height);
+  const innermost = inside.sort((a, b) => fragmentDepth(b, groups) - fragmentDepth(a, groups))[0];
+  return innermost ? appearances?.get(innermost.id)?.fill : undefined;
+}
+
+export const fragmentHeadingLayout = group => layoutText(group.label, Math.min(LAYOUT_TARGETS.headingWidth, Math.max(1, (group.size?.width ?? Infinity) - 88)), 15.12, 22);
+
+function fragmentHeading(group, executions) {
+  const frame = { ...group.position, ...group.size };
+  const layout = fragmentHeadingLayout(group);
+  const size = { width: Math.min(layout.width + 16, frame.width - 88), height: Math.max(24, layout.height + 8), lines: layout.lines };
+  return [frame.x + 16, ...executions.map(item => item.x + item.width + 12)].map(x => ({ x, y: frame.y + 6, ...size })).find(box => box.x >= frame.x + 16 && box.x + box.width <= frame.x + frame.width - 64 && !executions.some(item => intersects(box, item, 4)));
+}
+
+// An alt without operands (older graphs) keeps its authored frame: one placeholder condition goes into free space beside
+// the messages the frame encloses, and a warning says the real conditions are missing.
+function legacyFragment(group, routes, locale, executions, heading) {
+  const frame = { ...group.position, ...group.size }, end = frame.y + frame.height;
+  const all = [...routes.entries()];
+  const inside = route => route.points.some(p => p.x >= frame.x && p.x <= frame.x + frame.width && p.y > frame.y && p.y < frame.y + frame.height);
+  const selected = all.filter(([, route]) => inside(route)).map(([, route]) => route);
+  const warnings = [`group ${group.id}: alt branch conditions are unspecified (operands missing)`];
+  const obstacles = [
+    ...(heading ? [heading] : []),
+    { x: frame.x + frame.width - 52, y: frame.y, width: 52, height: 36 },
+    ...all.flatMap(([, r]) => [r.labelBox, ...segmentBoxes(r)]), ...executions
+  ];
+  const layout = layoutText(translate(locale, 'Branch conditions unspecified'), Math.max(1, frame.width - 32), 14, 20);
+  const size = { width: layout.width + 8, height: layout.height + 4 };
+  const xs = [frame.x + 16, ...obstacles.map(box => box.x + box.width + 8), frame.x + frame.width - size.width - 16];
+  const top = Math.min(...selected.map(r => Math.min(r.labelBox.y, ...r.points.map(p => p.y))));
+  const ys = [frame.y + 6, top, ...selected.map(r => r.points[0].y - size.height - 6)];
+  const box = ys.flatMap(y => xs.map(x => ({ x, y, ...size }))).find(b => b.x >= frame.x + 8 && b.x + b.width <= frame.x + frame.width - 8 && b.y >= frame.y + 6 && b.y + b.height <= end - 6 && !obstacles.some(o => intersects(b, o, 2)));
+  if (!box) warnings.push(`layout: group ${group.id} has no room for guard 1; shorten the guard or adjust the frame/participant spacing`);
+  return { warnings, guards: [{ ...(box ?? { x: frame.x + 16, y: frame.y + 38, ...size }), lines: layout.lines, operandId: operandId(null, 0) }] };
+}
+
+export function sequenceFragment(group, routes, locale, groups = [], executions = []) {
+  const errors = [], warnings = [], guards = [], bodies = [], separators = [];
+  const frame = { ...group.position, ...group.size }, bottom = frame.y + frame.height;
+  // Frame relationships apply before either the operand-less or the operand layout can return.
+  const parent = groups.find(item => item.id === group.parentId);
+  if (parent && !(frame.x >= parent.position.x + 8 && frame.x + frame.width <= parent.position.x + parent.size.width - 8 && frame.y >= parent.position.y + 36 && bottom <= parent.position.y + parent.size.height - 8)) errors.push(`layout: group ${group.id} exceeds parent ${parent.id}`);
+  const ancestors = new Set(); let ancestor = parent;
+  while (ancestor && !ancestors.has(ancestor.id)) { ancestors.add(ancestor.id); ancestor = groups.find(item => item.id === ancestor.parentId); }
+  for (const other of groups) if (other.id !== group.id && !ancestors.has(other.id)) {
+    let item = other; const seen = new Set();
+    while (item?.parentId && !seen.has(item.id)) { seen.add(item.id); if (item.parentId === group.id) break; item = groups.find(g => g.id === item.parentId); }
+    if (item?.parentId === group.id) continue;
+    if (intersects(frame, { ...other.position, ...other.size })) errors.push(`layout: groups ${group.id} and ${other.id} cross without nesting`);
+  }
+  if (group.kind !== 'alt' && !group.operands) return { errors, warnings, guards, bodies, separators };
+  const heading = fragmentHeading(group, executions);
+  if (!heading) errors.push(`layout: group ${group.id} has no room for heading; adjust its frame`);
+  const children = groups.filter(child => child.parentId === group.id);
+  if (group.kind === 'alt' && group.operands === undefined && !group.parentId && !children.length) {
+    const fragment = legacyFragment(group, routes, locale, executions, heading);
+    return { errors, warnings: fragment.warnings, guards: fragment.guards, separators: [], heading };
+  }
+  if (!group.operands) return { errors, warnings, guards, bodies, separators };
+  const headingBottom = Math.max(frame.y + 36, heading ? heading.y + heading.height + 6 : 0);
+  const sections = group.operands.map((operand, i) => {
+    const childFrames = children.filter(child => child.parentOperandId === operandId(operand, i)).map(child => ({ ...child.position, ...child.size, id: child.id }));
+    const selected = operandEdges(group, operand, i, groups).map(id => routes.get(id)).filter(Boolean);
+    const boxes = [...childFrames, ...selected.flatMap(route => [route.labelBox, ...segmentBoxes(route)])];
+    return { operand, selected, childFrames, boxes, top: Math.min(...boxes.map(box => box.y)), bottom: Math.max(...boxes.map(box => box.y + box.height)) };
+  });
+  for (let i = 1; i < sections.length; i++) {
+    const previous = sections[i - 1], next = sections[i];
+    separators.push(Number.isFinite(previous.bottom) && Number.isFinite(next.top) ? (previous.bottom + next.top) / 2 : headingBottom + (bottom - headingBottom) * i / sections.length);
+  }
+  const members = new Set(group.operands.flatMap((operand, i) => operandEdges(group, operand, i, groups)));
+  for (const [id, route] of routes) if (route.points.some(p => p.x >= frame.x && p.x <= frame.x + frame.width && p.y > frame.y && p.y < bottom) && !members.has(id)) errors.push(`layout: group ${group.id} omits enclosed message ${id}`);
+  const allObstacles = [...routes.values()].flatMap(route => [route.labelBox, ...segmentBoxes(route)]);
+  allObstacles.push(...executions);
+  sections.forEach(({ operand, selected, childFrames, top }, i) => {
+    const begin = i ? separators[i - 1] : headingBottom, end = separators[i] ?? bottom;
+    for (const box of [...childFrames, ...selected.flatMap(route => [route.labelBox, ...segmentBoxes(route)])]) {
+      if (box.x < frame.x + 4 || box.x + box.width > frame.x + frame.width - 4 || box.y < begin + 2 || box.y + box.height > end - 2) errors.push(`layout: group ${group.id} cannot contain operand ${operandId(operand, i)}${box.id ? ` child ${box.id}` : ''}; enlarge or reposition its frame`);
+    }
+    const label = group.kind === 'par' ? operand.label : `${group.kind === 'loop' ? `${group.loop.min}..${group.loop.max} ` : ''}[${operand.guard}]`;
+    const obstacles = [...allObstacles, ...childFrames, ...guards, ...bodies];
+    const place = (value, kind, after) => {
+      const fontSize = kind === 'body' ? 16 : 14, lineHeight = kind === 'body' ? 24 : 20;
+      const layout = layoutText(value, Math.min(LAYOUT_TARGETS.labelWidth, Math.max(1, frame.width - 40)), fontSize, lineHeight);
+      const size = { width: layout.width + 8, height: layout.height + 4 };
+      const xs = [frame.x + 16, ...obstacles.map(box => box.x + box.width + 8), frame.x + frame.width - size.width - 16];
+      const ys = [after, ...obstacles.map(box => box.y + box.height + 8), top - size.height - 8].filter(Number.isFinite).sort((a, b) => a - b);
+      const box = ys.flatMap(y => xs.map(x => ({ x, y, ...size }))).find(box => box.x >= frame.x + 8 && box.x + box.width <= frame.x + frame.width - 8 && box.y >= after && box.y + box.height <= end - 6 && !obstacles.some(obstacle => intersects(box, obstacle, 2)));
+      if (!box) errors.push(`layout: group ${group.id} has no room for ${kind} ${operandId(operand, i)}; adjust frame/message spacing`);
+      else { box.lines = layout.lines; box.fontSize = fontSize; box.lineHeight = lineHeight; box.operandId = operandId(operand, i); obstacles.push(box); (kind === 'guard' ? guards : bodies).push(box); }
+      return box;
+    };
+    const guard = place(label, 'guard', begin + 6);
+    if (operand.body) place(operand.body, 'body', guard ? guard.y + guard.height + 8 : begin + 38);
+  });
+  return { errors, warnings, guards, bodies, separators, heading };
+}
+
+export function renderFragment(fragment, group, offsetX = 0, offsetY = 0, stroke = 'currentColor', background = 'var(--canvas)') {
+  return fragment.separators.map(y => `<path class="operand-separator" d="M${group.position.x + offsetX} ${y + offsetY}h${group.size.width}" fill="none" stroke="${stroke}" stroke-dasharray="6 4"/>`).join('')
+    + [...fragment.guards, ...(fragment.bodies ?? [])].map(box => `<g data-fragment-group-id="${escapeXml(group.id)}" data-operand-id="${escapeXml(box.operandId)}" class="${fragment.guards.includes(box) ? 'operand-guard' : 'operand-body'}"><rect x="${box.x + offsetX}" y="${box.y + offsetY}" width="${box.width}" height="${box.height}" rx="2" fill="${background}"/>${box.lines.map((line, i) => text(box.x + offsetX + 4, box.y + offsetY + (box.fontSize === 16 ? 18 : 16) + i * (box.lineHeight ?? 20), line, box.fontSize === 16 ? 'body' : 'group')).join('')}</g>`).join('');
+}

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

@@ -0,0 +1,43 @@
+import { diagramTypeOf } from './diagrams/registry.js';
+
+// The generator embeds the graph as escaped JSON inside this script element; saving from the page rewrites the same
+// element, so the saved page reopens with its edits and the generator and the page never disagree about the encoding.
+const DATA_ELEMENT = /(<script\b[^>]*\bid="graph-data"[^>]*>)([\s\S]*?)(<\/script>)/;
+export const safeJson = graph => JSON.stringify(graph).replaceAll('&', '\\u0026').replaceAll('<', '\\u003c').replaceAll('>', '\\u003e').replaceAll('\u2028', '\\u2028').replaceAll('\u2029', '\\u2029');
+
+export function pageWithGraph(html, graph) {
+  if (!DATA_ELEMENT.test(html)) throw new Error('page has no graph-data element');
+  return html.replace(DATA_ELEMENT, (match, open, data, close) => `${open}${safeJson(graph)}${close}`);
+}
+
+export function graphInputWithEdits(input, drafts, currentGraph) {
+  const edited = graph => diagramTypeOf(graph) === diagramTypeOf(currentGraph) ? currentGraph : drafts.get(diagramTypeOf(graph)) ?? graph;
+  return Array.isArray(input.diagrams) ? { ...input, diagrams: input.diagrams.map(edited) } : currentGraph;
+}
+
+export function currentGraphFromFlow(graph, nodes, edges) {
+  const nodeState = new Map(nodes.filter(node => node.type === 'diagram').map(node => [node.id, node]));
+  const edgeState = new Map(edges.map(edge => [edge.id, edge]));
+  return {
+    ...graph,
+    nodes: graph.nodes.map(node => {
+      const current = nodeState.get(node.id);
+      if (!current) return node;
+      const text = { label: current.data.label };
+      if (Object.hasOwn(current.data, 'subtitle')) text.subtitle = current.data.subtitle;
+      return { ...node, ...text, position: current.position };
+    }),
+    edges: graph.edges.map(edge => {
+      const current = edgeState.get(edge.id);
+      return current && Object.hasOwn(current.data, 'label') ? { ...edge, label: current.data.label } : edge;
+    })
+  };
+}
+
+export function constrainNodeChanges(changes, nodes, diagramType) {
+  if (diagramType !== 'sequence') return changes;
+  const positions = new Map(nodes.map(node => [node.id, node.position]));
+  return changes.map(change => change.type === 'position' && change.position && positions.has(change.id)
+    ? { ...change, position: { ...change.position, y: positions.get(change.id).y } }
+    : change);
+}

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

@@ -0,0 +1,126 @@
+import { TYPOGRAPHY } from './visual-style.js';
+import { LAYOUT_LIMITS, LAYOUT_TARGETS } from './layout-spacing.js';
+
+// Conservative system-font widths keep server-rendered SVG and browser labels in the same bounds.
+const textWidth = (value, fontSize) => [...value].reduce((width, character) => width + fontSize * (/[^\u0000-\u00ff]|[MWmw@%&]/.test(character) ? 1 : /[A-Z]/.test(character) ? .8 : 6.8 / 12), 0);
+
+// A token (text between spaces) that fits on a line is never cut, so text without over-long tokens wraps exactly as it
+// always did. A token longer than the line is cut where it reads best instead of at the first character that overflows:
+// between CJK characters, then at an identifier's own separators (`_ . / - = ,` and camelCase humps), and only then
+// anywhere. Closing punctuation never starts a line and opening punctuation never ends one; the neighbour travels along.
+const CJK_CHARACTER = '\\p{Script=Han}\\p{Script=Hiragana}\\p{Script=Katakana}\\u3000-\\u303f\\uff00-\\uffef';
+const CJK = new RegExp(`[${CJK_CHARACTER}]`, 'u');
+const PIECES = new RegExp(`[${CJK_CHARACTER}]|[^${CJK_CHARACTER}]+`, 'gu');
+const SEPARATORS = /(?<=[_./\\\-=,;:|&)>\]}])|(?<=[a-z0-9])(?=[A-Z])/u;
+const NO_LINE_START = new Set([...'，。、．；：！？）］｝〕】》〉」』”’…']);
+const NO_LINE_END = new Set([...'（［｛〔【《〈「『“‘']);
+const canBreak = (before, after) => !NO_LINE_END.has([...before].at(-1)) && !NO_LINE_START.has([...after][0]);
+
+function cutPieces(token, fontSize, limit) {
+  const pieces = [];
+  for (const run of token.match(PIECES)) {
+    if (CJK.test(run) || textWidth(run, fontSize) <= limit) pieces.push(run);
+    else for (const part of run.split(SEPARATORS)) pieces.push(...(textWidth(part, fontSize) <= limit ? [part] : part));
+  }
+  return pieces;
+}
+
+export function layoutText(value, maxWidth, fontSize = TYPOGRAPHY.body, lineHeight = fontSize * 1.5) {
+  const content = String(value ?? '');
+  if (!content) return { lines: [], width: 0, height: 0, lineHeight };
+  const limit = Math.max(1, maxWidth);
+  const lines = [];
+  for (const paragraph of content.split(/\r?\n/)) {
+    let line = '';
+    let width = 0;
+    let cuts = []; // offsets in `line` where a token or piece starts: the places a kinsoku carry may cut
+    const wrap = () => {
+      lines.push(line);
+      line = '';
+      width = 0;
+      cuts = [];
+    };
+    for (const token of paragraph.match(/\s+|\S+/g) ?? []) {
+      const tokenWidth = textWidth(token, fontSize);
+      if (line && tokenWidth <= limit && width + tokenWidth > limit) wrap();
+      cuts.push(line.length);
+      if (tokenWidth <= limit || /^\s/.test(token)) {
+        for (const character of token) {
+          const characterWidth = textWidth(character, fontSize);
+          if (line && width + characterWidth > limit) wrap();
+          line += character;
+          width += characterWidth;
+        }
+        continue;
+      }
+      for (const piece of cutPieces(token, fontSize, limit)) {
+        const pieceWidth = textWidth(piece, fontSize);
+        if (line && width + pieceWidth > limit) {
+          if (canBreak(line, piece)) wrap();
+          else {
+            let k = cuts.length - 1;
+            while (k >= 0 && !(cuts[k] > 0 && canBreak(line.slice(0, cuts[k]), line.slice(cuts[k])))) k--;
+            if (k >= 0) {
+              const offset = cuts[k];
+              lines.push(line.slice(0, offset));
+              line = line.slice(offset);
+              width = textWidth(line, fontSize);
+              cuts = cuts.slice(k).map(cut => cut - offset);
+            }
+          }
+        }
+        cuts.push(line.length);
+        line += piece;
+        width += pieceWidth;
+      }
+    }
+    lines.push(line);
+  }
+  return { lines, width: Math.ceil(Math.max(...lines.map(line => textWidth(line, fontSize)))), height: lines.length * lineHeight, lineHeight };
+}
+
+export function cardTextLayout(node) {
+  const width = node.size.width - 30;
+  const title = layoutText(node.label, width, TYPOGRAPHY.title, 26);
+  const subtitle = layoutText(node.subtitle ?? '', width, TYPOGRAPHY.body, 24);
+  return { title, subtitle, minHeight: 65 + title.height + subtitle.height };
+}
+
+export function edgeLabelLayout(value, maxWidth = LAYOUT_TARGETS.labelWidth) {
+  const layout = layoutText(value, maxWidth);
+  return { ...layout, width: layout.lines.length ? Math.max(24, layout.width + 12) : 0, height: layout.lines.length ? layout.height + 6 : 0 };
+}
+
+// Each character of the joined label keeps the role of its part (the space between two parts keeps the role it follows);
+// the wrapped lines are cut along those roles. Paragraph breaks inside a part are not drawn, so they are skipped between
+// lines. Null when the lines do not spell the label.
+export function labelRunsByLine(lines, parts) {
+  const label = parts.map(part => part.text).join(' ');
+  const roles = parts.flatMap((part, index) => [...(index ? [parts[index - 1].role] : []), ...Array.from({ length: part.text.length }, () => part.role)]);
+  let offset = 0;
+  const runsByLine = lines.map(line => {
+    while (label[offset] === '\r' || label[offset] === '\n') offset++;
+    if (!label.startsWith(line, offset)) return null;
+    const runs = [];
+    for (let i = 0; i < line.length; i++) {
+      const role = roles[offset + i];
+      if (runs.at(-1)?.role === role) runs.at(-1).text += line[i]; else runs.push({ text: line[i], role });
+    }
+    offset += line.length;
+    return runs;
+  });
+  while (label[offset] === '\r' || label[offset] === '\n') offset++;
+  return offset === label.length && runsByLine.every(Boolean) ? runsByLine : null;
+}
+
+export function estimateLabelSize(value, maxWidth) {
+  const { width, height } = edgeLabelLayout(value, maxWidth);
+  return { width, height };
+}
+
+export function groupHeadingLayout(group) {
+  const width = Math.min(LAYOUT_TARGETS.headingWidth, Math.max(1, (group.size?.width ?? Infinity) - 2 * LAYOUT_LIMITS.groupInset));
+  // Reserve the same letter spacing as the SVG group heading, plus a font margin.
+  const layout = layoutText(group.label, width, TYPOGRAPHY.small + 1.12, 22);
+  return { ...layout, height: 12 + layout.height };
+}

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

@@ -0,0 +1,158 @@
+import { IDENTITY, IDENTITY_SCALES, RADIX } from './radix-colors.js';
+
+// Mix a color over a background: identity washes and headers stay tied to their chip color.
+export function mix(color, background, amount) {
+  const channel = index => Math.round(parseInt(color.slice(index, index + 2), 16) * amount + parseInt(background.slice(index, index + 2), 16) * (1 - amount)).toString(16).padStart(2, '0');
+  return `#${channel(1)}${channel(3)}${channel(5)}`;
+}
+
+// In-flight states of a state diagram walk this ramp, warm to cool, in the order the machine reaches them.
+const FLIGHT_SCALES = ['orange', 'blue', 'teal', 'violet', 'plum', 'indigo'];
+
+// Structure stays cool and neutral (Slate); identity is a saturated chip, a matching frame and a faint wash;
+// roles speak through a soft ring (core, failure) and the icon glyph, never through the text.
+export const PALETTES = Object.fromEntries(Object.entries(RADIX).map(([theme, { neutral: n, accent: t, data: b, warn: a, guard: g }]) => [theme, {
+  paper: n[1], surface: n[1], surface2: n[2],
+  ink: n[12], ink2: n[11], ink3: n[11], rule: n[6], ruleSoft: n[4],
+  accent: t[11], accentSoft: t[2], ringCore: t[5],
+  data: b[11], warn: a[11], ringWarn: a[5], guard: g[11],
+  badge: n[3], outline: theme === 'dark' ? n[10] : n[9],
+  // Dark cards lift one step above the canvas so a plain card still reads as a surface.
+  card: theme === 'dark' ? n[3] : n[1],
+  groupFill: n[2], groupFillNested: theme === 'dark' ? mix(n[2], n[3], .5) : n[1], groupLine: n[5],
+  moduleTones: IDENTITY_SCALES.map(name => { const scale = IDENTITY[theme][name]; return { name, chip: scale[9], accent: scale[10], wash: mix(scale[9], theme === 'dark' ? n[3] : n[1], theme === 'dark' ? .09 : .05), header: mix(scale[9], n[2], theme === 'dark' ? .16 : .1) }; }),
+  // Lifecycle tones of a state card: the goal is green, an ended state Slate, a failed one Red, and in-flight states take
+  // the ramp above. The body is step 3; the frame is step 11 on light cards and step 10 on dark ones, the first steps
+  // that hold 3:1 against that body in each theme.
+  stateTones: (() => {
+    const step = theme === 'dark' ? 10 : 11, scales = IDENTITY[theme], identity = name => ({ name, fill: scales[name][3], stroke: scales[name][step] });
+    return { goal: identity('grass'), ended: { name: 'slate', fill: n[3], stroke: n[step] }, failed: { name: 'red', fill: a[3], stroke: a[step] }, flight: FLIGHT_SCALES.map(identity) };
+  })(),
+  edge: theme === 'dark' ? n[10] : n[9],
+  mask: theme === 'dark' ? 'rgba(17,17,19,.75)' : 'rgba(252,252,253,.75)',
+  group: n[2]
+}]));
+
+export const warningKinds = new Set(['failure']);
+export const dataKinds = new Set(['data', 'database', 'dataStore', 'entity']);
+export const TYPOGRAPHY = { title: 20, body: 16, small: 14, edgeLineHeight: 24, sequenceHeader: 72, sequenceActorHeader: 108, erHeader: 72, erRow: 32, classHeader: 68, classRow: 28 };
+export const isCore = node => node.kind === 'business' || (node.tags ?? []).some(tag => ['core', 'business'].includes(String(tag).trim().toLowerCase()));
+
+// FNV-1a over the module name, bounded to the identity palette.
+function colorSlot(value, count) {
+  let hash = 2166136261;
+  for (const character of value) hash = Math.imul(hash ^ character.codePointAt(0), 16777619);
+  return (hash >>> 0) % count;
+}
+
+const hasTag = (node, name) => (node.tags ?? []).some(tag => String(tag).trim().toLowerCase() === name);
+
+// A state diagram describes one component, so its module says nothing there: its states are colored by lifecycle role
+// instead. The core state is the goal, a `failure`-tagged state is failed, a state with nowhere left to go (every way
+// out ends the machine, or there is none) is ended, and the states in between are in flight and take the warm-to-cool
+// ramp in the order the machine reaches them (distance from the initial state, then declaration order). Roles are
+// derived from facts the graph already has; there is no color field. Without a core state the module colors stay.
+export function stateToneRoles(graph) {
+  const states = graph.nodes.filter(node => node.kind === 'state');
+  if (graph.meta?.diagramType !== 'state' || !states.some(isCore)) return new Map();
+  const next = new Map(graph.nodes.map(node => [node.id, []]));
+  for (const edge of graph.edges) if (edge.kind === 'transition' && edge.source !== edge.target) next.get(edge.source)?.push(edge.target);
+  const ending = new Set(graph.nodes.filter(node => node.kind === 'final').map(node => node.id));
+  const distance = new Map(graph.nodes.filter(node => node.kind === 'initial').map(node => [node.id, 0]));
+  for (const id of distance.keys()) for (const target of next.get(id) ?? []) if (!distance.has(target)) distance.set(target, distance.get(id) + 1);
+  const role = node => hasTag(node, 'failure') ? 'failed' : isCore(node) ? 'goal' : next.get(node.id).every(id => ending.has(id)) ? 'ended' : 'flight';
+  const reach = node => distance.get(node.id) ?? Infinity;
+  const flight = states.filter(node => role(node) === 'flight').sort((a, b) => Math.sign(reach(a) - reach(b)) || 0);
+  return new Map(states.map(node => [node.id, role(node) === 'flight' ? { role: 'flight', index: flight.indexOf(node) } : { role: role(node) }]));
+}
+
+// The map also carries `stateTones` (state node id -> role): a collection has one state view, so the id is enough for
+// every nodeAppearance caller, none of which knows its graph.
+export function moduleColorMap(diagrams, palette) {
+  const modules = [...new Set(diagrams.flatMap(graph => [
+    ...graph.nodes.map(node => node.module), ...graph.edges.map(edge => edge.module)
+  ]).filter(Boolean))].sort();
+  // ponytail: bounded categorical slots can collide; module labels remain authoritative.
+  const colors = new Map(modules.map(module => [module, palette.moduleTones[colorSlot(module, palette.moduleTones.length)]]));
+  colors.stateTones = new Map(diagrams.flatMap(graph => [...stateToneRoles(graph)]));
+  return colors;
+}
+
+// A copy keeps what the map carries besides the module tones; a download snapshots the colors this way.
+export function copyColors(colors) {
+  const copy = new Map(colors);
+  copy.stateTones = colors.stateTones;
+  copy.plainStates = colors.plainStates;
+  return copy;
+}
+
+// The card-wash switch: module washes and state tones fall back to the plain card, frames and chips stay.
+export function withoutWash(colors, palette) {
+  for (const [name, tone] of colors) colors.set(name, { ...tone, wash: palette.card, header: palette.surface2 });
+  colors.plainStates = true;
+  return colors;
+}
+
+// Boundaries are containers, not information: a hairline fence on a barely-there surface, nested one step apart.
+export function groupAppearanceMap(groups, palette) {
+  const appearances = new Map();
+  const depth = group => { let level = 0, parent = groups.find(item => item.id === group.parentId); while (parent && level < groups.length) { level++; parent = groups.find(item => item.id === parent.parentId); } return level; };
+  for (const group of groups) appearances.set(group.id, { fill: depth(group) % 2 ? palette.groupFillNested : palette.groupFill, stroke: palette.groupLine });
+  return appearances;
+}
+
+const STATE_TONE_LABELS = { goal: 'Core state', ended: 'Ended state', failed: 'Failed state', flight: 'In-progress state' };
+
+// The frame, chip and wash say whose a node is (module); a ring says it is the business center or an explicit failure.
+// Text never follows either: titles stay ink. A failure keeps its red frame over any module. A state in a state
+// diagram wears its lifecycle tone instead of the module's frame and wash; the ring and the module's lines stay.
+export function nodeAppearance(node, palette, moduleColors) {
+  const tone = moduleColors?.get(node.module);
+  const stateRole = node.kind === 'state' ? moduleColors?.stateTones?.get(node.id) : undefined;
+  if (stateRole) {
+    const lifecycle = stateRole.role === 'flight' ? palette.stateTones.flight[stateRole.index % palette.stateTones.flight.length] : palette.stateTones[stateRole.role];
+    return { role: stateRole.role, label: STATE_TONE_LABELS[stateRole.role], fill: moduleColors.plainStates ? palette.card : lifecycle.fill, stroke: lifecycle.stroke, ring: isCore(node) ? palette.ringCore : undefined, toneIndex: stateRole.index, moduleColor: tone?.accent, chip: tone?.chip, header: tone?.header };
+  }
+  let appearance;
+  if (['initial', 'final'].includes(node.kind)) appearance = { role: node.kind, label: node.kind === 'initial' ? 'Initial state' : 'Final state', fill: node.kind === 'initial' ? palette.ink : palette.surface, stroke: palette.ink };
+  else if (warningKinds.has(node.kind)) appearance = { role: 'warning', label: 'Failure', fill: palette.card, stroke: palette.warn, ring: palette.ringWarn };
+  else if (isCore(node)) appearance = { role: 'core', label: 'Core component', fill: palette.card, stroke: palette.accent, ring: palette.ringCore };
+  else if (dataKinds.has(node.kind) || ['input', 'output'].includes(node.kind)) appearance = { role: 'data', label: 'Data / storage', fill: palette.card, stroke: palette.data };
+  else if (['start', 'end', 'usecase'].includes(node.kind)) appearance = { role: 'accent', label: node.kind === 'usecase' ? 'Use case' : 'Start / end', fill: palette.card, stroke: palette.accent };
+  else appearance = { role: 'neutral', label: 'Components / actors', fill: palette.card, stroke: palette.outline };
+  const framed = tone && !['initial', 'final', 'failure'].includes(node.kind);
+  return { ...appearance, fill: framed ? tone.wash : appearance.fill, stroke: framed ? tone.accent : appearance.stroke, moduleColor: tone?.accent, chip: tone?.chip, header: tone?.header };
+}
+
+// Pairs walk the identity scales in order; the order itself keeps neighbouring pair numbers far apart in hue.
+export const sequenceGroupColor = (pair, palette) => pair ? palette.moduleTones[pair.index % palette.moduleTones.length].accent : undefined;
+
+export function edgeColor(edge, target, palette, moduleColors, source, pair) {
+  if (pair) return sequenceGroupColor(pair, palette);
+  if (edge.kind === 'failure') return palette.warn;
+  if (edge.kind === 'success') return palette.accent;
+  const tone = moduleColors?.get(edge.module ?? source?.module ?? target?.module);
+  if (tone) return tone.accent;
+  return dataKinds.has(target?.kind) ? palette.data : palette.edge;
+}
+
+export function themeVariables(palette) {
+  const tokens = { bg: 'paper', panel: 'surface2', canvas: 'surface', ink: 'ink', muted: 'ink2', line: 'rule', accent: 'accent', 'accent-soft': 'accentSoft', warm: 'warn', guard: 'guard' };
+  const sizes = { 'font-body': 'body', 'font-small': 'small', 'edge-line-height': 'edgeLineHeight' };
+  return Object.fromEntries([...Object.entries(tokens).map(([name, key]) => [`--${name}`, palette[key]]), ...Object.entries(sizes).map(([name, key]) => [`--${name}`, `${TYPOGRAPHY[key]}px`])]);
+}
+
+export const kindLabels = {
+  external: 'External', config: 'Configuration', framework: 'Framework', security: 'Security', service: 'Service', business: 'Business',
+  data: 'Data', failure: 'Failure', system: 'System', component: 'Component', database: 'Database', start: 'Start', end: 'End',
+  process: 'Process', decision: 'Decision', input: 'Input', output: 'Output', subprocess: 'Subprocess', actor: 'Actor',
+  participant: 'Participant', entity: 'Entity', device: 'Device', node: 'Nodes', container: 'Container', artifact: 'Artifact',
+  class: 'Class', interface: 'Interface', abstract: 'Abstract class', state: 'State', initial: 'Initial', final: 'End', choice: 'Choice',
+  usecase: 'Use case', dataStore: 'Data store'
+};
+
+export function nodeMetrics(node) {
+  const erHeaderHeight = Math.min(TYPOGRAPHY.erHeader, node.size.height * .4);
+  const erRowHeight = Math.min(TYPOGRAPHY.erRow, (node.size.height - erHeaderHeight) / Math.max(1, node.fields?.length ?? 0));
+  return { erHeaderHeight, erRowHeight, erFontSize: Math.max(TYPOGRAPHY.small, Math.min(TYPOGRAPHY.body, erRowHeight - 6)), classHeaderHeight: TYPOGRAPHY.classHeader + (node.subtitle ? 24 : 0), classRowHeight: TYPOGRAPHY.classRow };
+}