Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

32.1 KB
Raw Blame
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 { ChromeVisualBrowser, findChrome, runVisualCheck } from '../archify/bin/visual-check.mjs';
import { DESKTOP_READABILITY_VIEWPORT, MIN_PROJECTED_NODE_TEXT_PX } from '../archify/renderers/shared/desktop-readability.mjs';

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const skillRoot = path.resolve(__dirname, '..', 'archify');
const chromePath = process.env.ARCHIFY_CHROME ? findChrome() : null;
const packagedHtmlExamples = fs.readdirSync(path.join(skillRoot, 'examples'))
  .filter((name) => name.endsWith('.html') && !name.endsWith('.visual-check.html'))
  .sort();

test('waterfall axis labels stay distinct and inside the SVG at nonzero origins', {
  skip: chromePath ? false : 'Set ARCHIFY_CHROME to run the real browser regression.',
}, async (t) => {
  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-axis-labels-'));
  t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
  const browser = new ChromeVisualBrowser(chromePath);
  try {
    for (const [timing, layout] of [
      [{ start: 0.0091, duration: 0.000004 }],
      [{ start: 1e16, end: 1e16 + 2 }],
      [{ start: 100000000000, end: 100000000000.00005 }, { width: 360 }],
    ]) {
      const input = path.join(directory, 'input.json');
      const artifactPath = path.join(directory, 'output.html');
      fs.writeFileSync(input, JSON.stringify({ schema_version: 1, diagram_type: 'waterfall',
        meta: { title: 'Recorded range', evidence: 'illustrative', unit: 'ms' }, layout,
        spans: [{ id: 'request', name: 'Request', ...timing }] }));
      execFileSync(process.execPath, [path.join(skillRoot, 'renderers/waterfall/render-waterfall.mjs'), input, artifactPath]);
      for (const theme of ['light', 'dark']) {
        await browser.inspect({ artifactPath, width: 1280, height: 900, theme });
        const session = await browser.sessionPromise;
        const response = await browser.cdp.send('Runtime.evaluate', { returnByValue: true, expression: `(() => {
          const svg = document.querySelector('svg[data-waterfall-ui]');
          const bounds = svg.getBoundingClientRect();
          return { left: bounds.left, right: bounds.right,
            labels: [...svg.querySelectorAll('text.wf-num[text-anchor="middle"]')].map(text => {
              const rect = text.getBoundingClientRect();
              return { text: text.textContent, left: rect.left, right: rect.right };
            }) };
        })()` }, session);
        const { left, right, labels } = response.result.value;
        assert.ok(labels.length >= 2);
        assert.equal(new Set(labels.map(label => label.text)).size, labels.length);
        for (const [index, label] of labels.entries()) {
          assert.ok(label.left >= left - 0.5 && label.right <= right + 0.5, JSON.stringify(label));
          if (index) assert.ok(label.left >= labels[index - 1].right, JSON.stringify(labels));
        }
      }
    }
  } finally {
    await browser.close();
  }
});

test('all packaged HTML examples pass the real visual-check desktop gate', {
  skip: chromePath ? false : 'Set ARCHIFY_CHROME to run the real browser regression.',
}, async () => {
  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-packaged-examples-'));
  try {
    assert.ok(packagedHtmlExamples.length > 0, 'expected at least one packaged HTML example');
    for (const name of packagedHtmlExamples) {
      const artifact = path.join(tmp, name);
      fs.copyFileSync(path.join(skillRoot, 'examples', name), artifact);
      const result = await runVisualCheck({ artifactPath: artifact, chromePath });
      assert.equal(result.exitCode, 0, `${name}: ${JSON.stringify(result.receipt, null, 2)}`);
      assert.equal(result.receipt.containment.status, 'pass', name);
      assert.equal(result.receipt.containment.viewports.every((viewport) => viewport.ok), true, name);
    }
  } finally {
    fs.rmSync(tmp, { recursive: true, force: true });
  }
});

test('default sequence and dataflow canvases fit the real desktop reader without changing explicit geometry', {
  skip: chromePath ? false : 'Set ARCHIFY_CHROME to run the real browser regression.',
}, async () => {
  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-default-reader-'));
  const cases = [
    ['sequence', {
      schema_version: 1, diagram_type: 'sequence',
      meta: { title: 'Ping', output: 'seq.html' },
      participants: [{ id: 'a', type: 'external', label: 'Client' }, { id: 'b', type: 'backend', label: 'Server' }],
      messages: [{ from: 'a', to: 'b', y: 160, label: 'ping' }],
    }, [920, 760]],
    ['dataflow', {
      schema_version: 1, diagram_type: 'dataflow',
      meta: { title: 'Pipe', output: 'df.html' },
      stages: [{ label: 'In' }, { label: 'Out' }],
      nodes: [
        { id: 'a', type: 'frontend', label: 'Client', stage: 0, row: 0 },
        { id: 'b', type: 'database', label: 'Store', stage: 1, row: 0 },
      ],
      flows: [{ from: 'a', to: 'b', label: 'write' }],
    }, [940, 720]],
  ];
  try {
    for (const [type, doc, viewBox] of cases) {
      for (const authored of [false, true]) {
        const input = path.join(tmp, `${type}-${authored}.json`);
        const artifact = path.join(tmp, `${type}-${authored}.html`);
        const candidate = structuredClone(doc);
        if (authored) candidate.meta.viewBox = viewBox;
        fs.writeFileSync(input, JSON.stringify(candidate));
        execFileSync(process.execPath, [path.join(skillRoot, 'bin/archify.mjs'), 'render', type, input, artifact]);
        const result = await runVisualCheck({ artifactPath: artifact, chromePath });
        if (authored) {
          assert.equal(result.exitCode, 1, `${type}: explicit narrow canvas still requires repair`);
          assert.ok(result.receipt.diagnostics.some(({ code }) => code === 'viewer/viewport-overflow'));
          assert.ok(result.receipt.containment.viewports.every((v) => !v.verticalScrollAccepted));
        } else {
          assert.equal(result.exitCode, 0, `${type}: ${JSON.stringify(result.receipt.diagnostics)}`);
          assert.equal(result.receipt.readability.status, 'pass');
          const readerFit = type === 'sequence' ? 'width-first' : 'intrinsic-height';
          assert.ok(result.receipt.containment.viewports.every((v) => v.ok && v.readerFit === readerFit),
            `${type}: ${JSON.stringify(result.receipt.containment.viewports)}`);
        }
      }
    }
  } finally {
    fs.rmSync(tmp, { recursive: true, force: true });
  }
});

test('visual-check collects nested ID-less semantic edge text for every renderer family', {
  skip: chromePath ? false : 'Set ARCHIFY_CHROME to run the real browser regression.',
}, async () => {
  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-visual-edge-collector-'));
  const cases = [
    ['architecture', 'examples/web-app.architecture.json'],
    ['workflow', 'examples/agent-tool-call.workflow.json'],
    ['sequence', 'examples/cache-miss-request.sequence.json'],
    ['dataflow', 'examples/event-stream.dataflow.json'],
    ['lifecycle', 'examples/agent-run.lifecycle.json'],
  ];
  try {
    for (const [index, [type, input]] of cases.entries()) {
      const artifact = path.join(tmp, `${type}.html`);
      execFileSync(process.execPath, [
        path.join(skillRoot, 'bin', 'archify.mjs'), 'render', type,
        path.join(skillRoot, input), artifact, '--quality', 'showcase',
      ], { cwd: skillRoot, encoding: 'utf8' });
      const edge = index % 2
        ? `<g data-edge-from="collector-${type}" data-edge-to="reader-${type}"><g data-detail="context"><text x="1" y="1" font-size="5">nested semantic edge</text><text data-detail="fine" x="1" y="2" font-size="1">fine edge annotation</text></g></g>`
        : `<g data-edge-from="collector-${type}" data-edge-to="reader-${type}" data-detail="context"><text x="1" y="1" font-size="5">same-group semantic edge</text><g data-detail="fine"><text x="1" y="2" font-size="1">fine nested annotation</text></g></g>`;
      const injected = fs.readFileSync(artifact, 'utf8').replace('</svg>', `${edge}</svg>`);
      fs.writeFileSync(artifact, injected);
      const result = await runVisualCheck({ artifactPath: artifact, chromePath });
      const desktop = result.receipt.readability.viewports.find(({ width, height }) => width === 1440 && height === 900);
      assert.ok(desktop, `${type}: missing desktop observation`);
      assert.equal(desktop.minimumProjectedNodeTextDetail, 'edge', `${type}: ${JSON.stringify(desktop)}`);
      assert.match(desktop.minimumProjectedNodeText, /semantic edge/, `${type}: fine text must be excluded`);
      assert.deepEqual(desktop.minimumProjectedNodeTextOwner, {
        kind: 'edge', id: null, from: `collector-${type}`, to: `reader-${type}`,
      }, `${type}: ${JSON.stringify(desktop)}`);
      assert.equal(result.receipt.readability.status, 'fail', `${type}: injected 5px edge must be measured`);
    }
  } finally {
    fs.rmSync(tmp, { recursive: true, force: true });
  }
});

const issue250TallGroup = {
  schema_version: 2,
  diagram_type: 'workflow',
  meta: { title: 'Issue 250 stacked stages', output: 'issue-250.html' },
  lanes: [{ id: 'cage', label: 'One cage' }],
  groups: [{
    id: 'group', label: 'Cage', lane: 'cage', fromCol: 1, toCol: 3, variant: 'security',
  }],
  mainPath: ['stageA', 'stageB', 'stageC'],
  nodes: [
    { id: 'stageA', lane: 'cage', col: 2, type: 'security', label: 'stageA', yOffset: -90 },
    { id: 'stageB', lane: 'cage', col: 2, type: 'security', label: 'stageB', yOffset: 0 },
    { id: 'stageC', lane: 'cage', col: 2, type: 'security', label: 'stageC', yOffset: 90 },
  ],
  edges: [
    {
      id: 'stage-a-b', from: 'stageA', to: 'stageB', role: 'main', fromSide: 'bottom', toSide: 'top',
    },
    {
      id: 'stage-b-c', from: 'stageB', to: 'stageC', role: 'main', fromSide: 'bottom', toSide: 'top',
    },
  ],
};

const issue250FiveStageGroup = {
  ...issue250TallGroup,
  meta: { title: 'Issue 250 five stacked stages', output: 'issue-250-five-stage.html' },
  mainPath: ['stageA', 'stageB', 'stageC', 'stageD', 'stageE'],
  nodes: [
    { id: 'stageA', lane: 'cage', col: 2, type: 'security', label: 'stageA', yOffset: -300 },
    { id: 'stageB', lane: 'cage', col: 2, type: 'security', label: 'stageB', yOffset: -150 },
    { id: 'stageC', lane: 'cage', col: 2, type: 'security', label: 'stageC', yOffset: 0 },
    { id: 'stageD', lane: 'cage', col: 2, type: 'security', label: 'stageD', yOffset: 150 },
    { id: 'stageE', lane: 'cage', col: 2, type: 'security', label: 'stageE', yOffset: 300 },
  ],
  edges: [
    { id: 'stage-a-b', from: 'stageA', to: 'stageB', role: 'main', fromSide: 'bottom', toSide: 'top' },
    { id: 'stage-b-c', from: 'stageB', to: 'stageC', role: 'main', fromSide: 'bottom', toSide: 'top' },
    { id: 'stage-c-d', from: 'stageC', to: 'stageD', role: 'main', fromSide: 'bottom', toSide: 'top' },
    { id: 'stage-d-e', from: 'stageD', to: 'stageE', role: 'main', fromSide: 'bottom', toSide: 'top' },
  ],
};

test('production showcase is readable in the real 1440 by 900 adaptive reader', {
  skip: chromePath ? false : 'Set ARCHIFY_CHROME to run the real browser regression.',
}, async () => {
  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-desktop-reader-'));
  const artifact = path.join(tmp, 'production-deployment.html');
  try {
    execFileSync(process.execPath, [
      path.join(skillRoot, 'bin', 'archify.mjs'),
      'render',
      'architecture',
      path.join(skillRoot, 'examples', 'production-deployment.architecture.json'),
      artifact,
      '--quality',
      'showcase',
    ], { cwd: skillRoot, encoding: 'utf8' });

    const artifactSource = fs.readFileSync(artifact, 'utf8');
    const svgRoot = artifactSource.match(/<svg\b[^>]*>/)?.[0];
    assert.ok(svgRoot, 'production fixture must contain an SVG root');
    // Guard what a reader sees, not one exact canvas: the showcase keeps the
    // full 1376 authored width, and its height may change when the layout gets
    // more correct (the audit archive sits outside the private network frame,
    // and the DR region keeps clear of the production region).
    const viewBox = svgRoot.match(/viewBox="0 0 (\d+) (\d+)"/);
    assert.ok(viewBox, svgRoot);
    assert.equal(Number(viewBox[1]), 1376);
    assert.match(svgRoot, /data-reader-fit="intrinsic-height"/);
    assert.match(svgRoot, /data-reader-min-text="7\.5"/);

    for (let attempt = 1; attempt <= 3; attempt += 1) {
      const result = await runVisualCheck({ artifactPath: artifact, chromePath });
      assert.equal(result.exitCode, 0, `attempt ${attempt}: ${JSON.stringify(result.receipt, null, 2)}`);
      assert.equal(result.receipt.readability.status, 'pass', `attempt ${attempt}: ${JSON.stringify(result.receipt, null, 2)}`);
      const desktop = result.receipt.readability.viewports.find(({ width, height }) => (
        width === DESKTOP_READABILITY_VIEWPORT.width && height === DESKTOP_READABILITY_VIEWPORT.height
      ));
      const darkDesktop = result.receipt.captures.screenshots.find(({ width, height, theme }) => (
        width === DESKTOP_READABILITY_VIEWPORT.width
        && height === DESKTOP_READABILITY_VIEWPORT.height
        && theme === 'dark'
      ));
      for (const observation of [desktop, darkDesktop]) {
        assert.ok(observation);
        // The intrinsic-height Reader may narrow the diagram so the whole
        // showcase fits the 1440x900 first screen. That is fine as long as it
        // never exceeds the reading cap, keeps the 30px frame inset, and the
        // projected text still meets the 7.5px reading target below.
        assert.ok(observation.readerWidth <= 1376, JSON.stringify(observation));
        assert.ok(observation.readerWidth >= 1200, JSON.stringify(observation));
        assert.equal(observation.diagramWidth, observation.readerWidth - 30, JSON.stringify(observation));
        assert.equal(observation.viewBoxWidth, 1376);
        assert.ok(Number.isFinite(observation.minimumProjectedNodeTextPx));
        assert.ok(observation.minimumProjectedNodeTextPx >= MIN_PROJECTED_NODE_TEXT_PX);
        assert.ok(observation.minimumProjectedNodeTextPx >= 7.5, JSON.stringify(observation));
        assert.equal(typeof observation.minimumProjectedNodeText, 'string');
        assert.ok(observation.minimumProjectedNodeText.trim().length > 0);
        assert.equal(observation.readabilityOk, true);
        assert.equal(observation.overflowX, false, JSON.stringify(observation));
        // The production showcase is the gallery's first impression: it must
        // read whole on a laptop screen without page scroll.
        assert.equal(observation.overflowY, false, JSON.stringify(observation));
        assert.equal(observation.verticalScrollAccepted, false, JSON.stringify(observation));
      }
    }
  } finally {
    fs.rmSync(tmp, { recursive: true, force: true });
  }
});

test('route-expanded intrinsic architecture preserves reading size with ordinary page scroll', {
  skip: chromePath ? false : 'Set ARCHIFY_CHROME to run the real browser regression.',
}, async () => {
  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-route-expanded-reader-'));
  const input = path.join(
    skillRoot, '..',
    'test/fixtures/architecture-viewport/route-expanded-worldscope.architecture.json',
  );
  const artifact = path.join(tmp, 'route-expanded-worldscope.html');
  try {
    execFileSync(process.execPath, [
      path.join(skillRoot, 'bin', 'archify.mjs'),
      'deliver',
      'architecture',
      input,
      artifact,
      '--quality',
      'showcase',
      '--json',
    ], { cwd: skillRoot, encoding: 'utf8' });

    const html = fs.readFileSync(artifact, 'utf8');
    const svgRoot = html.match(/<svg\b[^>]*>/)?.[0];
    assert.ok(svgRoot, 'expected an SVG root');
    assert.match(svgRoot, /viewBox="0 0 980 678"/);
    assert.match(svgRoot, /data-reader-fit="intrinsic-height"/);
    assert.match(svgRoot, /data-reader-min-text="7\.5"/);

    const result = await runVisualCheck({ artifactPath: artifact, chromePath });
    assert.equal(result.exitCode, 0, JSON.stringify(result.receipt, null, 2));
    assert.equal(result.receipt.containment.status, 'pass');
    assert.equal(result.receipt.readability.status, 'pass');
    assert.equal(result.receipt.viewerChrome.status, 'pass');
    for (const viewport of result.receipt.containment.viewports) {
      assert.equal(viewport.overflowX, false, JSON.stringify(viewport, null, 2));
      assert.equal(viewport.overflowY, viewport.verticalScrollAccepted, JSON.stringify(viewport, null, 2));
      for (const [field, floor] of [
        ['minimumProjectedNonEdgeTextPx', 7.5 - 0.01],
        ['minimumProjectedEdgeTextPx', MIN_PROJECTED_NODE_TEXT_PX],
        ['minimumProjectedNodeTextPx', MIN_PROJECTED_NODE_TEXT_PX],
      ]) {
        assert.ok(Number.isFinite(viewport[field]), field + ': ' + JSON.stringify(viewport, null, 2));
        assert.ok(viewport[field] >= floor, field + ': ' + JSON.stringify(viewport, null, 2));
      }
    }
    const desktop = result.receipt.containment.viewports.find(({ width, height }) => (
      width === DESKTOP_READABILITY_VIEWPORT.width
      && height === DESKTOP_READABILITY_VIEWPORT.height
    ));
    assert.ok(desktop);
    // Reading size holds; with notes below the fold the diagram itself fits,
    // and any remaining overflow must be accepted scroll (checked above).
    assert.ok(desktop.diagramWidth >= desktop.viewBoxWidth, JSON.stringify(desktop, null, 2));
  } finally {
    fs.rmSync(tmp, { recursive: true, force: true });
  }
});

test('extreme intrinsic architecture keeps readable page scroll below first-screen fit', {
  skip: chromePath ? false : 'Set ARCHIFY_CHROME to run the real browser regression.',
}, async () => {
  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-readable-scroll-reader-'));
  const input = path.join(
    skillRoot, '..',
    'test/fixtures/architecture-viewport/readable-scroll-worldscope.architecture.json',
  );
  const artifact = path.join(tmp, 'readable-scroll-worldscope.html');
  try {
    execFileSync(process.execPath, [
      path.join(skillRoot, 'bin', 'archify.mjs'),
      'deliver',
      'architecture',
      input,
      artifact,
      '--quality',
      'showcase',
      '--json',
    ], { cwd: skillRoot, encoding: 'utf8' });

    const html = fs.readFileSync(artifact, 'utf8');
    const svgRoot = html.match(/<svg\b[^>]*>/)?.[0];
    assert.ok(svgRoot, 'expected an SVG root');
    assert.match(svgRoot, /viewBox="0 0 980 1188"/);
    assert.match(svgRoot, /data-reader-fit="intrinsic-height"/);
    assert.match(svgRoot, /data-reader-min-text="7\.5"/);

    const result = await runVisualCheck({ artifactPath: artifact, chromePath });
    assert.equal(result.exitCode, 0, JSON.stringify(result.receipt, null, 2));
    assert.equal(result.receipt.containment.status, 'pass');
    assert.equal(result.receipt.containment.policy, 'fit-or-reader-declared-readable-vertical-scroll');
    assert.equal(result.receipt.readability.status, 'pass');
    assert.equal(result.receipt.viewerChrome.status, 'pass');
    assert.equal(result.receipt.diagnostics.length, 0, JSON.stringify(result.receipt, null, 2));

    let scrollViewportCount = 0;
    for (const viewport of result.receipt.containment.viewports) {
      assert.equal(viewport.overflowX, false, JSON.stringify(viewport, null, 2));
      for (const [field, floor] of [
        ['minimumProjectedNonEdgeTextPx', 7.5 - 0.01],
        ['minimumProjectedEdgeTextPx', MIN_PROJECTED_NODE_TEXT_PX],
        ['minimumProjectedNodeTextPx', MIN_PROJECTED_NODE_TEXT_PX],
      ]) {
        assert.ok(Number.isFinite(viewport[field]), field + ': ' + JSON.stringify(viewport, null, 2));
        assert.ok(viewport[field] >= floor, field + ': ' + JSON.stringify(viewport, null, 2));
      }
      if (viewport.overflowY) {
        scrollViewportCount += 1;
        assert.equal(viewport.verticalScrollAccepted, true, JSON.stringify(viewport, null, 2));
        assert.equal(viewport.overflowDisposition, 'readable-vertical-scroll');
        assert.equal(viewport.readerLayout, 'adaptive');
        assert.equal(viewport.readerOverflow, 'authored');
        assert.equal(viewport.readerFit, 'intrinsic-height');
      } else {
        assert.equal(viewport.overflowY, false, JSON.stringify(viewport, null, 2));
        assert.equal(viewport.verticalScrollAccepted, false);
        assert.equal(viewport.overflowDisposition, 'contained');
      }
    }
    assert.ok(scrollViewportCount > 0, 'expected the extreme intrinsic diagram to exercise readable page scroll');
  } finally {
    fs.rmSync(tmp, { recursive: true, force: true });
  }
});

test('offline intrinsic workflows fit while authored overflow still identifies lane frames', {
  skip: chromePath ? false : 'Set ARCHIFY_CHROME to run the real browser regression.',
}, async () => {
  const fixtureRoot = path.join(skillRoot, '..', 'test', 'fixtures/workflow-viewport');
  const failed = JSON.parse(fs.readFileSync(path.join(fixtureRoot, 'order-overflow.workflow.json'), 'utf8'));
  const repaired = JSON.parse(fs.readFileSync(path.join(fixtureRoot, 'order-reflow.workflow.json'), 'utf8'));
  const meaning = ({ lane, col, yOffset, ...node }) => node;
  assert.deepEqual(failed.nodes.map(meaning), repaired.nodes.map(meaning));
  for (const key of ['edges', 'semanticChecks', 'mainPath', 'cards', 'phases']) {
    assert.deepEqual(repaired[key], failed[key], key);
  }
  // Each fixture publishes to its own file; all authored metadata stays the same.
  assert.deepEqual({ ...repaired.meta, output: failed.meta.output }, failed.meta);
  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-workflow-viewport-'));
  try {
    for (const name of ['order-overflow', 'order-reflow', 'order-pinned-overflow']) {
      let input = path.join(fixtureRoot, `${name}.workflow.json`);
      if (name === 'order-pinned-overflow') {
        input = path.join(tmp, `${name}.workflow.json`);
        // Freeze the historical canvas: fitting must respect an authored viewBox.
        const pinned = structuredClone(failed);
        pinned.meta.viewBox = [860, 786];
        fs.writeFileSync(input, JSON.stringify(pinned));
      }
      const artifact = path.join(tmp, `${name}.html`);
      execFileSync(process.execPath, [path.join(skillRoot, 'bin/archify.mjs'), 'deliver', 'workflow',
        input, artifact, '--quality', 'showcase', '--json'], { cwd: skillRoot });
      const result = await runVisualCheck({
        artifactPath: artifact, chromePath,
        browserFactory: async (executable) => {
          const browser = new ChromeVisualBrowser(executable);
          try {
            const session = await browser.sessionPromise;
            await browser.cdp.send('Network.enable', {}, session);
            await browser.cdp.send('Network.setBlockedURLs', { urls: ['http://*', 'https://*'] }, session);
            return browser;
          } catch (error) {
            await browser.close();
            throw error;
          }
        },
      });
      if (name === 'order-pinned-overflow') {
        assert.equal(result.exitCode, 1);
        const diagnostic = result.receipt.diagnostics.find(({ code }) => code === 'viewer/viewport-overflow');
        assert.ok(diagnostic, JSON.stringify(result.receipt));
        assert.equal(diagnostic.evidence.workflowLanes[0].frameId, 'lane-0');
        assert.equal(diagnostic.evidence.workflowLanes[0].nodeCount, 12);
        assert.ok(diagnostic.evidence.workflowLanes[0].spaceAboveNodesPx > 100);
      } else {
        assert.equal(result.exitCode, 0, JSON.stringify(result.receipt));
        assert.equal(result.receipt.containment.status, 'pass');
      }
    }
  } finally {
    fs.rmSync(tmp, { recursive: true, force: true });
  }
});

// Every unpinned three-lane, five-column workflow measures 528 viewBox units
// tall. Width-first reading enlarges it to 1.5x, so the 1600x1000 page ends
// 1px past the viewport. The Reader ignored overflow up to 1px while
// visual-check rejects any rounded-up remainder, so browser-check failed
// a first draft that every earlier gate had accepted.
test('a 1px width-first remainder is declared instead of failing browser containment', {
  skip: chromePath ? false : 'Set ARCHIFY_CHROME to run the real browser regression.',
}, async () => {
  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-reader-remainder-'));
  try {
    const artifact = path.join(tmp, 'three-lane-remainder.html');
    execFileSync(process.execPath, [path.join(skillRoot, 'bin/archify.mjs'), 'deliver', 'workflow',
      path.join(skillRoot, '..', 'test', 'fixtures/workflow-viewport/three-lane-remainder.workflow.json'),
      artifact, '--quality', 'showcase', '--json'], { cwd: skillRoot });
    assert.match(fs.readFileSync(artifact, 'utf8'), /viewBox="0 0 \d+ 528" data-reader-fit="width-first"/);
    const result = await runVisualCheck({ artifactPath: artifact, chromePath });
    assert.equal(result.exitCode, 0, JSON.stringify(result.receipt));
    assert.equal(result.receipt.containment.status, 'pass');
    const tall = result.receipt.containment.viewports.find(({ width, height }) => width === 1600 && height === 1000);
    assert.ok(tall, JSON.stringify(result.receipt.containment));
    assert.ok(tall.scrollHeight <= tall.innerHeight || tall.readerOverflow === 'authored', JSON.stringify(tall));
  } finally {
    fs.rmSync(tmp, { recursive: true, force: true });
  }
});

test('issue #250 tall intrinsic workflow uses reading width and permits readable page scroll', {
  skip: chromePath ? false : 'Set ARCHIFY_CHROME to run the real browser regression.',
}, async () => {
  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-issue-250-reader-'));
  const input = path.join(tmp, 'issue-250.workflow.json');
  const artifact = path.join(tmp, 'issue-250.html');
  try {
    fs.writeFileSync(input, `${JSON.stringify(issue250TallGroup, null, 2)}\n`);
    execFileSync(process.execPath, [
      path.join(skillRoot, 'bin', 'archify.mjs'),
      'render',
      'workflow',
      input,
      artifact,
      '--quality',
      'showcase',
    ], { cwd: skillRoot, encoding: 'utf8' });

    const result = await runVisualCheck({ artifactPath: artifact, chromePath });
    assert.equal(result.exitCode, 0, JSON.stringify(result.receipt, null, 2));
    assert.equal(result.receipt.containment.status, 'pass');
    assert.equal(result.receipt.readability.status, 'pass');
    assert.equal(result.receipt.viewerChrome.status, 'pass');
    assert.equal(result.receipt.containment.viewports.length, 4);
    for (const viewport of result.receipt.containment.viewports) {
      assert.equal(viewport.overflowX, false, JSON.stringify(viewport, null, 2));
      assert.equal(viewport.readerFit, 'width-first');
      assert.equal(viewport.overflowY, viewport.verticalScrollAccepted, JSON.stringify(viewport, null, 2));
      assert.ok(viewport.scrollHeight >= viewport.height, JSON.stringify(viewport, null, 2));
      assert.ok(viewport.diagramWidth <= viewport.viewBoxWidth * 1.5 + 1);
      assert.ok(viewport.minimumProjectedNodeTextPx >= MIN_PROJECTED_NODE_TEXT_PX);
    }
    assert.deepEqual(
      result.receipt.captures.screenshots.map(({ width, height, theme, resolvedTheme }) => ({
        width, height, theme, resolvedTheme,
      })),
      [
        { width: 1440, height: 900, theme: 'light', resolvedTheme: 'light' },
        { width: 1440, height: 900, theme: 'dark', resolvedTheme: 'dark' },
        { width: 2048, height: 1320, theme: 'light', resolvedTheme: 'light' },
        { width: 2048, height: 1320, theme: 'dark', resolvedTheme: 'dark' },
      ],
    );
  } finally {
    fs.rmSync(tmp, { recursive: true, force: true });
  }
});

test('issue #250 five-stage stack retains reading scale within the automatic enlargement cap', {
  skip: chromePath ? false : 'Set ARCHIFY_CHROME to run the real browser regression.',
}, async () => {
  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-issue-250-five-stage-'));
  const input = path.join(tmp, 'issue-250-five-stage.workflow.json');
  const artifact = path.join(tmp, 'issue-250-five-stage.html');
  try {
    fs.writeFileSync(input, `${JSON.stringify(issue250FiveStageGroup, null, 2)}\n`);
    execFileSync(process.execPath, [
      path.join(skillRoot, 'bin', 'archify.mjs'),
      'render',
      'workflow',
      input,
      artifact,
      '--quality',
      'showcase',
    ], { cwd: skillRoot, encoding: 'utf8' });

    const result = await runVisualCheck({ artifactPath: artifact, chromePath });
    assert.equal(result.exitCode, 0, JSON.stringify(result.receipt, null, 2));
    for (const viewport of result.receipt.containment.viewports) {
      assert.equal(viewport.overflowX, false, JSON.stringify(viewport, null, 2));
      assert.equal(viewport.readerFit, 'width-first');
      assert.equal(viewport.overflowY, viewport.verticalScrollAccepted, JSON.stringify(viewport, null, 2));
      assert.ok(viewport.scrollHeight >= viewport.height, JSON.stringify(viewport, null, 2));
      assert.ok(viewport.diagramWidth <= viewport.viewBoxWidth * 1.5 + 1);
      assert.ok(viewport.minimumProjectedNodeTextPx >= MIN_PROJECTED_NODE_TEXT_PX);
    }
    const desktop = result.receipt.containment.viewports.find(({ width, height }) => (
      width === DESKTOP_READABILITY_VIEWPORT.width && height === DESKTOP_READABILITY_VIEWPORT.height
    ));
    assert.ok(desktop);
    assert.ok(desktop.diagramWidth >= desktop.viewBoxWidth, 'use available reading width instead of shrinking the stack: ' + JSON.stringify(desktop, null, 2));
  } finally {
    fs.rmSync(tmp, { recursive: true, force: true });
  }
});

test('authored Architecture canvas keeps its scale and accepts readable document scrolling', {
  skip: chromePath ? false : 'Set ARCHIFY_CHROME to run the real browser regression.',
}, async t => {
  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-authored-reader-'));
  t.after(() => fs.rmSync(tmp, { recursive: true, force: true }));
  const input = path.join(tmp, 'fixed.json');
  const artifact = path.join(tmp, 'fixed.html');
  const doc = {
    schema_version: 1, diagram_type: 'architecture',
    meta: { title: 'Authored overview', output: 'fixed.html', viewBox: [1040, 700], quality_profile: 'showcase' },
    components: [
      { id: 'client', type: 'frontend', label: 'Client', pos: [40, 80], size: [130, 60] },
      { id: 'api', type: 'backend', label: 'API', pos: [300, 80], size: [140, 64] },
      { id: 'store', type: 'database', label: 'Store', pos: [300, 470], size: [140, 64] },
    ],
    connections: [{ from: 'client', to: 'api', label: 'request' }, { from: 'api', to: 'store', label: 'persist' }],
  };
  fs.writeFileSync(input, JSON.stringify(doc));
  execFileSync(process.execPath, [path.join(skillRoot, 'bin/archify.mjs'), 'render', 'architecture', input, artifact]);
  const html = fs.readFileSync(artifact, 'utf8');
  assert.match(html, /viewBox="0 0 1040 700"/);
  assert.match(html, /<rect x="300" y="470" width="140" height="64"/);
  const baseline = path.join(tmp, 'legacy.html');
  fs.writeFileSync(baseline, html.replace(' data-reader-fit="authored-height"', ''));
  const old = await runVisualCheck({ artifactPath: baseline, chromePath });
  assert.equal(old.exitCode, 1, 'legacy page rejects ordinary document overflow');
  const result = await runVisualCheck({ artifactPath: artifact, chromePath });
  assert.equal(result.exitCode, 0, JSON.stringify(result.receipt.diagnostics));
  for (const viewport of result.receipt.containment.viewports) {
    const before = old.receipt.containment.viewports.find(v => v.width === viewport.width);
    assert.equal(viewport.diagramWidth, before.diagramWidth, 'keep the approved page scale');
    assert.equal(viewport.readerWidth, before.readerWidth);
    assert.equal(viewport.readerLayout, before.readerLayout);
    assert.equal(viewport.readerFit, 'authored-height');
    assert.equal(viewport.overflowX, false);
    if (viewport.overflowY) assert.equal(viewport.verticalScrollAccepted, true);
  }
  for (const overflow of ['hidden', 'auto']) {
    const clipped = path.join(tmp, `clipped-${overflow}.html`);
    fs.writeFileSync(clipped, html.replace('</head>', `<style>.diagram-container { height: 300px !important; overflow: ${overflow} !important; }</style></head>`));
    const failed = await runVisualCheck({ artifactPath: clipped, chromePath });
    assert.equal(failed.exitCode, 1);
    assert.ok(failed.receipt.diagnostics.some(d => d.code === 'viewer/diagram-clipped'), JSON.stringify(failed.receipt.diagnostics));
  }
});