@orchestrator-claude/definitions 3.38.0 → 3.39.0

package/skills/archify/scripts/render-examples.mjs

@@ -0,0 +1,26 @@
+// Re-render every bundled example from its JSON IR. Installed skills keep HTML
+// beside the JSON examples; the development script passes the golden directory.
+
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(__dirname, '..');
+const outputRoot = path.resolve(process.argv[2] || path.join(skillRoot, 'examples'));
+
+const TARGETS = [
+  ['workflow', 'agent-tool-call.workflow.json', 'workflow-agent-tool-call-rendered.html'],
+  ['sequence', 'cache-miss-request.sequence.json', 'sequence-cache-miss-request.html'],
+  ['dataflow', 'product-analytics.dataflow.json', 'dataflow-product-analytics.html'],
+  ['lifecycle', 'agent-run.lifecycle.json', 'lifecycle-agent-run.html'],
+  ['architecture', 'web-app.architecture.json', 'web-app-rendered.html'],
+];
+
+for (const [mode, input, output] of TARGETS) {
+  execFileSync(process.execPath, [
+    path.join(skillRoot, `renderers/${mode}/render-${mode}.mjs`),
+    path.join(skillRoot, 'examples', input),
+    path.join(outputRoot, output),
+  ], { stdio: 'inherit' });
+}

package/skills/archify/test/animation.test.mjs

@@ -0,0 +1,53 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(__dirname, '..');
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-animation-'));
+
+const CASES = {
+  architecture: 'web-app.architecture.json',
+  workflow: 'agent-tool-call.workflow.json',
+  sequence: 'cache-miss-request.sequence.json',
+  dataflow: 'product-analytics.dataflow.json',
+  lifecycle: 'agent-run.lifecycle.json',
+};
+
+function render(mode, example, animation = 'trace') {
+  const doc = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', example), 'utf8'));
+  if (animation) doc.meta = { ...doc.meta, animation };
+  const suffix = animation || 'static';
+  const input = path.join(tmp, `${mode}-${suffix}.json`);
+  const output = path.join(tmp, `${mode}-${suffix}.html`);
+  fs.writeFileSync(input, JSON.stringify(doc));
+  execFileSync('node', [path.join(skillRoot, `renderers/${mode}/render-${mode}.mjs`), input, output], {
+    stdio: ['ignore', 'ignore', 'pipe'],
+  });
+  return fs.readFileSync(output, 'utf8');
+}
+
+function svgBlock(html) {
+  return html.match(/<svg\b[\s\S]*?<\/svg>/)?.[0] || '';
+}
+
+test('static output omits animation attributes', () => {
+  const svg = svgBlock(render('workflow', CASES.workflow, null));
+  assert.doesNotMatch(svg, /data-animation=/);
+  assert.doesNotMatch(svg, /data-animate=/);
+});
+
+for (const [mode, example] of Object.entries(CASES)) {
+  test(`${mode}: trace animation annotates svg, edges, and nodes`, () => {
+    const svg = svgBlock(render(mode, example));
+    assert.match(svg, /<svg[^>]+data-animation="trace"/);
+    assert.match(svg, /data-animate="edge" style="--step:0"/);
+    assert.match(svg, /data-animate="node" style="--step:0"/);
+  });
+}
+
+process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));

package/skills/archify/test/cli.test.mjs

@@ -0,0 +1,206 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(__dirname, '..');
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-cli-'));
+const cli = path.join(skillRoot, 'bin/archify.mjs');
+
+function run(args, options = {}) {
+  return spawnSync(process.execPath, [cli, ...args], {
+    cwd: options.cwd || skillRoot,
+    encoding: 'utf8',
+    env: options.env || process.env,
+  });
+}
+
+function copyInstalledSkill(target) {
+  fs.cpSync(skillRoot, target, {
+    recursive: true,
+    filter(source) {
+      const rel = path.relative(skillRoot, source);
+      return rel !== 'node_modules' && !rel.startsWith(`node_modules${path.sep}`)
+        && rel !== 'test' && !rel.startsWith(`test${path.sep}`);
+    },
+  });
+}
+
+test('cli: help lists commands and diagram types', () => {
+  const result = run(['--help']);
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /archify render <type>/);
+  assert.match(result.stdout, /archify doctor/);
+  assert.match(result.stdout, /archify demo \[output-directory\]/);
+  assert.match(result.stdout, /architecture, workflow, sequence, dataflow, lifecycle/);
+});
+
+test('cli: doctor reports a complete installation is ready', () => {
+  const result = run(['doctor']);
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /\[ok\] Node\.js v\d+/);
+  assert.match(result.stdout, /\[ok\] Core template/);
+  assert.match(result.stdout, /\[ok\] Example renderer/);
+  assert.match(result.stdout, /\[ok\] Standalone schema validators/);
+  assert.match(result.stdout, /\[ok\] architecture renderer, schema, and example/);
+  assert.match(result.stdout, /\[ok\] lifecycle renderer, schema, and example/);
+  assert.match(result.stdout, /Archify is ready\./);
+});
+
+test('cli: doctor identifies an incomplete installation', () => {
+  const incompleteRoot = path.join(tmp, 'incomplete-skill');
+  const incompleteBin = path.join(incompleteRoot, 'bin');
+  fs.mkdirSync(incompleteBin, { recursive: true });
+  fs.copyFileSync(cli, path.join(incompleteBin, 'archify.mjs'));
+
+  const result = spawnSync(process.execPath, [path.join(incompleteBin, 'archify.mjs'), 'doctor'], {
+    cwd: incompleteRoot,
+    encoding: 'utf8',
+  });
+
+  assert.equal(result.status, 1);
+  assert.match(result.stdout, /\[missing\] Core template/);
+  assert.match(result.stdout, /\[missing\] workflow renderer, schema, and example/);
+  assert.match(result.stderr, /Archify is not ready: \d+ required files? missing\./);
+});
+
+test('cli: doctor rejects a corrupt standalone validator', () => {
+  const corruptRoot = path.join(tmp, 'corrupt-skill');
+  copyInstalledSkill(corruptRoot);
+  fs.writeFileSync(path.join(corruptRoot, 'renderers/shared/generated-validators.mjs'), 'export const workflow = ;\n');
+
+  const result = spawnSync(process.execPath, [path.join(corruptRoot, 'bin/archify.mjs'), 'doctor'], {
+    cwd: corruptRoot,
+    encoding: 'utf8',
+  });
+
+  assert.equal(result.status, 1);
+  assert.match(result.stdout, /\[invalid\] Standalone schema validators/);
+  assert.match(result.stderr, /Archify is not ready: 1 runtime check failed\./);
+});
+
+test('cli: examples renders from an installed skill', () => {
+  const installedRoot = path.join(tmp, 'installed-skill');
+  copyInstalledSkill(installedRoot);
+
+  const result = spawnSync(process.execPath, [path.join(installedRoot, 'bin/archify.mjs'), 'examples'], {
+    cwd: installedRoot,
+    encoding: 'utf8',
+  });
+
+  assert.equal(result.status, 0, result.stderr);
+  for (const output of [
+    'workflow-agent-tool-call-rendered.html',
+    'sequence-cache-miss-request.html',
+    'dataflow-product-analytics.html',
+    'lifecycle-agent-run.html',
+    'web-app-rendered.html',
+  ]) {
+    assert.equal(fs.existsSync(path.join(installedRoot, 'examples', output)), true, output);
+  }
+});
+
+test('cli: demo creates a ready-to-open diagram in a chosen directory', () => {
+  const outputDirectory = path.join(tmp, 'my-demo');
+  const output = path.join(outputDirectory, 'archify-demo.html');
+  const result = run(['demo', outputDirectory]);
+
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(fs.existsSync(output), true);
+  assert.match(fs.readFileSync(output, 'utf8'), /Sample Web App Diagram/);
+  assert.match(result.stdout, new RegExp(`Demo ready: ${output.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`));
+  assert.match(result.stdout, /Next: open the HTML in your browser/);
+  assert.match(result.stdout, /archify render architecture/);
+});
+
+test('cli: demo defaults to the current directory', () => {
+  const workingDirectory = path.join(tmp, 'default-demo');
+  fs.mkdirSync(workingDirectory);
+  const result = run(['demo'], { cwd: workingDirectory });
+
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(fs.existsSync(path.join(workingDirectory, 'archify-demo.html')), true);
+});
+
+test('cli: render writes a diagram html file', () => {
+  const out = path.join(tmp, 'workflow.html');
+  const input = path.join(skillRoot, 'examples/agent-tool-call.workflow.json');
+  const result = run(['render', 'workflow', input, out]);
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(fs.existsSync(out), true);
+  assert.match(fs.readFileSync(out, 'utf8'), /Agent Tool Call Workflow/);
+});
+
+test('cli: check validates rendered html', () => {
+  const out = path.join(tmp, 'workflow-check.html');
+  const input = path.join(skillRoot, 'examples/agent-tool-call.workflow.json');
+  assert.equal(run(['render', 'workflow', input, out]).status, 0);
+
+  const result = run(['check', out]);
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /"ok": true/);
+});
+
+test('cli: validate emits structured json without keeping html output', () => {
+  const input = path.join(skillRoot, 'examples/agent-tool-call.workflow.json');
+  const before = new Set(fs.readdirSync(tmp));
+  const result = run(['validate', 'workflow', input, '--json']);
+  assert.equal(result.status, 0, result.stderr);
+  const parsed = JSON.parse(result.stdout);
+  assert.equal(parsed.ok, true);
+  assert.equal(parsed.type, 'workflow');
+  assert.equal(parsed.checks.length, 4);
+  assert.deepEqual(new Set(fs.readdirSync(tmp)), before);
+});
+
+test('cli: inspect emits architecture layout json', () => {
+  const input = path.resolve(skillRoot, '../examples/archify-repo-grid.architecture.json');
+  const result = run(['inspect', 'architecture', input]);
+  assert.equal(result.status, 0, result.stderr);
+  const parsed = JSON.parse(result.stdout);
+  assert.equal(parsed.ok, true);
+  assert.equal(parsed.diagram_type, 'architecture');
+  assert.equal(parsed.layout.mode, 'grid');
+  assert.ok(parsed.components.length >= 5);
+  assert.ok(parsed.connections.length >= 1);
+});
+
+test('cli: validate returns renderer errors for bad input', () => {
+  const input = path.join(tmp, 'bad.workflow.json');
+  const validateTmp = path.join(tmp, 'validate-failure-tmp');
+  const doc = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples/agent-tool-call.workflow.json'), 'utf8'));
+  doc.edges[0].to = 'ghost';
+  fs.writeFileSync(input, JSON.stringify(doc));
+  fs.mkdirSync(validateTmp);
+
+  const result = run(['validate', 'workflow', input], {
+    env: { ...process.env, TMPDIR: validateTmp },
+  });
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /unknown target "ghost"/);
+  assert.deepEqual(fs.readdirSync(validateTmp), []);
+});
+
+test('cli: validate rejects an unknown type without leaking a temp directory', () => {
+  const validateTmp = path.join(tmp, 'validate-unknown-type-tmp');
+  fs.mkdirSync(validateTmp);
+
+  const result = run(['validate', 'unknown', 'ignored.json'], {
+    env: {
+      ...process.env,
+      TMPDIR: validateTmp,
+      TMP: validateTmp,
+      TEMP: validateTmp,
+    },
+  });
+
+  assert.equal(result.status, 2);
+  assert.match(result.stderr, /Unknown diagram type "unknown"/);
+  assert.deepEqual(fs.readdirSync(validateTmp), []);
+});
+
+process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));

package/skills/archify/test/degraded.test.mjs

@@ -0,0 +1,157 @@
+// Installation contract: the shipped skill performs full JSON Schema
+// validation without node_modules. AJV is a build-time dependency only; its
+// standalone validators are committed and included in the distribution.
+//
+// A malformed-but-JSON-legal document must EXIT
+// NON-ZERO with a friendly message — never crash (TypeError / is not a
+// function) and never write NaN/undefined into the HTML. A random VALID
+// perturbation of an example must still render (exit 0, no NaN).
+//
+//   node --test test/*.test.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(__dirname, '..');
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-degraded-'));
+
+const EXAMPLES = {
+  workflow: 'agent-tool-call.workflow.json',
+  sequence: 'cache-miss-request.sequence.json',
+  dataflow: 'product-analytics.dataflow.json',
+  lifecycle: 'agent-run.lifecycle.json',
+  architecture: 'web-app.architecture.json',
+};
+
+const installedRoot = path.join(tmp, 'installed-skill');
+fs.cpSync(skillRoot, installedRoot, {
+  recursive: true,
+  filter(source) {
+    const rel = path.relative(skillRoot, source);
+    return rel !== 'node_modules' && !rel.startsWith(`node_modules${path.sep}`)
+      && rel !== 'test' && !rel.startsWith(`test${path.sep}`);
+  },
+});
+
+function render(mode, doc) {
+  const input = path.join(tmp, `in-${Math.random().toString(36).slice(2)}.json`);
+  const out = path.join(tmp, 'out.html');
+  fs.writeFileSync(input, JSON.stringify(doc));
+  if (fs.existsSync(out)) fs.rmSync(out);
+  let code = 0;
+  let stderr = '';
+  try {
+    execFileSync('node', [path.join(installedRoot, `renderers/${mode}/render-${mode}.mjs`), input, out],
+      { stdio: ['ignore', 'ignore', 'pipe'] });
+  } catch (err) {
+    code = err.status ?? 1;
+    stderr = String(err.stderr || '');
+  }
+  const html = fs.existsSync(out) ? fs.readFileSync(out, 'utf8') : '';
+  return { code, stderr, html };
+}
+
+function assertFriendlyFailure(mode, doc, label) {
+  const { code, stderr, html } = render(mode, doc);
+  assert.notEqual(code, 0, `${label}: expected non-zero exit`);
+  assert.doesNotMatch(stderr, /TypeError|RangeError|is not a function|Cannot read/,
+    `${label}: crashed instead of reporting friendly error:\n${stderr}`);
+  assert.doesNotMatch(html, /NaN|undefined/, `${label}: wrote NaN/undefined into HTML`);
+}
+
+// ---- type-wrong-but-JSON-legal documents per mode ----
+const ARRAY_FIELDS = {
+  workflow: ['lanes', 'phases', 'groups', 'mainPath', 'nodes', 'edges', 'cards'],
+  sequence: ['participants', 'messages', 'segments', 'activations', 'cards'],
+  dataflow: ['stages', 'nodes', 'flows', 'cards'],
+  lifecycle: ['lanes', 'states', 'transitions', 'cards'],
+  architecture: ['components', 'boundaries', 'connections', 'cards'],
+};
+
+for (const [mode, fields] of Object.entries(ARRAY_FIELDS)) {
+  for (const field of fields) {
+    test(`${mode}: ${field} as a string fails friendly`, () => {
+      const doc = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', EXAMPLES[mode]), 'utf8'));
+      if (!(field in doc)) return; // optional field absent in this example
+      doc[field] = 'oops';
+      assertFriendlyFailure(mode, doc, `${mode}.${field}`);
+    });
+  }
+  test(`${mode}: scalar meta fails friendly`, () => {
+    const doc = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', EXAMPLES[mode]), 'utf8'));
+    doc.meta = 42;
+    assertFriendlyFailure(mode, doc, `${mode}.meta`);
+  });
+}
+
+// ---- missing-coordinate fields must not yield NaN coordinates ----
+test('workflow: node missing col never writes NaN', () => {
+  const doc = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', EXAMPLES.workflow), 'utf8'));
+  delete doc.nodes[0].col;
+  assertFriendlyFailure('workflow', doc, 'workflow node no col');
+});
+test('lifecycle: state missing col never writes NaN', () => {
+  const doc = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', EXAMPLES.lifecycle), 'utf8'));
+  delete doc.states[0].col;
+  assertFriendlyFailure('lifecycle', doc, 'lifecycle state no col');
+});
+
+// ---- property test: deterministic VALID perturbations always render ----
+// Seeded PRNG (no Math.random — keeps the test reproducible across runs).
+function mulberry32(seed) {
+  return function next() {
+    seed |= 0; seed = (seed + 0x6D2B79F5) | 0;
+    let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+test('property: shuffling node/state order still renders (order-independence)', () => {
+  for (const mode of ['workflow', 'dataflow', 'lifecycle']) {
+    const arrKey = mode === 'lifecycle' ? 'states' : 'nodes';
+    for (let seed = 1; seed <= 8; seed += 1) {
+      const doc = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', EXAMPLES[mode]), 'utf8'));
+      const rng = mulberry32(seed);
+      // Fisher–Yates with the seeded PRNG.
+      const a = doc[arrKey];
+      for (let i = a.length - 1; i > 0; i -= 1) {
+        const j = Math.floor(rng() * (i + 1));
+        [a[i], a[j]] = [a[j], a[i]];
+      }
+      const { code, html } = render(mode, doc);
+      assert.equal(code, 0, `${mode} seed ${seed}: valid shuffle should render (exit 0)`);
+      assert.doesNotMatch(html, /NaN|undefined>/, `${mode} seed ${seed}: NaN in output`);
+    }
+  }
+});
+
+test('installed skill rejects unknown fields without node_modules', () => {
+  const doc = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', EXAMPLES.workflow), 'utf8'));
+  doc.nodes[0].colour = 'cyan';
+  const { code, stderr } = render('workflow', doc);
+  assert.notEqual(code, 0);
+  assert.match(stderr, /workflow schema validation failed/);
+  assert.match(stderr, /\/nodes\/0 \(id\/label: "user"\) must NOT have additional properties/);
+  assert.match(stderr, /"additionalProperty":"colour"/);
+  assert.doesNotMatch(stderr, /ajv is not installed|skipping JSON-schema validation/);
+});
+
+for (const mode of Object.keys(EXAMPLES)) {
+  test(`installed skill retains full ${mode} schema without node_modules`, () => {
+    const doc = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', EXAMPLES[mode]), 'utf8'));
+    doc.unknownField = true;
+    const { code, stderr } = render(mode, doc);
+    assert.notEqual(code, 0);
+    assert.match(stderr, new RegExp(`${mode} schema validation failed`));
+    assert.match(stderr, /"additionalProperty":"unknownField"/);
+  });
+}
+
+process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));

package/skills/archify/test/generate-validators.test.mjs

@@ -0,0 +1,40 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(__dirname, '..');
+
+test('validator freshness check accepts CRLF checkouts', () => {
+  const scratch = fs.mkdtempSync(path.join(skillRoot, '.validator-check-'));
+  try {
+    fs.mkdirSync(path.join(scratch, 'scripts'));
+    fs.mkdirSync(path.join(scratch, 'renderers', 'shared'), { recursive: true });
+    fs.cpSync(path.join(skillRoot, 'schemas'), path.join(scratch, 'schemas'), { recursive: true });
+    fs.copyFileSync(
+      path.join(skillRoot, 'scripts', 'generate-validators.mjs'),
+      path.join(scratch, 'scripts', 'generate-validators.mjs'),
+    );
+
+    const validator = fs.readFileSync(
+      path.join(skillRoot, 'renderers', 'shared', 'generated-validators.mjs'),
+      'utf8',
+    );
+    fs.writeFileSync(
+      path.join(scratch, 'renderers', 'shared', 'generated-validators.mjs'),
+      validator.replace(/\r\n?|\n/g, '\r\n'),
+    );
+
+    const result = spawnSync(process.execPath, [
+      path.join(scratch, 'scripts', 'generate-validators.mjs'),
+      '--check',
+    ], { encoding: 'utf8' });
+
+    assert.equal(result.status, 0, result.stderr);
+  } finally {
+    fs.rmSync(scratch, { recursive: true, force: true });
+  }
+});

package/skills/archify/test/geometry.test.mjs

@@ -0,0 +1,186 @@
+// Unit tests for the pure geometry/text helpers that every renderer leans on.
+// These are exercised only transitively by the golden byte-compares, which
+// can't distinguish a geometry regression from an intentional layout change —
+// so they get a direct oracle here. Zero deps: node:test + node:assert.
+//
+//   node --test test/*.test.mjs   (or: npm test)
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  rectsOverlap,
+  segmentIntersectsRect,
+  asArray,
+  isFinitePoint,
+  anchor,
+  defaultFromSide,
+  defaultToSide,
+  chosenSide,
+  polylinePath,
+  roundedPath,
+  labelPoint,
+  suggestLabelObstacleFix,
+  suggestComponentSeparation,
+} from '../renderers/shared/geometry.mjs';
+import { textUnits, applyTemplate } from '../renderers/shared/utils.mjs';
+
+const rect = (x, y, w, h) => ({ x, y, width: w, height: h, cx: x + w / 2, cy: y + h / 2 });
+
+test('rectsOverlap: separated rects do not overlap', () => {
+  assert.equal(rectsOverlap(rect(0, 0, 10, 10), rect(20, 0, 10, 10)), false);
+});
+
+test('rectsOverlap: clearly overlapping rects overlap', () => {
+  assert.equal(rectsOverlap(rect(0, 0, 10, 10), rect(5, 5, 10, 10)), true);
+});
+
+test('rectsOverlap: edge-touching is NOT overlap at gap 0 (<= boundary)', () => {
+  // a ends at x=10, b starts at x=10 — exactly touching.
+  assert.equal(rectsOverlap(rect(0, 0, 10, 10), rect(10, 0, 10, 10), 0), false);
+});
+
+test('rectsOverlap: positive gap flags rects within that gap as too close', () => {
+  // 8px apart, required gap 8 → touching the threshold counts as too close.
+  assert.equal(rectsOverlap(rect(0, 0, 10, 10), rect(18, 0, 10, 10), 8), false);
+  assert.equal(rectsOverlap(rect(0, 0, 10, 10), rect(17, 0, 10, 10), 8), true);
+});
+
+test('rectsOverlap: negative gap shrinks the hit box (label-collision convention)', () => {
+  // gap -2 means rects must overlap by MORE than 2px to count — a 1px sliver
+  // does not. This is the sign convention the label checks rely on.
+  assert.equal(rectsOverlap(rect(0, 0, 10, 10), rect(9, 0, 10, 10), -2), false);
+  assert.equal(rectsOverlap(rect(0, 0, 10, 10), rect(7, 0, 10, 10), -2), true);
+});
+
+test('segmentIntersectsRect: detects an edge crossing a node box', () => {
+  assert.equal(segmentIntersectsRect({ start: [0, 5], end: [20, 5] }, rect(8, 0, 4, 10)), true);
+  assert.equal(segmentIntersectsRect({ start: [0, 20], end: [20, 20] }, rect(8, 0, 4, 10)), false);
+});
+
+test('asArray coerces non-arrays to [] (degraded-mode guard)', () => {
+  assert.deepEqual(asArray([1, 2]), [1, 2]);
+  assert.deepEqual(asArray('oops'), []);
+  assert.deepEqual(asArray(undefined), []);
+  assert.deepEqual(asArray(null), []);
+  assert.deepEqual(asArray({ length: 3 }), []);
+});
+
+test('isFinitePoint rejects NaN/undefined/Infinity', () => {
+  assert.equal(isFinitePoint(1, 2, 3, 4), true);
+  assert.equal(isFinitePoint(1, NaN), false);
+  assert.equal(isFinitePoint(1, undefined), false);
+  assert.equal(isFinitePoint(1, Infinity), false);
+});
+
+test('anchor returns the correct edge midpoint for each side', () => {
+  const r = rect(100, 100, 40, 20); // cx=120 cy=110
+  assert.deepEqual(anchor(r, 'left'), [100, 110]);
+  assert.deepEqual(anchor(r, 'right'), [140, 110]);
+  assert.deepEqual(anchor(r, 'top'), [120, 100]);
+  assert.deepEqual(anchor(r, 'bottom'), [120, 120]);
+});
+
+test('anchor falls back to the right edge for unknown/auto sides', () => {
+  const r = rect(100, 100, 40, 20);
+  assert.deepEqual(anchor(r, 'auto'), [140, 110]);
+  assert.deepEqual(anchor(r, undefined), [140, 110]);
+});
+
+test('defaultFromSide / defaultToSide are mirror pairs', () => {
+  const a = { cx: 0, cy: 0 };
+  const right = { cx: 100, cy: 0 };
+  assert.equal(defaultFromSide(a, right), 'right');
+  assert.equal(defaultToSide(a, right), 'left');
+  const below = { cx: 0, cy: 100 };
+  assert.equal(defaultFromSide(a, below), 'bottom');
+  assert.equal(defaultToSide(a, below), 'top');
+});
+
+test('chosenSide treats explicit "auto" as "use the geometric fallback"', () => {
+  assert.equal(chosenSide('left', 'right'), 'left');
+  assert.equal(chosenSide('auto', 'right'), 'right');
+  assert.equal(chosenSide(undefined, 'right'), 'right');
+});
+
+test('polylinePath emits M then L commands', () => {
+  assert.equal(polylinePath([[0, 0], [10, 0], [10, 10]]), 'M 0 0 L 10 0 L 10 10');
+});
+
+test('roundedPath degrades to a polyline for <3 points or radius<=0', () => {
+  assert.equal(roundedPath([[0, 0], [10, 0]], 10), 'M 0 0 L 10 0');
+  assert.equal(roundedPath([[0, 0], [10, 0], [10, 10]], 0), 'M 0 0 L 10 0 L 10 10');
+});
+
+test('roundedPath inserts a quadratic corner and never emits NaN', () => {
+  const d = roundedPath([[0, 0], [100, 0], [100, 100]], 10);
+  assert.match(d, /Q 100 0/); // corner pivots on the bend point
+  assert.doesNotMatch(d, /NaN/);
+});
+
+test('roundedPath clamps radius to half the shorter adjacent segment', () => {
+  // 6px segments with radius 10 → r clamps to 3; no overshoot / NaN.
+  const d = roundedPath([[0, 0], [6, 0], [6, 6]], 10);
+  assert.doesNotMatch(d, /NaN/);
+  assert.match(d, /^M 0 0/);
+});
+
+test('labelPoint: 2-point path is the midpoint lifted 10px, plus offsets', () => {
+  assert.deepEqual(labelPoint({}, [[0, 100], [100, 100]]), [50, 90]);
+  assert.deepEqual(labelPoint({ labelDx: 5, labelDy: -4 }, [[0, 100], [100, 100]]), [55, 86]);
+});
+
+test('labelPoint: labelSegment selects a segment and clamps to range', () => {
+  const pts = [[0, 0], [100, 0], [100, 100], [200, 100]];
+  // segment 0 → midpoint of pts[0],pts[1] = (50,0) lifted 10
+  assert.deepEqual(labelPoint({ labelSegment: 0 }, pts), [50, -10]);
+  // segment 99 clamps to the last segment
+  assert.deepEqual(labelPoint({ labelSegment: 99 }, pts), [150, 90]);
+});
+
+test('labelPoint: explicit labelAt wins outright', () => {
+  assert.deepEqual(labelPoint({ labelAt: [7, 8] }, [[0, 0], [100, 0]]), [7, 8]);
+});
+
+test('textUnits: ASCII=1, CJK=2, mixed sums, fullwidth supplementary=2', () => {
+  assert.equal(textUnits('abc'), 3);
+  assert.equal(textUnits('中文'), 4);
+  assert.equal(textUnits('a中'), 3);
+  assert.equal(textUnits(''), 0);
+  assert.equal(textUnits(null), 0);
+  assert.equal(textUnits('𠀀'), 2); // CJK Ext-B (supplementary plane)
+  assert.equal(textUnits('🚀'), 2); // emoji
+});
+
+test('suggestLabelObstacleFix includes rects and labelAt/labelDy hints', () => {
+  const labelRect = { x: 100, y: 180, width: 48, height: 14, label: '写入' };
+  const obstacle = { id: 'memtool', x: 30, y: 130, width: 230, height: 58 };
+  const hint = suggestLabelObstacleFix(labelRect, 124, 188, obstacle);
+  assert.match(hint, /label rect: \[100, 180, 48, 14\]/);
+  assert.match(hint, /component "memtool"/);
+  assert.match(hint, /Suggested fix: labelAt/);
+  assert.match(hint, /labelDy \+\d+/);
+});
+
+test('suggestComponentSeparation proposes nudged pos', () => {
+  const a = { id: 'api', x: 100, y: 200, width: 120, height: 60 };
+  const b = { id: 'db', x: 150, y: 200, width: 120, height: 60 };
+  const hint = suggestComponentSeparation(a, b, 8);
+  assert.match(hint, /move "db" pos to \[228, 200\]/);
+});
+
+test('applyTemplate preserves dollar sequences in titles', () => {
+  const template = `<title>[PROJECT NAME] Architecture Diagram</title>
+<h1>[PROJECT NAME] Architecture</h1>
+<p class="subtitle">[Subtitle description]</p>
+      <!-- ARCHIFY:SVG_SLOT_START --><svg></svg>      <!-- ARCHIFY:SVG_SLOT_END -->
+    <!-- ARCHIFY:CARDS_SLOT_START --><div></div>    <!-- ARCHIFY:CARDS_SLOT_END -->
+[Project Name] &bull; [Additional metadata]`;
+  const html = applyTemplate(template, {
+    title: 'Plan $$50 tier',
+    subtitle: 'test',
+    footer: 'f',
+    svg: '<svg/>',
+    cards: '',
+  });
+  assert.match(html, /Plan \$\$50 tier/);
+});