@xgent-ai/skills 0.3.0 → 0.5.0

package/skills/archify/test/route-probe.test.mjs

@@ -0,0 +1,114 @@
+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-route-probe-'));
+
+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) {
+  const output = path.join(tmp, `${mode}.html`);
+  execFileSync(process.execPath, [
+    path.join(skillRoot, `renderers/${mode}/render-${mode}.mjs`),
+    path.join(skillRoot, 'examples', example),
+    output,
+  ]);
+  return fs.readFileSync(output, 'utf8');
+}
+
+function canonicalSvg(html) {
+  return html.match(/<svg\b[\s\S]*?<\/svg>/)?.[0] || '';
+}
+
+test('all typed renderers inherit one viewer-only Route Probe', () => {
+  for (const [mode, example] of Object.entries(CASES)) {
+    const html = render(mode, example);
+    assert.match(html, /id="route-probe" hidden role="region" aria-labelledby="route-probe-title"/, mode);
+    assert.match(html, /id="btn-route-probe"[^>]+aria-label="Trace a directed route"[^>]+aria-pressed="false"[^>]+aria-controls="route-probe"/, mode);
+    assert.match(html, /Archify\.routeProbe = \(function \(\)/, mode);
+    assert.match(html, /Route Probe — shortest directed path over compiled semantics/, mode);
+    assert.equal((html.match(/<svg\b/g) || []).length, 1, `${mode} keeps one static canonical SVG`);
+    assert.doesNotMatch(canonicalSvg(html), /data-route-|route-probe-flow/, mode);
+  }
+});
+
+test('Route Probe uses deterministic authored-direction BFS and exposes reachability first', () => {
+  const html = render('workflow', CASES.workflow);
+  assert.match(html, /function outgoingByNode\(\)/);
+  assert.match(html, /var from = edge\.getAttribute\('data-edge-from'\)/);
+  assert.match(html, /var to = edge\.getAttribute\('data-edge-to'\)/);
+  assert.match(html, /if \(!byId\[from\] \|\| !byId\[to\] \|\| from === to\) return/);
+  assert.match(html, /outgoing\[from\]\.push\(\{ edge: edge, to: to \}\)/);
+  assert.match(html, /function reachableFrom\(source\)/);
+  assert.match(html, /data-route-candidate/);
+  assert.match(html, /function shortestDirectedPath\(source, target\)/);
+  assert.match(html, /var queue = \[source\]/);
+  assert.match(html, /previous\[link\.to\] = \{ from: queue\[cursor\], edge: link\.edge \}/);
+  assert.match(html, /routeEdges\.unshift\(step\.edge\)/);
+  assert.match(html, /nodeIds\.unshift\(step\.from\)/);
+});
+
+test('Route Probe turns a two-node question into a readable route receipt and stable link', () => {
+  const html = render('architecture', CASES.architecture);
+  assert.match(html, /svg\.setAttribute\('data-route-picking', 'target'\)/);
+  assert.match(html, /svg\.setAttribute\('data-route-active', startId \+ '~' \+ endId\)/);
+  assert.match(html, /node\.setAttribute\('data-route-step', String\(step\)\)/);
+  assert.match(html, /edge\.setAttribute\('data-route-match', ''\)/);
+  assert.match(html, /clone\.setAttribute\('pathLength', '1'\)/);
+  assert.match(html, /clone\.style\.setProperty\('--route-step', String\(step\)\)/);
+  assert.match(html, /#route=' \+ encodeURIComponent\(startId\) \+ '~' \+ encodeURIComponent\(endId\)/);
+  assert.match(html, /new URLSearchParams\(location\.hash\.replace/);
+  assert.match(html, /Archify\.view\.reveal\(result\.nodes, \{ includeNeighbors: false, reason: 'route' \}\)/);
+  assert.match(html, /shortest authored route/);
+});
+
+test('Route Probe hands large-diagram endpoint selection to a reachability-aware Finder', () => {
+  const html = render('dataflow', CASES.dataflow);
+  assert.match(html, /id="route-probe-find"[^>]+aria-label="Find a route start"[^>]+data-node-finder-trigger/);
+  assert.match(html, /function hopDistancesFrom\(source\)/);
+  assert.match(html, /kind: 'route-source'/);
+  assert.match(html, /outgoing\[id\] && outgoing\[id\]\.length/);
+  assert.match(html, /kind: 'route-target'/);
+  assert.match(html, /Object\.keys\(distances\)\.filter/);
+  assert.match(html, /targetBadges\[id\] = viewerCount\('viewer\.route\.hop', distances\[id\]\)/);
+  assert.match(html, /Archify\.finder\.open\(\{ context: context \}\)/);
+  assert.match(html, /findBtn\.textContent = viewerText\('viewer\.route\.destination\.find'\)/);
+  assert.match(html, /panel\.setAttribute\('data-finder-open', 'true'\)/);
+  assert.match(html, /\.route-probe\[data-finder-open="true"\]/);
+});
+
+test('Route Probe keeps pointer, keyboard, motion, embed, and export boundaries explicit', () => {
+  const html = render('sequence', CASES.sequence);
+  assert.match(html, /svg\.addEventListener\('click', interceptSelection, true\)/);
+  assert.match(html, /svg\.addEventListener\('keydown', interceptSelection, true\)/);
+  assert.match(html, /event\.key !== 'Enter' && event\.key !== ' '/);
+  assert.match(html, /e\.key === 'r' \|\| e\.key === 'R'/);
+  assert.match(html, /e\.key === 'Escape' && Archify\.routeProbe\.active\(\)/);
+  assert.match(html, /html\[data-embed="true"\] \.route-probe/);
+  assert.match(html, /html\.getAttribute\('data-embed'\) === 'true'/);
+  assert.match(html, /\.route-probe\[data-route-dock="top"\]/);
+  assert.match(html, /function overlapArea\(a, b\)/);
+  assert.match(html, /score\(topCandidate\) <= score\(bottomCandidate\)/);
+  assert.match(html, /container\.addEventListener\('scroll', updateDocking, \{ passive: true \}\)/);
+  assert.match(html, /@keyframes archify-route-probe-flow/);
+  assert.match(html, /@media \(prefers-reduced-motion: reduce\)[\s\S]+\.route-probe-flow \{[\s\S]+animation: none !important/);
+  assert.match(html, /clone\.removeAttribute\('data-route-picking'\)/);
+  assert.match(html, /clone\.removeAttribute\('data-route-active'\)/);
+  assert.match(html, /clone\.querySelectorAll\('\[data-route-probe-overlay\]'\)/);
+  assert.match(html, /!clone\.hasAttribute\('data-route-active'\)/);
+  assert.doesNotMatch(canonicalSvg(html), /data-route-|route-probe-flow/);
+});
+
+process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));

package/skills/archify/test/route-share-card.test.mjs

@@ -0,0 +1,163 @@
+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 repoRoot = path.resolve(skillRoot, '..');
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-route-share-card-'));
+
+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) {
+  const output = path.join(tmp, `${mode}.html`);
+  execFileSync(process.execPath, [
+    path.join(skillRoot, `renderers/${mode}/render-${mode}.mjs`),
+    path.join(skillRoot, 'examples', example),
+    output,
+  ]);
+  return fs.readFileSync(output, 'utf8');
+}
+
+function canonicalSvg(html) {
+  return html.match(/<svg\b[\s\S]*?<\/svg>/)?.[0] || '';
+}
+
+test('all five renderers inherit one resolved-only Route Share Card Export item', () => {
+  for (const [mode, example] of Object.entries(CASES)) {
+    const html = render(mode, example);
+    assert.match(html, /data-action="route-share-card"[^>]*hidden disabled[^>]*>[\s\S]*?Route Share Card[\s\S]*?1200(?:&times;|×)630 PNG/, mode);
+    assert.match(html, /function syncRouteShareItem\(\)/, mode);
+    assert.match(html, /routeShareItem\.hidden = !snapshot;/, mode);
+    assert.match(html, /routeShareItem\.disabled = !snapshot;/, mode);
+    assert.match(html, /\.toolbar \.export-menu button\[hidden\] \{ display: none; \}/, mode);
+    assert.doesNotMatch(html, /id="route-probe-share"|class="route-probe-share"/, mode);
+    assert.doesNotMatch(canonicalSvg(html), /data-share-route(?:-|=)/, mode);
+  }
+});
+
+test('Route Share Card menu lifecycle excludes hidden state from keyboard navigation', () => {
+  const html = render('workflow', CASES.workflow);
+  assert.match(html, /function open\(focusLast\)[\s\S]*?syncRouteShareItem\(\);/);
+  assert.match(html, /items\(\)\.filter\(function \(i\) \{ return !i\.hidden && !i\.disabled; \}\)/);
+  assert.match(html, /function clear\(options\)[\s\S]*?Archify\.exportMenu\.syncRouteShare\(\)/);
+  assert.match(html, /function showResult\(result, options\)[\s\S]*?Archify\.exportMenu\.syncRouteShare\(\)/);
+  assert.match(html, /html\[data-embed="true"\] \.toolbar/);
+  assert.match(html, /@media print[\s\S]*?\.toolbar/);
+});
+
+test('Route Share Card snapshots copy exact resolved node and relationship identity without rerouting', () => {
+  const html = render('architecture', CASES.architecture);
+  const snapshotBlock = html.match(/function exportSnapshot\(\) \{[\s\S]*?\n      \}/)?.[0] || '';
+  const geometryBlock = html.match(/function hasDrawableGeometry\(element\) \{[\s\S]*?\n    \}/)?.[0] || '';
+  assert.match(snapshotBlock, /nodeIds: activeNodeIds\.slice\(\)/);
+  assert.match(snapshotBlock, /hops: activeEdges\.length/);
+  assert.match(snapshotBlock, /edges: activeEdges\.map\(function \(edge\) \{/);
+  assert.match(snapshotBlock, /key: edge\.getAttribute\('data-edge-key'\)/);
+  assert.match(snapshotBlock, /seenNodeIds = Object\.create\(null\)/);
+  assert.match(snapshotBlock, /seenEdgeKeys = Object\.create\(null\)/);
+  assert.match(snapshotBlock, /fragment\.getAttribute\('data-edge-from'\) === activeNodeIds\[index\]/);
+  assert.match(snapshotBlock, /drawableFragments = fragments\.filter\(hasDrawableGeometry\)/);
+  assert.match(snapshotBlock, /drawableFragments\.length !== 1/);
+  assert.match(snapshotBlock, /drawableFragments\[0\] !== edge/);
+  assert.match(geometryBlock, /geometry\.getTotalLength/);
+  assert.match(geometryBlock, /Number\.isFinite\(length\) && length > 0/);
+  assert.match(geometryBlock, /nan\|infinity/i);
+  assert.match(html, /exportSnapshot: exportSnapshot/);
+  assert.doesNotMatch(snapshotBlock, /shortestDirectedPath|outgoingByNode|reachableFrom|labelAt|nearest/i);
+});
+
+test('Route Share Card snapshot fails closed when the resolved DOM becomes stale or conflicting', () => {
+  const html = render('workflow', CASES.workflow);
+  const snapshotBlock = html.match(/function exportSnapshot\(\) \{[\s\S]*?\n      \}/)?.[0] || '';
+  assert.match(snapshotBlock, /activeNodeIds\.length < 2/);
+  assert.match(snapshotBlock, /activeEdges\.length !== activeNodeIds\.length - 1/);
+  assert.match(snapshotBlock, /allNodes\.filter\(function \(node\)/);
+  assert.match(snapshotBlock, /!edge \|\| !svg\.contains\(edge\)/);
+  assert.match(snapshotBlock, /!edgeKey \|\| seenEdgeKeys\[edgeKey\]/);
+  assert.match(snapshotBlock, /!fragments\.every/);
+  assert.match(snapshotBlock, /return null/);
+});
+
+test('Route variant decorates only a finite canonical clone with dedicated static attributes', () => {
+  const html = render('architecture', CASES.architecture);
+  const applyBlock = html.match(/function applyRouteSnapshot\(clone, snapshot\) \{[\s\S]*?\n      \}/)?.[0] || '';
+  assert.match(applyBlock, /snapshot\.edges\.length !== snapshot\.nodeIds\.length - 1/);
+  assert.match(applyBlock, /snapshot\.hops !== snapshot\.edges\.length/);
+  assert.match(applyBlock, /matchedNodes\.length !== 1/);
+  assert.match(applyBlock, /matchedEdges\.every/);
+  assert.match(applyBlock, /drawableMatches = matchedEdges\.filter\(hasDrawableGeometry\)/);
+  assert.match(applyBlock, /drawableMatches\.length !== 1/);
+  assert.match(applyBlock, /data-share-route-match/);
+  assert.match(applyBlock, /data-share-route-start/);
+  assert.match(applyBlock, /data-share-route-middle/);
+  assert.match(applyBlock, /data-share-route-end/);
+  assert.match(applyBlock, /clone\.removeAttribute\('data-animation'\)/);
+  assert.doesNotMatch(applyBlock, /setAttribute\('data-route-(?:match|step|start|end|active|journey)/);
+  assert.match(html, /canonicalStateClean && finiteSvgDimensions && applyRouteSnapshot\(clone, opts\.routeSnapshot\)/);
+  assert.match(html, /Number\.isFinite\(vb\.width\)[\s\S]*?vb\.width > 0 && vb\.height > 0/);
+  assert.ok(html.indexOf('var canonicalStateClean =') < html.indexOf('applyRouteSnapshot(clone, opts.routeSnapshot)'), 'canonical cleanup must precede route decoration');
+});
+
+test('clone-only Route styling retains context and distinguishes start, middle, and end without motion', () => {
+  const html = render('dataflow', CASES.dataflow);
+  assert.match(html, /svg\[data-share-route\] \[data-node-id\], svg\[data-share-route\] \[data-edge-from\] \{ opacity: 0\.18; \}/);
+  assert.match(html, /svg\[data-share-route\] \[data-share-route-match\] \{ opacity: 1; \}/);
+  assert.match(html, /data-share-route-start[\s\S]*?stroke-dasharray: 5 3/);
+  assert.match(html, /data-share-route-middle[\s\S]*?stroke-width: 2\.2/);
+  assert.match(html, /data-share-route-end[\s\S]*?stroke-width: 3\.4/);
+  assert.doesNotMatch(html.match(/if \(opts\.routeSnapshot\) \{[\s\S]*?\n        \}/)?.[0] || '', /display:\s*none|animation:|filter:|transform:/);
+});
+
+test('Route Share Card reuses one 1200x630 variant seam and publishes a truthful receipt', () => {
+  const html = render('architecture', CASES.architecture);
+  assert.match(html, /function rasterizeShareCard\(options\)/);
+  assert.match(html, /options\.variant !== 'route'/);
+  assert.match(html, /var snapshot = Archify\.routeProbe && Archify\.routeProbe\.exportSnapshot\(\)/);
+  assert.match(html, /renderShareCard\(\{ routeSnapshot: snapshot \}\)/);
+  assert.doesNotMatch(html, /function rasterizeRouteShareCard|routeShareCard:/);
+  assert.match(html, /var title = titleNode \? titleNode\.textContent : document\.title;/);
+  assert.match(html, /viewerCount\('viewer\.export\.card\.routeSummary', routeSnapshot\.hops/);
+  assert.match(html, /source: routeSnapshot\.source\.label/);
+  assert.match(html, /target: routeSnapshot\.target\.label/);
+  assert.match(html, /recordExportReceipt\('share-card', blob, false, \{ width: SHARE_CARD_WIDTH, height: SHARE_CARD_HEIGHT \}, 'route', true\)/);
+  assert.match(html, /diagramFilename\(\) \+ '-route-share-card\.png'/);
+  assert.match(html, /data-last-export-variant/);
+  assert.match(html, /data-last-export-route-state-clean/);
+  assert.match(html, /clearExportReceipt\(\);[\s\S]*?var snapshot = Archify\.routeProbe/);
+  assert.match(html, /function runExport\(format\)[\s\S]*?clearExportReceipt\(\);/);
+  assert.match(html, /var ctx = canvas2dOrThrow\(canvas, viewerText\('viewer\.export\.shareCard'\)\)/);
+});
+
+test('skill and READMEs describe the optional Export variant and show one real card without changing the hero', () => {
+  const viewer = fs.readFileSync(path.join(skillRoot, 'references', 'viewer-runtime.md'), 'utf8');
+  assert.match(viewer, /Export → Route Share Card/);
+  assert.match(viewer, /format=share-card/);
+  assert.match(viewer, /variant=route/);
+  assert.match(viewer, /data-share-route-\*/);
+  assert.match(viewer, /download-only/i);
+
+  for (const readme of ['README.md', 'README_EN.md', 'README_ZH.md']) {
+    const text = fs.readFileSync(path.join(repoRoot, readme), 'utf8');
+    assert.match(text, /Export → Route Share Card/, readme);
+    assert.match(text, /docs\/assets\/archify-route-share-card\.png/, readme);
+  }
+
+  const png = fs.readFileSync(path.join(repoRoot, 'docs/assets/archify-route-share-card.png'));
+  assert.equal(png.subarray(0, 8).toString('hex'), '89504e470d0a1a0a');
+  assert.equal(png.readUInt32BE(16), 1200);
+  assert.equal(png.readUInt32BE(20), 630);
+
+});
+
+process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));

package/skills/archify/test/semantic-camera.test.mjs

@@ -0,0 +1,88 @@
+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-semantic-camera-'));
+
+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) {
+  const output = path.join(tmp, `${mode}.html`);
+  execFileSync(process.execPath, [
+    path.join(skillRoot, `renderers/${mode}/render-${mode}.mjs`),
+    path.join(skillRoot, 'examples', example),
+    output,
+  ]);
+  return fs.readFileSync(output, 'utf8');
+}
+
+function svg(html) {
+  return html.match(/<svg\b[\s\S]*?<\/svg>/)?.[0] || '';
+}
+
+test('all typed renderers ship the same geometry-neutral semantic camera', () => {
+  for (const [mode, example] of Object.entries(CASES)) {
+    const html = render(mode, example);
+    assert.match(html, /function frameDesktop\(ids, options\)/, mode);
+    assert.match(html, /function semanticIds\(ids, includeNeighbors\)/, mode);
+    assert.match(html, /if \(seeds\[from\] \|\| seeds\[to\]\) \{ wanted\[from\] = true; wanted\[to\] = true; \}/, mode);
+    assert.match(html, /contentScale = Math\.min\(svgWidth \/ viewBox\.width, svgHeight \/ viewBox\.height\)/, mode);
+    assert.match(html, /targetScale = Math\.max\(1, Math\.min\(maxScale, targetScale\)\)/, mode);
+    assert.match(html, /visibleTop = Math\.max\(0, -containerRect\.top\)/, mode);
+    assert.match(html, /visibleBottom - visibleTop >= 240/, mode);
+    assert.match(html, /data-camera-mode/, mode);
+    assert.match(html, /data-camera-indicator/, mode);
+    assert.match(html, /var resolvedLevel = semantic \? viewerText\('viewer\.nav\.level\.auto'\) : levelLabel/, mode);
+    assert.match(html, /is-camera-moving/, mode);
+    assert.match(html, /cubic-bezier\(0\.22, 1, 0\.36, 1\)/, mode);
+    assert.doesNotMatch(svg(html), /data-camera-mode|is-camera-moving|AUTO /, mode);
+  }
+});
+
+test('semantic camera follows reader intent but yields to manual navigation', () => {
+  const html = render('workflow', CASES.workflow);
+  assert.match(html, /beginHandoff\(previousIndex, index, previous, view, outgoingBeatIndex, options\.playback === true \? 'playback' : 'guided'\)/);
+  assert.match(html, /reveal\(\[id\], \{ includeNeighbors: true, reason: 'focus' \}\)/);
+  assert.match(html, /reveal\(\[id\], \{ includeNeighbors: true, reason: 'relationship' \}\)/);
+  assert.match(html, /reveal\(\[id\], \{ includeNeighbors: true, reason: 'finder' \}\)/);
+  assert.match(html, /function interruptCamera\(reason\)/);
+  assert.match(html, /Archify\.guidedViews\.pause\(\)/);
+  assert.match(html, /container\.addEventListener\('pointerdown',[\s\S]+interruptCamera\(\)/);
+  assert.match(html, /\.overview-map, \.route-probe, \.semantic-lens/);
+  assert.match(html, /window\.innerWidth <= 720 && container\.hasAttribute\('data-wide-diagram'\) && Date\.now\(\) > autoScrollUntil/);
+  assert.match(html, /reset\(\{ automatic: true \}\)/);
+  assert.match(html, /routeReceipt\.hasAttribute\('data-route-journey'\)/);
+  assert.match(html, /receiptBottom \+ 24/);
+});
+
+test('semantic camera keeps mobile on its contained scroll model and respects reduced motion', () => {
+  const html = render('sequence', CASES.sequence);
+  assert.match(html, /if \(window\.innerWidth > 720\) return frameDesktop\(ids, options\)/);
+  assert.match(html, /if \(!container\.hasAttribute\('data-wide-diagram'\)\) \{[\s\S]+cameraReceipt\(\{ scale: 1, x: 0, y: 0, mode: 'semantic' \}/);
+  assert.match(html, /state\.scale = 1;[\s\S]+state\.x = 0;[\s\S]+state\.y = 0;[\s\S]+state\.mode = 'semantic';[\s\S]+apply\(\)/);
+  assert.match(html, /autoScrollUntil = Date\.now\(\) \+ \(instant \? 50 : 470\)/);
+  assert.match(html, /behavior: instant \? 'auto' : 'smooth'/);
+  assert.match(html, /svg \[data-node-id\], svg \[data-edge-from\], svg \[data-detail\], svg \[data-detail-anchor\], svg \[data-legend-hit\], svg \{ transition: none !important; \}/);
+});
+
+test('semantic camera remains outside canonical SVG export state', () => {
+  const html = render('architecture', CASES.architecture);
+  assert.match(html, /clone\.style\.removeProperty\('transform'\)/);
+  assert.match(html, /clone\.removeAttribute\('data-view-scale'\)/);
+  assert.match(html, /!clone\.style\.getPropertyValue\('transform'\)/);
+  assert.doesNotMatch(svg(html), /style="[^"]*transform|data-view-scale|data-camera-mode/);
+});
+
+process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));

package/skills/archify/test/semantic-flow.test.mjs

@@ -0,0 +1,90 @@
+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-semantic-flow-'));
+
+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) {
+  const output = path.join(tmp, `${mode}.html`);
+  execFileSync(process.execPath, [
+    path.join(skillRoot, `renderers/${mode}/render-${mode}.mjs`),
+    path.join(skillRoot, 'examples', example),
+    output,
+  ]);
+  return fs.readFileSync(output, 'utf8');
+}
+
+function canonicalSvg(html) {
+  return html.match(/<svg\b[\s\S]*?<\/svg>/)?.[0] || '';
+}
+
+test('all typed renderers inherit one selection-triggered Semantic Flow signal', () => {
+  for (const [mode, example] of Object.entries(CASES)) {
+    const html = render(mode, example);
+    assert.match(html, /function renderFlowOverlay\(entries\)/, mode);
+    assert.match(html, /var MAX_LENS_FLOW_EDGES = 24/, mode);
+    assert.match(html, /setAttribute\('class', 'semantic-lens-flow'\)/, mode);
+    assert.match(html, /data-semantic-lens-overlay/, mode);
+    assert.doesNotMatch(canonicalSvg(html), /semantic-lens-flow|semantic-lens-overlay|data-lens-flow/, mode);
+  }
+});
+
+test('Semantic Flow clones only exact matched authored geometry and preserves direction', () => {
+  const html = render('architecture', CASES.architecture);
+  assert.match(html, /var matchedFlow = \[\]/);
+  assert.match(html, /direction = fromKind === selectedKinds\[0\] \? 'forward' : 'reverse'/);
+  assert.match(html, /fromKind === selectedKinds\[0\] && toKind !== selectedKinds\[0\] \? 'out'/);
+  assert.match(html, /toKind === selectedKinds\[0\] && fromKind !== selectedKinds\[0\] \? 'in'/);
+  assert.match(html, /matchedFlow\.push\(\{ edge: edge, direction: direction \}\)/);
+  assert.match(html, /clone\.removeAttribute\('marker-end'\)/);
+  assert.match(html, /clone\.removeAttribute\('data-edge-key'\)/);
+  assert.match(html, /clone\.setAttribute\('pathLength', '1'\)/);
+  assert.match(html, /wrapper\.setAttribute\('transform', entry\.edge\.members\[0\]\.getAttribute\('transform'\)\)/);
+  assert.match(html, /svg\.setAttribute\('data-lens-flow-count', String\(entries\.length\)\)/);
+  assert.match(html, /svg\.insertBefore\(overlay, firstNode\)/);
+});
+
+test('Semantic Flow has preset identities and motion-safe density boundaries', () => {
+  const html = render('workflow', CASES.workflow);
+  assert.match(html, /\.semantic-lens-flow\[data-direction="out"\],[\s\S]+var\(--frontend-stroke\)/);
+  assert.match(html, /\.semantic-lens-flow\[data-direction="in"\],[\s\S]+var\(--database-stroke\)/);
+  assert.match(html, /\.semantic-lens-flow\[data-direction="within"\][\s\S]+var\(--messagebus-stroke\)/);
+  assert.match(html, /svg\[data-preset="signal-flow"\] \.semantic-lens-flow/);
+  assert.match(html, /svg\[data-preset="blueprint"\] \.semantic-lens-flow/);
+  assert.match(html, /@keyframes archify-semantic-lens-flow/);
+  assert.match(html, /animation: archify-semantic-lens-flow 1\.35s linear 1 both/);
+  assert.match(html, /entries\.length > MAX_LENS_FLOW_EDGES/);
+  assert.match(html, /data-lens-flow-density', 'quiet'/);
+  assert.match(html, /html\[data-embed="true"\] \.semantic-lens-overlay/);
+  assert.match(html, /@media print \{[\s\S]+\.semantic-lens-overlay \{ display: none !important; \}/);
+  assert.match(html, /@media \(prefers-reduced-motion: reduce\)[\s\S]+\.semantic-lens-flow \{[\s\S]+animation: none !important/);
+});
+
+test('Semantic Flow cleanup and exports remain canonical', () => {
+  const html = render('dataflow', CASES.dataflow);
+  assert.match(html, /function removeFlowOverlay\(\)/);
+  assert.match(html, /svg\.querySelectorAll\('\[data-semantic-lens-overlay\]'\)/);
+  assert.match(html, /svg\.removeAttribute\('data-lens-flow-count'\)/);
+  assert.match(html, /svg\.removeAttribute\('data-lens-flow-density'\)/);
+  assert.match(html, /clone\.removeAttribute\('data-lens-flow-count'\)/);
+  assert.match(html, /clone\.removeAttribute\('data-lens-flow-density'\)/);
+  assert.match(html, /clone\.querySelectorAll\('\[data-semantic-lens-overlay\]'\)/);
+  assert.match(html, /\[data-semantic-lens-overlay\],[^']*\[data-lens-match\]/);
+  assert.doesNotMatch(canonicalSvg(html), /semantic-lens-flow|semantic-lens-overlay|data-lens-flow/);
+});
+
+process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));

package/skills/archify/test/semantic-legend-gateway.test.mjs

@@ -0,0 +1,156 @@
+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-semantic-legend-'));
+
+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, mutate) {
+  const output = path.join(tmp, `${mode}.html`);
+  let input = path.join(skillRoot, 'examples', CASES[mode]);
+  if (mutate) {
+    const document = JSON.parse(fs.readFileSync(input, 'utf8'));
+    mutate(document);
+    input = path.join(tmp, `${mode}.json`);
+    fs.writeFileSync(input, JSON.stringify(document));
+  }
+  execFileSync(process.execPath, [
+    path.join(skillRoot, `renderers/${mode}/render-${mode}.mjs`),
+    input,
+    output,
+  ]);
+  return fs.readFileSync(output, 'utf8');
+}
+
+function canonicalSvg(html) {
+  return html.match(/<svg\b[\s\S]*?<\/svg>/)?.[0] || '';
+}
+
+function values(svg, attribute) {
+  const pattern = new RegExp(`${attribute}="([^"]+)"`, 'g');
+  return [...svg.matchAll(pattern)].map((match) => match[1]);
+}
+
+test('only legends with an exact node-kind meaning publish bridge entries', () => {
+  const architecture = canonicalSvg(render('architecture'));
+  const architectureKinds = new Set(values(architecture, 'data-node-kind'));
+  assert.deepEqual(new Set(values(architecture, 'data-legend-kind')), architectureKinds);
+  assert.equal((architecture.match(/data-legend-bridge=""/g) || []).length, 1);
+
+  const workflow = canonicalSvg(render('workflow', (document) => {
+    // The production fixture intentionally fills its legend band with authored
+    // routes, so legacy implicit-auto correctly hides that legend. Keep this
+    // semantic bridge contract focused by rendering the same typed nodes with
+    // an explicit full legend and no relationship geometry in the band.
+    document.meta.legend = { mode: 'all' };
+    delete document.meta.viewBox;
+    document.edges = [];
+    delete document.mainPath;
+  }));
+  assert.deepEqual(values(workflow, 'data-legend-kind'), [
+    'frontend', 'backend', 'security', 'messagebus', 'database', 'cloud', 'external',
+  ]);
+
+  const lifecycle = canonicalSvg(render('lifecycle'));
+  assert.deepEqual(values(lifecycle, 'data-legend-kind'), [
+    'start', 'active', 'waiting', 'decision', 'success', 'failure',
+  ]);
+
+  const sequence = canonicalSvg(render('sequence'));
+  assert.deepEqual(values(sequence, 'data-legend-semantic-kind'), [
+    'emphasis', 'return', 'security', 'dashed', 'default',
+  ]);
+  assert.doesNotMatch(sequence, /data-legend-bridge|data-legend-kind=/);
+  assert.match(sequence, />Legend</);
+
+  const dataflow = canonicalSvg(render('dataflow'));
+  assert.deepEqual(values(dataflow, 'data-legend-semantic-kind'), [
+    'emphasis', 'security', 'dashed', 'database', 'default',
+  ]);
+  assert.deepEqual(values(dataflow, 'data-legend-kind'), ['database']);
+  assert.equal((dataflow.match(/data-legend-bridge=""/g) || []).length, 1);
+  assert.ok(values(dataflow, 'data-node-kind').includes('database'));
+  assert.match(dataflow, />Legend</);
+});
+
+test('runtime decoration derives counts from compiled node facts and stays viewer-only', () => {
+  const html = render('architecture');
+  const svg = canonicalSvg(html);
+  assert.match(html, /collectKinds\(\)\.forEach\(function \(kind\) \{ facts\[kind\.id\] = kind; \}\)/);
+  assert.match(html, /var count = fact \? fact\.nodes\.length : 0/);
+  assert.match(html, /data-legend-bridge-runtime/);
+  assert.match(html, /data-legend-count-badge/);
+  assert.match(html, /entry\.setAttribute\('role', 'button'\)/);
+  assert.match(html, /legendBridge\.setAttribute\('role', legendEntries\.length >= 3 \? 'toolbar' : 'group'\)/);
+  assert.match(html, /var visibleLabel = entry\.getAttribute\('data-legend-label'\) \|\| fact\.label/);
+  assert.match(html, /entry\.setAttribute\('aria-label', viewerCount\('viewer\.lens\.legend\.inspect', count/);
+  assert.match(html, /if \(!legendBridge \|\| html\.getAttribute\('data-embed'\) === 'true'\) return false/);
+  assert.doesNotMatch(svg, /data-legend-bridge-runtime|data-legend-count=|role="toolbar"/);
+  assert.doesNotMatch(svg, /data-legend-kind="[^"]+"[^>]+(?:role=|aria-pressed=)/);
+});
+
+test('preview is soft, input-aware, and yields to stronger exploration owners', () => {
+  const html = render('workflow');
+  const preview = html.slice(
+    html.indexOf('function previewLegendKind'),
+    html.indexOf('function syncLegendPreview'),
+  );
+  assert.match(html, /window\.matchMedia\('\(hover: hover\) and \(pointer: fine\)'\)/);
+  assert.match(html, /event\.pointerType === 'touch' \|\| \(finePointerQuery && !finePointerQuery\.matches\)/);
+  assert.match(html, /legendBridge\.addEventListener\('focusin'/);
+  assert.match(html, /legendBridge\.addEventListener\('focusout'/);
+  assert.match(preview, /data-legend-preview-match/);
+  assert.match(preview, /data-legend-preview-peer/);
+  assert.doesNotMatch(preview, /renderFlowOverlay|data-semantic-lens-overlay/);
+  assert.match(html, /selectedKinds\.length > 0 \|\| !panel\.hidden \|\| html\.getAttribute\('data-present'\) === 'true'/);
+  assert.match(html, /data-focus-active.*data-intent-trace-active/s);
+  assert.match(html, /data-route-picking.*data-story-active.*data-relationship-preview-active/s);
+  assert.match(html, /svg\[data-legend-preview-active\] \[data-node-id\]/);
+});
+
+test('activation delegates to Semantic Lens and supports roving keyboard navigation', () => {
+  const html = render('lifecycle');
+  const activation = html.slice(
+    html.indexOf('function activateLegendEntry'),
+    html.indexOf('function removeFlowOverlay'),
+  );
+  assert.match(activation, /select\(entry\.getAttribute\('data-legend-kind'\)\)/);
+  assert.match(activation, /open\(\{ opener: entry \}\)/);
+  assert.match(html, /event\.key === 'Enter' \|\| event\.key === ' '/);
+  assert.match(html, /event\.key === 'ArrowRight'/);
+  assert.match(html, /event\.key === 'ArrowLeft'/);
+  assert.match(html, /event\.key === 'Home'/);
+  assert.match(html, /event\.key === 'End'/);
+  assert.match(html, /lensOpener\.focus\(\)/);
+  assert.match(html, /entry\.setAttribute\('aria-pressed', selected \? 'true' : 'false'\)/);
+});
+
+test('bridge state is print-safe, reduced-motion-safe, and absent from canonical export', () => {
+  const html = render('architecture');
+  assert.match(html, /\[data-legend-bridge-runtime\] \{ display: none !important; \}/);
+  assert.match(html, /html:not\(\[data-embed="true"\]\) \.diagram-container \{\s*padding: 0\.75rem 0\.75rem 4\.25rem;/);
+  assert.match(html, /data-legend-hit[^}]*transition/s);
+  assert.match(html, /prefers-reduced-motion: reduce[\s\S]*\[data-legend-hit\]/);
+  assert.match(html, /clone\.removeAttribute\('data-legend-preview-active'\)/);
+  assert.match(html, /clone\.querySelectorAll\('\[data-legend-bridge-runtime\]'\)/);
+  assert.match(html, /el\.removeAttribute\('data-legend-kind'\)/);
+  assert.match(html, /el\.removeAttribute\('data-legend-label'\)/);
+  assert.match(html, /el\.removeAttribute\('data-legend-bridge'\)/);
+  assert.match(html, /\[data-legend-preview-match\], \[data-legend-preview-selected\], \[data-legend-preview-peer\]/);
+  assert.match(html, /\[data-legend-bridge\], \[data-legend-kind\], \[data-legend-bridge-runtime\]/);
+});
+
+process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));