Skip to content

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

143 KB
Raw Blame
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { spawnSync } from 'node:child_process';
import { createHash } from 'node:crypto';
import { EventEmitter } from 'node:events';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { PassThrough } from 'node:stream';
import { fileURLToPath, pathToFileURL } from 'node:url';

import {
  CHROME_STARTUP_TIMEOUT_MS,
  verticalBudgetFixes,
  ChromeVisualBrowser,
  VISUAL_CHECK_VIEWPORTS,
  chromeVisualBrowserArgs,
  findChrome,
  persistVisualCheckFailure,
  runVisualCheck,
  runBrowserCheck,
  browserCheckSidecarPaths,
  sidecarPaths,
  summarizeBrowserEvidence,
} from '../archify/bin/visual-check.mjs';
import { sameLocation } from '../archify/renderers/shared/path-semantics.mjs';

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const skillRoot = path.resolve(__dirname, '..', 'archify');
const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-visual-check-'));
const png = Buffer.from('89504e470d0a1a0a', 'hex');

test('summary indexes every captured viewport/theme and preserves failed diagnostics', async () => {
  const input = artifact('summary-captures.html');
  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: () => fakeBrowser(),
  });
  const receipt = result.receipt;
  const summary = summarizeBrowserEvidence(receipt);
  assert.equal(summary.visualReview, 'pending');
  assert.equal(summary.evidence.screenshots.length, 4);
  for (const capture of summary.evidence.screenshots) {
    assert.ok(path.isAbsolute(capture.path));
    assert.ok(fs.existsSync(capture.path));
    assert.ok(['light', 'dark'].includes(capture.theme));
  }
  assert.deepEqual(summary.evidence.screenshots.map(({ width, height, theme }) => [width, height, theme]),
    receipt.captures.screenshots.map(({ width, height, theme }) => [width, height, theme]));
  assert.ok(fs.existsSync(summary.evidence.receipt));
  assert.ok(fs.existsSync(summary.evidence.contactSheet));
  assert.ok(JSON.stringify(summary).length < JSON.stringify(receipt).length / 2);
  const diagnostic = { code: 'viewer/example', severity: 'error', evidence: { gap: 3 }, supportedFixes: ['reposition'] };
  const failed = summarizeBrowserEvidence({ ...receipt, ok: false, status: 'fail', diagnostics: [diagnostic] });
  assert.equal(failed.ok, false);
  assert.equal(failed.status, 'fail');
  assert.deepEqual(failed.diagnostics, [diagnostic]);
  assert.equal(failed.evidence.receipt, undefined);
  assert.equal(failed.evidence.contactSheet, undefined);
  assert.deepEqual(failed.evidence.screenshots, [], 'unpublished capture metadata is not an evidence link');
});

function artifact(name = 'diagram.html') {
  const file = path.join(tmp, name);
  fs.writeFileSync(file, '<!doctype html><html><body>checked artifact</body></html>');
  return file;
}

function sha256(file) {
  return createHash('sha256').update(fs.readFileSync(file)).digest('hex');
}

function entryIdentity(file) {
  const stat = fs.lstatSync(file, { bigint: true });
  return { device: stat.dev, inode: stat.ino, mode: stat.mode };
}

function stagingDirectories(directory) {
  return fs.readdirSync(directory).filter((name) => name.startsWith('.archify-visual-check-'));
}

function fakeBrowser({
  overflowAt,
  tallAt,
  readableScrollAt,
  automaticReaderFit = 'intrinsic-height',
  authoredScrollAt,
  authoredDiagramType = 'architecture',
  authoredUnclipped = true,
  unreadableAt,
  chromeCollisionAt,
  stageCollisionAt,
  stageGapAt,
  screenshotFailure,
  resolvedThemeAt,
} = {}) {
  const calls = [];
  return {
    calls,
    async inspect({ width, height, theme, screenshotPath, writeScreenshot }) {
      calls.push({ width, height, theme, screenshotPath });
      if (screenshotPath && screenshotFailure?.({ width, height, theme })) {
        throw new Error('synthetic screenshot failure');
      }
      if (screenshotPath) {
        if (writeScreenshot) writeScreenshot(png);
        else fs.writeFileSync(screenshotPath, png, { flag: 'wx' });
      }
      const overflow = overflowAt?.({ width, height, theme }) || false;
      const tall = tallAt?.({ width, height, theme }) || false;
      const readableScroll = readableScrollAt?.({ width, height, theme }) || false;
      const authoredScroll = authoredScrollAt?.({ width, height, theme }) || false;
      const unreadable = unreadableAt?.({ width, height, theme }) || false;
      const chromeCollision = chromeCollisionAt?.({ width, height, theme }) || false;
      const stageCollision = stageCollisionAt?.({ width, height, theme }) || false;
      const dockStageGap = stageGapAt?.({ width, height, theme }) ?? (stageCollision ? -12 : 10);
      const stageClearanceFailure = stageCollision || dockStageGap < 10;
      return {
        innerWidth: width,
        innerHeight: height,
        scrollWidth: width + (overflow ? 1 : 0),
        scrollHeight: height + (readableScroll || authoredScroll ? 240 : 0) + (tall ? 300 : 0),
        resolvedTheme: resolvedThemeAt?.({ width, height, theme }) ?? theme,
        ...(tall ? {
          pageComposition: {
            bodyPaddingPx: 12, headerPx: 100, diagramChromePx: 76,
            svgPx: 800, cardsPx: 212, viewBoxHeight: 1000,
          },
        } : {}),
        readerLayout: readableScroll ? 'adaptive' : null,
        readerOverflow: readableScroll ? 'authored' : null,
        readerFit: readableScroll ? automaticReaderFit : authoredScroll ? 'authored-height' : null,
        diagramType: authoredScroll ? authoredDiagramType : null,
        documentScrollUnclipped: authoredScroll && authoredUnclipped,
        readerWidth: 960,
        diagramWidth: 930,
        viewBoxWidth: 1300,
        minimumProjectedNodeTextPx: unreadable ? 5.72 : 6.44,
        minimumProjectedNodeText: unreadable ? 'Compact node' : 'Readable node',
        minimumProjectedNodeTextDetail: unreadable ? 'primary' : 'context',
        hasLegend: true,
        hasNavigationDock: true,
        legendDockIntersectionArea: chromeCollision ? 42 : 0,
        dockStageIntersectionArea: stageCollision ? 84 : 0,
        dockStageGap,
        viewerChromeRequiredGap: 10,
        viewerChromeReserve: chromeCollision || stageClearanceFailure ? 0 : 44,
        viewerChromeActive: !chromeCollision && !stageClearanceFailure,
      };
    },
    async close() {},
  };
}

function fakeChromeChild() {
  const child = new EventEmitter();
  child.exitCode = null;
  child.signalCode = null;
  child.stderr = new PassThrough();
  child.stdio = [null, null, child.stderr, new PassThrough(), new PassThrough()];
  child.kill = (signal) => {
    child.signalCode = signal;
    queueMicrotask(() => {
      child.emit('exit', null, signal);
      child.emit('close', null, signal);
    });
    return true;
  };
  return child;
}

test('findChrome discovers chrome.exe from a Windows PATH after default locations', () => {
  const checked = [];
  const expected = String.raw`D:\Browser Bin\chrome.EXE`;
  const resolved = findChrome({
    platform: 'win32',
    env: {
      PROGRAMFILES: String.raw`C:\Program Files`,
      PATH: String.raw`C:\Tools;D:\Browser Bin`,
      PATHEXT: '.EXE;.CMD',
    },
    resolveExecutable(candidate) {
      checked.push(candidate);
      return candidate === expected ? candidate : null;
    },
  });

  assert.equal(resolved, expected);
  assert.deepEqual(checked.slice(0, 2), [
    String.raw`C:\Program Files\Google\Chrome\Application\chrome.exe`,
    String.raw`C:\Program Files\Chromium\Application\chrome.exe`,
  ]);
  assert.ok(
    checked.indexOf(String.raw`C:\Program Files\Chromium\Application\chrome.exe`)
      < checked.indexOf(String.raw`C:\Tools\chrome.EXE`),
    'default install locations must be checked before PATH',
  );
});

test('findChrome keeps an installed Windows Chrome ahead of PATH candidates', () => {
  const checked = [];
  const installed = String.raw`C:\Program Files\Google\Chrome\Application\chrome.exe`;
  const portable = String.raw`D:\Browser Bin\chrome.EXE`;
  const resolved = findChrome({
    platform: 'win32',
    env: {
      PROGRAMFILES: String.raw`C:\Program Files`,
      PATH: String.raw`D:\Browser Bin`,
      PATHEXT: '.EXE',
    },
    resolveExecutable(candidate) {
      checked.push(candidate);
      return candidate === installed || candidate === portable ? candidate : null;
    },
  });

  assert.equal(resolved, installed);
  assert.deepEqual(checked, [installed]);
});

test('findChrome checks Chromium command names on a Windows PATH', () => {
  const checked = [];
  const expected = String.raw`D:\Browser Bin\chromium.EXE`;
  const resolved = findChrome({
    platform: 'win32',
    env: {
      PATH: String.raw`D:\Browser Bin`,
      PATHEXT: '.EXE',
    },
    resolveExecutable(candidate) {
      checked.push(candidate);
      return candidate === expected ? candidate : null;
    },
  });

  assert.equal(resolved, expected);
  assert.deepEqual(checked, [
    String.raw`D:\Browser Bin\chrome.EXE`,
    String.raw`D:\Browser Bin\google-chrome.EXE`,
    String.raw`D:\Browser Bin\google-chrome-stable.EXE`,
    expected,
  ]);
});

test('findChrome discovers Edge in each standard Windows installation root', () => {
  for (const [name, root] of [
    ['ProgramFiles(x86)', String.raw`C:\Program Files (x86)`],
    ['ProgramFiles', String.raw`D:\Program Files`],
    ['LocalAppData', String.raw`C:\Users\tester\AppData\Local`],
  ]) {
    const expected = path.win32.join(root, 'Microsoft', 'Edge', 'Application', 'msedge.exe');
    assert.equal(findChrome({
      platform: 'win32', env: { [name]: root },
      resolveExecutable: (candidate) => candidate === expected ? candidate : null,
    }), expected, name);
  }
});

test('findChrome finds a real Windows filesystem Edge entry with mixed-case environment names', {
  skip: process.platform !== 'win32',
}, () => {
  const root = fs.mkdtempSync(path.join(tmp, 'Edge Install '));
  const installed = path.join(root, 'Microsoft', 'Edge', 'Application', 'msedge.exe');
  fs.mkdirSync(path.dirname(installed), { recursive: true });
  fs.writeFileSync(installed, 'discovery fixture only; not a browser');
  try {
    assert.equal(findChrome({ env: { 'ProgramFiles(x86)': root } }), installed);
    assert.equal(findChrome({ env: { Path: path.dirname(installed), PathExt: '.EXE' } }).toLowerCase(), installed.toLowerCase());
  } finally {
    fs.rmSync(root, { recursive: true, force: true });
  }
});

test('findChrome keeps explicit browser overrides authoritative even when invalid', () => {
  const edge = String.raw`D:\Portable Edge\msedge.exe`;
  for (const override of [edge, '', String.raw`D:\missing.exe`]) {
    const checked = [];
    const resolved = findChrome({
      platform: 'win32',
      env: { ARCHIFY_CHROME: override, PROGRAMFILES: String.raw`C:\Program Files` },
      resolveExecutable(candidate) {
        checked.push(candidate);
        return candidate === edge ? candidate : null;
      },
    });
    assert.equal(resolved, override === edge ? edge : null);
    assert.deepEqual(checked, [override], 'an invalid explicit path must not silently use another browser');
  }
});

test('findChrome prefers every Chrome/Chromium PATH candidate over installed Edge', () => {
  const edge = String.raw`C:\Program Files\Microsoft\Edge\Application\msedge.exe`;
  for (const command of ['chrome', 'google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser']) {
    const preferred = String.raw`D:\Browser Bin` + `\\${command}.EXE`;
    assert.equal(findChrome({
      platform: 'win32',
      env: { PROGRAMFILES: String.raw`C:\Program Files`, PATH: String.raw`D:\Browser Bin`, PATHEXT: '.EXE' },
      resolveExecutable: (candidate) => [preferred, edge].includes(candidate) ? candidate : null,
    }), preferred, command);
  }
});

test('findChrome checks installed Edge before its Windows PATH fallback', () => {
  const installed = String.raw`C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`;
  const portable = String.raw`D:\Browser Bin\msedge.EXE`;
  const env = {
    'ProgramFiles(x86)': String.raw`C:\Program Files (x86)`,
    Path: String.raw`C:\Tools;D:\Browser Bin`,
    PathExt: '.EXE;.CMD',
  };
  for (const found of [[installed, portable], [portable]]) {
    const checked = [];
    const resolved = findChrome({
      platform: 'win32', env,
      resolveExecutable(candidate) {
        checked.push(candidate);
        return found.includes(candidate) ? candidate : null;
      },
    });
    assert.equal(resolved, found[0]);
    assert.ok(checked.includes(installed));
    if (found.length === 1) assert.ok(checked.indexOf(installed) < checked.indexOf(portable));
    else assert.equal(checked.includes(portable), false);
  }
});

test('findChrome discovers Edge from the macOS application bundle', () => {
  const expected = '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge';
  assert.equal(findChrome({
    platform: 'darwin', env: { PATH: '/usr/bin' },
    resolveExecutable: (candidate) => candidate === expected ? candidate : null,
  }), expected);
});

test('findChrome finds microsoft-edge command names on a macOS or Linux PATH', () => {
  for (const platform of ['darwin', 'linux']) {
    for (const command of ['microsoft-edge', 'microsoft-edge-stable']) {
      const expected = `/usr/bin/${command}`;
      assert.equal(findChrome({
        platform, env: { PATH: '/usr/bin' },
        resolveExecutable: (candidate) => candidate === expected ? candidate : null,
      }), expected, `${platform}:${command}`);
    }
  }
});

test('findChrome keeps Chrome/Chromium ahead of Edge on macOS and Linux', () => {
  for (const platform of ['darwin', 'linux']) {
    const chrome = platform === 'darwin'
      ? '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
      : '/usr/bin/google-chrome';
    const edge = platform === 'darwin'
      ? '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'
      : '/usr/bin/microsoft-edge';
    assert.equal(findChrome({
      platform, env: { PATH: '/usr/bin' },
      resolveExecutable: (candidate) => [chrome, edge].includes(candidate) ? candidate : null,
    }), chrome, platform);
  }
});

test('findChrome returns null when no browser is found and probes Edge on non-Windows', () => {
  for (const platform of ['win32', 'darwin', 'linux']) {
    const checked = [];
    assert.equal(findChrome({
      platform, env: { PATH: '/usr/bin', PROGRAMFILES: String.raw`C:\Program Files` },
      resolveExecutable(candidate) { checked.push(candidate); return null; },
    }), null, platform);
    if (platform !== 'win32') {
      assert.ok(checked.some((candidate) => /edge/i.test(candidate)), `${platform} probes Edge candidates`);
    }
  }
});

test('visual-check disables the Chrome sandbox only for root or an explicit environment opt-in', () => {
  const profileRoot = path.join(tmp, 'chrome-profile');
  const ordinary = chromeVisualBrowserArgs(profileRoot, { env: {}, getuid: () => 1001 });
  const optedIn = chromeVisualBrowserArgs(profileRoot, {
    env: { ARCHIFY_CHROME_NO_SANDBOX: '1' },
    getuid: () => 1001,
  });
  const root = chromeVisualBrowserArgs(profileRoot, { env: {}, getuid: () => 0 });

  assert.equal(ordinary.includes('--no-sandbox'), false);
  assert.equal(optedIn.includes('--no-sandbox'), true);
  assert.equal(root.includes('--no-sandbox'), true);
});

test('Windows browser launch removes only the standalone inherited app-health layer', async () => {
  for (const [key, layer] of [
    ['__COMPAT_LAYER', 'DetectorsAppHealth'],
    ['__compat_layer', 'detectorsapphealth'],
    ['__Compat_Layer', '  DetectorsAppHealth  '],
  ]) {
    const env = Object.freeze({
      [key]: layer,
      Path: String.raw`C:\Windows\System32`,
      SystemRoot: String.raw`C:\Windows`,
      TEMP: String.raw`C:\Temp`,
      ARCHIFY_CHROME_NO_SANDBOX: '0',
      UNRELATED_SETTING: 'preserved',
    });
    const child = fakeChromeChild();
    let launched;
    const browser = new ChromeVisualBrowser('/fake/msedge.exe', {
      platform: 'win32', env, getuid: null,
      spawnImpl: (executable, args, options) => {
        launched = { executable, args, options };
        return child;
      },
    });
    const attached = browser.sessionPromise.catch(() => {});
    try {
      assert.equal(launched.executable, '/fake/msedge.exe');
      assert.equal(Object.hasOwn(launched.options.env, key), false);
      assert.deepEqual(launched.options.env, Object.fromEntries(
        Object.entries(env).filter(([name]) => name !== key),
      ));
      assert.equal(env[key], layer, 'the parent environment is untouched');
      assert.deepEqual(launched.args, chromeVisualBrowserArgs(browser.profileRoot, { env, getuid: null }));
      assert.ok(launched.args.includes('--remote-debugging-pipe'));
      assert.ok(launched.args.includes(`--user-data-dir=${browser.profileRoot}`));
      assert.equal(launched.args.includes('--no-sandbox'), false);
      assert.equal(launched.args.includes('--do-not-de-elevate'), false);
      assert.equal(launched.args.includes('--edge-skip-compat-layer-relaunch'), false);
      assert.deepEqual(launched.options.stdio, ['ignore', 'ignore', 'pipe', 'pipe', 'pipe']);
    } finally {
      await browser.close();
      await attached;
    }
    assert.equal(fs.existsSync(browser.profileRoot), false);
  }
});

test('browser launch preserves unknown, combined and non-Windows compatibility layers', async () => {
  for (const [platform, layer] of [
    ['win32', 'Installer'],
    ['win32', 'RunAsInvoker'],
    ['win32', 'DetectorsAppHealth RunAsInvoker'],
    ['win32', 'UnknownLayer'],
    ['darwin', 'DetectorsAppHealth'],
    ['linux', 'DetectorsAppHealth'],
  ]) {
    const env = Object.freeze({ __COMPAT_LAYER: layer, UNRELATED_SETTING: 'preserved' });
    const child = fakeChromeChild();
    let spawnOptions;
    const browser = new ChromeVisualBrowser('/fake/chrome', {
      platform, env, getuid: () => 1001,
      spawnImpl: (_executable, _args, options) => {
        spawnOptions = options;
        return child;
      },
    });
    const attached = browser.sessionPromise.catch(() => {});
    try {
      assert.deepEqual(spawnOptions.env, env, `${platform}: ${layer}`);
    } finally {
      await browser.close();
      await attached;
    }
    assert.equal(fs.existsSync(browser.profileRoot), false);
  }
});

test('browser environment defaults to the actual host platform', async () => {
  const env = Object.freeze({ __COMPAT_LAYER: 'DetectorsAppHealth' });
  const child = fakeChromeChild();
  let spawnOptions;
  const browser = new ChromeVisualBrowser('/fake/chrome', {
    env, getuid: () => 1001,
    spawnImpl: (_executable, _args, options) => {
      spawnOptions = options;
      return child;
    },
  });
  const attached = browser.sessionPromise.catch(() => {});
  try {
    assert.deepEqual(spawnOptions.env, process.platform === 'win32' ? {} : env);
  } finally {
    await browser.close();
    await attached;
  }
});

test('browser relaunch hint is absent after a response or on non-Windows hosts', async () => {
  for (const [platform, response] of [['win32', true], ['linux', false], ['darwin', false]]) {
    const child = fakeChromeChild();
    const browser = new ChromeVisualBrowser('/fake/chrome', {
      platform, env: {}, getuid: () => 1001, spawnImpl: () => child,
    });
    try {
      const failed = assert.rejects(browser.sessionPromise, (error) => {
        assert.doesNotMatch(error.message, /Windows browser startup/);
        return true;
      });
      if (response) child.stdio[4].write('{"method":"Target.targetCreated","params":{}}\0');
      child.stdio[4].end();
      await failed;
    } finally {
      await browser.close();
    }
  }
});

test('Windows pipe startup failure provides a non-elevated remedy without claiming its cause', async () => {
  const child = fakeChromeChild();
  const browser = new ChromeVisualBrowser('/fake/msedge.exe', {
    platform: 'win32', env: {}, getuid: null, spawnImpl: () => child,
  });
  try {
    const failed = assert.rejects(browser.sessionPromise, (error) => {
      assert.match(error.message, /receivedBytes=0/);
      assert.match(error.message, /Windows browser startup may have relaunched/);
      assert.match(error.message, /non-elevated PowerShell/);
      assert.match(error.message, /does not disable browser de-elevation or the sandbox/);
      return true;
    });
    child.stdio[4].end();
    await failed;
  } finally {
    await browser.close();
  }
  assert.equal(fs.existsSync(browser.profileRoot), false);
});

test('visual-check converts a Chrome DevTools pipe reset and captured stderr into a structured failure', async () => {
  const input = artifact('chrome-pipe-reset.html');
  const child = fakeChromeChild();

  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => {
      const browser = new ChromeVisualBrowser('/fake/chrome', {
        env: { ARCHIFY_CHROME_NO_SANDBOX: '1' },
        getuid: () => 1001,
        spawnImpl: () => child,
      });
      setImmediate(() => {
        child.stderr.write('Chrome sandbox initialization failed\n');
        const error = new Error('read ECONNRESET');
        error.code = 'ECONNRESET';
        child.stdio[4].emit('error', error);
      });
      return browser;
    },
  });

  assert.equal(result.exitCode, 1);
  assert.equal(result.receipt.status, 'fail');
  assert.match(result.receipt.error, /Chrome DevTools read pipe failed/);
  assert.match(result.receipt.error, /ECONNRESET/);
  assert.match(result.receipt.error, /Chrome sandbox initialization failed/);
  assert.equal(result.receipt.diagnostics[0]?.code, 'viewer/visual-check-runtime');
  assert.match(result.receipt.diagnostics[0]?.evidence?.reason || '', /ECONNRESET/);
  assert.equal(fs.existsSync(sidecarPaths(input).receipt), true);
});

test('visual-check reports Chrome early exit status and stderr without an uncaught exception', async () => {
  const input = artifact('chrome-early-exit.html');
  const child = fakeChromeChild();

  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => {
      const browser = new ChromeVisualBrowser('/fake/chrome', {
        env: { ARCHIFY_CHROME_NO_SANDBOX: '1' },
        getuid: () => 1001,
        spawnImpl: () => child,
      });
      setImmediate(() => {
        child.stderr.write('Chrome rejected its launch flags\n');
        child.exitCode = 23;
        child.emit('close', 23, null);
      });
      return browser;
    },
  });

  assert.equal(result.exitCode, 1);
  assert.equal(result.receipt.status, 'fail');
  assert.match(result.receipt.error, /Chrome DevTools process exit failed/);
  assert.match(result.receipt.error, /exit code 23/);
  assert.match(result.receipt.error, /Chrome rejected its launch flags/);
  assert.equal(result.receipt.diagnostics[0]?.code, 'viewer/visual-check-runtime');
});

test('visual-check records four containment viewports and four endpoint theme captures', async () => {
  const input = artifact('passing.html');
  const before = sha256(input);
  const browser = fakeBrowser();
  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    deliveryProvenance: { status: 'current', receiptId: 'delivery-receipt-123' },
    browserFactory: async () => browser,
  });

  assert.equal(result.exitCode, 0);
  assert.equal(result.receipt.status, 'pass');
  assert.equal(result.receipt.evidenceKind, 'automated-browser');
  assert.equal(result.receipt.provenance, 'current');
  assert.equal(result.receipt.deliveryReceiptId, 'delivery-receipt-123');
  assert.deepEqual(result.receipt.diagnostics, []);
  assert.equal(result.receipt.visualReview, 'pending');
  assert.equal(result.receipt.viewerChrome.status, 'pass');
  assert.equal(result.receipt.containment.viewports.length, VISUAL_CHECK_VIEWPORTS.length);
  assert.equal(result.receipt.containment.viewports.every((entry) => entry.ok), true);
  assert.deepEqual(
    result.receipt.captures.screenshots.map(({ width, height, theme }) => [width, height, theme]),
    [
      [1440, 900, 'light'],
      [1440, 900, 'dark'],
      [2048, 1320, 'light'],
      [2048, 1320, 'dark'],
    ],
  );
  assert.equal(result.receipt.artifact.sha256, before);
  assert.equal(sha256(input), before, 'visual-check mutated the delivered artifact');

  const outputs = sidecarPaths(input);
  assert.equal(fs.existsSync(outputs.receipt), true);
  assert.equal(JSON.parse(fs.readFileSync(outputs.receipt, 'utf8')).deliveryReceiptId, 'delivery-receipt-123');
  assert.equal(fs.existsSync(outputs.contactSheet), true);
  assert.equal(outputs.screenshots.every((entry) => fs.existsSync(entry.path)), true);
  const contactSheet = fs.readFileSync(outputs.contactSheet, 'utf8');
  assert.match(contactSheet, /Automated browser evidence/);
  assert.match(contactSheet, /perceptual visual review pending/);
  for (const screenshot of outputs.screenshots) {
    assert.match(contactSheet, new RegExp(path.basename(screenshot.path).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
    assert.doesNotMatch(contactSheet, new RegExp(screenshot.path.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
  }
});

test('visual-check inspects a private snapshot even if the public artifact is replaced and restored', async () => {
  const input = artifact('private-inspection-snapshot.html');
  const original = fs.readFileSync(input);
  const displaced = path.join(tmp, 'private-inspection-original.html');
  const replacement = Buffer.from('<!doctype html><title>replacement must not be inspected</title>');
  const browser = fakeBrowser();
  const inspect = browser.inspect.bind(browser);
  const inspectedPaths = [];
  let calls = 0;
  browser.inspect = async (args) => {
    inspectedPaths.push(path.resolve(args.artifactPath));
    assert.deepEqual(fs.readFileSync(args.artifactPath), original);
    calls += 1;
    if (calls === 1) {
      fs.renameSync(input, displaced);
      fs.writeFileSync(input, replacement, { flag: 'wx' });
    }
    if (calls === 6) {
      fs.unlinkSync(input);
      fs.renameSync(displaced, input);
    }
    return inspect(args);
  };

  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => browser,
  });

  assert.equal(result.exitCode, 0, JSON.stringify(result.receipt.diagnostics));
  assert.equal(inspectedPaths.length, 6);
  assert.equal(inspectedPaths.every((candidate) => candidate !== path.resolve(input)), true);
  assert.deepEqual(fs.readFileSync(input), original);
});

for (const browserFailure of [false, true]) {
  test(`visual-check uses and retires a short local snapshot with long evidence paths${browserFailure ? ' after a browser failure' : ''}`, async (t) => {
    const input = artifact(`local-inspection-${browserFailure}.html`);
    const original = fs.readFileSync(input);
    const originalDigest = sha256(input);
    const root = fs.mkdtempSync(path.join(tmp, 'long-evidence-'));
    const outDir = path.join(root, ...Array.from({ length: 5 }, (_, index) => `${index}-${'long'.repeat(16)}`));
    t.after(() => fs.rmSync(root, { recursive: true, force: true }));
    const browser = fakeBrowser();
    const inspect = browser.inspect.bind(browser);
    let inspectionPath;
    browser.inspect = async (args) => {
      inspectionPath = args.artifactPath;
      const inspectionParent = path.dirname(path.dirname(inspectionPath));
      assert.equal(sameLocation(inspectionParent, os.tmpdir()).status, 'match');
      assert.ok(inspectionPath.length < outDir.length);
      assert.deepEqual(fs.readFileSync(inspectionPath), original);
      assert.equal(sha256(inspectionPath), originalDigest);
      if (args.screenshotPath) {
        assert.equal(sameLocation(path.dirname(path.dirname(args.screenshotPath)), outDir).status, 'match');
      }
      if (browserFailure) throw new Error('synthetic local snapshot browser failure');
      return inspect(args);
    };

    const result = await runVisualCheck({
      artifactPath: input,
      outDir,
      chromePath: '/fake/chrome',
      browserFactory: async () => browser,
    });

    assert.equal(result.exitCode, browserFailure ? 1 : 0, JSON.stringify(result.receipt.diagnostics));
    assert.ok(inspectionPath);
    assert.equal(fs.existsSync(inspectionPath), false);
    assert.equal(fs.existsSync(path.dirname(inspectionPath)), false);
    assert.deepEqual(stagingDirectories(outDir), []);
    assert.equal(fs.existsSync(sidecarPaths(input, { outDir }).receipt), true);
    if (browserFailure) assert.match(result.receipt.error, /synthetic local snapshot browser failure/);
  });
}

test('visual-check retains and reports a local inspection directory that cannot be removed', async (t) => {
  const input = artifact('local-inspection-rmdir-failure.html');
  const browser = fakeBrowser();
  const inspect = browser.inspect.bind(browser);
  const rmdirSync = fs.rmdirSync.bind(fs);
  let inspectionDirectory;
  browser.inspect = async (args) => {
    inspectionDirectory = path.dirname(args.artifactPath);
    return inspect(args);
  };
  t.mock.method(fs, 'rmdirSync', (directory, ...args) => {
    if (String(directory) === inspectionDirectory) {
      throw Object.assign(new Error('synthetic local inspection directory removal failure'), { code: 'EACCES' });
    }
    return rmdirSync(directory, ...args);
  });
  t.after(() => {
    t.mock.restoreAll();
    if (inspectionDirectory) fs.rmSync(inspectionDirectory, { recursive: true, force: true });
  });

  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => browser,
  });

  assert.equal(result.exitCode, 1);
  assert.equal(sameLocation(path.dirname(inspectionDirectory), os.tmpdir()).status, 'match');
  assert.equal(result.receipt.publication?.status, 'committed-with-warning');
  assert.equal(result.receipt.publication?.recoveryDirectory, inspectionDirectory);
  assert.ok(result.receipt.publication.cleanupErrors.some((entry) => entry.file === inspectionDirectory));
  assert.deepEqual(fs.readdirSync(inspectionDirectory), []);
});

test('visual-check reports the retained local snapshot directory when its identity is unavailable', async (t) => {
  const input = artifact('local-inspection-unknown-identity.html');
  const lstatSync = fs.lstatSync.bind(fs);
  let inspectionDirectory;
  let browserStarted = false;
  t.mock.method(fs, 'lstatSync', (file, ...args) => {
    const stat = lstatSync(file, ...args);
    if (!inspectionDirectory && path.basename(String(file)).startsWith('archify-inspection-')) {
      inspectionDirectory = String(file);
      stat.ino = 0n;
    }
    return stat;
  });
  t.after(() => {
    if (inspectionDirectory) fs.rmSync(inspectionDirectory, { recursive: true, force: true });
  });

  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => {
      browserStarted = true;
      return fakeBrowser();
    },
  });

  assert.equal(result.exitCode, 1);
  assert.equal(browserStarted, false);
  assert.equal(result.receipt.diagnostics[0]?.code, 'viewer/artifact-snapshot');
  assert.ok(result.receipt.diagnostics.at(-1)?.evidence?.errors.some(
    (entry) => entry.file === inspectionDirectory && entry.recoveryDirectory === inspectionDirectory,
  ));
  assert.deepEqual(fs.readdirSync(inspectionDirectory), []);
});

for (const claimantFile of [false, true]) {
  test(`visual-check preserves a replacement local snapshot directory${claimantFile ? ' containing a file' : ' that is empty'} and reports its location`, async (t) => {
    const input = artifact(`local-inspection-directory-claimant-${claimantFile}.html`);
    const sentinel = 'external local snapshot directory claimant\n';
    let inspectionDirectory;
    let detached;
    let claimantPath;
    t.after(() => {
      if (inspectionDirectory) fs.rmSync(inspectionDirectory, { recursive: true, force: true });
      if (detached) fs.rmSync(detached, { recursive: true, force: true });
    });
    const result = await runVisualCheck({
      artifactPath: input,
      chromePath: '/fake/chrome',
      browserFactory: async () => ({
        async inspect({ artifactPath }) {
          inspectionDirectory = path.dirname(artifactPath);
          detached = `${inspectionDirectory}-detached`;
          fs.renameSync(inspectionDirectory, detached);
          fs.mkdirSync(inspectionDirectory);
          claimantPath = path.join(inspectionDirectory, 'artifact-snapshot.html');
          if (claimantFile) fs.writeFileSync(claimantPath, sentinel, { flag: 'wx' });
          throw new Error('synthetic browser failure after directory replacement');
        },
        async close() {},
      }),
    });

    assert.equal(result.exitCode, 1);
    assert.equal(sameLocation(path.dirname(inspectionDirectory), os.tmpdir()).status, 'match');
    if (claimantFile) assert.equal(fs.readFileSync(claimantPath, 'utf8'), sentinel);
    else assert.deepEqual(fs.readdirSync(inspectionDirectory), []);
    const errors = result.receipt.diagnostics.at(-1)?.evidence?.errors;
    assert.ok(errors.some((entry) => entry.file === inspectionDirectory
      && entry.recoveryDirectory === inspectionDirectory
      && /identity changed; it was preserved/.test(entry.reason)));
    assert.equal(fs.existsSync(path.join(detached, 'artifact-snapshot.html')), true);
  });
}

for (const scenario of [
  { name: 'a regular screenshot claimant swapped before registration', replace: true },
  { name: 'screenshot bytes changed after capture without an identity change', replace: false },
]) {
  test(`visual-check preserves ${scenario.name}`, async (t) => {
    const input = artifact(`staged-screenshot-regular-claimant-${scenario.replace}.html`);
    const outputs = sidecarPaths(input);
    const browser = fakeBrowser();
    const inspect = browser.inspect.bind(browser);
    const sentinel = Buffer.from('external regular screenshot claimant\n');
    const stagingBefore = new Set(stagingDirectories(path.dirname(outputs.receipt)));
    let claimantPath;
    browser.inspect = async (args) => {
      const metrics = await inspect(args);
      if (!claimantPath && args.screenshotPath) {
        claimantPath = args.screenshotPath;
        const before = entryIdentity(claimantPath);
        if (scenario.replace) fs.unlinkSync(claimantPath);
        fs.writeFileSync(claimantPath, sentinel, { flag: scenario.replace ? 'wx' : 'w' });
        if (!scenario.replace) assert.deepEqual(entryIdentity(claimantPath), before);
      }
      return metrics;
    };
    t.after(() => {
      for (const directory of stagingDirectories(path.dirname(outputs.receipt))) {
        if (!stagingBefore.has(directory)) {
          fs.rmSync(path.join(path.dirname(outputs.receipt), directory), { recursive: true, force: true });
        }
      }
    });

    const result = await runVisualCheck({
      artifactPath: input,
      chromePath: '/fake/chrome',
      browserFactory: async () => browser,
    });

    assert.equal(result.exitCode, 1);
    assert.deepEqual(fs.readFileSync(claimantPath), sentinel);
    assert.equal(fs.existsSync(outputs.receipt), false);
    const cleanupErrors = result.receipt.diagnostics.at(-1)?.evidence?.errors;
    assert.ok(cleanupErrors.some((entry) => entry.file === claimantPath && /preserved/.test(entry.reason)));
  });
}

test('visual-check cleanup preserves a successor swapped at its final removal boundary', async (t) => {
  const input = artifact('staged-cleanup-successor.html');
  const outputs = sidecarPaths(input);
  const detached = path.join(tmp, 'detached-owned-artifact-snapshot.html');
  const successor = Buffer.from('external artifact snapshot cleanup successor\n');
  const unlinkSync = fs.unlinkSync.bind(fs);
  const renameSync = fs.renameSync.bind(fs);
  let stagedPath;
  let injected = false;
  const inject = (source) => {
    injected = true;
    stagedPath = String(source);
    renameSync(stagedPath, detached);
    fs.writeFileSync(stagedPath, successor, { flag: 'wx' });
  };
  t.mock.method(fs, 'unlinkSync', (file) => {
    if (!injected && path.basename(String(file)) === 'artifact-snapshot.html') inject(file);
    return unlinkSync(file);
  });
  t.mock.method(fs, 'renameSync', (source, destination) => {
    if (!injected
      && path.basename(String(source)) === 'artifact-snapshot.html'
      && path.basename(path.dirname(String(destination))).startsWith('.archify-remove-')) {
      inject(source);
    }
    return renameSync(source, destination);
  });
  t.after(() => {
    fs.rmSync(detached, { force: true });
    if (stagedPath) fs.rmSync(path.dirname(stagedPath), { recursive: true, force: true });
    for (const directory of stagingDirectories(path.dirname(outputs.receipt))) {
      fs.rmSync(path.join(path.dirname(outputs.receipt), directory), { recursive: true, force: true });
    }
  });

  const result = await runVisualCheck({
    artifactPath: input,
    verifyArtifact() {
      throw new Error('synthetic failure after private snapshot staging');
    },
  });

  assert.equal(result.exitCode, 1);
  assert.equal(injected, true);
  assert.equal(fs.existsSync(stagedPath), true);
  assert.deepEqual(fs.readFileSync(stagedPath), successor);
  assert.equal(fs.existsSync(detached), true);
});

test('sidecarPaths places outputs in outDir instead of beside the artifact', () => {
  const input = artifact('outdir-source.html');
  const separateDir = path.join(tmp, 'evidence-nested', 'deeper');
  assert.equal(fs.existsSync(separateDir), false, 'precondition: outDir must not exist yet');

  const outputs = sidecarPaths(input, { outDir: separateDir });

  assert.equal(fs.existsSync(separateDir), false, 'calculating paths must not create directories');
  assert.equal(path.dirname(outputs.receipt), separateDir);
  assert.equal(path.dirname(outputs.contactSheet), separateDir);
  assert.equal(outputs.screenshots.every((entry) => path.dirname(entry.path) === separateDir), true);
  assert.equal(path.basename(outputs.receipt), 'outdir-source.visual-check.json');

  // Omitting outDir keeps evidence beside the physical artifact.
  const defaultOutputs = sidecarPaths(input);
  assert.equal(path.dirname(defaultOutputs.receipt), path.dirname(fs.realpathSync.native(input)));
});

test('sidecarPaths keeps source-distinct case and Unicode names distinct under target semantics', (t) => {
  const sourceDir = path.join(tmp, 'semantic-source-directory');
  const outDir = path.join(tmp, 'semantic-target-directory');
  fs.mkdirSync(sourceDir, { recursive: true });
  fs.mkdirSync(outDir, { recursive: true });
  const artifactNames = ['Report.html', 'report.html', 'Caf\u00e9.html', 'Cafe\u0301.html'];
  const artifacts = artifactNames.map((name) => path.join(sourceDir, name));

  const targetSemanticKey = (name) => name
    .normalize('NFC')
    .toLocaleUpperCase('en-US')
    .toLocaleLowerCase('en-US')
    .normalize('NFC');
  const simulatedEntries = new Map();
  const originalOpen = fs.openSync;
  const originalStat = fs.statSync;
  const originalRealpath = fs.realpathSync.native;
  const sourcePhysical = originalRealpath(sourceDir);
  const outPhysical = originalRealpath(outDir);
  const sourceProbes = new Set();
  fs.openSync = function simulateTargetSemantics(file, ...args) {
    const descriptor = originalOpen.call(this, file, ...args);
    if (path.basename(String(file)).startsWith('.archify-path-semantics-')) {
      if (path.dirname(String(file)) === outPhysical) {
        simulatedEntries.set(targetSemanticKey(path.basename(String(file))), String(file));
      } else if (path.dirname(String(file)) === sourcePhysical) {
        sourceProbes.add(String(file));
      }
    }
    return descriptor;
  };
  fs.statSync = function resolveSimulatedAlias(file, ...args) {
    if (path.dirname(String(file)) === sourcePhysical
      && path.basename(String(file)).startsWith('.archify-path-semantics-')
      && !sourceProbes.has(String(file))) {
      const error = new Error('simulated case- and normalization-sensitive lookup');
      error.code = 'ENOENT';
      throw error;
    }
    const alias = path.dirname(String(file)) === outPhysical
      ? simulatedEntries.get(targetSemanticKey(path.basename(String(file))))
      : undefined;
    return originalStat.call(this, alias || file, ...args);
  };
  fs.realpathSync.native = function resolveSimulatedAlias(file, ...args) {
    if (path.dirname(String(file)) === sourceDir
      && !path.basename(String(file)).startsWith('.archify-path-semantics-')) {
      return path.join(sourcePhysical, path.basename(String(file)));
    }
    const alias = path.dirname(String(file)) === outPhysical
      ? simulatedEntries.get(targetSemanticKey(path.basename(String(file))))
      : undefined;
    return originalRealpath.call(this, alias || file, ...args);
  };
  t.after(() => {
    fs.openSync = originalOpen;
    fs.statSync = originalStat;
    fs.realpathSync.native = originalRealpath;
  });

  const calculateOutputs = () => artifacts.map((file) => {
    fs.writeFileSync(file, '<!doctype html>', { flag: 'wx' });
    try {
      return sidecarPaths(file, { outDir });
    } finally {
      fs.unlinkSync(file);
    }
  });
  const outputs = calculateOutputs();
  const outputNames = outputs.map(({ receipt }) => path.basename(receipt));
  assert.notEqual(
    targetSemanticKey(outputNames[0]),
    targetSemanticKey(outputNames[1]),
    `case-distinct source artifacts must not claim one case-insensitive target name: ${outputNames.join(', ')}`,
  );
  assert.notEqual(
    targetSemanticKey(outputNames[2]),
    targetSemanticKey(outputNames[3]),
    'normalization-distinct source artifacts must not claim one normalization-insensitive target name',
  );
  assert.deepEqual(
    calculateOutputs().map(({ receipt }) => receipt),
    outputs.map(({ receipt }) => receipt),
    'the namespace must be deterministic',
  );
  const futureOutDir = path.join(tmp, 'future-semantic-target-directory');
  fs.writeFileSync(artifacts[0], '<!doctype html>', { flag: 'wx' });
  try {
    const beforeCreation = sidecarPaths(artifacts[0], { outDir: futureOutDir });
    fs.mkdirSync(futureOutDir);
    const afterCreation = sidecarPaths(artifacts[0], { outDir: futureOutDir });
    assert.deepEqual(afterCreation, beforeCreation, 'creating --out-dir must not rename its sidecars');
  } finally {
    fs.unlinkSync(artifacts[0]);
  }
  for (const [{ receipt }, file] of outputs.map((entry, index) => [entry, artifacts[index]])) {
    assert.match(path.basename(receipt), new RegExp(`^${path.basename(file, '.html')}.*\\.visual-check\\.json$`, 'u'));
    assert.ok(Buffer.byteLength(path.basename(receipt), 'utf8') <= 255);
  }
});

test('visual-check writes all sidecars into --out-dir end-to-end, none beside the artifact', async () => {
  const input = artifact('outdir-e2e.html');
  const outDir = path.join(tmp, 'outdir-e2e-evidence');
  const browser = fakeBrowser();
  const result = await runVisualCheck({
    artifactPath: input,
    outDir,
    chromePath: '/fake/chrome',
    browserFactory: async () => browser,
  });

  assert.equal(result.exitCode, 0);
  assert.equal(result.receipt.status, 'pass');

  const outputs = sidecarPaths(input, { outDir });
  assert.equal(result.receipt.sidecars.directory, outDir);
  assert.equal(fs.existsSync(path.join(result.receipt.sidecars.directory, result.receipt.sidecars.receipt)), true);
  assert.equal(fs.existsSync(path.join(result.receipt.sidecars.directory, result.receipt.captures.contactSheet)), true);
  assert.equal(fs.existsSync(outputs.receipt), true);
  assert.equal(fs.existsSync(outputs.contactSheet), true);
  assert.equal(outputs.screenshots.every((entry) => fs.existsSync(entry.path)), true);

  const besideArtifact = sidecarPaths(input);
  assert.equal(fs.existsSync(besideArtifact.receipt), false, 'no sidecar should land beside the artifact when outDir is set');
  assert.equal(fs.existsSync(besideArtifact.contactSheet), false);
});

test('visual-check sidecar directory identity treats a physical alias as redundant', async (t) => {
  const physicalDirectory = path.join(tmp, 'physical-sidecar-directory');
  const aliasDirectory = path.join(tmp, 'aliased-sidecar-directory');
  fs.mkdirSync(physicalDirectory, { recursive: true });
  try {
    fs.symlinkSync(
      physicalDirectory,
      aliasDirectory,
      process.platform === 'win32' ? 'junction' : 'dir',
    );
  } catch (error) {
    t.skip(`directory aliases are unavailable: ${error.message}`);
    return;
  }

  const input = path.join(physicalDirectory, 'aliased-sidecars.html');
  fs.writeFileSync(input, '<!doctype html><html><body>aliased evidence</body></html>');
  const outputs = sidecarPaths(input, { outDir: aliasDirectory });
  assert.notEqual(path.dirname(outputs.receipt), path.dirname(input), 'precondition: spellings differ');

  const result = await runVisualCheck({
    artifactPath: input,
    outDir: aliasDirectory,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser(),
  });
  assert.equal(result.exitCode, 0);
  assert.equal('directory' in result.receipt.sidecars, false);

  const failure = persistVisualCheckFailure(input, {
    schemaVersion: 1,
    command: 'visual-check',
    artifact: { path: input },
    error: 'synthetic delivery failure',
    diagnostics: [{ code: 'delivery/provenance-failed' }],
  }, { outDir: aliasDirectory });
  assert.equal('directory' in failure.sidecars, false);
});

test('visual-check preserves unowned receipt, contact-sheet, and screenshot path collisions', async () => {
  const cases = [
    { name: 'receipt', select: (outputs) => outputs.receipt, bytes: Buffer.from('{"foreign":true}\n') },
    { name: 'contact-sheet', select: (outputs) => outputs.contactSheet, bytes: Buffer.from('<!doctype html><title>real artifact</title>\n') },
    { name: 'screenshot', select: (outputs) => outputs.screenshots[0].path, bytes: Buffer.from('foreign png bytes\n') },
  ];

  for (const scenario of cases) {
    const input = artifact(`unowned-${scenario.name}.html`);
    const outputs = sidecarPaths(input);
    const collision = scenario.select(outputs);
    fs.writeFileSync(collision, scenario.bytes);
    let launched = false;

    const result = await runVisualCheck({
      artifactPath: input,
      chromePath: '/fake/chrome',
      browserFactory: async () => {
        launched = true;
        return fakeBrowser();
      },
    });

    assert.equal(result.exitCode, 1, scenario.name);
    assert.equal(result.receipt.diagnostics.at(-1)?.code, 'viewer/evidence-path-conflict', scenario.name);
    assert.equal(launched, false, scenario.name);
    assert.deepEqual(fs.readFileSync(collision), scenario.bytes, scenario.name);
  }

  const input = artifact('unowned-persist-failure.html');
  const outputs = sidecarPaths(input);
  const sentinel = Buffer.from('<!doctype html><title>real artifact</title>\n');
  fs.writeFileSync(outputs.contactSheet, sentinel);
  const receipt = persistVisualCheckFailure(input, {
    schemaVersion: 1,
    command: 'visual-check',
    artifact: { path: input, sha256: sha256(input), bytes: fs.statSync(input).size },
    error: 'synthetic delivery failure',
    diagnostics: [{ code: 'delivery/provenance-failed' }],
  });
  assert.equal(receipt.diagnostics.at(-1)?.code, 'viewer/evidence-path-conflict');
  assert.deepEqual(fs.readFileSync(outputs.contactSheet), sentinel);
  assert.equal(fs.existsSync(outputs.receipt), false);
});

test('visual-check preserves receipt, contact-sheet, and PNG claimants created after preflight', async () => {
  const cases = [
    { name: 'receipt', select: (outputs) => outputs.receipt, noChrome: true },
    { name: 'contact-sheet', select: (outputs) => outputs.contactSheet },
    { name: 'screenshot', select: (outputs) => outputs.screenshots[0].path },
  ];

  for (const scenario of cases) {
    const input = artifact(`late-${scenario.name}-claimant.html`);
    const outDir = path.join(tmp, `late-${scenario.name}-evidence`);
    const outputs = sidecarPaths(input, { outDir });
    const claimant = scenario.select(outputs);
    const sentinel = Buffer.from(`late ${scenario.name} claimant\n`);
    let claimed = false;
    const claim = () => {
      if (claimed) return;
      claimed = true;
      fs.writeFileSync(claimant, sentinel, { flag: 'wx' });
    };
    const browser = fakeBrowser();
    const inspect = browser.inspect.bind(browser);
    browser.inspect = async (args) => {
      const metrics = await inspect(args);
      claim();
      return metrics;
    };

    const result = await runVisualCheck({
      artifactPath: input,
      outDir,
      ...(scenario.noChrome
        ? { resolveChrome: () => { claim(); return null; } }
        : { chromePath: '/fake/chrome', browserFactory: async () => browser }),
    });

    assert.equal(result.exitCode, 1, scenario.name);
    assert.equal(result.receipt.diagnostics.at(-1)?.code, 'viewer/evidence-path-conflict', scenario.name);
    assert.deepEqual(fs.readFileSync(claimant), sentinel, scenario.name);
    assert.deepEqual(stagingDirectories(outDir), [], scenario.name);
    for (const target of [outputs.receipt, outputs.contactSheet, ...outputs.screenshots.map((entry) => entry.path)]) {
      if (target !== claimant) assert.equal(fs.existsSync(target), false, `${scenario.name}: ${target}`);
    }
  }
});

test('visual-check preserves receipt, contact-sheet, and PNG replacements made after preflight', async () => {
  const cases = [
    { name: 'receipt', select: (outputs) => outputs.receipt, noChrome: true },
    { name: 'contact-sheet', select: (outputs) => outputs.contactSheet },
    { name: 'screenshot', select: (outputs) => outputs.screenshots[0].path },
  ];

  for (const scenario of cases) {
    const input = artifact(`late-${scenario.name}-replacement.html`);
    const outputs = sidecarPaths(input);
    const first = await runVisualCheck({
      artifactPath: input,
      chromePath: '/fake/chrome',
      browserFactory: async () => fakeBrowser(),
    });
    assert.equal(first.exitCode, 0, `${scenario.name}: initial evidence`);
    const targets = [outputs.receipt, outputs.contactSheet, ...outputs.screenshots.map((entry) => entry.path)];
    const before = new Map(targets.map((target) => [target, fs.readFileSync(target)]));
    const replaced = scenario.select(outputs);
    const sentinel = Buffer.from(`replacement ${scenario.name}\n`);
    let replacementIdentity;
    let injected = false;
    const replace = () => {
      if (injected) return;
      injected = true;
      fs.unlinkSync(replaced);
      fs.writeFileSync(replaced, sentinel, { flag: 'wx' });
      replacementIdentity = entryIdentity(replaced);
    };
    const browser = fakeBrowser();
    const inspect = browser.inspect.bind(browser);
    browser.inspect = async (args) => {
      const metrics = await inspect(args);
      replace();
      return metrics;
    };

    const result = await runVisualCheck({
      artifactPath: input,
      ...(scenario.noChrome
        ? { resolveChrome: () => { replace(); return null; } }
        : { chromePath: '/fake/chrome', browserFactory: async () => browser }),
    });

    assert.equal(result.exitCode, 1, scenario.name);
    assert.equal(result.receipt.diagnostics.at(-1)?.code, 'viewer/evidence-path-conflict', scenario.name);
    assert.deepEqual(fs.readFileSync(replaced), sentinel, scenario.name);
    assert.deepEqual(entryIdentity(replaced), replacementIdentity, scenario.name);
    for (const target of targets) {
      if (target !== replaced) assert.deepEqual(fs.readFileSync(target), before.get(target), `${scenario.name}: ${target}`);
    }
    assert.deepEqual(stagingDirectories(path.dirname(outputs.receipt)), [], scenario.name);
  }
});

test('visual-check preserves a regular successor swapped at the backup link boundary', async (t) => {
  const input = artifact('backup-link-regular-successor.html');
  const outputs = sidecarPaths(input);
  const first = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser(),
  });
  assert.equal(first.exitCode, 0);

  const displaced = path.join(tmp, 'backup-link-regular-displaced.json');
  const successor = Buffer.from('external regular successor at backup boundary\n');
  const stagingBefore = new Set(stagingDirectories(path.dirname(outputs.receipt)));
  const linkSync = fs.linkSync.bind(fs);
  const renameSync = fs.renameSync.bind(fs);
  let injected = false;
  let successorIdentity;
  t.after(() => {
    fs.rmSync(displaced, { force: true });
    for (const directory of stagingDirectories(path.dirname(outputs.receipt))) {
      if (!stagingBefore.has(directory)) {
        fs.rmSync(path.join(path.dirname(outputs.receipt), directory), { recursive: true, force: true });
      }
    }
  });
  t.mock.method(fs, 'linkSync', (source, target) => {
    const sourcePath = String(source);
    const targetPath = String(target);
    if (!injected
      && path.basename(sourcePath) === path.basename(outputs.receipt)
      && path.basename(targetPath) === 'previous-0'
      && path.basename(path.dirname(targetPath)).startsWith('.archify-visual-check-')) {
      renameSync(sourcePath, displaced);
      fs.writeFileSync(sourcePath, successor, { flag: 'wx' });
      successorIdentity = entryIdentity(sourcePath);
      injected = true;
    }
    return linkSync(sourcePath, targetPath);
  });

  const result = await runVisualCheck({
    artifactPath: input,
    resolveChrome: () => null,
  });

  assert.equal(injected, true);
  assert.equal(result.exitCode, 1);
  assert.equal(result.receipt.diagnostics.at(-1)?.code, 'viewer/evidence-path-conflict');
  assert.deepEqual(fs.readFileSync(outputs.receipt), successor);
  assert.deepEqual(entryIdentity(outputs.receipt), successorIdentity);
});

for (const scenario of [
  {
    name: 'directory',
    create(file) {
      fs.mkdirSync(file);
    },
    assertPreserved(file) {
      assert.equal(fs.lstatSync(file).isDirectory(), true);
    },
  },
  {
    name: 'FIFO',
    skip: process.platform === 'win32' && 'POSIX FIFOs are not native Windows filesystem entries',
    create(file, t) {
      const created = spawnSync('mkfifo', [file], { encoding: 'utf8' });
      if (created.status !== 0) {
        t.skip(`mkfifo is unavailable: ${created.stderr || `exit ${created.status}`}`);
        const error = new Error('mkfifo unavailable');
        error.code = 'ARCHIFY_TEST_SKIPPED';
        throw error;
      }
      assert.equal(fs.lstatSync(file).isFIFO(), true, 'mkfifo must create a native FIFO visible to Node');
    },
    assertPreserved(file) {
      assert.equal(fs.lstatSync(file).isFIFO(), true);
    },
  },
  {
    name: 'symlink',
    create(file, t) {
      const target = path.join(tmp, 'backup-link-symlink-target');
      fs.writeFileSync(target, 'symlink target', { flag: fs.existsSync(target) ? 'w' : 'wx' });
      try {
        fs.symlinkSync(target, file, 'file');
      } catch (error) {
        if (error?.code === 'EPERM') {
          t.skip(`file symlinks are unavailable: ${error.message}`);
          const skipped = new Error('file symlinks unavailable');
          skipped.code = 'ARCHIFY_TEST_SKIPPED';
          throw skipped;
        }
        throw error;
      }
    },
    assertPreserved(file) {
      assert.equal(fs.lstatSync(file).isSymbolicLink(), true);
    },
  },
]) {
  test(`visual-check preserves a ${scenario.name} swapped at the backup link boundary`, {
    skip: scenario.skip,
  }, async (t) => {
    const input = artifact(`backup-link-${scenario.name.toLowerCase()}-successor.html`);
    const outputs = sidecarPaths(input);
    const first = await runVisualCheck({
      artifactPath: input,
      chromePath: '/fake/chrome',
      browserFactory: async () => fakeBrowser(),
    });
    assert.equal(first.exitCode, 0);

    const displaced = path.join(tmp, `backup-link-${scenario.name.toLowerCase()}-displaced.json`);
    const stagingBefore = new Set(stagingDirectories(path.dirname(outputs.receipt)));
    const linkSync = fs.linkSync.bind(fs);
    const renameSync = fs.renameSync.bind(fs);
    let injected = false;
    t.after(() => {
      fs.rmSync(displaced, { force: true });
      fs.rmSync(outputs.receipt, { recursive: true, force: true });
      for (const directory of stagingDirectories(path.dirname(outputs.receipt))) {
        if (!stagingBefore.has(directory)) {
          fs.rmSync(path.join(path.dirname(outputs.receipt), directory), { recursive: true, force: true });
        }
      }
    });
    t.mock.method(fs, 'linkSync', (source, target) => {
      const sourcePath = String(source);
      const targetPath = String(target);
      if (!injected
        && path.basename(sourcePath) === path.basename(outputs.receipt)
        && path.basename(targetPath) === 'previous-0'
        && path.basename(path.dirname(targetPath)).startsWith('.archify-visual-check-')) {
        renameSync(sourcePath, displaced);
        scenario.create(sourcePath, t);
        injected = true;
      }
      return linkSync(sourcePath, targetPath);
    });

    let result;
    try {
      result = await runVisualCheck({
        artifactPath: input,
        resolveChrome: () => null,
      });
    } catch (error) {
      if (error?.code === 'ARCHIFY_TEST_SKIPPED') return;
      throw error;
    }

    assert.equal(injected, true);
    assert.equal(result.exitCode, 1);
    assert.equal(result.receipt.diagnostics.at(-1)?.code, 'viewer/evidence-path-conflict');
    scenario.assertPreserved(outputs.receipt);
  });
}

test('visual-check preserves an in-place evidence edit made after preflight', async () => {
  const input = artifact('late-in-place-evidence-edit.html');
  const outputs = sidecarPaths(input);
  const first = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser(),
  });
  assert.equal(first.exitCode, 0);

  const targets = [
    outputs.receipt,
    outputs.contactSheet,
    ...outputs.screenshots.map((entry) => entry.path),
  ];
  const before = new Map(targets.map((target) => [target, fs.readFileSync(target)]));
  const originalIdentity = entryIdentity(outputs.contactSheet);
  const sentinel = Buffer.from('external in-place contact-sheet edit\n');
  let editedIdentity;
  let injected = false;
  const browser = fakeBrowser();
  const inspect = browser.inspect.bind(browser);
  browser.inspect = async (args) => {
    const metrics = await inspect(args);
    if (!injected) {
      fs.writeFileSync(outputs.contactSheet, sentinel);
      editedIdentity = entryIdentity(outputs.contactSheet);
      injected = true;
    }
    return metrics;
  };

  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => browser,
  });

  assert.equal(injected, true);
  assert.deepEqual(editedIdentity, originalIdentity, 'the injected edit must retain the captured inode');
  assert.equal(result.exitCode, 1);
  assert.equal(result.receipt.diagnostics.at(-1)?.code, 'viewer/evidence-path-conflict');
  assert.equal(
    result.receipt.diagnostics.at(-1)?.evidence?.reason?.code,
    'previous-evidence-content-changed',
  );
  assert.deepEqual(fs.readFileSync(outputs.contactSheet), sentinel);
  assert.deepEqual(entryIdentity(outputs.contactSheet), editedIdentity);
  for (const target of targets) {
    if (target !== outputs.contactSheet) assert.deepEqual(fs.readFileSync(target), before.get(target), target);
  }
  assert.deepEqual(stagingDirectories(path.dirname(outputs.receipt)), []);
});

test('visual-check preserves an in-place backup edit made before cleanup', async (t) => {
  const input = artifact('late-in-place-backup-edit.html');
  const outputs = sidecarPaths(input);
  const first = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser(),
  });
  assert.equal(first.exitCode, 0);

  const targets = [
    outputs.receipt,
    outputs.contactSheet,
    ...outputs.screenshots.map((entry) => entry.path),
  ];
  const before = new Map(targets.map((target) => [target, fs.readFileSync(target)]));
  const originalIdentity = entryIdentity(outputs.contactSheet);
  const sentinel = Buffer.from('external in-place backup edit\n');
  const linkSync = fs.linkSync.bind(fs);
  let editedIdentity;
  let injected = false;
  t.mock.method(fs, 'linkSync', (source, target) => {
    const result = linkSync(source, target);
    if (!injected
      && path.basename(String(source)) === 'receipt.json'
      && path.basename(path.dirname(String(source))).startsWith('.archify-visual-check-')) {
      const backup = path.join(path.dirname(String(source)), 'previous-1');
      fs.writeFileSync(backup, sentinel);
      editedIdentity = entryIdentity(backup);
      injected = true;
    }
    return result;
  });

  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser(),
  });

  assert.equal(injected, true);
  assert.deepEqual(editedIdentity, originalIdentity, 'the injected edit must retain the backup inode');
  assert.equal(result.exitCode, 1);
  assert.equal(result.receipt.diagnostics.at(-1)?.code, 'viewer/evidence-path-conflict');
  assert.equal(
    result.receipt.diagnostics.at(-1)?.evidence?.reason?.code,
    'backup-content-changed-before-cleanup',
  );
  assert.deepEqual(fs.readFileSync(outputs.contactSheet), sentinel);
  assert.deepEqual(entryIdentity(outputs.contactSheet), editedIdentity);
  for (const target of targets) {
    if (target !== outputs.contactSheet) assert.deepEqual(fs.readFileSync(target), before.get(target), target);
  }
  assert.deepEqual(stagingDirectories(path.dirname(outputs.receipt)), []);
});

test('visual-check refuses hard-linked receipt, contact-sheet, and PNG evidence without mutation', async (t) => {
  const selectors = [
    ['receipt', (outputs) => outputs.receipt],
    ['contact-sheet', (outputs) => outputs.contactSheet],
    ['screenshot', (outputs) => outputs.screenshots[0].path],
  ];

  for (const [name, select] of selectors) {
    const input = artifact(`hardlinked-${name}.html`);
    const outputs = sidecarPaths(input);
    const first = await runVisualCheck({
      artifactPath: input,
      chromePath: '/fake/chrome',
      browserFactory: async () => fakeBrowser(),
    });
    assert.equal(first.exitCode, 0, `${name}: initial evidence`);
    const target = select(outputs);
    const alias = `${target}.alias`;
    try {
      fs.linkSync(target, alias);
    } catch (error) {
      t.skip(`hard links are unavailable: ${error.message}`);
      return;
    }
    const before = fs.readFileSync(target);
    let launched = false;
    const result = await runVisualCheck({
      artifactPath: input,
      chromePath: '/fake/chrome',
      browserFactory: async () => { launched = true; return fakeBrowser(); },
    });
    assert.equal(result.exitCode, 1, name);
    assert.equal(launched, false, name);
    assert.equal(result.receipt.diagnostics.at(-1)?.code, 'viewer/evidence-path-conflict', name);
    assert.match(
      result.receipt.diagnostics.at(-1)?.evidence?.reason?.code || '',
      /^(?:requested-entry|target)-hardlinked$/,
      name,
    );
    assert.deepEqual(fs.readFileSync(target), before, name);
    assert.deepEqual(fs.readFileSync(alias), before, `${name}: alias`);
  }
});

test('visual-check rejects an lstat-to-open symlink substitution without following it', async (t) => {
  const input = artifact('staged-evidence-symlink-race.html');
  const outputs = sidecarPaths(input);
  const sentinel = path.join(tmp, 'staged-evidence-symlink-sentinel.txt');
  const probe = path.join(tmp, 'staged-evidence-symlink-probe');
  const sentinelBytes = Buffer.from('must never be read through the staged evidence path\n');
  fs.writeFileSync(sentinel, sentinelBytes);
  try {
    fs.symlinkSync(sentinel, probe, 'file');
    fs.unlinkSync(probe);
  } catch (error) {
    t.skip(`file symlinks are unavailable: ${error.message}`);
    return;
  }

  const browser = fakeBrowser();
  const inspect = browser.inspect.bind(browser);
  let screenshotReady = false;
  browser.inspect = async (args) => {
    const metrics = await inspect(args);
    if (args.screenshotPath) screenshotReady = true;
    return metrics;
  };

  const openSync = fs.openSync.bind(fs);
  let injected = false;
  let claimant;
  t.mock.method(fs, 'openSync', (file, flags, mode) => {
    const candidate = String(file);
    if (!injected
      && screenshotReady
      && path.basename(candidate) === 'capture-0.png'
      && path.basename(path.dirname(candidate)).startsWith('.archify-visual-check-')) {
      fs.unlinkSync(candidate);
      fs.symlinkSync(sentinel, candidate, 'file');
      claimant = candidate;
      injected = true;
    }
    return openSync(file, flags, mode);
  });
  t.after(() => {
    for (const directory of stagingDirectories(path.dirname(outputs.receipt))) {
      fs.rmSync(path.join(path.dirname(outputs.receipt), directory), { recursive: true, force: true });
    }
  });

  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => browser,
  });

  assert.equal(injected, true);
  assert.equal(result.exitCode, 1);
  assert.deepEqual(fs.readFileSync(sentinel), sentinelBytes);
  assert.equal(fs.lstatSync(claimant).isSymbolicLink(), true);
  assert.equal(fs.existsSync(outputs.receipt), false);
  assert.equal(fs.existsSync(outputs.contactSheet), false);
  assert.equal(outputs.screenshots.every((entry) => !fs.existsSync(entry.path)), true);
});

test('visual-check rejects an lstat-to-open FIFO substitution without blocking', {
  skip: process.platform === 'win32' ? 'named pipes use different APIs on Windows' : false,
  timeout: 5_000,
}, async (t) => {
  const input = artifact('staged-evidence-fifo-race.html');
  const outputs = sidecarPaths(input);
  const probe = path.join(tmp, 'staged-evidence-fifo-probe');
  const probeResult = spawnSync('mkfifo', [probe]);
  if (probeResult.status !== 0) {
    t.skip(`mkfifo is unavailable: ${probeResult.stderr?.toString() || 'unknown error'}`);
    return;
  }
  fs.unlinkSync(probe);

  const browser = fakeBrowser();
  const inspect = browser.inspect.bind(browser);
  let screenshotReady = false;
  browser.inspect = async (args) => {
    const metrics = await inspect(args);
    if (args.screenshotPath) screenshotReady = true;
    return metrics;
  };

  const openSync = fs.openSync.bind(fs);
  let injected = false;
  let claimant;
  t.mock.method(fs, 'openSync', (file, flags, mode) => {
    const candidate = String(file);
    if (!injected
      && screenshotReady
      && path.basename(candidate) === 'capture-0.png'
      && path.basename(path.dirname(candidate)).startsWith('.archify-visual-check-')) {
      fs.unlinkSync(candidate);
      const created = spawnSync('mkfifo', [candidate]);
      assert.equal(created.status, 0, created.stderr?.toString());
      claimant = candidate;
      injected = true;
    }
    return openSync(file, flags, mode);
  });
  t.after(() => {
    for (const directory of stagingDirectories(path.dirname(outputs.receipt))) {
      fs.rmSync(path.join(path.dirname(outputs.receipt), directory), { recursive: true, force: true });
    }
  });

  const started = Date.now();
  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => browser,
  });

  assert.equal(injected, true);
  assert.equal(result.exitCode, 1);
  assert.ok(Date.now() - started < 2_000, 'FIFO inspection must fail without waiting for a writer');
  assert.equal(fs.lstatSync(claimant).isFIFO(), true);
  assert.equal(fs.existsSync(outputs.receipt), false);
  assert.equal(fs.existsSync(outputs.contactSheet), false);
  assert.equal(outputs.screenshots.every((entry) => !fs.existsSync(entry.path)), true);
});

for (const operation of ['run', 'persist-failure']) {
  test(`visual-check ${operation} rejects an artifact changed to a FIFO before open`, {
    skip: process.platform === 'win32' ? 'named pipes use different APIs on Windows' : false,
    timeout: 10_000,
  }, (t) => {
    const input = artifact(`artifact-fifo-substitution-${operation}.html`);
    const outputs = sidecarPaths(input);
    const visualCheckUrl = new URL('../archify/bin/visual-check.mjs', import.meta.url).href;
    t.after(() => {
      try {
        if (fs.lstatSync(input).isFIFO()) fs.unlinkSync(input);
      } catch {}
    });
    const script = `
      import { spawnSync } from 'node:child_process';
      import fs from 'node:fs';
      import path from 'node:path';
      import { persistVisualCheckFailure, runVisualCheck } from ${JSON.stringify(visualCheckUrl)};
      const artifact = ${JSON.stringify(input)};
      const openSync = fs.openSync.bind(fs);
      let injected = false;
      fs.openSync = (file, flags, mode) => {
        if (!injected && path.resolve(String(file)) === artifact) {
          fs.unlinkSync(artifact);
          const created = spawnSync('mkfifo', [artifact]);
          if (created.status !== 0) throw new Error(created.stderr?.toString() || 'mkfifo failed');
          injected = true;
        }
        return openSync(file, flags, mode);
      };
      ${operation === 'run'
        ? `try {
            await runVisualCheck({ artifactPath: artifact, resolveChrome: () => null });
            console.error('operation unexpectedly accepted the FIFO');
            process.exitCode = 2;
          } catch (error) {
            console.log(JSON.stringify({ injected, reason: error.evidenceReason?.code || error.message }));
          }`
        : `const receipt = persistVisualCheckFailure(artifact, {
            schemaVersion: 1,
            command: 'visual-check',
            status: 'fail',
            diagnostics: [],
          });
          console.log(JSON.stringify({
            injected,
            reason: receipt.diagnostics?.at(-1)?.evidence?.reason?.code || receipt.error,
          }));`}
    `;

    const child = spawnSync(process.execPath, ['--input-type=module', '--eval', script], {
      encoding: 'utf8',
      timeout: 3_000,
    });

    assert.equal(child.error, undefined, child.error?.message);
    assert.equal(child.status, 0, child.stderr || child.stdout);
    const observed = JSON.parse(child.stdout);
    assert.equal(observed.injected, true);
    assert.match(observed.reason, /not-regular-file|changed-during-inspection|artifact-unreadable/);
    assert.equal(fs.lstatSync(input).isFIFO(), true);
    assert.equal(fs.existsSync(outputs.receipt), false);
    assert.equal(fs.existsSync(outputs.contactSheet), false);
    assert.equal(outputs.screenshots.every((entry) => !fs.existsSync(entry.path)), true);
  });
}

test('visual-check rejects a previous receipt changed to a FIFO before its content open', {
  skip: process.platform === 'win32' ? 'named pipes use different APIs on Windows' : false,
  timeout: 10_000,
}, async (t) => {
  const input = artifact('previous-receipt-fifo-substitution.html');
  const outputs = sidecarPaths(input);
  const first = await runVisualCheck({ artifactPath: input, resolveChrome: () => null });
  assert.equal(first.exitCode, 2);
  const receiptBefore = fs.readFileSync(outputs.receipt);
  const visualCheckUrl = new URL('../archify/bin/visual-check.mjs', import.meta.url).href;
  t.after(() => {
    try {
      if (fs.lstatSync(outputs.receipt).isFIFO()) fs.unlinkSync(outputs.receipt);
    } catch {}
  });
  const script = `
    import { spawnSync } from 'node:child_process';
    import fs from 'node:fs';
    import path from 'node:path';
    import { runVisualCheck } from ${JSON.stringify(visualCheckUrl)};
    const artifact = ${JSON.stringify(input)};
    const receipt = ${JSON.stringify(outputs.receipt)};
    const openSync = fs.openSync.bind(fs);
    let receiptOpens = 0;
    let injected = false;
    fs.openSync = (file, flags, mode) => {
      if (path.resolve(String(file)) === receipt) {
        receiptOpens += 1;
        if (!injected && receiptOpens === 3) {
          fs.unlinkSync(receipt);
          const created = spawnSync('mkfifo', [receipt]);
          if (created.status !== 0) throw new Error(created.stderr?.toString() || 'mkfifo failed');
          injected = true;
        }
      }
      return openSync(file, flags, mode);
    };
    const result = await runVisualCheck({ artifactPath: artifact, resolveChrome: () => null });
    console.log(JSON.stringify({
      injected,
      receiptOpens,
      exitCode: result.exitCode,
      reason: result.receipt.diagnostics?.at(-1)?.evidence?.reason?.code,
    }));
  `;

  const child = spawnSync(process.execPath, ['--input-type=module', '--eval', script], {
    encoding: 'utf8',
    timeout: 3_000,
  });

  assert.equal(child.error, undefined, child.error?.message);
  assert.equal(child.status, 0, child.stderr || child.stdout);
  const observed = JSON.parse(child.stdout);
  assert.equal(observed.injected, true, JSON.stringify(observed));
  assert.equal(observed.receiptOpens, 3);
  assert.equal(observed.exitCode, 1);
  assert.equal(observed.reason, 'requested-entry-changed-during-inspection');
  assert.equal(fs.lstatSync(outputs.receipt).isFIFO(), true);
  assert.deepEqual(receiptBefore.length > 0, true);
  assert.deepEqual(stagingDirectories(path.dirname(outputs.receipt)), []);
});

test('visual-check preserves existing evidence modes under a restrictive umask', async (t) => {
  if (process.platform === 'win32') {
    t.skip('POSIX permission bits are not portable to Windows');
    return;
  }

  const input = artifact('preserved-evidence-modes.html');
  const outputs = sidecarPaths(input);
  const targets = [
    outputs.receipt,
    outputs.contactSheet,
    ...outputs.screenshots.map((entry) => entry.path),
  ];
  const first = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser(),
  });
  assert.equal(first.exitCode, 0);
  for (const target of targets) fs.chmodSync(target, 0o666);

  const previousUmask = process.umask(0o077);
  let second;
  try {
    second = await runVisualCheck({
      artifactPath: input,
      chromePath: '/fake/chrome',
      browserFactory: async () => fakeBrowser(),
    });
  } finally {
    process.umask(previousUmask);
  }

  assert.equal(second.exitCode, 0);
  for (const target of targets) {
    assert.equal(fs.statSync(target).mode & 0o777, 0o666, target);
  }
});

test('visual-check never follows the former predictable temporary symlink', async (t) => {
  const input = artifact('predictable-temporary-symlink.html');
  const outputs = sidecarPaths(input);
  const sentinel = path.join(tmp, 'predictable-temporary-sentinel.txt');
  const temporary = `${outputs.receipt}.tmp-${process.pid}`;
  const bytes = Buffer.from('must not be truncated\n');
  fs.writeFileSync(sentinel, bytes);
  try {
    fs.symlinkSync(sentinel, temporary, 'file');
  } catch (error) {
    t.skip(`file symlinks are unavailable: ${error.message}`);
    return;
  }

  const result = await runVisualCheck({ artifactPath: input, resolveChrome: () => null });

  assert.equal(result.exitCode, 2);
  assert.deepEqual(fs.readFileSync(sentinel), bytes);
  assert.equal(fs.lstatSync(temporary).isSymbolicLink(), true);
  assert.deepEqual(stagingDirectories(path.dirname(outputs.receipt)), []);
});

test('visual-check preserves absent and replaced paths that become symlinks after preflight', async (t) => {
  const sentinel = path.join(tmp, 'late-symlink-sentinel.txt');
  const sentinelBytes = Buffer.from('symlink claimant target\n');
  fs.writeFileSync(sentinel, sentinelBytes);
  const cases = [
    { name: 'absent', prepare: async () => {} },
    {
      name: 'existing',
      prepare: async (input) => {
        const first = await runVisualCheck({
          artifactPath: input,
          chromePath: '/fake/chrome',
          browserFactory: async () => fakeBrowser(),
        });
        assert.equal(first.exitCode, 0);
      },
    },
  ];

  for (const scenario of cases) {
    const input = artifact(`late-${scenario.name}-symlink.html`);
    const outputs = sidecarPaths(input);
    await scenario.prepare(input);
    const before = new Map(
      [outputs.contactSheet, ...outputs.screenshots.map((entry) => entry.path)]
        .filter((file) => fs.existsSync(file))
        .map((file) => [file, fs.readFileSync(file)]),
    );
    let injected = false;
    const inject = () => {
      if (injected) return;
      injected = true;
      if (fs.existsSync(outputs.receipt)) fs.unlinkSync(outputs.receipt);
      fs.symlinkSync(sentinel, outputs.receipt, 'file');
    };

    let result;
    try {
      result = await runVisualCheck({
        artifactPath: input,
        resolveChrome: () => { inject(); return null; },
      });
    } catch (error) {
      if (error?.code === 'EPERM') {
        t.skip(`file symlinks are unavailable: ${error.message}`);
        return;
      }
      throw error;
    }

    assert.equal(result.exitCode, 1, scenario.name);
    assert.equal(result.receipt.diagnostics.at(-1)?.code, 'viewer/evidence-path-conflict', scenario.name);
    assert.equal(fs.lstatSync(outputs.receipt).isSymbolicLink(), true, scenario.name);
    assert.deepEqual(fs.readFileSync(sentinel), sentinelBytes, scenario.name);
    for (const [file, bytes] of before) assert.deepEqual(fs.readFileSync(file), bytes, `${scenario.name}: ${file}`);
    assert.deepEqual(stagingDirectories(path.dirname(outputs.receipt)), [], scenario.name);
  }
});

test('visual-check rejects a screenshot candidate externally hard-linked before registration', async (t) => {
  const input = artifact('staged-screenshot-hardlink.html');
  const outputs = sidecarPaths(input);
  const alias = path.join(tmp, 'staged-screenshot-external-alias.png');
  const browser = fakeBrowser();
  const inspect = browser.inspect.bind(browser);
  let injected = false;
  let hardLinkUnavailable;
  browser.inspect = async (args) => {
    const metrics = await inspect(args);
    if (args.screenshotPath && !injected && !hardLinkUnavailable) {
      try {
        fs.linkSync(args.screenshotPath, alias);
      } catch (error) {
        if (['EPERM', 'EACCES', 'ENOTSUP'].includes(error?.code)) {
          hardLinkUnavailable = error;
          return metrics;
        }
        throw error;
      }
      injected = true;
    }
    return metrics;
  };

  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => browser,
  });

  if (hardLinkUnavailable) {
    t.skip(`hard links are unavailable: ${hardLinkUnavailable.message}`);
    return;
  }
  assert.equal(injected, true, 'the staged screenshot hard-link injection must run');
  assert.equal(result.exitCode, 1);
  assert.equal(fs.existsSync(alias), true);
  assert.deepEqual(fs.readFileSync(alias), png);
  assert.equal(fs.lstatSync(alias, { bigint: true }).nlink, 1n);
  assert.equal(fs.existsSync(outputs.contactSheet), false);
  assert.equal(outputs.screenshots.every((entry) => !fs.existsSync(entry.path)), true);
  assert.deepEqual(stagingDirectories(path.dirname(outputs.receipt)), []);
});

for (const candidate of [
  { name: 'contact-sheet', stagedName: 'contact-sheet.html', chrome: true },
  { name: 'receipt', stagedName: 'receipt.json', chrome: false },
]) {
  test(`visual-check rolls back when the staged ${candidate.name} gains an external hard link during publish`, async (t) => {
    const input = artifact(`staged-${candidate.name}-publish-hardlink.html`);
    const outputs = sidecarPaths(input);
    const alias = path.join(tmp, `staged-${candidate.name}-publish-external-alias`);
    const linkSync = fs.linkSync.bind(fs);
    let injected = false;
    t.mock.method(fs, 'linkSync', (source, target) => {
      if (!injected && path.basename(source) === candidate.stagedName) {
        linkSync(source, alias);
        injected = true;
      }
      return linkSync(source, target);
    });

    const result = await runVisualCheck({
      artifactPath: input,
      ...(candidate.chrome
        ? { chromePath: '/fake/chrome', browserFactory: async () => fakeBrowser() }
        : { resolveChrome: () => null }),
    });

    assert.equal(injected, true);
    assert.equal(result.exitCode, 1);
    assert.equal(result.receipt.diagnostics.at(-1)?.code, 'viewer/evidence-path-conflict');
    assert.equal(fs.existsSync(alias), true);
    assert.equal(fs.lstatSync(alias, { bigint: true }).nlink, 1n);
    assert.equal(fs.existsSync(outputs.receipt), false);
    assert.equal(fs.existsSync(outputs.contactSheet), false);
    assert.equal(outputs.screenshots.every((entry) => !fs.existsSync(entry.path)), true);
    assert.deepEqual(stagingDirectories(path.dirname(outputs.receipt)), []);
  });
}

test('visual-check keeps staged evidence identity-bound across public link creation', async (t) => {
  const input = artifact('staged-publication-binding.html');
  const outputs = sidecarPaths(input);
  const first = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser(),
  });
  assert.equal(first.exitCode, 0);
  const targets = [
    outputs.receipt,
    outputs.contactSheet,
    ...outputs.screenshots.map((entry) => entry.path),
  ];
  const before = new Map(targets.map((target) => [target, fs.readFileSync(target)]));
  const stagingBefore = new Set(stagingDirectories(path.dirname(outputs.receipt)));
  const detached = path.join(tmp, 'detached-bound-contact-sheet.html');
  const claimant = Buffer.from('external staged contact-sheet claimant\n');
  const linkSync = fs.linkSync.bind(fs);
  let stagedClaimant;
  let injected = false;
  t.mock.method(fs, 'linkSync', (source, target) => {
    const sourcePath = String(source);
    const targetPath = String(target);
    if (!injected
      && path.basename(sourcePath) === 'contact-sheet.html'
      && path.basename(path.dirname(sourcePath)).startsWith('.archify-visual-check-')
      && path.resolve(targetPath) === path.resolve(outputs.contactSheet)) {
      injected = true;
      stagedClaimant = sourcePath;
      fs.renameSync(sourcePath, detached);
      fs.writeFileSync(sourcePath, claimant, { flag: 'wx' });
    }
    return linkSync(sourcePath, targetPath);
  });
  t.after(() => {
    fs.rmSync(detached, { force: true });
    for (const directory of stagingDirectories(path.dirname(outputs.receipt))) {
      if (!stagingBefore.has(directory)) {
        fs.rmSync(path.join(path.dirname(outputs.receipt), directory), { recursive: true, force: true });
      }
    }
  });

  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser(),
  });

  assert.equal(injected, true);
  assert.equal(result.exitCode, 1);
  assert.equal(result.receipt.diagnostics.at(-1)?.code, 'viewer/evidence-path-conflict');
  for (const target of targets) assert.deepEqual(fs.readFileSync(target), before.get(target), target);
  assert.deepEqual(fs.readFileSync(stagedClaimant), claimant);
  assert.equal(fs.existsSync(detached), true);
});

for (const scenario of [
  {
    name: 'contact sheet',
    selectEarly: (outputs) => outputs.contactSheet,
    triggerStagedName: 'capture-0.png',
  },
  {
    name: 'first screenshot',
    selectEarly: (outputs) => outputs.screenshots[0].path,
    triggerStagedName: 'receipt.json',
  },
]) {
  test(`visual-check final set sweep preserves a replacement of the early ${scenario.name}`, async (t) => {
    const input = artifact(`final-sweep-${scenario.name.replaceAll(' ', '-')}.html`);
    const outputs = sidecarPaths(input);
    const stagingBefore = new Set(stagingDirectories(path.dirname(outputs.receipt)));
    t.after(() => {
      for (const directory of stagingDirectories(path.dirname(outputs.receipt))) {
        if (!stagingBefore.has(directory)) {
          fs.rmSync(path.join(path.dirname(outputs.receipt), directory), { recursive: true, force: true });
        }
      }
    });
    const first = await runVisualCheck({
      artifactPath: input,
      chromePath: '/fake/chrome',
      browserFactory: async () => fakeBrowser(),
    });
    assert.equal(first.exitCode, 0);
    const targets = [outputs.receipt, outputs.contactSheet, ...outputs.screenshots.map((entry) => entry.path)];
    const before = new Map(targets.map((target) => [target, fs.readFileSync(target)]));
    const replaced = scenario.selectEarly(outputs);
    const sentinel = Buffer.from(`late replacement of ${scenario.name}\n`);
    const linkSync = fs.linkSync.bind(fs);
    let replacementIdentity;
    let injected = false;
    t.mock.method(fs, 'linkSync', (source, target) => {
      const result = linkSync(source, target);
      if (!injected
          && path.basename(String(source)) === scenario.triggerStagedName
          && path.basename(path.dirname(String(source))).startsWith('.archify-visual-check-')) {
        injected = true;
        fs.unlinkSync(replaced);
        fs.writeFileSync(replaced, sentinel, { flag: 'wx' });
        replacementIdentity = entryIdentity(replaced);
      }
      return result;
    });

    const result = await runVisualCheck({
      artifactPath: input,
      chromePath: '/fake/chrome',
      browserFactory: async () => fakeBrowser(),
    });

    assert.equal(injected, true);
    assert.equal(result.exitCode, 1);
    assert.equal(result.receipt.diagnostics.at(-1)?.code, 'viewer/evidence-path-conflict');
    assert.equal(result.receipt.diagnostics.at(-1)?.evidence?.reason?.code, 'published-set-identity-mismatch');
    assert.deepEqual(fs.readFileSync(replaced), sentinel);
    assert.deepEqual(entryIdentity(replaced), replacementIdentity);
    for (const target of targets) {
      if (target !== replaced) assert.deepEqual(fs.readFileSync(target), before.get(target), target);
    }
  });
}

test('visual-check rollback preserves an in-place edit to an already published member', async (t) => {
  const input = artifact('rollback-published-content-edit.html');
  const outputs = sidecarPaths(input);
  const first = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser(),
  });
  assert.equal(first.exitCode, 0);

  const targets = [
    outputs.receipt,
    outputs.contactSheet,
    ...outputs.screenshots.map((entry) => entry.path),
  ];
  const before = new Map(targets.map((target) => [target, fs.readFileSync(target)]));
  const originalContactIdentity = entryIdentity(outputs.contactSheet);
  const stagingBefore = new Set(stagingDirectories(path.dirname(outputs.receipt)));
  t.after(() => {
    for (const directory of stagingDirectories(path.dirname(outputs.receipt))) {
      if (!stagingBefore.has(directory)) {
        fs.rmSync(path.join(path.dirname(outputs.receipt), directory), { recursive: true, force: true });
      }
    }
  });

  const sentinel = Buffer.from('external in-place edit after contact-sheet publication\n');
  const linkSync = fs.linkSync.bind(fs);
  let firstPublishedIdentity;
  let editedIdentity;
  let injected = false;
  t.mock.method(fs, 'linkSync', (source, target) => {
    const sourceName = path.basename(String(source));
    const fromStaging = path.basename(path.dirname(String(source))).startsWith('.archify-visual-check-');
    if (!injected && firstPublishedIdentity && fromStaging && sourceName === 'capture-0.png') {
      fs.writeFileSync(outputs.contactSheet, sentinel);
      editedIdentity = entryIdentity(outputs.contactSheet);
      injected = true;
      throw new Error('synthetic later evidence publication failure');
    }
    const result = linkSync(source, target);
    if (!firstPublishedIdentity && fromStaging && sourceName === 'contact-sheet.html') {
      firstPublishedIdentity = entryIdentity(target);
    }
    return result;
  });

  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser(),
  });

  assert.equal(injected, true);
  assert.deepEqual(editedIdentity, firstPublishedIdentity, 'the edit must retain the published inode');
  assert.equal(result.exitCode, 1);
  assert.equal(result.receipt.diagnostics.at(-1)?.code, 'viewer/evidence-write');
  const rollbackReasons = result.receipt.diagnostics.at(-1)?.evidence?.errors
    ?.map((entry) => entry.reason).join('\n') || '';
  assert.match(rollbackReasons, /published entry content changed; it was preserved/);
  assert.match(rollbackReasons, /final path is occupied; the owned backup was preserved/);
  assert.deepEqual(fs.readFileSync(outputs.contactSheet), sentinel);
  assert.deepEqual(entryIdentity(outputs.contactSheet), editedIdentity);
  for (const target of targets) {
    if (target !== outputs.contactSheet) assert.deepEqual(fs.readFileSync(target), before.get(target), target);
  }

  const retained = stagingDirectories(path.dirname(outputs.receipt))
    .filter((directory) => !stagingBefore.has(directory));
  assert.equal(retained.length, 1);
  const backup = path.join(path.dirname(outputs.receipt), retained[0], 'previous-1');
  assert.deepEqual(fs.readFileSync(backup), before.get(outputs.contactSheet));
  assert.deepEqual(entryIdentity(backup), originalContactIdentity);
});

test('visual-check rollback preserves a successor swapped at the public removal boundary', async (t) => {
  const input = artifact('rollback-public-removal-successor.html');
  const outputs = sidecarPaths(input);
  const first = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser(),
  });
  assert.equal(first.exitCode, 0);

  const stagingBefore = new Set(stagingDirectories(path.dirname(outputs.receipt)));
  const displaced = path.join(tmp, 'rollback-public-removal-owned-displaced.html');
  const successor = Buffer.from('external successor at the public removal boundary\n');
  t.after(() => {
    fs.rmSync(displaced, { force: true });
    for (const directory of stagingDirectories(path.dirname(outputs.receipt))) {
      if (!stagingBefore.has(directory)) {
        fs.rmSync(path.join(path.dirname(outputs.receipt), directory), { recursive: true, force: true });
      }
    }
  });

  const linkSync = fs.linkSync.bind(fs);
  const renameSync = fs.renameSync.bind(fs);
  let contactPublished = false;
  let failureInjected = false;
  let successorInjected = false;
  let successorIdentity;
  t.mock.method(fs, 'linkSync', (source, target) => {
    const sourceName = path.basename(String(source));
    const fromStaging = path.basename(path.dirname(String(source))).startsWith('.archify-visual-check-');
    if (!failureInjected && contactPublished && fromStaging && sourceName === 'capture-0.png') {
      failureInjected = true;
      throw new Error('synthetic later evidence publication failure');
    }
    const result = linkSync(source, target);
    if (!contactPublished && fromStaging && sourceName === 'contact-sheet.html') {
      contactPublished = true;
    }
    return result;
  });
  t.mock.method(fs, 'renameSync', (source, target) => {
    const sourcePath = String(source);
    const targetPath = String(target);
    if (failureInjected
      && !successorInjected
      && path.basename(sourcePath) === path.basename(outputs.contactSheet)
      && path.basename(path.dirname(targetPath)).startsWith('.archify-remove-')) {
      renameSync(sourcePath, displaced);
      fs.writeFileSync(sourcePath, successor, { flag: 'wx' });
      successorIdentity = entryIdentity(sourcePath);
      successorInjected = true;
    }
    return renameSync(sourcePath, targetPath);
  });

  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser(),
  });

  assert.equal(failureInjected, true, JSON.stringify(result.receipt.diagnostics.at(-1)));
  assert.equal(successorInjected, true, JSON.stringify(result.receipt.diagnostics.at(-1)));
  assert.equal(result.exitCode, 1);
  assert.deepEqual(fs.readFileSync(outputs.contactSheet), successor);
  assert.deepEqual(entryIdentity(outputs.contactSheet), successorIdentity);
  const rollbackErrors = result.receipt.diagnostics.at(-1)?.evidence?.errors || [];
  assert.ok(rollbackErrors.some(
    (entry) => entry.file
      && path.basename(entry.file) === path.basename(outputs.contactSheet)
      && /successor was restored and preserved/.test(entry.reason),
  ));
});

test('visual-check restore rollback preserves a successor swapped at its public cleanup boundary', async (t) => {
  const input = artifact('restore-public-cleanup-successor.html');
  const outputs = sidecarPaths(input);
  const first = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser(),
  });
  assert.equal(first.exitCode, 0);

  const displaced = path.join(tmp, 'restore-public-cleanup-owned-displaced.html');
  const successor = Buffer.from('external successor at restore cleanup boundary\n');
  const stagingBefore = new Set(stagingDirectories(path.dirname(outputs.receipt)));
  const linkSync = fs.linkSync.bind(fs);
  const lstatSync = fs.lstatSync.bind(fs);
  const unlinkSync = fs.unlinkSync.bind(fs);
  const renameSync = fs.renameSync.bind(fs);
  let publicationFailed = false;
  let corruptNextRestoredStat = false;
  let verificationInjected = false;
  let successorInjected = false;
  let successorIdentity;
  const injectSuccessor = (publicPath) => {
    renameSync(publicPath, displaced);
    fs.writeFileSync(publicPath, successor, { flag: 'wx' });
    successorIdentity = entryIdentity(publicPath);
    successorInjected = true;
  };
  t.after(() => {
    fs.rmSync(displaced, { force: true });
    for (const directory of stagingDirectories(path.dirname(outputs.receipt))) {
      if (!stagingBefore.has(directory)) {
        fs.rmSync(path.join(path.dirname(outputs.receipt), directory), { recursive: true, force: true });
      }
    }
  });
  t.mock.method(fs, 'linkSync', (source, target) => {
    const sourcePath = String(source);
    const targetPath = String(target);
    const fromStaging = path.basename(path.dirname(sourcePath)).startsWith('.archify-visual-check-');
    if (!publicationFailed
      && fromStaging
      && path.basename(sourcePath) === 'contact-sheet.html'
      && path.basename(targetPath) === path.basename(outputs.contactSheet)) {
      publicationFailed = true;
      throw new Error('synthetic publication failure before backup restore');
    }
    const result = linkSync(sourcePath, targetPath);
    if (path.basename(sourcePath) === 'previous-1'
      && path.basename(targetPath) === path.basename(outputs.contactSheet)) {
      corruptNextRestoredStat = true;
    }
    return result;
  });
  t.mock.method(fs, 'lstatSync', (file, options) => {
    const filePath = String(file);
    const stat = lstatSync(filePath, options);
    if (corruptNextRestoredStat
      && path.basename(filePath) === path.basename(outputs.contactSheet)) {
      corruptNextRestoredStat = false;
      verificationInjected = true;
      return new Proxy(stat, {
        get(target, property, receiver) {
          if (property === 'ino') return target.ino + 1n;
          const value = Reflect.get(target, property, receiver);
          return typeof value === 'function' ? value.bind(target) : value;
        },
      });
    }
    return stat;
  });
  t.mock.method(fs, 'unlinkSync', (file) => {
    const filePath = String(file);
    if (verificationInjected
      && !successorInjected
      && path.basename(filePath) === path.basename(outputs.contactSheet)) {
      injectSuccessor(filePath);
    }
    return unlinkSync(filePath);
  });
  t.mock.method(fs, 'renameSync', (source, target) => {
    const sourcePath = String(source);
    const targetPath = String(target);
    if (verificationInjected
      && !successorInjected
      && path.basename(sourcePath) === path.basename(outputs.contactSheet)
      && path.basename(path.dirname(targetPath)).startsWith('.archify-remove-')) {
      injectSuccessor(sourcePath);
    }
    return renameSync(sourcePath, targetPath);
  });

  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser(),
  });

  assert.equal(publicationFailed, true);
  assert.equal(verificationInjected, true);
  assert.equal(successorInjected, true);
  assert.equal(result.exitCode, 1);
  assert.equal(fs.existsSync(outputs.contactSheet), true);
  assert.deepEqual(fs.readFileSync(outputs.contactSheet), successor);
  assert.deepEqual(entryIdentity(outputs.contactSheet), successorIdentity);
});

test('visual-check keeps slow Chrome startup inside one bounded gate invocation', async () => {
  assert.equal(CHROME_STARTUP_TIMEOUT_MS, 90000);
  const input = artifact('chrome-startup-timeout.html');
  const child = fakeChromeChild();

  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => new ChromeVisualBrowser('/fake/chrome', {
      startupTimeoutMs: 5,
      spawnImpl: () => child,
    }),
  });

  assert.equal(result.exitCode, 1);
  assert.equal(result.receipt.diagnostics[0]?.code, 'viewer/chrome-startup-timeout');
  assert.match(result.receipt.error, /Target\.getTargets: timed out after 5ms/);
  assert.match(result.receipt.error, /Chrome process: still running/);
  assert.match(
    result.receipt.diagnostics[0]?.supportedFixes?.join('\n') || '',
    /do not edit or simplify the artifact/,
  );
  assert.match(
    result.receipt.diagnostics[0]?.supportedFixes?.join('\n') || '',
    /retry visual-check once.*stop and report the environment failure/,
  );
});

for (const scenario of [
  { name: 'backup unlink', fault: 'unlink' },
  { name: 'staging rmdir', fault: 'rmdir' },
]) {
  test(`visual-check reports committed cleanup warning after ${scenario.name} failure`, async (t) => {
    const input = artifact(`committed-cleanup-${scenario.fault}.html`);
    const outputs = sidecarPaths(input);
    const first = await runVisualCheck({
      artifactPath: input,
      chromePath: '/fake/chrome',
      browserFactory: async () => fakeBrowser(),
    });
    assert.equal(first.exitCode, 0);
    const oldContactSheet = fs.readFileSync(outputs.contactSheet);
    const stagingBefore = new Set(stagingDirectories(path.dirname(outputs.receipt)));
    const claimantBytes = Buffer.from('external staging cleanup claimant\n');
    let injected = false;
    let retainedPath;

    if (scenario.fault === 'unlink') {
      const unlinkSync = fs.unlinkSync.bind(fs);
      t.mock.method(fs, 'unlinkSync', (file) => {
        const candidate = String(file);
        if (!injected
          && path.basename(candidate) === 'previous-1'
          && path.basename(path.dirname(candidate)).startsWith('.archify-remove-')) {
          injected = true;
          retainedPath = candidate;
          const error = new Error('synthetic backup unlink failure');
          error.code = 'EACCES';
          throw error;
        }
        return unlinkSync(file);
      });
    } else {
      const rmdirSync = fs.rmdirSync.bind(fs);
      t.mock.method(fs, 'rmdirSync', (directory) => {
        const candidate = String(directory);
        if (!injected && path.basename(candidate).startsWith('.archify-visual-check-')) {
          retainedPath = path.join(candidate, 'external-cleanup-claimant');
          fs.writeFileSync(retainedPath, claimantBytes, { flag: 'wx' });
          injected = true;
        }
        return rmdirSync(directory);
      });
    }
    t.after(() => {
      for (const directory of stagingDirectories(path.dirname(outputs.receipt))) {
        if (!stagingBefore.has(directory)) {
          fs.rmSync(path.join(path.dirname(outputs.receipt), directory), { recursive: true, force: true });
        }
      }
    });

    const result = await runVisualCheck({
      artifactPath: input,
      chromePath: '/fake/chrome',
      browserFactory: async () => fakeBrowser(),
    });

    assert.equal(injected, true);
    assert.equal(result.exitCode, 1);
    assert.equal(result.receipt.ok, false);
    assert.equal(result.receipt.status, 'fail');
    assert.equal(result.receipt.publication?.status, 'committed-with-warning');
    const expectedRecovery = scenario.fault === 'unlink'
      ? path.dirname(path.dirname(retainedPath))
      : path.dirname(retainedPath);
    assert.equal(result.receipt.publication?.recoveryDirectory, expectedRecovery);
    assert.ok(result.receipt.publication?.cleanupErrors?.length > 0);
    assert.match(result.receipt.error, /cleanup is incomplete/i);
    assert.ok(result.receipt.error.includes(expectedRecovery));
    const cleanupDiagnostic = result.receipt.diagnostics.at(-1);
    assert.equal(cleanupDiagnostic?.code, 'viewer/evidence-cleanup-incomplete');
    assert.equal(cleanupDiagnostic?.severity, 'warning');
    assert.equal(
      cleanupDiagnostic?.evidence?.recoveryDirectory,
      expectedRecovery,
    );
    assert.equal(fs.existsSync(retainedPath), true);
    assert.deepEqual(
      fs.readFileSync(retainedPath),
      scenario.fault === 'unlink' ? oldContactSheet : claimantBytes,
    );
    assert.equal(JSON.parse(fs.readFileSync(outputs.receipt, 'utf8')).status, 'pass');
    const summary = summarizeBrowserEvidence(result.receipt);
    assert.equal(summary.status, 'fail', 'cleanup failure stays visible after evidence was committed');
    assert.equal(fs.realpathSync.native(summary.evidence.receipt), fs.realpathSync.native(outputs.receipt));
    assert.deepEqual(summary.publication, result.receipt.publication);
    assert.equal(summary.publication.recoveryDirectory, expectedRecovery);
    assert.deepEqual(summary.diagnostics, result.receipt.diagnostics);
    assert.equal(fs.existsSync(outputs.contactSheet), true);
    assert.equal(outputs.screenshots.every((entry) => fs.existsSync(entry.path)), true);
  });
}

test('public visual-check CLI reports a committed cleanup warning', (t) => {
  const input = artifact('public-cli-committed-cleanup-warning.html');
  const outputs = sidecarPaths(input);
  const cli = path.join(skillRoot, 'bin', 'archify.mjs');
  const missingChrome = path.join(tmp, 'missing-cleanup-warning-chrome');
  const baseEnv = {
    ...process.env,
    ARCHIFY_CHROME: missingChrome,
    ARCHIFY_UPDATE_CHECK_DISABLED: '1',
  };
  const first = spawnSync(process.execPath, [cli, 'visual-check', input, '--json'], {
    encoding: 'utf8',
    env: baseEnv,
  });
  assert.equal(first.status, 2, first.stderr || first.stdout);
  const oldReceipt = fs.readFileSync(outputs.receipt);
  const stagingBefore = new Set(stagingDirectories(path.dirname(outputs.receipt)));
  const hook = path.join(tmp, 'visual-cleanup-warning-hook.mjs');
  fs.writeFileSync(hook, `
    import fs from 'node:fs';
    import path from 'node:path';
    const unlinkSync = fs.unlinkSync.bind(fs);
    let injected = false;
    fs.unlinkSync = (file) => {
      const candidate = String(file);
      if (!injected
        && path.basename(candidate) === 'previous-0'
        && path.basename(path.dirname(candidate)).startsWith('.archify-remove-')) {
        injected = true;
        const error = new Error('synthetic public CLI backup unlink failure');
        error.code = 'EACCES';
        throw error;
      }
      return unlinkSync(file);
    };
  `);
  t.after(() => {
    for (const directory of stagingDirectories(path.dirname(outputs.receipt))) {
      if (!stagingBefore.has(directory)) {
        fs.rmSync(path.join(path.dirname(outputs.receipt), directory), { recursive: true, force: true });
      }
    }
  });

  const second = spawnSync(process.execPath, [cli, 'visual-check', input, '--json'], {
    encoding: 'utf8',
    env: {
      ...baseEnv,
      NODE_OPTIONS: `--import=${pathToFileURL(hook).href}`,
    },
  });

  assert.equal(second.status, 1, second.stderr || second.stdout);
  const receipt = JSON.parse(second.stdout);
  assert.equal(receipt.status, 'fail');
  assert.equal(receipt.ok, false);
  assert.equal(receipt.publication?.status, 'committed-with-warning');
  assert.match(receipt.error, /cleanup is incomplete/i);
  assert.equal(receipt.diagnostics.at(-1)?.code, 'viewer/evidence-cleanup-incomplete');
  assert.equal(receipt.diagnostics.at(-1)?.severity, 'warning');
  const recoveryDirectory = receipt.publication?.recoveryDirectory;
  assert.equal(typeof recoveryDirectory, 'string');
  const quarantine = fs.readdirSync(recoveryDirectory)
    .find((entry) => entry.startsWith('.archify-remove-'));
  assert.equal(typeof quarantine, 'string');
  const retained = path.join(recoveryDirectory, quarantine, 'previous-0');
  assert.deepEqual(fs.readFileSync(retained), oldReceipt);
  assert.equal(JSON.parse(fs.readFileSync(outputs.receipt, 'utf8')).status, 'skipped');
});

test('visual-check retries transient remote ENOTEMPTY during staging cleanup', async (t) => {
  const input = artifact('transient-staging-enotempty.html');
  const outputDirectory = path.dirname(input);
  const rmdirSync = fs.rmdirSync.bind(fs);
  let injected = false;
  t.mock.method(fs, 'rmdirSync', (directory, ...args) => {
    if (!injected && path.basename(String(directory)).startsWith('.archify-visual-check-')) {
      injected = true;
      throw Object.assign(new Error('simulated remote deletion visibility delay'), { code: 'ENOTEMPTY' });
    }
    return rmdirSync(directory, ...args);
  });

  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser(),
  });

  assert.equal(injected, true);
  assert.equal(result.exitCode, 0);
  assert.deepEqual(result.receipt.diagnostics, []);
  assert.deepEqual(stagingDirectories(outputDirectory), []);
});

for (const scenario of ['successful evidence set', 'failure receipt', 'publication rollback']) {
  test(`visual-check closes staged bindings before SMB cleanup for ${scenario}`, async (t) => {
    const input = artifact(`smb-binding-cleanup-${scenario.replaceAll(' ', '-')}.html`);
    const outDir = fs.mkdtempSync(path.join(tmp, 'smb-binding-cleanup-'));
    t.after(() => fs.rmSync(outDir, { recursive: true, force: true }));
    const openSync = fs.openSync.bind(fs);
    const closeSync = fs.closeSync.bind(fs);
    const renameSync = fs.renameSync.bind(fs);
    const rmdirSync = fs.rmdirSync.bind(fs);
    const linkSync = fs.linkSync.bind(fs);
    const descriptors = new Map();
    const quarantines = new Map();
    let deferredRemovals = 0;
    let publicationFailed = false;
    const identityKey = (stat) => `${stat.dev}:${stat.ino}`;
    t.mock.method(fs, 'openSync', (...args) => {
      const descriptor = openSync(...args);
      descriptors.set(descriptor, identityKey(fs.fstatSync(descriptor, { bigint: true })));
      return descriptor;
    });
    t.mock.method(fs, 'closeSync', (descriptor) => {
      closeSync(descriptor);
      descriptors.delete(descriptor);
    });
    t.mock.method(fs, 'renameSync', (source, destination) => {
      const directory = path.dirname(String(destination));
      if (path.basename(directory).startsWith('.archify-remove-')) {
        quarantines.set(directory, identityKey(fs.lstatSync(source, { bigint: true })));
      }
      return renameSync(source, destination);
    });
    t.mock.method(fs, 'rmdirSync', (directory, ...args) => {
      const identity = quarantines.get(String(directory));
      if (identity && [...descriptors.values()].includes(identity)) {
        deferredRemovals += 1;
        throw Object.assign(new Error('SMB deletion remains pending while a file handle is open'), {
          code: 'ENOTEMPTY',
        });
      }
      return rmdirSync(directory, ...args);
    });
    if (scenario === 'publication rollback') {
      t.mock.method(fs, 'linkSync', (source, destination) => {
        if (!publicationFailed && path.basename(String(source)) === 'capture-0.png') {
          publicationFailed = true;
          throw new Error('synthetic screenshot publication failure');
        }
        return linkSync(source, destination);
      });
    }

    const result = await runVisualCheck({
      artifactPath: input,
      outDir,
      chromePath: '/fake/chrome',
      browserFactory: async () => fakeBrowser({
        screenshotFailure: () => scenario === 'failure receipt',
      }),
    });

    assert.ok(deferredRemovals > 0, 'the fixture must exercise an open-handle SMB deletion delay');
    assert.equal(result.exitCode, scenario === 'successful evidence set' ? 0 : 1);
    assert.equal(publicationFailed, scenario === 'publication rollback');
    assert.deepEqual(stagingDirectories(outDir), []);
    assert.equal(descriptors.size, 0);
    assert.doesNotMatch(JSON.stringify(result.receipt.diagnostics), /ENOTEMPTY|cleanup is incomplete/);
  });
}

test('visual-check reports a claimant retained by deferred staging cleanup', async (t) => {
  const input = artifact('smb-binding-cleanup-claimant.html');
  const outDir = fs.mkdtempSync(path.join(tmp, 'smb-cleanup-claimant-'));
  t.after(() => fs.rmSync(outDir, { recursive: true, force: true }));
  const rmdirSync = fs.rmdirSync.bind(fs);
  const sentinel = 'external claimant retained during deferred cleanup\n';
  let claimantPath;
  t.mock.method(fs, 'rmdirSync', (directory, ...args) => {
    if (!claimantPath && path.basename(String(directory)).startsWith('.archify-remove-')) {
      claimantPath = path.join(directory, 'external-claimant');
      fs.writeFileSync(claimantPath, sentinel, { flag: 'wx' });
    }
    return rmdirSync(directory, ...args);
  });

  const result = await runVisualCheck({
    artifactPath: input,
    outDir,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser(),
  });

  assert.equal(result.exitCode, 1);
  assert.equal(result.receipt.publication?.status, 'committed-with-warning');
  assert.equal(fs.readFileSync(claimantPath, 'utf8'), sentinel);
  const cleanupError = result.receipt.publication.cleanupErrors.find(
    (entry) => entry.recoveryDirectory === path.dirname(claimantPath),
  );
  assert.equal(cleanupError?.reason, 'removal-quarantine-cleanup-failed');
  assert.equal(cleanupError?.bindingState.systemCode, 'ENOTEMPTY');
  assert.equal(result.receipt.diagnostics.at(-1)?.code, 'viewer/evidence-cleanup-incomplete');
});

test('visual-check rolls back when staged evidence changes after receipt binding', async (t) => {
  const input = artifact('staged-content-changed-after-receipt-binding.html');
  const outputs = sidecarPaths(input);
  const sentinel = Buffer.from('mutated staged screenshot bytes\n');
  const linkSync = fs.linkSync.bind(fs);
  const stagingBefore = new Set(stagingDirectories(path.dirname(outputs.receipt)));
  let changedPath;
  t.after(() => {
    for (const directory of stagingDirectories(path.dirname(outputs.receipt))) {
      if (!stagingBefore.has(directory)) {
        fs.rmSync(path.join(path.dirname(outputs.receipt), directory), { recursive: true, force: true });
      }
    }
  });
  let injected = false;
  t.mock.method(fs, 'linkSync', (source, target) => {
    const result = linkSync(source, target);
    if (!injected
      && path.basename(String(source)) === 'contact-sheet.html'
      && path.basename(path.dirname(String(source))).startsWith('.archify-visual-check-')) {
      changedPath = path.join(path.dirname(String(source)), 'capture-0.png');
      fs.writeFileSync(changedPath, sentinel);
      injected = true;
    }
    return result;
  });

  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser(),
  });

  assert.equal(injected, true);
  assert.equal(result.exitCode, 1);
  assert.equal(result.receipt.diagnostics.at(-1)?.code, 'viewer/evidence-path-conflict');
  assert.equal(
    result.receipt.diagnostics.at(-1)?.evidence?.reason?.code,
    'staged-evidence-content-mismatch',
  );
  assert.equal(fs.existsSync(outputs.receipt), false);
  assert.equal(fs.existsSync(outputs.contactSheet), false);
  assert.equal(outputs.screenshots.every((entry) => !fs.existsSync(entry.path)), true);
  assert.deepEqual(fs.readFileSync(changedPath), sentinel);
  const rollbackErrors = result.receipt.diagnostics.at(-1)?.evidence?.rollbackErrors;
  assert.ok(rollbackErrors.some((entry) => entry.file === changedPath && /content changed; it was preserved/.test(entry.reason)));
});

test('visual-check preserves digest-mismatched evidence instead of treating its receipt as ownership', async () => {
  const input = artifact('digest-mismatched-evidence.html');
  const outputs = sidecarPaths(input);
  const first = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser(),
  });
  assert.equal(first.exitCode, 0);
  const sentinel = Buffer.from('tampered contact sheet\n');
  fs.writeFileSync(outputs.contactSheet, sentinel);
  const receiptBefore = fs.readFileSync(outputs.receipt);
  let launched = false;

  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => { launched = true; return fakeBrowser(); },
  });

  assert.equal(result.exitCode, 1);
  assert.equal(launched, false);
  assert.equal(result.receipt.diagnostics.at(-1)?.code, 'viewer/evidence-path-conflict');
  assert.equal(result.receipt.diagnostics.at(-1)?.evidence?.reason?.code, 'ownership-evidence-digest-mismatch');
  assert.deepEqual(fs.readFileSync(outputs.contactSheet), sentinel);
  assert.deepEqual(fs.readFileSync(outputs.receipt), receiptBefore);
});

test('public visual-check CLI preserves an unowned contact-sheet path', () => {
  const input = artifact('public-cli-evidence-collision.html');
  const outputs = sidecarPaths(input);
  const sentinel = Buffer.from('<!doctype html><title>independent artifact</title>\n');
  fs.writeFileSync(outputs.contactSheet, sentinel);

  const result = spawnSync(process.execPath, [
    path.join(skillRoot, 'bin', 'archify.mjs'),
    'visual-check',
    input,
    '--json',
  ], {
    cwd: skillRoot,
    encoding: 'utf8',
    env: { ...process.env, ARCHIFY_CHROME: '' },
  });

  assert.equal(result.status, 1, result.stderr);
  const receipt = JSON.parse(result.stdout);
  assert.equal(receipt.diagnostics.at(-1)?.code, 'viewer/evidence-path-conflict');
  assert.deepEqual(fs.readFileSync(outputs.contactSheet), sentinel);
  assert.equal(fs.existsSync(outputs.receipt), false);
});

test('visual-check fails closed without writes when sidecar directory identity is unknown', async () => {
  const input = artifact('unknown-sidecar-identity.html');
  const unknownIdentity = () => ({
    status: 'unknown',
    reason: { code: 'synthetic-identity-unavailable', systemCode: 'EACCES' },
  });
  const runOutDir = path.join(tmp, 'unknown-sidecar-run');
  let launched = false;

  const result = await runVisualCheck({
    artifactPath: input,
    outDir: runOutDir,
    chromePath: '/fake/chrome',
    compareSidecarParents: unknownIdentity,
    browserFactory: async () => {
      launched = true;
      return fakeBrowser();
    },
  });

  assert.equal(result.exitCode, 1);
  assert.equal(result.receipt.status, 'fail');
  assert.match(result.receipt.error, /physical identity/i);
  assert.equal(result.receipt.diagnostics.at(-1)?.code, 'viewer/sidecar-directory-identity');
  assert.equal(
    result.receipt.diagnostics.at(-1)?.evidence?.comparison?.code,
    'synthetic-identity-unavailable',
  );
  assert.equal(launched, false);
  assert.equal(fs.existsSync(runOutDir), false, 'identity failure must precede evidence directory creation');

  const persistOutDir = path.join(tmp, 'unknown-sidecar-persist');
  const persistOutputs = sidecarPaths(input, { outDir: persistOutDir });
  fs.mkdirSync(persistOutDir, { recursive: true });
  const existingEvidence = [
    persistOutputs.receipt,
    persistOutputs.contactSheet,
    ...persistOutputs.screenshots.map((entry) => entry.path),
  ];
  for (const [index, file] of existingEvidence.entries()) {
    fs.writeFileSync(file, `existing evidence ${index}\n`);
  }
  const before = existingEvidence.map((file) => fs.readFileSync(file));
  const failure = persistVisualCheckFailure(input, {
    schemaVersion: 1,
    command: 'visual-check',
    artifact: { path: input },
    error: 'synthetic delivery failure',
    diagnostics: [{ code: 'delivery/provenance-failed' }],
  }, {
    outDir: persistOutDir,
    compareSidecarParents: unknownIdentity,
  });
  assert.match(failure.error, /physical identity/i);
  assert.equal(failure.diagnostics.at(-1)?.code, 'viewer/sidecar-directory-identity');
  assert.deepEqual(
    existingEvidence.map((file) => fs.readFileSync(file)),
    before,
    'failure persistence must not invalidate or replace evidence on unknown identity',
  );
});

test('visual-check returns 1 and preserves evidence when any viewport overflows', async () => {
  const input = artifact('overflow.html');
  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser({
      overflowAt: ({ width, theme }) => width === 1600 && theme === 'light',
    }),
  });

  assert.equal(result.exitCode, 1);
  assert.equal(result.receipt.status, 'fail');
  assert.equal(result.receipt.containment.status, 'fail');
  assert.deepEqual(
    result.receipt.containment.viewports.filter((entry) => !entry.ok).map((entry) => [entry.width, entry.height]),
    [[1600, 1000]],
  );
  const diagnostic = result.receipt.diagnostics.find(
    (entry) => entry.code === 'viewer/viewport-overflow',
  );
  assert.deepEqual(diagnostic?.subject, {
    artifact: input,
    viewport: { width: 1600, height: 1000, theme: 'light' },
  });
  assert.equal(diagnostic?.evidence?.scrollWidth, 1601);
  assert.equal(fs.existsSync(sidecarPaths(input).contactSheet), true);
});

test('vertical overflow fixes state the stacked page budget and the actionable target', () => {
  const page = { bodyPaddingPx: 12, headerPx: 100, diagramChromePx: 76, svgPx: 800, cardsPx: 212, viewBoxHeight: 1000 };
  const base = { overflowY: true, innerHeight: 900, scrollHeight: 1200, diagramWidth: 930, pageComposition: page };

  const atMinimum = verticalBudgetFixes({ ...base, readerLayout: 'adaptive', readerOverflow: 'authored' });
  assert.match(atMinimum[0], /300px too tall/);
  assert.match(atMinimum[0], /12px body padding \+ 100px header \+ 76px diagram chrome \+ 800px SVG \+ 212px cards = 1200px against 900px/);
  assert.match(atMinimum[0], /reduce the viewBox height to at most 625 \(from 1000\)/, 'SVG height follows viewBox height at the fixed minimum width: 1000 * 500 / 800');
  assert.equal(atMinimum.length, 1, 'cards (212px) cannot absorb a 300px excess, so no card alternative is offered');

  const fullWidth = verticalBudgetFixes({ ...base, readerLayout: null, readerOverflow: null });
  assert.match(fullWidth[0], /viewBox ratio is below 1\.55/);
  assert.match(fullWidth[0], /remove meta\.viewBox|1\.55x wider than tall/);

  const cardsAbsorb = verticalBudgetFixes({ ...base, scrollHeight: 1000, readerLayout: 'adaptive', readerOverflow: 'authored' });
  assert.match(cardsAbsorb[1], /cards take at most 112px/);

  assert.deepEqual(verticalBudgetFixes({ ...base, pageComposition: undefined }), [], 'old artifacts without composition metrics keep the generic fix');
  assert.deepEqual(verticalBudgetFixes({ ...base, overflowY: false }), []);
});

test('visual-check reports the page composition when a viewport overflows vertically', async () => {
  const input = artifact('tall-overflow.html');
  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser({ tallAt: ({ width }) => width === 1440 }),
  });

  assert.equal(result.exitCode, 1);
  const diagnostic = result.receipt.diagnostics.find((entry) => entry.code === 'viewer/viewport-overflow');
  assert.equal(diagnostic.evidence.pageComposition.svgPx, 800);
  assert.match(diagnostic.evidence.pageCompositionMeasurement, /sum to scrollHeight/);
  assert.match(diagnostic.supportedFixes[0], /300px too tall/);
  assert.equal(diagnostic.supportedFixes.some((fix) => /contain the rendered layout within/.test(fix)), false, 'the numeric budget replaces the generic instruction');
  const viewport = result.receipt.containment.viewports.find(({ width }) => width === 1440);
  assert.equal(viewport.pageComposition.cardsPx, 212);
});

test('visual-check accepts only Reader-declared readable vertical page scrolling', async () => {
  const input = artifact('readable-scroll.html');
  const target = ({ width, theme }) => width === 1440 && theme === 'light';
  for (const automaticReaderFit of ['intrinsic-height', 'width-first']) {
    const result = await runVisualCheck({
      artifactPath: input,
      chromePath: '/fake/chrome',
      browserFactory: async () => fakeBrowser({ readableScrollAt: target, automaticReaderFit }),
    });

    assert.equal(result.exitCode, 0);
    assert.equal(result.receipt.status, 'pass');
    assert.equal(result.receipt.containment.status, 'pass');
    assert.equal(result.receipt.containment.policy, 'fit-or-reader-declared-readable-vertical-scroll');
    const viewport = result.receipt.containment.viewports.find(({ width }) => width === 1440);
    assert.equal(viewport.overflowY, true);
    assert.equal(viewport.verticalScrollAccepted, true);
    assert.equal(viewport.overflowDisposition, 'readable-vertical-scroll');
    assert.equal(viewport.readerLayout, 'adaptive');
    assert.equal(viewport.readerOverflow, 'authored');
    assert.equal(viewport.readerFit, automaticReaderFit);
    assert.equal(result.receipt.diagnostics.some(({ code }) => code === 'viewer/viewport-overflow'), false);
  }
  for (const automaticReaderFit of [null, 'unknown']) {
    const result = await runVisualCheck({ artifactPath: input, chromePath: '/fake/chrome',
      browserFactory: async () => fakeBrowser({ readableScrollAt: target, automaticReaderFit }) });
    assert.equal(result.exitCode, 1);
    assert.equal(result.receipt.containment.viewports.find(({ width }) => width === 1440).verticalScrollAccepted, false);
  }
});

test('visual-check still rejects horizontal overflow and unreadable text in Reader scroll state', async () => {
  const input = artifact('invalid-readable-scroll.html');
  const target = ({ width, theme }) => width === 1440 && theme === 'light';
  const horizontal = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser({ overflowAt: target, readableScrollAt: target }),
  });
  const horizontalViewport = horizontal.receipt.containment.viewports.find(({ width }) => width === 1440);
  assert.equal(horizontal.exitCode, 1);
  assert.equal(horizontalViewport.verticalScrollAccepted, false);
  assert.equal(horizontalViewport.overflowDisposition, 'unexpected-overflow');
  assert.ok(horizontal.receipt.diagnostics.some(({ code }) => code === 'viewer/viewport-overflow'));

  const unreadable = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser({ readableScrollAt: target, unreadableAt: target }),
  });
  const unreadableViewport = unreadable.receipt.containment.viewports.find(({ width }) => width === 1440);
  assert.equal(unreadable.exitCode, 1);
  assert.equal(unreadableViewport.verticalScrollAccepted, false);
  assert.equal(unreadableViewport.overflowDisposition, 'unexpected-overflow');
  assert.ok(unreadable.receipt.diagnostics.some(({ code }) => code === 'viewer/viewport-overflow'));
  assert.ok(unreadable.receipt.diagnostics.some(({ code }) => code === 'viewer/projected-text-readability'));
});

test('visual-check refuses changed delivery evidence before launching a browser', async () => {
  const input = artifact('changed-before-browser.html');
  const outDir = path.join(tmp, 'changed-before-browser-evidence');
  const outputs = sidecarPaths(input, { outDir });
  const previous = await runVisualCheck({
    artifactPath: input,
    outDir,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser(),
  });
  assert.equal(previous.exitCode, 0);
  let launched = false;
  const result = await runVisualCheck({
    artifactPath: input,
    outDir,
    verifyArtifact: () => {
      const error = new Error('delivery changed');
      error.deliveryProvenance = { status: 'mismatch' };
      error.archifyDiagnostics = [{ code: 'delivery/provenance-mismatch' }];
      throw error;
    },
    browserFactory: async () => { launched = true; return fakeBrowser(); },
  });
  assert.equal(launched, false);
  assert.equal(result.exitCode, 1);
  assert.equal(result.receipt.provenance, 'mismatch');
  assert.equal(result.receipt.sidecars.directory, outDir);
  assert.equal(JSON.parse(fs.readFileSync(outputs.receipt)).status, 'fail');
  assert.equal(fs.existsSync(outputs.contactSheet), false);
  assert.ok(outputs.screenshots.every((entry) => !fs.existsSync(entry.path)));
  assert.equal(fs.existsSync(sidecarPaths(input).receipt), false);
});

test('visual-check failure persistence refuses an unowned non-file evidence path', () => {
  const input = artifact('uncleanable-evidence.html');
  const outputs = sidecarPaths(input);
  fs.mkdirSync(outputs.screenshots[0].path);
  const receipt = persistVisualCheckFailure(input, {
    schemaVersion: 1, command: 'visual-check', artifact: { path: input },
    error: 'delivery failed', diagnostics: [{ code: 'delivery/provenance-failed' }],
  });
  assert.equal(receipt.diagnostics[1].code, 'viewer/evidence-path-conflict');
  assert.equal(receipt.diagnostics[1].subject.evidencePath, outputs.screenshots[0].path);
  assert.equal(fs.existsSync(outputs.receipt), false);
  assert.equal(fs.statSync(outputs.screenshots[0].path).isDirectory(), true);
});

test('visual-check rechecks delivery evidence after capture and discards screenshots on failure', async () => {
  const input = artifact('changed-during-browser.html');
  let failedDelivery = false;
  const before = fs.readFileSync(input);
  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    deliveryProvenance: { status: 'current', receiptId: 'previous-receipt' },
    verifyArtifact: (bytes) => {
      assert.deepEqual(bytes, before);
      if (failedDelivery) {
        const error = new Error('Another delivery failed during capture.');
        error.deliveryProvenance = { status: 'failed' };
        error.archifyDiagnostics = [{ code: 'delivery/provenance-failed' }];
        throw error;
      }
    },
    browserFactory: async () => { failedDelivery = true; return fakeBrowser(); },
  });
  assert.equal(result.exitCode, 1);
  assert.equal(result.receipt.provenance, 'failed');
  assert.equal(result.receipt.diagnostics[0].code, 'delivery/provenance-failed');
  const outputs = sidecarPaths(input);
  assert.equal(JSON.parse(fs.readFileSync(outputs.receipt)).status, 'fail');
  assert.equal(fs.existsSync(outputs.contactSheet), false);
  assert.ok(outputs.screenshots.every((entry) => !fs.existsSync(entry.path)));
});

test('visual-check preserves a screenshot-path claimant after post-capture provenance failure', async () => {
  const input = artifact('changed-with-uncleanable-browser-evidence.html');
  const outputs = sidecarPaths(input);
  let verificationCount = 0;
  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    deliveryProvenance: { status: 'current', receiptId: 'previous-receipt' },
    verifyArtifact: () => {
      verificationCount += 1;
      if (verificationCount === 2) {
        fs.mkdirSync(outputs.screenshots[0].path);
        const error = new Error('Another delivery failed during capture.');
        error.deliveryProvenance = { status: 'failed' };
        error.archifyDiagnostics = [{ code: 'delivery/provenance-failed' }];
        throw error;
      }
    },
    browserFactory: async () => fakeBrowser(),
  });

  assert.equal(result.exitCode, 1);
  assert.equal(result.receipt.provenance, 'failed');
  assert.deepEqual(result.receipt.diagnostics.map((entry) => entry.code), [
    'delivery/provenance-failed',
    'viewer/evidence-path-conflict',
  ]);
  assert.equal(result.receipt.diagnostics[1].subject.evidencePath, outputs.screenshots[0].path);
  assert.equal(fs.statSync(outputs.screenshots[0].path).isDirectory(), true);
  assert.equal(fs.existsSync(outputs.receipt), false);
});

test('visual-check returns 1 when the real reader projects node text below 6px', async () => {
  const input = artifact('unreadable.html');
  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser({
      unreadableAt: ({ width, height, theme }) => width === 1440 && height === 900 && theme === 'light',
    }),
  });

  assert.equal(result.exitCode, 1);
  assert.equal(result.receipt.status, 'fail');
  assert.equal(result.receipt.readability.status, 'fail');
  const desktop = result.receipt.readability.viewports.find(
    (entry) => entry.width === 1440 && entry.height === 900,
  );
  assert.equal(desktop?.diagramWidth, 930);
  assert.equal(desktop?.minimumProjectedNodeText, 'Compact node');
  assert.equal(desktop?.minimumProjectedNodeTextDetail, 'primary');
  assert.equal(desktop?.readabilityOk, false);
  const diagnostic = result.receipt.diagnostics.find(
    (entry) => entry.code === 'viewer/projected-text-readability',
  );
  assert.equal(diagnostic?.evidence?.text, 'Compact node');
  assert.equal(diagnostic?.evidence?.minimumProjectedNodeTextPx, 5.72);
  assert.equal(diagnostic?.evidence?.minimumRequiredNodeTextPx, 6);
});

test('visual-check returns 1 when the navigation dock obscures the SVG legend', async () => {
  const input = artifact('viewer-chrome-collision.html');
  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser({
      chromeCollisionAt: ({ width, height, theme }) => (
        width === 1920 && height === 1080 && theme === 'light'
      ),
    }),
  });

  assert.equal(result.exitCode, 1);
  assert.equal(result.receipt.status, 'fail');
  assert.equal(result.receipt.viewerChrome.status, 'fail');
  const desktop = result.receipt.viewerChrome.viewports.find(
    (entry) => entry.width === 1920 && entry.height === 1080,
  );
  assert.equal(desktop?.legendDockIntersectionArea, 42);
  assert.equal(desktop?.viewerChromeOk, false);
  const diagnostic = result.receipt.diagnostics.find(
    (entry) => entry.code === 'viewer/chrome-legend-clearance',
  );
  assert.equal(diagnostic?.evidence?.legendDockIntersectionArea, 42);
});

test('visual-check returns 1 when the navigation dock enters the SVG stage', async () => {
  const input = artifact('viewer-stage-collision.html');
  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser({
      stageCollisionAt: ({ width, height, theme }) => (
        width === 1920 && height === 1080 && theme === 'light'
      ),
    }),
  });

  assert.equal(result.exitCode, 1);
  assert.equal(result.receipt.status, 'fail');
  assert.equal(result.receipt.viewerChrome.status, 'fail');
  const desktop = result.receipt.viewerChrome.viewports.find(
    (entry) => entry.width === 1920 && entry.height === 1080,
  );
  assert.equal(desktop?.dockStageIntersectionArea, 84);
  assert.equal(desktop?.dockStageGap, -12);
  assert.equal(desktop?.requiredDockStageGap, 10);
  assert.equal(desktop?.viewerChromeStageOk, false);
  assert.equal(desktop?.viewerChromeOk, false);
  const diagnostic = result.receipt.diagnostics.find(
    (entry) => entry.code === 'viewer/chrome-stage-clearance',
  );
  assert.deepEqual(diagnostic?.subject, {
    artifact: input,
    viewport: { width: 1920, height: 1080, theme: 'light' },
  });
  assert.deepEqual(diagnostic?.evidence, {
    dockStageIntersectionArea: 84,
    dockStageGap: -12,
    requiredDockStageGap: 10,
  });
  assert.match(diagnostic?.message || '', /enters the protected SVG stage/);
  assert.ok(diagnostic?.supportedFixes.some((fix) => fix.includes('dockStageGap')));
  assert.equal(diagnostic?.supportedFixes.some((fix) => fix.includes('regenerate')), false);
});

test('visual-check describes insufficient stage clearance without claiming an overlap', async () => {
  const input = artifact('viewer-stage-low-gap.html');
  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser({
      stageGapAt: ({ width, height, theme }) => (
        width === 1920 && height === 1080 && theme === 'light' ? 5 : 10
      ),
    }),
  });

  assert.equal(result.exitCode, 1);
  const diagnostic = result.receipt.diagnostics.find(
    (entry) => entry.code === 'viewer/chrome-stage-clearance',
  );
  assert.equal(diagnostic?.evidence?.dockStageIntersectionArea, 0);
  assert.equal(diagnostic?.evidence?.dockStageGap, 5);
  assert.match(diagnostic?.message || '', /clearance.*below the required gap/i);
  assert.doesNotMatch(diagnostic?.message || '', /enters/i);
});

test('visual-check returns 1 and removes misleading capture sidecars on screenshot failure', async () => {
  const input = artifact('capture-failure.html');
  const outputs = sidecarPaths(input);
  const previous = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser(),
  });
  assert.equal(previous.exitCode, 0);

  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser({
      screenshotFailure: ({ theme }) => theme === 'dark',
    }),
  });

  assert.equal(result.exitCode, 1);
  assert.equal(result.receipt.status, 'fail');
  assert.equal(result.receipt.captures.status, 'fail');
  assert.match(result.receipt.error, /synthetic screenshot failure/);
  assert.equal(result.receipt.diagnostics[0]?.code, 'viewer/visual-check-runtime');
  assert.match(result.receipt.diagnostics[0]?.evidence?.reason || '', /synthetic screenshot failure/);
  assert.equal(fs.existsSync(outputs.contactSheet), false);
  assert.equal(outputs.screenshots.some((entry) => fs.existsSync(entry.path)), false);
  assert.equal(fs.existsSync(outputs.receipt), true);
});

test('visual-check returns 2 with a truthful skipped receipt when Chrome is unavailable', async () => {
  const input = artifact('no-chrome.html');
  const result = await runVisualCheck({
    artifactPath: input,
    resolveChrome: () => null,
  });

  assert.equal(result.exitCode, 2);
  assert.equal(result.receipt.status, 'skipped');
  assert.equal(result.receipt.containment.status, 'skipped');
  assert.equal(result.receipt.viewerChrome.status, 'skipped');
  assert.equal(result.receipt.captures.status, 'skipped');
  assert.equal(result.receipt.visualReview, 'pending');
  assert.equal(result.receipt.diagnostics[0]?.code, 'viewer/chrome-unavailable');
  assert.match(result.receipt.error, /Microsoft Edge/);
  assert.ok(result.receipt.diagnostics[0]?.supportedFixes.some((fix) => fix.includes('ARCHIFY_CHROME') && fix.includes('Microsoft Edge')));
  assert.equal(fs.existsSync(sidecarPaths(input).receipt), true);
});

test('a no-Chrome rerun retires captures only when the successful receipt proves ownership', async () => {
  const input = artifact('no-chrome-owned-rerun.html');
  const outputs = sidecarPaths(input);
  const first = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => fakeBrowser(),
  });
  assert.equal(first.exitCode, 0);
  assert.equal(fs.existsSync(outputs.contactSheet), true);
  assert.equal(outputs.screenshots.every((entry) => fs.existsSync(entry.path)), true);

  const skipped = await runVisualCheck({ artifactPath: input, resolveChrome: () => null });

  assert.equal(skipped.exitCode, 2);
  assert.equal(JSON.parse(fs.readFileSync(outputs.receipt, 'utf8')).status, 'skipped');
  assert.equal(fs.existsSync(outputs.contactSheet), false);
  assert.equal(outputs.screenshots.every((entry) => !fs.existsSync(entry.path)), true);
  assert.deepEqual(stagingDirectories(path.dirname(outputs.receipt)), []);
});

process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));

test('vertical workflow overflow reports measured frames and conditional reflow guidance without changing the artifact', async () => {
  const file = artifact('workflow-overflow.html');
  const before = sha256(file);
  const browser = fakeBrowser();
  const inspect = browser.inspect.bind(browser);
  const lanes = [{ frameId: 'lane-0', heightPx: 720, nodeCount: 12, nodeIds: ['wait', 'cancel'], nodeSpanPx: 480, spaceAboveNodesPx: 180, spaceBelowNodesPx: 60 }];
  browser.inspect = async (args) => ({ ...(await inspect(args)), scrollHeight: args.height + 599, workflowLanes: lanes });
  const result = await runVisualCheck({ artifactPath: file, chromePath: '/fake/chrome', browserFactory: async () => browser });
  assert.equal(result.exitCode, 1);
  const diagnostic = result.receipt.diagnostics.find(({ code }) => code === 'viewer/viewport-overflow');
  assert.deepEqual(diagnostic.evidence.workflowLanes, lanes);
  assert.match(diagnostic.evidence.measurement, /not guaranteed removable/);
  assert.match(diagnostic.supportedFixes.join('\n'), /--layout-json/);
  assert.match(diagnostic.supportedFixes.join('\n'), /ownership and explicit geometry permit/);
  assert.match(diagnostic.supportedFixes.join('\n'), /not a verified coordinate fix/);
  assert.equal(sha256(file), before);
  browser.inspect = async (args) => ({ ...(await inspect(args)), scrollWidth: args.width + 1, workflowLanes: lanes });
  const horizontal = await runVisualCheck({ artifactPath: file, chromePath: '/fake/chrome', browserFactory: async () => browser });
  const horizontalOverflow = horizontal.receipt.diagnostics.find(({ code }) => code === 'viewer/viewport-overflow');
  assert.equal(horizontalOverflow.evidence.workflowLanes, undefined);
  assert.equal(horizontalOverflow.supportedFixes.length, 1);
});

test('visual-check reports local inspection cleanup failure alongside an evidence target conflict', async (t) => {
  const input = artifact('inspection-cleanup-target-conflict.html');
  const outDir = fs.mkdtempSync(path.join(tmp, 'inspection-cleanup-target-conflict-'));
  const outputs = sidecarPaths(input, { outDir });
  const sentinel = 'external receipt claimant\n';
  const browser = fakeBrowser();
  const inspect = browser.inspect.bind(browser);
  const rmdirSync = fs.rmdirSync.bind(fs);
  let inspectionDirectory;
  let claimed = false;
  let cleanupAttempts = 0;
  browser.inspect = async (args) => {
    inspectionDirectory = path.dirname(args.artifactPath);
    if (!claimed) {
      fs.writeFileSync(outputs.receipt, sentinel, { flag: 'wx' });
      claimed = true;
    }
    return inspect(args);
  };
  t.mock.method(fs, 'rmdirSync', (directory, ...args) => {
    if (String(directory) === inspectionDirectory) {
      cleanupAttempts += 1;
      throw Object.assign(new Error('synthetic inspection cleanup denied during target conflict'), {
        code: 'EACCES',
      });
    }
    return rmdirSync(directory, ...args);
  });
  t.after(() => {
    t.mock.restoreAll();
    if (inspectionDirectory) fs.rmSync(inspectionDirectory, { recursive: true, force: true });
    fs.rmSync(outDir, { recursive: true, force: true });
  });

  const result = await runVisualCheck({
    artifactPath: input,
    outDir,
    chromePath: '/fake/chrome',
    browserFactory: async () => browser,
  });

  assert.equal(claimed, true);
  assert.ok(cleanupAttempts > 0, 'the fixture must exercise local inspection cleanup failure');
  assert.equal(result.exitCode, 1);
  assert.equal(fs.readFileSync(outputs.receipt, 'utf8'), sentinel);
  assert.deepEqual(fs.readdirSync(inspectionDirectory), []);
  assert.deepEqual(stagingDirectories(outDir), []);
  const conflict = result.receipt.diagnostics.at(-1);
  assert.equal(conflict?.code, 'viewer/evidence-path-conflict');
  assert.ok(conflict.evidence.rollbackErrors?.some((entry) => (
    entry.file === inspectionDirectory
    && entry.recoveryDirectory === inspectionDirectory
    && /synthetic inspection cleanup denied/.test(entry.reason)
  )), 'the conflict must report the retained local inspection directory');
});

test('browser-check proves rendered behavior without creating screenshots or requiring perceptual review', async () => {
  const input = artifact('browser-check-passing.html');
  const browser = fakeBrowser();
  const result = await runBrowserCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => browser,
  });

  assert.equal(result.exitCode, 0);
  assert.equal(result.receipt.command, 'browser-check');
  assert.equal(result.receipt.status, 'pass');
  assert.equal(result.receipt.visualReview, 'not-requested');
  assert.equal(result.receipt.themeStates.status, 'pass');
  assert.equal(result.receipt.themeStates.viewports.length, 6);
  assert.equal(result.receipt.captures.status, 'not-requested');
  assert.deepEqual(result.receipt.captures.screenshots, []);
  assert.equal(result.receipt.captures.contactSheet, null);
  assert.equal(browser.calls.length, VISUAL_CHECK_VIEWPORTS.length + 2);
  assert.equal(browser.calls.every(({ screenshotPath }) => screenshotPath === undefined), true);

  const outputs = browserCheckSidecarPaths(input);
  assert.equal(fs.existsSync(outputs.receipt), true);
  assert.equal(fs.existsSync(outputs.contactSheet), false);
  assert.equal(outputs.screenshots.every(({ path: screenshot }) => !fs.existsSync(screenshot)), true);
});

test('browser-check fails when an endpoint theme does not resolve without needing image inspection', async () => {
  const input = artifact('browser-check-theme-mismatch.html');
  const browser = fakeBrowser({
    resolvedThemeAt: ({ theme }) => theme === 'dark' ? 'light' : theme,
  });
  const result = await runBrowserCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: async () => browser,
  });

  assert.equal(result.exitCode, 1);
  assert.equal(result.receipt.status, 'fail');
  assert.equal(result.receipt.themeStates.status, 'fail');
  assert.equal(result.receipt.themeStates.viewports.filter(({ ok }) => !ok).length, 2);
  assert.equal(result.receipt.diagnostics.filter(({ code }) => code === 'viewer/theme-state').length, 2);
  assert.equal(result.receipt.captures.status, 'not-requested');
});

for (const [command, run] of [['browser-check', runBrowserCheck], ['visual-check', runVisualCheck]]) {
  for (const width of [1600, 1920]) {
    test(`${command} rejects a mismatched light theme at the ${width}px intermediate viewport`, async () => {
      const input = artifact(`${command}-intermediate-theme-${width}.html`);
      const browser = fakeBrowser({
        resolvedThemeAt: (entry) => entry.width === width ? 'dark' : entry.theme,
      });
      const result = await run({
        artifactPath: input,
        chromePath: '/fake/chrome',
        browserFactory: async () => browser,
      });

      assert.equal(result.exitCode, 1);
      assert.equal(result.receipt.ok, false);
      assert.equal(result.receipt.status, 'fail');
      assert.equal(result.receipt.themeStates.status, 'fail');
      assert.deepEqual(result.receipt.themeStates.viewports.filter(({ ok }) => !ok), [{
        width, height: width === 1600 ? 1000 : 1080,
        requestedTheme: 'light', resolvedTheme: 'dark', ok: false,
      }]);
      assert.equal(result.receipt.diagnostics.filter(({ code }) => code === 'viewer/theme-state').length, 1);
    });
  }
}


test('authored Architecture scroll requires readable unclipped document flow and preserves other modes', async () => {
  const input = artifact('authored-scroll.html');
  const target = ({ width, theme }) => width === 1440 && theme === 'light';
  for (const [name, options, accepted] of [
    ['readable document', {}, true],
    ['other diagram mode', { authoredDiagramType: 'workflow' }, false],
    ['missing mode', { authoredDiagramType: null }, false],
    ['clipped or internally scrolled SVG', { authoredUnclipped: false }, false],
    ['unreadable text', { unreadableAt: target }, false],
    ['horizontal overflow', { overflowAt: target }, false],
  ]) {
    const result = await runVisualCheck({
      artifactPath: input, outDir: path.join(tmp, `authored-${name.replace(/[^a-z]/g, '-')}`),
      chromePath: '/fake/chrome',
      browserFactory: async () => fakeBrowser({ authoredScrollAt: target, ...options }),
    });
    const viewport = result.receipt.containment.viewports.find(({ width }) => width === 1440);
    assert.equal(result.exitCode, accepted ? 0 : 1, name);
    assert.equal(viewport.verticalScrollAccepted, accepted, name);
    assert.equal(viewport.readerLayout, null, 'the fixed canvas does not acquire adaptive scaling');
  }
});


test('browser cleanup failure publishes a failed receipt instead of successful evidence', async () => {
  const input = artifact('chrome-cleanup-failure.html');
  const browser = fakeBrowser();
  browser.close = async () => {
    const error = new Error('Temporary directory cleanup failed: locked');
    error.code = 'ARCHIFY_TEMP_CLEANUP';
    error.directory = '/retained/profile';
    throw error;
  };
  const result = await runVisualCheck({
    artifactPath: input,
    chromePath: '/fake/chrome',
    browserFactory: () => browser,
  });
  assert.equal(result.exitCode, 1);
  assert.equal(result.receipt.ok, false);
  assert.equal(result.receipt.diagnostics[0].code, 'viewer/temp-cleanup-incomplete');
  assert.equal(result.receipt.diagnostics[0].evidence.retainedDirectory, '/retained/profile');
  const saved = JSON.parse(fs.readFileSync(sidecarPaths(input).receipt, 'utf8'));
  assert.equal(saved.ok, false);
  assert.deepEqual(saved.captures.screenshots, []);
});