@xgent-ai/skills 0.1.0 → 0.4.0

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

@@ -0,0 +1,86 @@
+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-zoom-'));
+
+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 emit explicit context and fine reading-depth semantics', () => {
+  for (const [mode, example] of Object.entries(CASES)) {
+    const html = render(mode, example);
+    assert.match(html, /data-detail="context"/, mode);
+    assert.match(html, /data-detail="fine"/, mode);
+    assert.match(html, /data-detail-anchor/, mode);
+    assert.doesNotMatch(html, /<text[^>]*data-detail="(?:context|fine)"[^>]*class="t-primary"/, mode);
+    assert.match(html, /class="diagram-container" data-detail-level="read"/, mode);
+  }
+});
+
+test('semantic zoom exposes MAP, READ, and FULL at deterministic thresholds', () => {
+  const html = render('workflow', CASES.workflow);
+  assert.match(html, /function detailLevel\(\)/);
+  assert.match(html, /if \(state\.mode === 'semantic'\) return 'full'/);
+  assert.match(html, /if \(state\.scale >= 1\.75\) return 'full'/);
+  assert.match(html, /if \(state\.scale >= 1\) return 'read'/);
+  assert.match(html, /return 'map'/);
+  assert.match(html, /container\.setAttribute\('data-detail-level', detail\)/);
+  assert.match(html, /var levelLabel = viewerText\('viewer\.nav\.level\.' \+ detail\)/);
+  assert.match(html, /var resolvedLevel = semantic \? viewerText\('viewer\.nav\.level\.auto'\) : levelLabel/);
+  assert.match(html, /Zoom in to reveal relationship labels and node context/);
+  assert.match(html, /Zoom in again to reveal tags and annotations/);
+  assert.match(html, /Full diagram detail/);
+});
+
+test('reading depth stays quiet at overview and yields to semantic intent', () => {
+  const html = render('architecture', CASES.architecture);
+  assert.match(html, /\.diagram-container\[data-detail-level="map"\] svg \[data-detail="context"\]/);
+  assert.match(html, /\.diagram-container\[data-detail-level="map"\] svg \[data-detail="fine"\]/);
+  assert.match(html, /\.diagram-container\[data-detail-level="read"\] svg \[data-detail="fine"\]/);
+  assert.match(html, /\.diagram-container\[data-detail-level="map"\] svg \[data-detail-anchor\]/);
+  assert.match(html, /svg\[data-focus-active\] \[data-focus-match\] \[data-detail\]/);
+  assert.match(html, /svg\[data-intent-trace-active\] \[data-intent-trace-match\] \[data-detail\]/);
+  assert.match(html, /svg\[data-route-active\] \[data-route-match\] \[data-detail\]/);
+  assert.match(html, /svg\[data-story-active\] \[data-story-step\] \[data-detail\]/);
+  assert.match(html, /svg\[data-relationship-preview-active\] \[data-relationship-preview\] \[data-detail\]/);
+});
+
+test('semantic zoom is motion-safe and full-fidelity in print and export', () => {
+  const html = render('dataflow', CASES.dataflow);
+  assert.match(html, /\[data-detail\] \{ transition: opacity 160ms ease/);
+  assert.match(html, /@media print \{[\s\S]+\.diagram-container svg \[data-detail\] \{[\s\S]+opacity: 1 !important/);
+  assert.match(html, /@media \(prefers-reduced-motion: reduce\)[\s\S]+svg \[data-detail\]/);
+  assert.match(html, /clone\.querySelectorAll\('\[data-detail\], \[data-detail-anchor\]'\)/);
+  assert.match(html, /el\.removeAttribute\('data-detail'\)/);
+  assert.match(html, /el\.removeAttribute\('data-detail-anchor'\)/);
+  assert.match(html, /clone\.querySelectorAll\('[^']*\[data-detail\][^']*\[data-detail-anchor\][^']*'\)\.length === 0/);
+  assert.doesNotMatch(svg(html), /data-detail-level=/);
+});
+
+process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));

package/skills/archify/test/sequence-column-fit.test.mjs

@@ -0,0 +1,137 @@
+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';
+import { textUnits } from '../renderers/shared/utils.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(__dirname, '..');
+
+function renderOutcome(doc) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-column-fit-'));
+  const input = path.join(tmp, 'input.json');
+  const output = path.join(tmp, 'output.html');
+  fs.writeFileSync(input, JSON.stringify(doc));
+  try {
+    execFileSync('node', [
+      path.join(skillRoot, 'renderers/sequence/render-sequence.mjs'),
+      input,
+      output,
+    ], { stdio: ['ignore', 'ignore', 'pipe'] });
+    return { code: 0, stderr: '', html: fs.readFileSync(output, 'utf8') };
+  } catch (err) {
+    return { code: err.status ?? 1, stderr: String(err.stderr || ''), html: '' };
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+function render(doc) {
+  const outcome = renderOutcome(doc);
+  assert.equal(outcome.code, 0, outcome.stderr);
+  return outcome.html;
+}
+
+function participantBoxes(html) {
+  return [...html.matchAll(/<rect x="([\d.]+)" y="72" width="([\d.]+)" height="54"/g)]
+    .map(([, x, width]) => ({ x: Number(x), width: Number(width) }))
+    .filter((box, index, all) => all.findIndex((other) => other.x === box.x) === index)
+    .sort((left, right) => left.x - right.x);
+}
+
+function wideSequence(columnFit) {
+  const meta = { title: 'Column fit', viewBox: [1320, 620] };
+  if (columnFit) meta.column_fit = columnFit;
+  return {
+    schema_version: 1,
+    diagram_type: 'sequence',
+    meta,
+    participants: [
+      { id: 'browser', type: 'frontend', label: 'Browser' },
+      { id: 'gateway', type: 'backend', label: 'Gateway' },
+      { id: 'idp', type: 'security', label: 'IdP' },
+      { id: 'api', type: 'backend', label: 'API' },
+      { id: 'store', type: 'database', label: 'Store' }
+    ],
+    messages: [
+      { from: 'browser', to: 'gateway', y: 200, label: 'request' },
+      { from: 'gateway', to: 'idp', y: 260, label: 'authorize' },
+      { from: 'idp', to: 'api', y: 320, label: 'token' },
+      { from: 'api', to: 'store', y: 380, label: 'read' }
+    ]
+  };
+}
+
+test('fixed column fit keeps the historical 108px gap regardless of viewBox width', () => {
+  const boxes = participantBoxes(render(wideSequence()));
+  assert.equal(boxes.length, 5);
+  assert.equal(boxes[0].width, 86);
+  assert.equal(boxes[1].x - boxes[0].x, 108);
+  assert.equal(boxes.at(-1).x + boxes.at(-1).width < 600, true,
+    'fixed lanes stay packed on the left, leaving the wide canvas unused');
+});
+
+test('spread column fit uses the viewBox width and stays inside it', () => {
+  const boxes = participantBoxes(render(wideSequence('spread')));
+  assert.equal(boxes.length, 5);
+  assert.ok(boxes[0].width > 86, 'participant boxes widen with the available room');
+  assert.ok(boxes[1].x - boxes[0].x > 108, 'columns spread past the fixed gap');
+  assert.equal(boxes[0].x, 62, 'first lane keeps the side margin');
+  assert.ok(boxes.at(-1).x + boxes.at(-1).width <= 1320 - 40,
+    'last lane stays inside the viewBox with the reserved margin');
+});
+
+test('spread column fit is opt-in, so an unset value renders like fixed', () => {
+  assert.equal(render(wideSequence()), render(wideSequence('fixed')));
+});
+
+const wideLabel = 'Payment Gateway Service';
+
+function labelledSequence(columnFit) {
+  const doc = wideSequence(columnFit);
+  doc.participants[1].label = wideLabel;
+  return doc;
+}
+
+test('a label the fixed box rejects fits the spread box on the same viewBox', () => {
+  const estimatedLabelW = textUnits(wideLabel) * 6.8;
+  assert.ok(estimatedLabelW > 86 + 6, 'the fixture label must actually exceed the fixed box');
+
+  const fixed = renderOutcome(labelledSequence());
+  assert.notEqual(fixed.code, 0, 'the fixed box still rejects a label it cannot hold');
+  assert.ok(fixed.stderr.includes(`Label "${wideLabel}"`), `expected the label in stderr:\n${fixed.stderr}`);
+  assert.ok(fixed.stderr.includes('86px participant box'), `expected the fixed box width in stderr:\n${fixed.stderr}`);
+
+  const spread = renderOutcome(labelledSequence('spread'));
+  assert.equal(spread.code, 0, spread.stderr);
+  const box = participantBoxes(spread.html)[1];
+  assert.ok(estimatedLabelW <= box.width + 6, `label ~${estimatedLabelW}px must fit the ${box.width}px spread box`);
+  assert.ok(spread.html.includes(`>${wideLabel}</text>`), 'the label renders unshortened');
+});
+
+test('the sublabel diagnostic reports the width in force, not the historical constant', () => {
+  const unrescuable = 'Payment authorization gateway detail text that stays far too long to shrink';
+  const doc = wideSequence('spread');
+  doc.participants[0].sublabel = unrescuable;
+
+  const { code, stderr } = renderOutcome(doc);
+  assert.notEqual(code, 0, 'a sublabel past the legible minimum is still rejected');
+  assert.match(stderr, /participant boxes are 190px for this viewBox width and 5 participants/);
+  assert.doesNotMatch(stderr, /boxes are a fixed/, 'spread must not quote the fixed layout');
+});
+
+test('the fast authoring path explains when to opt into spread', () => {
+  const schema = JSON.parse(fs.readFileSync(path.join(skillRoot, 'schemas/sequence.schema.json'), 'utf8'));
+  const description = schema.properties.meta.properties.column_fit.description;
+  const skill = fs.readFileSync(path.join(skillRoot, 'SKILL.md'), 'utf8');
+  const rendererReadme = fs.readFileSync(path.join(skillRoot, 'renderers/sequence/README.md'), 'utf8');
+
+  assert.match(description, /wide viewBox/);
+  assert.match(description, /meaningful participant labels/);
+  assert.match(skill, /do not shorten semantic labels before trying `spread`/);
+  assert.match(rendererReadme, /Use `"spread"` when a wide/);
+  assert.match(rendererReadme, /try `meta\.column_fit: "spread"` before shortening/);
+});

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

@@ -0,0 +1,97 @@
+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';
+import { animateAttr } from '../renderers/shared/cli.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(__dirname, '..');
+const template = fs.readFileSync(path.join(skillRoot, 'assets', 'template.html'), 'utf8');
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-settled-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 doc = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', example), 'utf8'));
+  doc.meta = { ...doc.meta, animation: 'trace' };
+  const input = path.join(tmp, `${mode}.json`);
+  const output = path.join(tmp, `${mode}.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');
+}
+
+test('all five renderers inherit one finite running-to-settled ambient contract', () => {
+  for (const [mode, example] of Object.entries(CASES)) {
+    const html = render(mode, example);
+    assert.match(html, /data-ambient-motion/, mode);
+    assert.match(html, /function startAmbient\(\)/, mode);
+    assert.match(html, /function settleAmbient\(reason\)/, mode);
+    assert.match(html, /animation: archify-edge-flow [^;]+ 1;/, mode);
+    assert.match(html, /animation: archify-node-pulse [^;]+ 1;/, mode);
+    assert.doesNotMatch(html, /animation: archify-edge-flow [^;]+ infinite/, mode);
+    assert.doesNotMatch(html, /animation: archify-node-pulse [^;]+ infinite/, mode);
+  }
+});
+
+test('settled flow restores authored security and async dash semantics', () => {
+  assert.match(template, /\.a-security\s*\{[^}]*stroke-dasharray:\s*5,5/);
+  assert.match(template, /\.a-dashed\s*\{[^}]*stroke-dasharray:\s*4,4/);
+  assert.match(template, /@keyframes archify-edge-flow\s*\{[\s\S]*?stroke-dasharray:\s*10 8/);
+  assert.match(template, /100%\s*\{\s*stroke-dashoffset:\s*0;\s*opacity:\s*1;\s*\}/);
+  const runningRule = template.match(/html\[data-ambient-motion="running"\][^{]+\[data-animate="edge"\][^{]*\{([^}]*)\}/)?.[1] || '';
+  assert.ok(runningRule, 'running edge rule missing');
+  assert.doesNotMatch(runningRule, /stroke-dasharray|stroke-dashoffset/);
+});
+
+test('ambient ownership is generation-bounded and cannot replay after settle', () => {
+  assert.match(template, /var ambientStarted = false/);
+  assert.match(template, /var ambientPending = new Set\(\)/);
+  assert.match(template, /if \(ambientStarted \|\| !capable\) return false/);
+  assert.match(template, /ambientStarted = true;[\s\S]*?html\.setAttribute\('data-ambient-motion', 'running'\)/);
+  assert.match(template, /ambientPending\.delete\(event\.target\)/);
+  assert.match(template, /if \(!ambientPending\.size\) settleAmbient\('complete'\)/);
+  assert.match(template, /svg\.addEventListener\('animationend', onAmbientBoundary, true\)/);
+  assert.match(template, /svg\.addEventListener\('animationcancel', onAmbientBoundary, true\)/);
+  assert.match(template, /if \(paused \|\| owner \|\| html\.hasAttribute\('data-embed'\)/);
+  assert.doesNotMatch(template, /setInterval\([^)]*ambient|addEventListener\('scroll'[^)]*ambient/);
+});
+
+test('animation delay is capped without changing normal authored order', () => {
+  assert.equal(animateAttr({ animation: 'trace' }, 'edge', 0), ' data-animate="edge" style="--step:0"');
+  assert.equal(animateAttr({ animation: 'trace' }, 'node', 8), ' data-animate="node" style="--step:8"');
+  assert.equal(animateAttr({ animation: 'trace' }, 'edge', 99), ' data-animate="edge" style="--step:12"');
+  assert.equal(animateAttr({}, 'edge', 99), '');
+});
+
+test('only the WebM canvas scene opts into a repeatable finite motion timeline', () => {
+  assert.match(template, /var motionScene = createMotionScene\(svg\)/);
+  assert.match(template, /drawMotionFrame\(ctx, backgroundImage, motionScene, elapsed\)/);
+  assert.match(template, /var data = serializeSvg\(scale\);/);
+  assert.match(template, /getPointAtLength/);
+  assert.doesNotMatch(template, /serializeSvg\(1, \{ autoTheme: true, motion: true \}\)/);
+});
+
+test('Still, reduced motion, embed, share, hidden state, and stronger intent settle ambient flow', () => {
+  assert.match(template, /reducedMotion\(\)/);
+  assert.match(template, /html\.hasAttribute\('data-embed'\)/);
+  assert.match(template, /html\.hasAttribute\('data-share-playback'\)/);
+  assert.match(template, /html\.hasAttribute\('data-document-hidden'\)/);
+  assert.match(template, /paused \|\| owner/);
+  assert.match(template, /settleAmbient\('suppressed'\)/);
+  assert.match(template, /html\[data-motion="still"\] svg\[data-animation="trace"\] \[data-animate\]/);
+  assert.match(template, /@media \(prefers-reduced-motion: reduce\)/);
+});
+
+process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));

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

@@ -0,0 +1,132 @@
+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 here = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(here, '..');
+const repoRoot = path.resolve(skillRoot, '..');
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-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) {
+  const output = path.join(tmp, `${mode}.html`);
+  execFileSync(process.execPath, [
+    path.join(skillRoot, `renderers/${mode}/render-${mode}.mjs`),
+    path.join(skillRoot, 'examples', CASES[mode]),
+    output,
+  ]);
+  return fs.readFileSync(output, 'utf8');
+}
+
+function svgBlock(html) {
+  return html.match(/<svg\b[\s\S]*?<\/svg>/)?.[0] || '';
+}
+
+test('all five renderers expose one explicit 1200x630 Share Card export', () => {
+  for (const mode of Object.keys(CASES)) {
+    const html = render(mode);
+    assert.match(html, /data-format="share-card"/, mode);
+    assert.match(html, /Share Card[\s\S]*?1200(?:&times;|×)630 PNG/, mode);
+    assert.match(html, /var SHARE_CARD_WIDTH = 1200;/, mode);
+    assert.match(html, /var SHARE_CARD_HEIGHT = 630;/, mode);
+    assert.match(html, /function rasterizeShareCard\(options\)/, mode);
+    assert.match(html, /format === 'share-card'/, mode);
+  }
+});
+
+test('Share Card uses contain-only canonical geometry with fixed safe areas', () => {
+  const html = render('architecture');
+  assert.match(html, /var availableWidth = SHARE_CARD_WIDTH - SHARE_CARD_PADDING \* 2;/);
+  assert.match(html, /var availableHeight = SHARE_CARD_HEIGHT - SHARE_CARD_HEADER - SHARE_CARD_PADDING;/);
+  assert.match(html, /var fit = Math\.min\(availableWidth \/ data\.width, availableHeight \/ data\.height\);/);
+  assert.match(html, /ctx\.drawImage\(img, drawX, drawY, drawWidth, drawHeight\);/);
+  assert.match(html, /function canvas2dOrThrow\(canvas, label\)/);
+  assert.match(html, /throw exportError\('viewer\.export\.error\.contextUnavailable'/);
+  assert.match(html, /throw exportError\('viewer\.export\.error\.toBlobUnavailable'/);
+  assert.match(html, /img\.onload = function \(\) \{\s*try \{/);
+  assert.match(html, /function rasterizeShareCard\(options\)[\s\S]*?if \(!options\.variant\) return renderShareCard\(\);/);
+  assert.match(html, /function renderShareCard\(options\)[\s\S]*?serializeSvg\(sourceScale, \{ routeSnapshot: routeSnapshot, reachSnapshot: reachSnapshot \}\)/);
+  assert.match(html, /fitCanvasText\(ctx, title, [^)]+\)/);
+  assert.match(html, /ARCHIFY ·/);
+  assert.doesNotMatch(svgBlock(html), /share-card|Share Card|ARCHIFY ·/);
+});
+
+test('Share Card is a canonical PNG with exact receipt dimensions and filename', () => {
+  const html = render('workflow');
+  assert.match(html, /recordExportReceipt\('share-card', blob, true, \{ width: SHARE_CARD_WIDTH, height: SHARE_CARD_HEIGHT \}\)/);
+  assert.match(html, /base \+ '-share-card\.png'/);
+  assert.match(html, /data-last-export-width/);
+  assert.match(html, /data-last-export-height/);
+  assert.match(html, /shareCard: rasterizeShareCard/);
+  assert.match(html, /if \(format === 'share-card'\) return true;/);
+});
+
+test('Copy Share Card reuses one canonical card blob and writes only PNG to the clipboard', () => {
+  const html = render('architecture');
+  assert.match(html, /data-action="copy-share-card"/);
+  assert.match(html, /Copy Share Card[\s\S]*?<small class="hint">PNG to clipboard<\/small>/);
+  assert.match(html, /function runCopyShareCard\(\)[\s\S]*?var blobPromise = rasterizeShareCard\(\);/);
+  const copyBlock = html.match(/function runCopyShareCard\(\) \{[\s\S]*?\n      \}/)?.[0] || '';
+  assert.equal((copyBlock.match(/rasterizeShareCard\(\)/g) || []).length, 1);
+  assert.match(copyBlock, /writePngToClipboard\(blobPromise\)/);
+  assert.match(html, /new ClipboardItem\(\{ 'image\/png': blobPromise \}\)/);
+  assert.match(copyBlock, /recordExportReceipt\('share-card', blob, true, \{ width: SHARE_CARD_WIDTH, height: SHARE_CARD_HEIGHT \}\)/);
+  assert.match(copyBlock, /toast\(viewerText\('viewer\.export\.copiedShare'\)\)/);
+  assert.match(html, /copyShareCard: runCopyShareCard/);
+});
+
+test('Copy Share Card fails closed when image clipboard writing is unavailable', () => {
+  const html = render('workflow');
+  assert.match(html, /it\.dataset\.action === 'copy-share-card'[\s\S]*?!canCopyImage\(\)/);
+  assert.match(html, /function runCopyShareCard\(\)[\s\S]*?if \(!canCopyImage\(\)\)/);
+  assert.match(html, /Clipboard image write not supported by this browser/);
+  assert.match(html, /button\[data-action="copy-share-card"\]/);
+  assert.match(html, /document\.documentElement\.removeAttribute\('data-last-export-format'\)/);
+  assert.match(html, /data-last-export-error-format', 'share-card'/);
+});
+
+test('ordinary Copy PNG keeps its existing full-diagram raster path', () => {
+  const html = render('sequence');
+  assert.match(html, /function runCopy\(\)[\s\S]*?var blobPromise = rasterize\('png'\);/);
+  assert.match(html, /runCopy\(\)[\s\S]*?writePngToClipboard\(blobPromise\)/);
+  assert.doesNotMatch(svgBlock(html), /copy-share-card|Copy Share Card/);
+});
+
+test('Share Card stays viewer-only and reuses export cleanup instead of source state', () => {
+  const html = render('sequence');
+  assert.match(html, /html\[data-embed="true"\] \.toolbar/);
+  assert.match(html, /@media print[\s\S]*?\.toolbar/);
+  assert.match(html, /function rasterizeShareCard\(options\)[\s\S]*?if \(!options\.variant\) return renderShareCard\(\);/);
+  assert.match(html, /function renderShareCard\(options\)[\s\S]*?serializeSvg\(sourceScale, \{ routeSnapshot: routeSnapshot, reachSnapshot: reachSnapshot \}\)/);
+  assert.match(html, /if \(!data\.canonicalStateClean\) return Promise\.reject\(exportError\('viewer\.export\.error\.viewerState'\)\);/);
+  assert.match(html, /canonicalStateClean/);
+  assert.doesNotMatch(svgBlock(html), /data-last-export-|data-format="share-card"/);
+});
+
+test('the skill and every README make the optional Share Card discoverable', () => {
+  const viewer = fs.readFileSync(path.join(skillRoot, 'references', 'viewer-runtime.md'), 'utf8');
+  assert.match(viewer, /optional 1200(?:×|x)630 Share Card PNG/i);
+  assert.match(viewer, /current theme and visual preset/i);
+  assert.match(viewer, /never claim(?:s|ing)? validation/i);
+  assert.match(viewer, /Copy Share Card/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, /Share Card/i, readme);
+    assert.match(text, /1200(?:×|x)630/, readme);
+    assert.match(text, /copy|复制/i, readme);
+  }
+});
+
+process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));