@stacksjs/defaults 0.70.207 → 0.70.208

package/ai/skills/stacks-technical-diagrams/renderers/shared/geometry.mjs

@@ -0,0 +1,230 @@
+// Geometry helpers shared by all typed renderers. Every function here is
+// pure; renderers own their layout tables and pass measured rects
+// ({x, y, width, height, cx, cy}) in.
+
+// Keep layout checks defensive even after standalone schema validation.
+// Coerce non-arrays to [] so the module-level Maps build without throwing and
+// the friendly validator checks (which run later) report the real problem.
+export function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+// A computed coordinate must be a finite number; NaN/undefined would silently
+// write `<rect x="NaN">` into the output. Used by the validators as a backstop.
+export function isFinitePoint(...coords) {
+  return coords.every((c) => Number.isFinite(c));
+}
+
+export function rectsOverlap(a, b, gap = 0) {
+  return !(
+    a.x + a.width + gap <= b.x ||
+    b.x + b.width + gap <= a.x ||
+    a.y + a.height + gap <= b.y ||
+    b.y + b.height + gap <= a.y
+  );
+}
+
+export function segmentIntersectsRect(segment, rect, gap = 0) {
+  const box = {
+    x1: rect.x - gap,
+    y1: rect.y - gap,
+    x2: rect.x + rect.width + gap,
+    y2: rect.y + rect.height + gap
+  };
+  const [a, b] = [segment.start, segment.end];
+  if (pointInBox(a, box) || pointInBox(b, box)) return true;
+  return (
+    segmentsIntersect(a, b, [box.x1, box.y1], [box.x2, box.y1]) ||
+    segmentsIntersect(a, b, [box.x2, box.y1], [box.x2, box.y2]) ||
+    segmentsIntersect(a, b, [box.x2, box.y2], [box.x1, box.y2]) ||
+    segmentsIntersect(a, b, [box.x1, box.y2], [box.x1, box.y1])
+  );
+}
+
+function pointInBox(point, box) {
+  return point[0] >= box.x1 && point[0] <= box.x2 && point[1] >= box.y1 && point[1] <= box.y2;
+}
+
+function segmentsIntersect(a, b, c, d) {
+  const o1 = orientation(a, b, c);
+  const o2 = orientation(a, b, d);
+  const o3 = orientation(c, d, a);
+  const o4 = orientation(c, d, b);
+
+  if (o1 === 0 && onSegment(a, c, b)) return true;
+  if (o2 === 0 && onSegment(a, d, b)) return true;
+  if (o3 === 0 && onSegment(c, a, d)) return true;
+  if (o4 === 0 && onSegment(c, b, d)) return true;
+
+  return o1 !== o2 && o3 !== o4;
+}
+
+function orientation(a, b, c) {
+  const value = (b[1] - a[1]) * (c[0] - b[0]) - (b[0] - a[0]) * (c[1] - b[1]);
+  if (Math.abs(value) < 0.0001) return 0;
+  return value > 0 ? 1 : 2;
+}
+
+function onSegment(a, b, c) {
+  return (
+    b[0] <= Math.max(a[0], c[0]) &&
+    b[0] >= Math.min(a[0], c[0]) &&
+    b[1] <= Math.max(a[1], c[1]) &&
+    b[1] >= Math.min(a[1], c[1])
+  );
+}
+
+export function anchor(rect, side) {
+  switch (side) {
+    case 'left': return [rect.x, rect.cy];
+    case 'right': return [rect.x + rect.width, rect.cy];
+    case 'top': return [rect.cx, rect.y];
+    case 'bottom': return [rect.cx, rect.y + rect.height];
+    default:
+      return [rect.x + rect.width, rect.cy];
+  }
+}
+
+export function defaultFromSide(from, to) {
+  if (to.cx < from.cx) return 'left';
+  if (to.cx > from.cx) return 'right';
+  if (to.cy > from.cy) return 'bottom';
+  return 'top';
+}
+
+export function defaultToSide(from, to) {
+  if (to.cx < from.cx) return 'right';
+  if (to.cx > from.cx) return 'left';
+  if (to.cy > from.cy) return 'top';
+  return 'bottom';
+}
+
+export function chosenSide(side, fallback) {
+  return side && side !== 'auto' ? side : fallback;
+}
+
+export function polylinePath(points) {
+  return points.map(([x, y], index) => `${index === 0 ? 'M' : 'L'} ${x} ${y}`).join(' ');
+}
+
+export function roundedPath(points, radius) {
+  if (points.length < 3 || radius <= 0) {
+    return polylinePath(points);
+  }
+
+  const commands = [`M ${points[0][0]} ${points[0][1]}`];
+  for (let i = 1; i < points.length - 1; i += 1) {
+    const [px, py] = points[i - 1];
+    const [cx, cy] = points[i];
+    const [nx, ny] = points[i + 1];
+    const prevLen = Math.hypot(cx - px, cy - py);
+    const nextLen = Math.hypot(nx - cx, ny - cy);
+    const r = Math.min(radius, prevLen / 2, nextLen / 2);
+    if (r < 1) {
+      commands.push(`L ${cx} ${cy}`);
+      continue;
+    }
+    const before = [cx - ((cx - px) / prevLen) * r, cy - ((cy - py) / prevLen) * r];
+    const after = [cx + ((nx - cx) / nextLen) * r, cy + ((ny - cy) / nextLen) * r];
+    commands.push(`L ${before[0]} ${before[1]}`);
+    commands.push(`Q ${cx} ${cy} ${after[0]} ${after[1]}`);
+  }
+  const [endX, endY] = points[points.length - 1];
+  commands.push(`L ${endX} ${endY}`);
+  return commands.join(' ');
+}
+
+// Shared by edges/flows/transitions: all carry the same optional
+// labelAt/labelDx/labelDy/labelSegment knobs.
+export function labelPoint(item, points) {
+  if (item.labelAt) return item.labelAt;
+  if (points.length === 2) {
+    return [
+      (points[0][0] + points[1][0]) / 2 + (item.labelDx || 0),
+      points[0][1] - 10 + (item.labelDy || 0)
+    ];
+  }
+  const segmentIndex = Math.min(points.length - 2, Math.max(0, item.labelSegment ?? 1));
+  const a = points[segmentIndex];
+  const b = points[segmentIndex + 1];
+  return [(a[0] + b[0]) / 2 + (item.labelDx || 0), (a[1] + b[1]) / 2 - 10 + (item.labelDy || 0)];
+}
+
+export const componentFill = {
+  frontend: 'c-frontend',
+  backend: 'c-backend',
+  database: 'c-database',
+  cloud: 'c-cloud',
+  security: 'c-security',
+  messagebus: 'c-messagebus',
+  external: 'c-external'
+};
+
+export const componentText = {
+  frontend: 't-frontend',
+  backend: 't-backend',
+  database: 't-database',
+  cloud: 't-cloud',
+  security: 't-security',
+  messagebus: 't-messagebus',
+  external: 't-external'
+};
+
+export const arrowClassMap = {
+  default: ['a-default', 'arrowhead'],
+  emphasis: ['a-emphasis', 'arrowhead-emphasis'],
+  security: ['a-security', 'arrowhead-security'],
+  dashed: ['a-dashed', 'arrowhead-dashed']
+};
+
+// Label accent per edge variant. Workflow colors dashed (async trace) labels
+// like the trace store it points at; the other renderers use the bus color.
+export function variantAccent(variant, { dashed = 't-messagebus' } = {}) {
+  return variant === 'security'
+    ? 't-security'
+    : variant === 'emphasis'
+      ? 't-backend'
+      : variant === 'dashed'
+        ? dashed
+        : 't-muted';
+}
+
+export function formatRect(r) {
+  return `[${Math.round(r.x)}, ${Math.round(r.y)}, ${Math.round(r.width)}, ${Math.round(r.height)}]`;
+}
+
+function formatDelta(n) {
+  const v = Math.round(n);
+  return v >= 0 ? `+${v}` : String(v);
+}
+
+/** Actionable hint when an edge label rect hits a node/component box (#7). */
+export function suggestLabelObstacleFix(labelRect, lx, ly, obstacle, obstacleKind = 'component') {
+  const lxR = Math.round(lx);
+  const lyR = Math.round(ly);
+  const belowY = Math.round(obstacle.y + obstacle.height + 14);
+  const aboveY = Math.round(obstacle.y - 4);
+  return [
+    `  label rect: ${formatRect(labelRect)}`,
+    `  ${obstacleKind} "${obstacle.id}" rect: ${formatRect(obstacle)}`,
+    `  Suggested fix: labelAt [${lxR}, ${belowY}] or labelDy ${formatDelta(belowY - lyR)} (below); or labelAt [${lxR}, ${aboveY}] or labelDy ${formatDelta(aboveY - lyR)} (above)`,
+  ].join('\n');
+}
+
+/** Hint when two edge labels collide. */
+export function suggestLabelPairFix(a, b) {
+  return [
+    `  "${a.label}" ${formatRect(a)}; "${b.label}" ${formatRect(b)}`,
+    '  Suggested fix: add labelDy +24 on one edge, adjust labelDx, or remove one label',
+  ].join('\n');
+}
+
+/** Hint when two components/nodes are too close. */
+export function suggestComponentSeparation(a, b, minGap = 8) {
+  const rightX = Math.round(a.x + a.width + minGap);
+  const belowY = Math.round(a.y + a.height + minGap);
+  return [
+    `  "${a.id}" ${formatRect(a)}; "${b.id}" ${formatRect(b)}`,
+    `  Suggested fix: move "${b.id}" pos to [${rightX}, ${Math.round(b.y)}] (right of "${a.id}") or [${Math.round(b.x)}, ${belowY}] (below)`,
+  ].join('\n');
+}

package/ai/skills/stacks-technical-diagrams/renderers/shared/layout-report.mjs

@@ -0,0 +1,40 @@
+/** Serialize computed layout for dry-run / inspect (#9). */
+
+export function componentBox(c) {
+  return {
+    id: c.id,
+    type: c.type,
+    label: c.label,
+    x: Math.round(c.x),
+    y: Math.round(c.y),
+    width: c.width,
+    height: c.height,
+    ...(Number.isInteger(c.row) ? { row: c.row } : {}),
+    ...(Number.isInteger(c.col) ? { col: c.col } : {}),
+    ...(Array.isArray(c.pos) ? { pos: c.pos.map(Math.round) } : {}),
+  };
+}
+
+export function boundaryBox(b) {
+  return {
+    kind: b.kind,
+    label: b.label,
+    x: Math.round(b.x),
+    y: Math.round(b.y),
+    width: Math.round(b.width),
+    height: Math.round(b.height),
+    wraps: b.wraps,
+  };
+}
+
+export function connectionPath(conn, routed, labelAt) {
+  return {
+    from: conn.from,
+    to: conn.to,
+    label: conn.label ?? null,
+    variant: conn.variant ?? 'default',
+    route: conn.route ?? 'auto',
+    points: routed.points.map(([x, y]) => [Math.round(x), Math.round(y)]),
+    ...(labelAt ? { labelAt: labelAt.map(Math.round) } : {}),
+  };
+}

package/ai/skills/stacks-technical-diagrams/renderers/shared/utils.mjs

@@ -0,0 +1,88 @@
+const ESCAPE_MAP = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+
+export function esc(value) {
+  return String(value ?? '').replace(/[&<>"']/g, (c) => ESCAPE_MAP[c]);
+}
+
+export function renderDefinitions() {
+  return `        <!-- Definitions -->
+        <defs>
+          <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+            <polygon points="0 0, 10 3.5, 0 7" class="m-default" />
+          </marker>
+          <marker id="arrowhead-emphasis" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+            <polygon points="0 0, 10 3.5, 0 7" class="m-emphasis" />
+          </marker>
+          <marker id="arrowhead-security" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+            <polygon points="0 0, 10 3.5, 0 7" class="m-security" />
+          </marker>
+          <marker id="arrowhead-dashed" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+            <polygon points="0 0, 10 3.5, 0 7" class="m-dashed" />
+          </marker>
+          <pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
+            <path d="M 40 0 L 0 0 0 40" class="c-grid" stroke-width="0.5"/>
+          </pattern>
+        </defs>`;
+}
+
+export function renderCards(cards) {
+  const list = Array.isArray(cards) ? cards : [];
+  return `    <!-- Info Cards -->
+    <div class="cards">
+${list.map((card) => `      <div class="card">
+        <div class="card-header">
+          <div class="card-dot ${esc(card.dot)}"></div>
+          <h3>${esc(card.title)}</h3>
+        </div>
+        <ul>
+${card.items.map((item) => `          <li>&bull; ${esc(item)}</li>`).join('\n')}
+        </ul>
+      </div>`).join('\n\n')}
+    </div>`;
+}
+
+const SVG_SLOT_RE = /      <!-- ARCHIFY:SVG_SLOT_START -->[\s\S]*?      <!-- ARCHIFY:SVG_SLOT_END -->/;
+const CARDS_SLOT_RE = /    <!-- ARCHIFY:CARDS_SLOT_START -->[\s\S]*?    <!-- ARCHIFY:CARDS_SLOT_END -->/;
+
+const TEMPLATE_PLACEHOLDERS = [
+  '<title>[PROJECT NAME] Architecture Diagram</title>',
+  '<h1>[PROJECT NAME] Architecture</h1>',
+  '<p class="subtitle">[Subtitle description]</p>',
+  '[Project Name] &bull; [Additional metadata]',
+];
+
+// `footer` is injected as raw HTML so callers can embed <kbd> hints;
+// pass only trusted strings here, never user input.
+export function applyTemplate(template, { title, subtitle, footer, svg, cards }) {
+  if (!SVG_SLOT_RE.test(template)) {
+    throw new Error('applyTemplate: template missing ARCHIFY:SVG_SLOT sentinel');
+  }
+  if (!CARDS_SLOT_RE.test(template)) {
+    throw new Error('applyTemplate: template missing ARCHIFY:CARDS_SLOT sentinel');
+  }
+  for (const ph of TEMPLATE_PLACEHOLDERS) {
+    if (!template.includes(ph)) {
+      throw new Error(`applyTemplate: template missing placeholder ${JSON.stringify(ph)}`);
+    }
+  }
+  // Function replacers: a literal `$&`, `$'`, `$\`` or `$$` in titles, labels,
+  // or rendered SVG must not be interpreted as a replacement pattern.
+  return template
+    .replace(TEMPLATE_PLACEHOLDERS[0], () => `<title>${esc(title)} Diagram</title>`)
+    .replace(TEMPLATE_PLACEHOLDERS[1], () => `<h1>${esc(title)}</h1>`)
+    .replace(TEMPLATE_PLACEHOLDERS[2], () => `<p class="subtitle">${esc(subtitle ?? '')}</p>`)
+    .replace(SVG_SLOT_RE, () => svg)
+    .replace(CARDS_SLOT_RE, () => cards)
+    .replace(TEMPLATE_PLACEHOLDERS[3], () => footer);
+}
+
+// CJK and other fullwidth glyphs render at roughly twice the advance width of
+// ASCII in the monospace stacks the template uses. Includes the supplementary
+// CJK extensions and emoji, which also render double-width.
+const FULLWIDTH_RE = /[ᄀ-ᅟ⺀-꓏가-힣豈-﫿︰-﹏＀-｠￠-￦　-〿\u{1F000}-\u{1FAFF}\u{20000}-\u{3FFFD}]/u;
+
+export function textUnits(text) {
+  let units = 0;
+  for (const ch of String(text ?? '')) units += FULLWIDTH_RE.test(ch) ? 2 : 1;
+  return units;
+}

package/ai/skills/stacks-technical-diagrams/renderers/shared/validator.mjs

@@ -0,0 +1,40 @@
+import * as validators from './generated-validators.mjs';
+
+// "/nodes/3/label" reads much better as "/nodes/3 (id: "router") /label" for the
+// LLM fixing the JSON; resolve the nearest enclosing element's id or label.
+function annotatePath(instancePath, data) {
+  if (!instancePath) return '/';
+  let node = data;
+  let hint = null;
+  for (const seg of instancePath.split('/').slice(1)) {
+    if (node == null || typeof node !== 'object') break;
+    node = node[/^\d+$/.test(seg) ? Number(seg) : seg];
+    if (node && typeof node === 'object' && !Array.isArray(node)) {
+      const tag = node.id ?? node.label;
+      if (tag != null) hint = String(tag);
+    }
+  }
+  return hint != null ? `${instancePath} (id/label: ${JSON.stringify(hint)})` : instancePath;
+}
+
+function formatErrors(errors, data) {
+  return errors.map((e) => {
+    const where = annotatePath(e.instancePath, data);
+    const detail = e.params && Object.keys(e.params).length
+      ? ' ' + JSON.stringify(e.params)
+      : '';
+    return `  ${where} ${e.message}${detail}`;
+  }).join('\n');
+}
+
+export function validateSchema(diagramType, data) {
+  const validate = validators[diagramType];
+  if (!validate) {
+    throw new Error(`validateSchema: unknown diagram type "${diagramType}"`);
+  }
+  if (!validate(data)) {
+    throw new Error(
+      `${diagramType} schema validation failed:\n${formatErrors(validate.errors, data)}`
+    );
+  }
+}

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

@@ -0,0 +1,103 @@
+# Workflow Renderer
+
+Render `diagram_type: "workflow"` JSON files into the standalone technical diagram HTML
+template.
+
+```bash
+bun --config=.claude/skills/stacks-technical-diagrams/bunfig.toml --no-env-file .claude/skills/stacks-technical-diagrams/renderers/workflow/render-workflow.mjs input.workflow.json output.html
+```
+
+The renderer validates input against `.claude/skills/stacks-technical-diagrams/schemas/workflow.schema.json`
+with the bundled standalone validator. No dependency installation is required.
+
+If `output.html` is omitted, the renderer uses `meta.output` from the JSON file
+or falls back to `workflow.html` in the current working directory.
+
+After rendering, run the artifact checker:
+
+```bash
+bun --config=.claude/skills/stacks-technical-diagrams/bunfig.toml --no-env-file .claude/skills/stacks-technical-diagrams/scripts/check-render-output.mjs output.html
+```
+
+It catches final-SVG issues that are easiest to see in a browser: non-finite
+SVG values, accidental two-point diagonal arrows, and arrows crossing the
+legend.
+
+## Input
+
+Workflow JSON files must set:
+
+```json
+{
+  "schema_version": 1,
+  "diagram_type": "workflow",
+  "meta": {
+    "title": "Agent Tool Call Workflow",
+    "subtitle": "Renderer-driven workflow prototype"
+  },
+  "lanes": [],
+  "phases": [],
+  "groups": [],
+  "mainPath": [],
+  "nodes": [],
+  "edges": [],
+  "cards": []
+}
+```
+
+Omit `meta.viewBox` for the common case: the width is fixed at 720 and the
+height is derived from the lane count, so lanes and legend always fit. A
+complete worked example lives at
+`.claude/skills/stacks-technical-diagrams/examples/agent-tool-call.workflow.json`.
+
+The schema lives at:
+
+```text
+.claude/skills/stacks-technical-diagrams/schemas/workflow.schema.json
+```
+
+## Layout budget
+
+| Constant | Value |
+|----------|-------|
+| viewBox | default `[720, auto]` - auto height = 52 + lanes×104 + (lanes−1)×20 + 124 |
+| Lane frame | x 40, width 640, height 104, gap 20; first lane top at y 52 |
+| Lane title strip | top 30px of each lane; node boxes must stay below it |
+| Column centers (`col` 0-5) | x = 88, 220, 300, 430, 500, 625 |
+| Phase headers | Optional `phases[]` render above the first lane, spanning `fromCol..toCol` |
+| Lane groups | Optional `groups[]` frame parallel work or branch work inside one lane |
+| Exception lanes | Set `lane.variant: "exception"` for retry, denial, fallback, or failure paths |
+| Main path lint | Optional `mainPath[]` checks that happy-path steps have matching edges and do not move backward |
+| Default node | 92×52 (height 68 when `tag` is set) |
+| Node spacing | ≥8px between nodes in the same lane |
+| Edge length | straight segments must span ≥28px |
+| Legend row | y = lane bottom + 44; viewBox height must be ≥ legend y + 18 |
+
+Column-center gaps are 132 / 80 / 130 / 70 / 125 px: columns 1↔2 (80px) and
+3↔4 (70px) cannot both hold default-width 92px nodes in the same lane - skip a
+column or reduce `width`.
+
+## Design Rules
+
+- Use lanes for ownership or runtime boundaries.
+- Use phase headers for high-level story beats such as Intake, Plan, Execute, and Report.
+- Use groups for parallel checks, branch handling, or bounded work within a lane; every group must contain at least one node.
+- Use `lane.variant: "exception"` for human wait, denial, retry, fallback, and failure lanes instead of mixing those paths into the happy path.
+- Set `mainPath` when the diagram has a clear happy path; the renderer validates that consecutive ids have matching edges and move left-to-right.
+- Place nodes with lane IDs and column indexes, not raw SVG coordinates.
+- Leave short adjacent links unlabeled; the arrow is enough.
+- Use labels for cross-lane decisions, approvals, async traces, and return paths.
+- Prefer route presets - `drop` (bend between lanes; `bias` 0-1 picks where),
+  `outside-right`, `return-left`, `bottom-channel`, and `up-channel` - before
+  using raw `via` points. `straight` and the default `auto` cover the rest.
+- Keep workflow examples compact enough to render well in narrow chat/browser
+  previews.
+
+Schema violations exit non-zero with path-prefixed messages annotated with the
+element's id or label. The renderer additionally fails when it can detect
+layout problems, including node overlap, nodes outside their lanes, invalid
+phase/group column ranges, empty groups, broken `mainPath` steps, unknown edge
+targets, labels colliding with nodes or other labels, labels wider than their
+node, legends outside the viewBox, or straight arrows that are too short to
+read cleanly. Text width is estimated CJK-aware: fullwidth glyphs count as two
+units.