@stacksjs/defaults 0.74.40 → 0.74.42

package/ai/skills/stacks-technical-diagrams/renderers/dataflow/README.md

@@ -4,7 +4,7 @@ Render `diagram_type: "dataflow"` JSON files into the standalone technical diagr
 template.
 
 ```bash
-bun --config=.claude/skills/stacks-technical-diagrams/bunfig.toml --no-env-file .claude/skills/stacks-technical-diagrams/renderers/dataflow/render-dataflow.mjs input.dataflow.json output.html
+node .claude/skills/stacks-technical-diagrams/renderers/dataflow/render-dataflow.mjs input.dataflow.json output.html
 ```
 
 The renderer validates input against `.claude/skills/stacks-technical-diagrams/schemas/dataflow.schema.json`
@@ -23,7 +23,6 @@ Data-flow JSON files must set:
   "diagram_type": "dataflow",
   "meta": {
     "title": "Product Analytics Data Flow",
-    "subtitle": "Events, consent, PII isolation, warehouse sync, and consumers",
     "viewBox": [940, 720]
   },
   "stages": [],
@@ -42,6 +41,18 @@ The schema lives at:
 .claude/skills/stacks-technical-diagrams/schemas/dataflow.schema.json
 ```
 
+## Legend
+
+The default visual legend derives kinds from `flows[].variant` (omitting
+`variant` means `default`) and adds `database` only when a database node exists.
+Supported `meta.legend.entries` keys, in stable order, are `emphasis`,
+`security`, `dashed`, `database`, and `default`. Flow variants remain
+visual-only because the renderer has no compiled edge-kind facts in this slice. A
+present `database` entry is different: it comes from exact
+`nodes[].type: "database"` facts, so it publishes the normal Semantic Legend
+count, accessible name, and keyboard interaction. Forcing `database` visible
+without a database node keeps it visual-only.
+
 ## Layout budget
 
 | Constant | Value |
@@ -78,5 +89,16 @@ element's id or label. The renderer additionally fails when it can detect
 layout problems, including missing stages, duplicate node IDs, nodes outside
 the readable diagram area, node overlap, labels colliding with nodes or other
 labels, labels wider than their node, unknown flow endpoints, missing flow
-labels, unreadably short flows, or stages that exceed the viewBox. Text width
+labels, unreadably short flows, flows crossing unrelated nodes (2px Clean Flow
+clearance), or stages that exceed the viewBox. Stage frames remain intentional
+pass-through containers. Text width
 is estimated CJK-aware: fullwidth glyphs count as two units.
+
+Set `meta.quality_profile` to `showcase` for polished delivery. Unrelated proper
+X crossings then fail with `composition/proper-crossing`; default `standard`
+keeps them as artifact-receipt warnings. Collinear stage corridors are outside
+the proper-X rule, but a separate gate warns in `standard` and fails in
+`showcase` when unrelated flows overlap for at least 8px. Shared semantic
+endpoints, point touches, and shorter overlaps remain valid. Showcase also
+rejects any route segment below 8px and any interior turn segment below 16px;
+ordinary 8-15px endpoint stubs remain valid.

package/ai/skills/stacks-technical-diagrams/renderers/dataflow/render-dataflow.mjs

@@ -1,18 +1,32 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { esc, renderDefinitions, textUnits } from '../shared/utils.mjs';
-import { animateAttr, loadDiagram, writeDiagram, svgRootAttrs } from '../shared/cli.mjs';
+import { esc, renderDefinitions, renderSemanticSigil, textUnits } from '../shared/utils.mjs';
+import { animateAttr, focusEdgeAttrs, focusNodeAttrs, focusNodeTitle, loadDiagramWithBrandMarks, writeDiagram, svgAccessibleText, svgRootAttrs } from '../shared/cli.mjs';
+import { throwDiagnosticProblems } from '../shared/diagnostics.mjs';
+import { resolveLegend, renderLegend as renderResolvedLegend } from '../shared/legend.mjs';
+import { availableNodeTextWidth, fittedNodeFontSize, minimumNodeTextWidth } from '../shared/text-fit.mjs';
+import { brandLabelFitWidth, brandMetadataFor, brandTopRailProblem, renderBrandMark } from '../shared/brand-marks.mjs';
+import { translateMessage as i18nText } from '../shared/i18n.mjs';
 import {
   asArray,
   isFinitePoint,
   rectsOverlap,
+  cleanEndpointSideProblems,
+  cleanFlowProblems,
+  cleanCrossingProblems,
+  cleanAmbiguousCorridorProblems,
+  cleanBorderRunProblems,
+  cleanRouteRhythmProblems,
+  cleanLabelRouteClearanceProblems,
   suggestLabelObstacleFix,
   suggestLabelPairFix,
   anchor,
+  automaticPortSpread,
   defaultFromSide,
   defaultToSide,
   chosenSide,
   polylinePath,
+  routePointsValue,
   labelPoint,
   componentFill,
   componentText,
@@ -20,8 +34,15 @@ import {
   variantAccent
 } from '../shared/geometry.mjs';
 
+const nodeTextFit = {
+  sublabelPreferred: 7,
+  sublabelMinimum: 6,
+  tagPreferred: 7,
+  tagMinimum: 6,
+};
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const { diagram: dataflow, template, outPath } = loadDiagram({
+const { diagram: dataflow, template, outPath } = await loadDiagramWithBrandMarks({
   rendererDir: __dirname,
   diagramType: 'dataflow',
   defaultExample: 'product-analytics.dataflow.json'
@@ -41,10 +62,33 @@ const layout = {
   labelH: 16
 };
 
+function flowLabelSize(flow) {
+  const longestLine = Math.max(textUnits(flow.label), textUnits(flow.classification || ''));
+  return {
+    width: Math.round(Math.max(34, longestLine * 4.9 + 12) * 10) / 10,
+    height: flow.classification ? 27 : layout.labelH,
+  };
+}
+
 function stageX(index) {
   return layout.leftX + index * layout.colGap;
 }
 
+function stageFrame(stage, index) {
+  return {
+    id: index,
+    label: stage.label,
+    kind: 'stage',
+    x: stageX(index) - layout.stageW / 2,
+    y: layout.stageY,
+    width: layout.stageW,
+    height: viewBox[1] - layout.stageY - layout.stageBottomPad,
+    radius: 10,
+  };
+}
+
+const compositionFrames = asArray(dataflow.stages).map(stageFrame);
+
 function measureNode(node) {
   const width = node.width || layout.nodeW;
   const height = node.height || layout.nodeH;
@@ -73,17 +117,6 @@ for (const [index, node] of asArray(dataflow.nodes).entries()) {
 
 function validateDataflow() {
   const problems = [];
-  if (dataflow.schema_version !== 1) problems.push('Data-flow files must set "schema_version": 1.');
-  if (dataflow.diagram_type !== 'dataflow') problems.push('Data-flow files must set "diagram_type": "dataflow".');
-  if (!dataflow.meta?.title) problems.push('Data-flow files must include meta.title.');
-  if (!Array.isArray(dataflow.stages) || dataflow.stages.length < 2) {
-    problems.push('Data-flow diagrams need at least two stages.');
-  }
-  if (!Array.isArray(dataflow.nodes) || dataflow.nodes.length < 2) {
-    problems.push('Data-flow diagrams need at least two nodes.');
-  }
-  if (!Array.isArray(dataflow.flows)) problems.push('Data-flow diagrams must include a flows array.');
-  if (dataflow.cards !== undefined && !Array.isArray(dataflow.cards)) problems.push('Data-flow "cards" must be an array.');
   if (nodes.size !== asArray(dataflow.nodes).length) problems.push('Node ids must be unique.');
 
   const stageCount = asArray(dataflow.stages).length;
@@ -106,7 +139,22 @@ function validateDataflow() {
     }
     const estLabelW = textUnits(node.label) * 6.2;
     if (estLabelW > node.width + 6) {
-      problems.push(`Label "${node.label}" (~${Math.round(estLabelW)}px) is wider than node "${node.id}" (${node.width}px) - shorten the label, move detail to sublabel, or increase node.width.`);
+      problems.push(`Label "${node.label}" (~${Math.round(estLabelW)}px) is wider than node "${node.id}" (${node.width}px) - shorten the label or increase node.width.`);
+    }
+    const brandRailProblem = brandTopRailProblem(node, node.width, 8);
+    if (brandRailProblem) problems.push(brandRailProblem);
+    // sublabel and tag render as single unwrapped <text> elements; shrink-to-fit
+    // handles the ordinary case, this rejects what it cannot rescue.
+    const availableTextW = availableNodeTextWidth(node.width);
+    for (const [field, value, minimum] of [
+      ['Sublabel', node.sublabel, nodeTextFit.sublabelMinimum],
+      ['Tag', node.tag, nodeTextFit.tagMinimum],
+    ]) {
+      if (!value) continue;
+      const minimumW = minimumNodeTextWidth(value, minimum);
+      if (minimumW > availableTextW) {
+        problems.push(`${field} "${value}" needs ~${Math.ceil(minimumW)}px at the ${minimum}px legible minimum, but node "${node.id}" provides ${availableTextW}px - shorten the ${field.toLowerCase()} or increase node.width.`);
+      }
     }
   }
 
@@ -130,17 +178,83 @@ function validateDataflow() {
       const [start, end] = [routed.points[0], routed.points[routed.points.length - 1]];
       const distance = Math.hypot(end[0] - start[0], end[1] - start[1]);
       if (distance < 34) problems.push(`Flow "${flow.label}" is too short (${Math.round(distance)}px; minimum 34px) - route it through a channel or spread its nodes.`);
+      if (Array.isArray(flow.via)) {
+        for (let segmentIndex = 0; segmentIndex < routed.points.length - 1; segmentIndex += 1) {
+          const segmentStart = routed.points[segmentIndex];
+          const segmentEnd = routed.points[segmentIndex + 1];
+          const isDiagonal = Math.abs(segmentStart[0] - segmentEnd[0]) > 0.01
+            && Math.abs(segmentStart[1] - segmentEnd[1]) > 0.01;
+          if (!isDiagonal) continue;
+          const viaIndex = Math.min(segmentIndex, flow.via.length - 1);
+          problems.push(`Flow "${flow.label}" has a diagonal segment from (${segmentStart.join(', ')}) to (${segmentEnd.join(', ')}) - align via[${viaIndex}] with its adjacent point by sharing the same x or y coordinate.`);
+        }
+      }
     }
   }
 
+  problems.push(...cleanEndpointSideProblems({
+    relations: dataflow.flows,
+    endpointIds: new Set(nodes.keys()),
+    pathFor,
+    diagramType: 'dataflow',
+    relationCollection: 'flows',
+    fromSideFor: (flow) => flowSides(flow).fromSide,
+    toSideFor: (flow) => flowSides(flow).toSide,
+    routeHint: 'keep automatic routing, or choose fromSide/toSide and via points whose first and final segments cross node borders perpendicularly',
+  }));
+  problems.push(...cleanFlowProblems({
+    relations: dataflow.flows,
+    obstacles: nodes.values(),
+    pathFor,
+    diagramType: 'dataflow',
+    relationCollection: 'flows',
+    obstacleKind: 'node',
+    routeHint: 'adjust fromSide/toSide, set route/via or channelX/channelY, or move the node to another stage/row'
+  }));
+  problems.push(...cleanCrossingProblems({
+    relations: dataflow.flows,
+    endpointIds: new Set(nodes.keys()),
+    pathFor,
+    diagramType: 'dataflow',
+    relationCollection: 'flows',
+    profile: dataflow.meta?.quality_profile,
+    routeHint: 'adjust route/via or channelX/channelY so the flows use separate stage corridors'
+  }));
+  problems.push(...cleanAmbiguousCorridorProblems({
+    relations: dataflow.flows,
+    endpointIds: new Set(nodes.keys()),
+    pathFor,
+    diagramType: 'dataflow',
+    relationCollection: 'flows',
+    profile: dataflow.meta?.quality_profile,
+    routeHint: 'adjust route/via or channelX/channelY so unrelated flows do not visually merge'
+  }));
+  problems.push(...cleanBorderRunProblems({
+    relations: dataflow.flows,
+    endpointIds: new Set(nodes.keys()),
+    frames: compositionFrames,
+    pathFor,
+    diagramType: 'dataflow',
+    relationCollection: 'flows',
+    profile: dataflow.meta?.quality_profile,
+    routeHint: 'adjust route/via or channelX/channelY so the flow crosses the stage perpendicularly instead of following its border'
+  }));
+  problems.push(...cleanRouteRhythmProblems({
+    relations: dataflow.flows,
+    endpointIds: new Set(nodes.keys()),
+    pathFor,
+    diagramType: 'dataflow',
+    relationCollection: 'flows',
+    profile: dataflow.meta?.quality_profile,
+    routeHint: 'adjust route/via or channelX/channelY so each turn uses a clear inter-stage corridor'
+  }));
+
   const labelRects = [];
-  for (const flow of asArray(dataflow.flows)) {
+  for (const [flowIndex, flow] of asArray(dataflow.flows).entries()) {
     if (!flow.label || !nodes.has(flow.from) || !nodes.has(flow.to)) continue;
     const [lx, ly] = labelPoint(flow, pathFor(flow).points);
-    const longestLine = Math.max(textUnits(flow.label), textUnits(flow.classification || ''));
-    const width = Math.max(34, longestLine * 4.9 + 12);
-    const height = flow.classification ? 27 : layout.labelH;
-    labelRects.push({ label: flow.label, x: lx - width / 2, y: ly - 11, width, height, lx, ly });
+    const { width, height } = flowLabelSize(flow);
+    labelRects.push({ relation: flow, relationIndex: flowIndex, label: flow.label, x: lx - width / 2, y: ly - 11, width, height, lx, ly });
   }
   for (const rect of labelRects) {
     for (const node of nodes.values()) {
@@ -156,6 +270,16 @@ function validateDataflow() {
       }
     }
   }
+  problems.push(...cleanLabelRouteClearanceProblems({
+    relations: dataflow.flows,
+    labels: labelRects,
+    endpointIds: new Set(nodes.keys()),
+    pathFor,
+    diagramType: 'dataflow',
+    relationCollection: 'flows',
+    profile: dataflow.meta?.quality_profile,
+    routeHint: 'adjust labelAt, labelDx, labelDy, or labelSegment; otherwise adjust the other flow route/via/channelX/channelY'
+  }));
 
   const lastStageX = stageX(asArray(dataflow.stages).length - 1);
   if (lastStageX + layout.stageW / 2 > viewBox[0] - 24) {
@@ -163,7 +287,9 @@ function validateDataflow() {
   }
 
   if (problems.length) {
-    throw new Error(`Data-flow layout validation failed:\n- ${problems.join('\n- ')}`);
+    throwDiagnosticProblems('Data-flow layout validation failed', problems, {
+      subject: { diagramType: 'dataflow' },
+    });
   }
 }
 
@@ -195,73 +321,135 @@ function routeVia(flow, from, to, start, end) {
 
 const pathCache = new Map();
 
+function flowSides(flow) {
+  const from = nodes.get(flow.from);
+  const to = nodes.get(flow.to);
+  return {
+    fromSide: chosenSide(flow.fromSide, defaultFromSide(from, to)),
+    toSide: chosenSide(flow.toSide, defaultToSide(from, to)),
+  };
+}
+
+const automaticPorts = automaticPortSpread(dataflow.flows, nodes, {
+  sideFor: (flow, endpoint) => flowSides(flow)[endpoint === 'source' ? 'fromSide' : 'toSide'],
+});
+
 function pathFor(flow) {
   if (pathCache.has(flow)) return pathCache.get(flow);
   const from = nodes.get(flow.from);
   const to = nodes.get(flow.to);
-  const start = anchor(from, chosenSide(flow.fromSide, defaultFromSide(from, to)));
-  const end = anchor(to, chosenSide(flow.toSide, defaultToSide(from, to)));
-  const points = [start, ...routeVia(flow, from, to, start, end), end];
+  const ports = automaticPorts.get(flow);
+  const { fromSide, toSide } = flowSides(flow);
+  const start = ports?.from || anchor(from, fromSide);
+  const end = ports?.to || anchor(to, toSide);
+  // Drop consecutive duplicate points so a purely vertical (or horizontal)
+  // auto-route never emits a zero-length final segment - SVG derives
+  // marker-end orientation from the last segment, and a degenerate segment
+  // leaves the arrowhead angle undefined (see #169).
+  const rawPoints = [start, ...routeVia(flow, from, to, start, end), end];
+  const points = [];
+  for (const p of rawPoints) {
+    const prev = points.at(-1);
+    if (!prev || Math.abs(p[0] - prev[0]) > 0.0001 || Math.abs(p[1] - prev[1]) > 0.0001) {
+      points.push(p);
+    }
+  }
+  // Guard against an all-degenerate route (e.g. start === end): keep both
+  // endpoints so the path is still well-formed even if the marker is hidden.
+  if (points.length < 2) points.push(end);
   const routed = { d: polylinePath(points), points };
   pathCache.set(flow, routed);
   return routed;
 }
 
 function renderStage(stage, index) {
+  const frame = compositionFrames[index];
   const cx = stageX(index);
-  const x = cx - layout.stageW / 2;
-  const h = viewBox[1] - layout.stageY - layout.stageBottomPad;
-  return `        <rect x="${x}" y="${layout.stageY}" width="${layout.stageW}" height="${h}" rx="10" class="c-lane" stroke-width="1"/>
+  return `        <rect data-graph-role="structural-frame" data-composition-frame-kind="stage" data-composition-frame-id="${index}" x="${frame.x}" y="${frame.y}" width="${frame.width}" height="${frame.height}" rx="${frame.radius}" class="c-lane" stroke-width="1"/>
         <text x="${cx}" y="${layout.stageY + 22}" class="t-dim" font-size="9" font-weight="600" text-anchor="middle">${String(index + 1).padStart(2, '0')} / ${esc(stage.label)}</text>`;
 }
 
 function renderNode(node) {
   const fill = componentFill[node.type] || 'c-external';
   const accent = componentText[node.type] || 't-muted';
+  const hasSub = node.sublabel != null && node.sublabel !== '';
+  const sub = hasSub
+    ? `\n          <text data-detail="context" x="${node.cx}" y="${node.y + 37}" class="t-muted" font-size="${fittedNodeFontSize(node.sublabel, node.width, nodeTextFit.sublabelPreferred, nodeTextFit.sublabelMinimum)}" text-anchor="middle">${esc(node.sublabel)}</text>`
+    : '';
   const tag = node.tag
-    ? `\n        <text x="${node.cx}" y="${node.y + node.height - 11}" class="${accent}" font-size="7" text-anchor="middle">${esc(node.tag)}</text>`
+    ? `\n        <text data-detail="fine" x="${node.cx}" y="${node.y + node.height - 11}" class="${accent}" font-size="${fittedNodeFontSize(node.tag, node.width, nodeTextFit.tagPreferred, nodeTextFit.tagMinimum)}" text-anchor="middle">${esc(node.tag)}</text>`
     : '';
-  return `        <rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="6" class="c-mask"/>
-        <rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="6" class="${fill}"${animateAttr(dataflow.meta, 'node', nodeSteps.get(node.id))} stroke-width="1.5"/>
-        <text x="${node.cx}" y="${node.y + 21}" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">${esc(node.label)}</text>
-        <text x="${node.cx}" y="${node.y + 37}" class="t-muted" font-size="7" text-anchor="middle">${esc(node.sublabel || '')}</text>${tag}`;
+  const stage = asArray(dataflow.stages)[node.stage];
+  const context = stage
+    ? `${String(node.stage + 1).padStart(2, '0')} / ${stage.label}`
+    : i18nText(dataflow.meta.locale, 'node.context.dataflow');
+  const brand = renderBrandMark(node, { x: node.x + node.width - 22, y: node.y + 6 });
+  const labelFontSize = fittedNodeFontSize(node.label, brandLabelFitWidth(node, node.width), 10, 8);
+  const passport = { kind: node.type, sublabel: node.sublabel, tag: node.tag, context, ...brandMetadataFor(node) };
+  return `        <g ${focusNodeAttrs(node.id, node.label, passport, dataflow.meta.locale)}>
+          ${focusNodeTitle(node.label, passport)}
+          <rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="6" class="c-mask"/>
+          <rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="6" class="${fill}"${animateAttr(dataflow.meta, 'node', nodeSteps.get(node.id))} stroke-width="1.5"/>
+          ${renderSemanticSigil(node.type, { x: node.x + 6, y: node.y + 6 })}${brand ? `\n          ${brand}` : ''}
+          <text data-node-label=""${hasSub ? ' data-detail-anchor=""' : ''} x="${node.cx}" y="${node.y + 21}" class="t-primary" font-size="${labelFontSize}" font-weight="600" text-anchor="middle">${esc(node.label)}</text>${sub}${tag}
+        </g>`;
 }
 
 function renderFlowPath(flow, index) {
   const [cls, marker] = arrowClassMap[flow.variant || 'default'] || arrowClassMap.default;
   const routed = pathFor(flow);
   const strokeWidth = flow.width || (flow.variant === 'emphasis' ? 1.8 : 1.4);
-  return `        <path d="${routed.d}" class="${cls}"${animateAttr(dataflow.meta, 'edge', index)} stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;
+  return `        <path ${focusEdgeAttrs(flow.from, flow.to, flow.label, index, flow.id)} data-composition-points="${routePointsValue(routed.points)}" d="${routed.d}" class="${cls}"${animateAttr(dataflow.meta, 'edge', index)} stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;
 }
 
-function renderFlowLabel(flow) {
+function renderFlowLabel(flow, index) {
   const routed = pathFor(flow);
   const [lx, ly] = labelPoint(flow, routed.points);
-  const longestLine = Math.max(textUnits(flow.label), textUnits(flow.classification || ''));
-  const labelW = Math.max(34, longestLine * 4.9 + 12);
+  const { width: labelW, height: labelH } = flowLabelSize(flow);
   const classification = flow.classification
-    ? `\n        <text x="${lx}" y="${ly + 11}" class="t-dim" font-size="7" text-anchor="middle">${esc(flow.classification)}</text>`
+    ? `\n        <text data-detail="fine" x="${lx}" y="${ly + 11}" class="t-dim" font-size="7" text-anchor="middle">${esc(flow.classification)}</text>`
     : '';
-  const labelH = flow.classification ? 27 : layout.labelH;
-  return `        <rect x="${lx - labelW / 2}" y="${ly - 11}" width="${labelW}" height="${labelH}" rx="4" class="c-mask"/>
-        <text x="${lx}" y="${ly}" class="${variantAccent(flow.variant)}" font-size="8" text-anchor="middle">${esc(flow.label)}</text>${classification}`;
+  return `        <g data-detail="context" ${focusEdgeAttrs(flow.from, flow.to, flow.label, index, flow.id)}>
+          <rect x="${lx - labelW / 2}" y="${ly - 11}" width="${labelW}" height="${labelH}" rx="4" class="c-mask"/>
+          <text x="${lx}" y="${ly}" class="${variantAccent(flow.variant)}" font-size="8" text-anchor="middle">${esc(flow.label)}</text>${classification}
+        </g>`;
 }
 
+const LEGEND_CATALOG = [
+  { kind: 'emphasis', className: 'a-emphasis', marker: 'arrowhead-emphasis', strokeWidth: 1.8, swatchWidth: 34, swatchGap: 9, interactive: false },
+  { kind: 'security', className: 'a-security', marker: 'arrowhead-security', swatchWidth: 34, swatchGap: 9, interactive: false },
+  { kind: 'dashed', className: 'a-dashed', marker: 'arrowhead-dashed', swatchWidth: 34, swatchGap: 9, interactive: false },
+  { kind: 'database' },
+  { kind: 'default', className: 'a-default', marker: 'arrowhead', swatchWidth: 34, swatchGap: 9, interactive: false },
+].map((entry) => ({
+  ...entry,
+  label: i18nText(dataflow.meta.locale, `legend.dataflow.${entry.kind}`),
+}));
+
 function renderLegend() {
-  const y = viewBox[1] - 36;
-  return `        <text x="214" y="${y - 20}" class="t-primary" font-size="10" font-weight="600">Legend</text>
-        <path d="M 214 ${y} L 248 ${y}" class="a-emphasis" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
-        <text x="257" y="${y + 3}" class="t-muted" font-size="8">primary data</text>
-        <path d="M 340 ${y} L 374 ${y}" class="a-security" stroke-width="1.4" marker-end="url(#arrowhead-security)"/>
-        <text x="383" y="${y + 3}" class="t-muted" font-size="8">policy / PII</text>
-        <path d="M 480 ${y} L 514 ${y}" class="a-dashed" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
-        <text x="523" y="${y + 3}" class="t-muted" font-size="8">async batch</text>
-        <rect x="625" y="${y - 8}" width="14" height="9" rx="2" class="c-database" stroke-width="1"/>
-        <text x="646" y="${y}" class="t-muted" font-size="8">data store</text>`;
+  const presentKinds = new Set(asArray(dataflow.flows).map((flow) => flow.variant || 'default'));
+  if ([...nodes.values()].some((node) => node.type === 'database')) presentKinds.add('database');
+  const entries = resolveLegend(dataflow.meta?.legend, LEGEND_CATALOG, presentKinds);
+  return renderResolvedLegend({
+    entries,
+    locale: dataflow.meta.locale,
+    layout: {
+      x: 40,
+      baselineY: viewBox[1] - 36,
+      width: viewBox[0] - 80,
+      minTitleY: viewBox[1] - 66,
+      unfit: dataflow.meta?.legend === undefined ? 'hide' : 'error',
+      diagramType: 'dataflow',
+    },
+    renderSwatch: (entry) => entry.kind === 'database'
+      ? `<rect x="${entry.x}" y="${entry.baseline - 8}" width="14" height="9" rx="2" class="c-database" stroke-width="1"/>`
+      : `<path d="M ${entry.x} ${entry.baseline - 3} L ${entry.x + 34} ${entry.baseline - 3}" class="${entry.className}" stroke-width="${entry.strokeWidth || 1.4}" marker-end="url(#${entry.marker})"/>`,
+  });
 }
 
 function renderSvg() {
-  return `      <svg viewBox="0 0 ${viewBox[0]} ${viewBox[1]}" ${svgRootAttrs(dataflow.meta, 'data-flow diagram')}>
+  return `      <svg viewBox="0 0 ${viewBox[0]} ${viewBox[1]}" ${svgRootAttrs(dataflow.meta)}>
+${svgAccessibleText(dataflow.meta, 'dataflow')}
 ${renderDefinitions()}
 
         <!-- Background Grid -->
@@ -288,8 +476,8 @@ validateDataflow();
 writeDiagram({
   outPath,
   template,
+  diagramType: 'dataflow',
   meta: dataflow.meta,
-  footerLabel: 'Data-flow diagram',
   svg: renderSvg(),
   cards: dataflow.cards,
 });

package/ai/skills/stacks-technical-diagrams/renderers/lifecycle/README.md

@@ -4,7 +4,7 @@ Render `diagram_type: "lifecycle"` JSON files into the standalone technical diag
 template.
 
 ```bash
-bun --config=.claude/skills/stacks-technical-diagrams/bunfig.toml --no-env-file .claude/skills/stacks-technical-diagrams/renderers/lifecycle/render-lifecycle.mjs input.lifecycle.json output.html
+node .claude/skills/stacks-technical-diagrams/renderers/lifecycle/render-lifecycle.mjs input.lifecycle.json output.html
 ```
 
 The renderer validates input against `.claude/skills/stacks-technical-diagrams/schemas/lifecycle.schema.json`
@@ -23,7 +23,6 @@ Lifecycle JSON files must set:
   "diagram_type": "lifecycle",
   "meta": {
     "title": "Agent Run Lifecycle",
-    "subtitle": "Lifecycle phases, interruptions, recovery, and terminal exits",
     "viewBox": [980, 660]
   },
   "lanes": [],
@@ -37,7 +36,7 @@ Lane ids are semantic and reserved: a lane with id `main` is required and maps
 to the top phase band; `terminal` maps to the bottom outcome band; every other
 lane id (up to 4 lanes total) shares the single middle event band. The three
 band headers render from your lane labels - the middle band joins the labels of
-all event lanes with `+`. A complete worked example lives at
+all event lanes with a `+` separator. A complete worked example lives at
 `.claude/skills/stacks-technical-diagrams/examples/agent-run.lifecycle.json`.
 
 The schema lives at:
@@ -46,6 +45,14 @@ The schema lives at:
 .claude/skills/stacks-technical-diagrams/schemas/lifecycle.schema.json
 ```
 
+## Legend
+
+The default legend derives kinds from `states[].type`. Supported
+`meta.legend.entries` keys, in stable order, are `start`, `active`, `waiting`,
+`decision`, `success`, `failure`, `neutral`, and `external`. Labels and
+visibility may be overridden through the shared legend contract; only kinds
+backed by rendered states receive Semantic Legend controls.
+
 ## Layout budget
 
 | Band | Lane id | Top y | Column centers | Default state |
@@ -54,13 +61,18 @@ The schema lives at:
 | Event | any other id | 278 | `col` 0-2 → x = 402, 556, 710 | 126×58 |
 | Outcome | `terminal` | 450 | `col` 0-2 → x = 402, 556, 710 | 118×58 |
 
+Event and terminal columns are intentionally offset from the main rail:
+event/terminal `col: N` uses the same x coordinate as main `col: N + 2`.
+For example, lower-band columns 0, 1, and 2 align beneath main columns 2, 3,
+and 4 respectively.
+
 | Constant | Value |
 |----------|-------|
-| viewBox | default `[980, 660]`; schema minimum `[420, 360]` |
-| State area | x within `[32, width − 32]`; y within `[64, legend y − 24]` |
+| viewBox | default `[980, 660]`; schema minimum `[420, 566]` |
+| State area | x within `[32, width − 32]`; state bottom at or above `height − 122` |
 | State spacing | ≥10px between any two states - checked across lanes, because all event lanes share one band; separate same-band states with `col` or `yOffset` |
 | Transition length | ≥32px between endpoints |
-| Legend row | y = height − 98 |
+| Legend row | final baseline y = height − 36; extra measured rows wrap upward |
 
 The primary lifecycle rail runs along the phase band and extends to the
 furthest occupied phase column. Route presets for transitions: `straight`,
@@ -87,5 +99,17 @@ element's id or label. The renderer additionally fails when it can detect
 layout problems, including a missing `main` lane, duplicate state IDs, unknown
 lanes, unknown transition endpoints, states outside the lifecycle area,
 overlapping states (including across lanes), labels colliding with states or
-other labels, labels wider than their state, or unreadably short transitions.
+other labels, labels wider than their state, unreadably short transitions, or
+transitions crossing unrelated states (2px Clean Flow clearance). Lifecycle
+bands remain intentional pass-through containers.
 Text width is estimated CJK-aware: fullwidth glyphs count as two units.
+
+Set `meta.quality_profile` to `showcase` for polished delivery. Unrelated proper
+X crossings then fail with `composition/proper-crossing`; default `standard`
+keeps them as artifact-receipt warnings. The final artifact check samples
+rounded `Q` corners. Collinear corridors remain outside the proper-X rule, but
+a separate gate warns in `standard` and fails in `showcase` when unrelated
+transitions overlap for at least 8px. Shared semantic endpoints, point touches,
+and shorter overlaps remain valid. Showcase also rejects any route segment
+below 8px and any interior turn segment below 16px; ordinary 8-15px endpoint
+stubs remain valid.