@deeeed/metamask-harness 0.14.5 → 0.15.0

package/library/actions/extension/platform/cdp.mjs

@@ -120,18 +120,23 @@ async function captureHelperBrowserPid(context, port) {
   );
 }
 
-async function captureHelperSnapshot(page, context, relPath, metadata) {
-  if (process.platform !== 'darwin') {
-    throw new Error('Extension ui.screenshot uses capture-helper snapshot and is currently supported only on macOS.');
-  }
+async function captureCdpViewportSnapshot(page, context, relPath, metadata, captureHelperError = null) {
   const { relative, absolute } = resolveRelativeArtifactPath(context.artifactsDir, relPath);
   await mkdir(path.dirname(absolute), { recursive: true });
-
-  await page.session.call('Page.bringToFront');
-  const pid = await captureHelperBrowserPid(context, page.port);
-  const timeoutMs = Number(metadata?.timeoutMs ?? 30000);
-  const sessionSnapshot = await captureActiveRecipeRecordingSnapshot(pid, absolute, timeoutMs);
-  if (sessionSnapshot) {
+  try {
+    const timeoutMs = Number(metadata?.cdpTimeoutMs ?? 5000);
+    const result = await Promise.race([
+      page.session.call('Page.captureScreenshot', {
+        format: 'png',
+        fromSurface: true,
+        captureBeyondViewport: false,
+      }),
+      new Promise((_, reject) => setTimeout(() => reject(new Error(`Chrome Page.captureScreenshot timed out after ${timeoutMs}ms.`)), timeoutMs)),
+    ]);
+    if (typeof result?.data !== 'string' || result.data.length === 0) {
+      throw new Error('Chrome Page.captureScreenshot returned no image data.');
+    }
+    await writeFile(absolute, Buffer.from(result.data, 'base64'));
     return {
       path: relative,
       type: 'screenshot',
@@ -140,25 +145,62 @@ async function captureHelperSnapshot(page, context, relPath, metadata) {
       category: metadata?.category ?? 'evidence',
       mimeType: 'image/png',
       metadata: {
-        provider: 'capture-helper',
-        mode: 'record_session_snapshot',
-        pid,
-        captureHelper: sessionSnapshot,
+        provider: 'cdp',
+        mode: 'Page.captureScreenshot',
+        ...(captureHelperError ? { fallbackFrom: 'capture-helper', captureHelperError } : {}),
       },
     };
+  } catch (error) {
+    const cdpError = error instanceof Error ? error.message : String(error);
+    return captureDomRasterSnapshot(page, context, relPath, metadata, captureHelperError, cdpError);
   }
+}
 
-  const result = await runProcess(captureHelperPath(), ['snapshot', '--pid', String(pid), '--output', absolute], {
-    cwd: context.projectRoot,
-    env: process.env,
-    timeoutMs,
-  });
-  if (result.exitCode !== 0) {
-    throw new Error(
-      `capture-helper snapshot failed for Extension ui.screenshot (pid ${pid}): ${result.stderr || result.stdout}`,
-    );
+async function captureDomRasterSnapshot(page, context, relPath, metadata, captureHelperError, cdpError) {
+  const { relative, absolute } = resolveRelativeArtifactPath(context.artifactsDir, relPath);
+  const dataUrl = await page.evaluate(`(async () => {
+    const width = Math.max(1, window.innerWidth);
+    const height = Math.max(1, window.innerHeight);
+    const source = document.documentElement;
+    const clone = source.cloneNode(true);
+    const sourceNodes = [source, ...source.querySelectorAll('*')];
+    const cloneNodes = [clone, ...clone.querySelectorAll('*')];
+    for (let index = 0; index < sourceNodes.length; index += 1) {
+      const sourceNode = sourceNodes[index];
+      const cloneNode = cloneNodes[index];
+      if (!(sourceNode instanceof Element) || !(cloneNode instanceof Element)) continue;
+      const computed = getComputedStyle(sourceNode);
+      cloneNode.setAttribute('style', Array.from(computed).map((name) => name + ':' + computed.getPropertyValue(name) + ';').join(''));
+      if ('value' in sourceNode && typeof sourceNode.value === 'string') cloneNode.setAttribute('value', sourceNode.value);
+      if (sourceNode instanceof HTMLCanvasElement) {
+        const image = document.createElement('img');
+        try { image.src = sourceNode.toDataURL('image/png'); } catch { image.alt = 'canvas'; }
+        image.setAttribute('style', cloneNode.getAttribute('style') || '');
+        cloneNode.replaceWith(image);
+      }
+    }
+    clone.querySelectorAll('script').forEach((node) => node.remove());
+    clone.setAttribute('xmlns', 'http://www.w3.org/1999/xhtml');
+    clone.style.width = width + 'px';
+    clone.style.height = height + 'px';
+    clone.style.overflow = 'hidden';
+    const serialized = new XMLSerializer().serializeToString(clone);
+    const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="' + width + '" height="' + height + '"><foreignObject width="100%" height="100%">' + serialized + '</foreignObject></svg>';
+    const image = new Image();
+    const loaded = new Promise((resolve, reject) => { image.onload = resolve; image.onerror = () => reject(new Error('DOM raster image load failed.')); });
+    image.src = 'data:image/svg+xml;base64,' + btoa(unescape(encodeURIComponent(svg)));
+    await loaded;
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const context = canvas.getContext('2d');
+    context.drawImage(image, 0, 0, width, height);
+    return canvas.toDataURL('image/png');
+  })()`);
+  if (typeof dataUrl !== 'string' || !dataUrl.startsWith('data:image/png;base64,')) {
+    throw new Error(`Extension screenshot fallbacks failed: capture-helper=${captureHelperError ?? 'not attempted'}; cdp=${cdpError}; DOM raster returned no PNG.`);
   }
-  const details = parseJsonObject(result.stdout);
+  await writeFile(absolute, Buffer.from(dataUrl.slice('data:image/png;base64,'.length), 'base64'));
   return {
     path: relative,
     type: 'screenshot',
@@ -167,14 +209,72 @@ async function captureHelperSnapshot(page, context, relPath, metadata) {
     category: metadata?.category ?? 'evidence',
     mimeType: 'image/png',
     metadata: {
-      provider: 'capture-helper',
-      mode: 'snapshot',
-      pid,
-      ...(details ? { captureHelper: details } : {}),
+      provider: 'dom-raster',
+      mode: 'computed-style-viewport',
+      fallbackFrom: captureHelperError ? 'capture-helper+cdp' : 'cdp',
+      ...(captureHelperError ? { captureHelperError } : {}),
+      cdpError,
     },
   };
 }
 
+export async function captureHelperSnapshot(page, context, relPath, metadata) {
+  if (process.platform !== 'darwin') {
+    return captureCdpViewportSnapshot(page, context, relPath, metadata);
+  }
+  const { relative, absolute } = resolveRelativeArtifactPath(context.artifactsDir, relPath);
+  await mkdir(path.dirname(absolute), { recursive: true });
+
+  try {
+    const pid = await captureHelperBrowserPid(context, page.port);
+    const timeoutMs = Number(metadata?.timeoutMs ?? 30000);
+    const sessionSnapshot = await captureActiveRecipeRecordingSnapshot(pid, absolute, timeoutMs);
+    if (sessionSnapshot) {
+      return {
+        path: relative,
+        type: 'screenshot',
+        nodeId: context.nodeId,
+        label: metadata?.label ?? `${context.nodeId} screenshot`,
+        category: metadata?.category ?? 'evidence',
+        mimeType: 'image/png',
+        metadata: {
+          provider: 'capture-helper',
+          mode: 'record_session_snapshot',
+          pid,
+          captureHelper: sessionSnapshot,
+        },
+      };
+    }
+
+    const result = await runProcess(captureHelperPath(), ['snapshot', '--pid', String(pid), '--output', absolute], {
+      cwd: context.projectRoot,
+      env: process.env,
+      timeoutMs,
+    });
+    if (result.exitCode !== 0) {
+      throw new Error(`capture-helper snapshot failed for pid ${pid}: ${result.stderr || result.stdout}`);
+    }
+    const details = parseJsonObject(result.stdout);
+    return {
+      path: relative,
+      type: 'screenshot',
+      nodeId: context.nodeId,
+      label: metadata?.label ?? `${context.nodeId} screenshot`,
+      category: metadata?.category ?? 'evidence',
+      mimeType: 'image/png',
+      metadata: {
+        provider: 'capture-helper',
+        mode: 'snapshot',
+        pid,
+        ...(details ? { captureHelper: details } : {}),
+      },
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return captureCdpViewportSnapshot(page, context, relPath, metadata, message);
+  }
+}
+
 function autolaunchEnabled(input) {
   return input.node?.launch_existing_dist === true ||
     input.node?.autolaunch === true ||

package/library/actions/extension/ui/navigate.mjs

@@ -2,7 +2,7 @@ import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
 
 const PAGE_HASHES = {
   home: '#/',
-  perps: '#/?tab=perps',
+  perps: '#/perps-home',
 };
 
 function text(value) {

package/library/actions/mobile/perps/perps.mjs

@@ -1,5 +1,6 @@
 import { pathToFileURL } from 'node:url';
 import { evalAsync, navigate, runAdapter } from '../platform/bridge.mjs';
+import { ensureUnlocked } from '../wallet/ensure_unlocked.mjs';
 
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -637,6 +638,17 @@ async function applyTutorialState(input, config) {
 export async function startState(input) {
   const params = paramsForState(input);
   const config = mergeStateConfig(profileDefaults(params.profile), params);
+  // Product edits require an app restart before proof. Mobile relocks on restart,
+  // so a deterministic Perps start state must restore the fixture-backed wallet
+  // prerequisite before it navigates or converges controller state.
+  const wallet = await ensureUnlocked({
+    ...input,
+    action: 'metamask.wallet.ensure_unlocked',
+    node: { ...input.node, action: 'metamask.wallet.ensure_unlocked' },
+  });
+  // Entering Perps initializes the provider client on a freshly launched app.
+  // State reads before this navigation fail with CLIENT_NOT_INITIALIZED.
+  const navigation = await applyStateNavigation(input, config);
   const provider = await ensureProvider(input, config);
   const network = await ensureNetwork(input, config);
   const tutorial = await applyTutorialState(input, config);
@@ -644,11 +656,11 @@ export async function startState(input) {
   const balance = await assertBalance(input, config);
   const orders = await applyOrdersState(input, config.orders);
   const positions = await applyPositionsState(input, config.positions);
-  const navigation = await applyStateNavigation(input, config);
   return {
     action: input.action,
     profile: config.profile ?? params.profile ?? 'clean_market_testnet',
     phase: 'start_state',
+    wallet,
     provider,
     network,
     tutorial,

package/library/actions/mobile/platform/bridge.mjs

@@ -1,4 +1,6 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import { mkdir, open, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { execFile, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
 import path from 'node:path';
@@ -405,25 +407,54 @@ export async function simulatorScreenshot(input, relPath) {
   const adbSerial = targetInfo.adbSerial;
   const platform = String(input.node?.platform ?? process.env.PLATFORM ?? '').toLowerCase();
   if (androidTarget || adbSerial || platform === 'android') {
-    return androidScreenshot(input, relPath, adbSerial);
+    return androidScreenshot(input, relPath);
   }
   const target = targetInfo.iosSimulator;
   if (!target) {
+    const { absolute } = resolveArtifactPath(input.context.artifactsDir, relPath || `screenshots/${input.context.nodeId}.png`);
+    await rm(absolute, { force: true });
     throw new Error('iOS screenshot requires node.simulator, node.ios_simulator, or IOS_SIMULATOR so the proof is tied to the same device as the bridge commands.');
   }
   const { relative, absolute } = resolveArtifactPath(input.context.artifactsDir, relPath || `screenshots/${input.context.nodeId}.png`);
   await mkdir(path.dirname(absolute), { recursive: true });
-  const result = await new Promise((resolve, reject) => {
-    const child = spawn('xcrun', ['simctl', 'io', String(target), 'screenshot', absolute], { stdio: ['ignore', 'pipe', 'pipe'] });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.on('error', reject);
-    child.on('close', (exitCode) => resolve({ exitCode, stdout, stderr }));
-  });
-  if (result.exitCode !== 0) {
-    throw new Error(`simctl screenshot failed for ${target}: ${result.stderr || result.stdout}`);
+  await rm(absolute, { force: true });
+  let temporaryDirectory;
+  try {
+    temporaryDirectory = await createScreenshotTemporaryDirectory(absolute);
+    const captured = path.join(temporaryDirectory, 'captured.png');
+    await createPrivateScreenshotFile(captured);
+    let result;
+    try {
+      result = await runScreenshotProcess('xcrun', ['simctl', 'io', String(target), 'screenshot', captured], false);
+    } catch (error) {
+      throw new Error(
+        `simctl screenshot could not start for ${target}: ${error instanceof Error ? error.message : String(error)}\n` +
+        '  Next: install Xcode Command Line Tools (`xcode-select --install`), then rerun the same mm-harness command.',
+      );
+    }
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `simctl screenshot failed for ${target}: ${result.stderr || result.stdout}\n` +
+        `  Next: mm-harness doctor --adapter mobile --device ${target} --json`,
+      );
+    }
+    const png = await readPrivateScreenshotFile(captured);
+    const invalid = pngStructureError(png);
+    if (invalid) {
+      throw new Error(
+        `simctl screenshot produced invalid PNG bytes for ${target}: ${invalid}\n` +
+        `  Next: mm-harness doctor --adapter mobile --device ${target} --json`,
+      );
+    }
+    await publishPrivateScreenshot(png, temporaryDirectory, absolute);
+    await rm(temporaryDirectory, { recursive: true, force: true });
+  } catch (error) {
+    await removeScreenshotResidue(temporaryDirectory, absolute);
+    if (String(error?.message ?? error).includes('\n  Next:')) throw error;
+    throw new Error(
+      `simctl screenshot could not publish for ${target}: ${error instanceof Error ? error.message : String(error)}\n` +
+      `  Next: mm-harness doctor --adapter mobile --device ${target} --json`,
+    );
   }
   return {
     path: relative,
@@ -431,35 +462,277 @@ export async function simulatorScreenshot(input, relPath) {
     nodeId: input.context.nodeId,
     label: input.node?.description || `${input.action} screenshot`,
     category: 'evidence',
+    mimeType: 'image/png',
+    metadata: {
+      provider: 'simctl',
+      mode: 'xcrun simctl io screenshot',
+      selectedDevice: String(target),
+    },
   };
 }
 
-async function androidScreenshot(input, relPath, androidDevice) {
+async function androidScreenshot(input, relPath) {
   const { relative, absolute } = resolveArtifactPath(input.context.artifactsDir, relPath || `screenshots/${input.context.nodeId}.png`);
   await mkdir(path.dirname(absolute), { recursive: true });
-  const args = [];
-  if (androidDevice) args.push('-s', String(androidDevice));
-  args.push('exec-out', 'screencap', '-p');
-  const result = await new Promise((resolve, reject) => {
-    const child = spawn('adb', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+  await rm(absolute, { force: true });
+  let temporaryDirectory;
+  try {
+    temporaryDirectory = await createScreenshotTemporaryDirectory(absolute);
+    const adbSerial = await resolveAndroidScreenshotSerial(input);
+    let result;
+    try {
+      result = await runScreenshotProcess('adb', ['-s', adbSerial, 'exec-out', 'screencap', '-p'], true);
+    } catch (error) {
+      throw new Error(
+        `adb screenshot could not start for ${adbSerial}: ${error instanceof Error ? error.message : String(error)}\n` +
+        '  Next: install Android SDK Platform-Tools, ensure adb is on PATH, then rerun the same mm-harness command.',
+      );
+    }
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `adb screenshot failed for ${adbSerial}: ${result.stderr}\n` +
+        `  Next: mm-harness doctor --adapter mobile --device ${adbSerial} --json`,
+      );
+    }
+    const invalid = pngStructureError(result.stdout);
+    if (invalid) {
+      throw new Error(
+        `adb screenshot produced invalid PNG bytes for ${adbSerial}: ${invalid}\n` +
+        `  Next: mm-harness doctor --adapter mobile --device ${adbSerial} --json`,
+      );
+    }
+    await publishPrivateScreenshot(result.stdout, temporaryDirectory, absolute);
+    await rm(temporaryDirectory, { recursive: true, force: true });
+    return {
+      path: relative,
+      type: 'screenshot',
+      nodeId: input.context.nodeId,
+      label: input.node?.description || `${input.action} screenshot`,
+      category: 'evidence',
+      mimeType: 'image/png',
+      metadata: {
+        provider: 'adb',
+        mode: 'adb exec-out screencap -p',
+        selectedDevice: adbSerial,
+      },
+    };
+  } catch (error) {
+    await removeScreenshotResidue(temporaryDirectory, absolute);
+    if (String(error?.message ?? error).includes('\n  Next:')) throw error;
+    throw new Error(
+      `adb screenshot could not publish: ${error instanceof Error ? error.message : String(error)}\n` +
+      '  Next: mm-harness doctor --adapter mobile --json',
+    );
+  }
+}
+
+async function resolveAndroidScreenshotSerial(input) {
+  const contextEnv = input.context?.env || {};
+  const explicit = input.node?.adb_serial ??
+    input.node?.android_device ??
+    input.node?.device ??
+    contextEnv.ADB_SERIAL ??
+    contextEnv.ANDROID_SERIAL ??
+    contextEnv.ANDROID_DEVICE ??
+    process.env.ADB_SERIAL ??
+    process.env.ANDROID_SERIAL ??
+    process.env.ANDROID_DEVICE;
+  if (explicit !== undefined && explicit !== null && String(explicit).trim()) return String(explicit).trim();
+
+  let result;
+  try {
+    result = await runScreenshotProcess('adb', ['devices'], false);
+  } catch (error) {
+    throw new Error(
+      `Android screenshot could not resolve an adb serial: ${error instanceof Error ? error.message : String(error)}\n` +
+      '  Next: install Android SDK Platform-Tools, ensure adb is on PATH, then rerun with --device <adb-serial>.',
+    );
+  }
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `Android screenshot could not resolve an adb serial: ${result.stderr || result.stdout}\n` +
+      '  Next: mm-harness doctor --adapter mobile --json',
+    );
+  }
+  const serials = result.stdout
+    .split(/\r?\n/u)
+    .map((line) => line.trim().split(/\s+/u))
+    .filter((fields) => fields.length >= 2 && fields[1] === 'device')
+    .map(([serial]) => serial);
+  if (serials.length === 1) return serials[0];
+  throw new Error(
+    `Android screenshot requires one exact adb serial, but ${serials.length} ready devices were discovered.\n` +
+    '  Next: mm-harness doctor --adapter mobile --json   # choose devices[].id and rerun with --device <id>',
+  );
+}
+
+function runScreenshotProcess(command, args, binaryOutput) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
     const stdout = [];
     let stderr = '';
     child.stdout.on('data', (chunk) => { stdout.push(Buffer.from(chunk)); });
     child.stderr.on('data', (chunk) => { stderr += chunk; });
     child.on('error', reject);
-    child.on('close', (exitCode) => resolve({ exitCode, stdout: Buffer.concat(stdout), stderr }));
+    child.on('close', (exitCode) => resolve({
+      exitCode,
+      stdout: binaryOutput ? Buffer.concat(stdout) : Buffer.concat(stdout).toString('utf8'),
+      stderr,
+    }));
   });
-  if (result.exitCode !== 0) {
-    throw new Error(`adb screenshot failed${androidDevice ? ` for ${androidDevice}` : ''}: ${result.stderr}`);
+}
+
+function pngStructureError(bytes) {
+  const signature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+  if (!Buffer.isBuffer(bytes) || bytes.length < signature.length || !bytes.subarray(0, signature.length).equals(signature)) {
+    return `bad signature (${Buffer.isBuffer(bytes) ? bytes.length : 0} bytes)`;
   }
-  await writeFile(absolute, result.stdout);
-  return {
-    path: relative,
-    type: 'screenshot',
-    nodeId: input.context.nodeId,
-    label: input.node?.description || `${input.action} screenshot`,
-    category: 'evidence',
+  let offset = signature.length;
+  let sawHeader = false;
+  let sawPalette = false;
+  let sawImageData = false;
+  let imageDataClosed = false;
+  let colorType;
+  let bitDepth;
+  while (offset < bytes.length) {
+    if (bytes.length - offset < 12) return `truncated chunk at byte ${offset}`;
+    const length = bytes.readUInt32BE(offset);
+    const typeBytes = bytes.subarray(offset + 4, offset + 8);
+    const type = typeBytes.toString('ascii');
+    const end = offset + 12 + length;
+    if (end > bytes.length) return `truncated ${type || 'unknown'} chunk at byte ${offset}`;
+    if (![...typeBytes].every((byte) => (byte >= 65 && byte <= 90) || (byte >= 97 && byte <= 122))) {
+      return `invalid chunk type at byte ${offset}`;
+    }
+    const expectedCrc = bytes.readUInt32BE(offset + 8 + length);
+    const actualCrc = pngCrc32(bytes, offset + 4, offset + 8 + length);
+    if (actualCrc !== expectedCrc) return `CRC mismatch for ${type} chunk at byte ${offset}`;
+    if (!sawHeader && (type !== 'IHDR' || length !== 13)) return `first chunk must be IHDR length 13 (got ${type} length ${length})`;
+    if (type === 'IHDR') {
+      if (sawHeader) return 'duplicate IHDR chunk';
+      const invalidHeader = pngHeaderError(bytes.subarray(offset + 8, offset + 8 + length));
+      if (invalidHeader) return invalidHeader;
+      sawHeader = true;
+      bitDepth = bytes[offset + 16];
+      colorType = bytes[offset + 17];
+    } else if (type === 'PLTE') {
+      if (sawPalette) return 'duplicate PLTE chunk';
+      if (sawImageData) return 'PLTE chunk must precede IDAT';
+      if (colorType === 0 || colorType === 4) return `PLTE chunk is forbidden for color type ${colorType}`;
+      if (length === 0 || length % 3 !== 0 || length > 768) return `invalid PLTE length ${length}`;
+      if (colorType === 3 && length / 3 > 2 ** bitDepth) return `PLTE has too many entries for bit depth ${bitDepth}`;
+      sawPalette = true;
+    } else if (type === 'IDAT') {
+      if (imageDataClosed) return 'IDAT chunks must be consecutive';
+      if (colorType === 3 && !sawPalette) return 'indexed-color PNG requires PLTE before IDAT';
+      sawImageData = true;
+    } else {
+      if (sawImageData) imageDataClosed = true;
+      if (type[0] === type[0].toUpperCase() && type !== 'IEND') return `unknown critical chunk ${type}`;
+    }
+    if (type === 'IEND') {
+      if (length !== 0) return `IEND length must be 0 (got ${length})`;
+      if (!sawImageData) return 'missing IDAT chunk';
+      if (end !== bytes.length) return `trailing bytes after IEND (${bytes.length - end})`;
+      return null;
+    }
+    offset = end;
+  }
+  return sawHeader ? 'missing IEND chunk' : 'missing IHDR chunk';
+}
+
+function pngHeaderError(header) {
+  const width = header.readUInt32BE(0);
+  const height = header.readUInt32BE(4);
+  const bitDepth = header[8];
+  const colorType = header[9];
+  const allowedDepths = {
+    0: [1, 2, 4, 8, 16],
+    2: [8, 16],
+    3: [1, 2, 4, 8],
+    4: [8, 16],
+    6: [8, 16],
   };
+  if (width === 0 || width > 0x7fffffff || height === 0 || height > 0x7fffffff) {
+    return `invalid IHDR dimensions ${width}x${height}`;
+  }
+  if (!allowedDepths[colorType]) return `invalid IHDR color type ${colorType}`;
+  if (!allowedDepths[colorType].includes(bitDepth)) return `invalid IHDR bit depth ${bitDepth} for color type ${colorType}`;
+  if (header[10] !== 0) return `invalid IHDR compression method ${header[10]}`;
+  if (header[11] !== 0) return `invalid IHDR filter method ${header[11]}`;
+  if (header[12] !== 0 && header[12] !== 1) return `invalid IHDR interlace method ${header[12]}`;
+  return null;
+}
+
+const PNG_CRC_TABLE = Uint32Array.from({ length: 256 }, (_, value) => {
+  let crc = value;
+  for (let bit = 0; bit < 8; bit += 1) crc = (crc & 1) === 1 ? 0xedb88320 ^ (crc >>> 1) : crc >>> 1;
+  return crc >>> 0;
+});
+
+function pngCrc32(bytes, start, end) {
+  let crc = 0xffffffff;
+  for (let index = start; index < end; index += 1) crc = PNG_CRC_TABLE[(crc ^ bytes[index]) & 0xff] ^ (crc >>> 8);
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+async function createScreenshotTemporaryDirectory(absolute) {
+  const temporary = path.join(path.dirname(absolute), `.${path.basename(absolute)}.${process.pid}.${randomUUID()}.tmp`);
+  await mkdir(temporary, { mode: 0o700 });
+  return temporary;
+}
+
+async function createPrivateScreenshotFile(file) {
+  const handle = await open(
+    file,
+    fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW,
+    0o600,
+  );
+  try {
+    const stats = await handle.stat();
+    if (!stats.isFile() || stats.nlink !== 1) throw new Error('temporary screenshot is not a private regular file');
+  } finally {
+    await handle.close();
+  }
+}
+
+async function readPrivateScreenshotFile(file) {
+  let handle;
+  try {
+    handle = await open(file, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK);
+    const stats = await handle.stat();
+    if (!stats.isFile() || stats.nlink !== 1) throw new Error('captured screenshot is not a private regular file');
+    return await handle.readFile();
+  } catch (error) {
+    throw new Error(`captured screenshot is not a safe regular file: ${error instanceof Error ? error.message : String(error)}`);
+  } finally {
+    await handle?.close();
+  }
+}
+
+async function publishPrivateScreenshot(png, temporaryDirectory, absolute) {
+  const publication = path.join(temporaryDirectory, 'validated.png');
+  const handle = await open(
+    publication,
+    fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW,
+    0o600,
+  );
+  try {
+    const stats = await handle.stat();
+    if (!stats.isFile() || stats.nlink !== 1) throw new Error('validated screenshot is not a private regular file');
+    await handle.writeFile(png);
+    await handle.sync();
+    await rename(publication, absolute);
+  } finally {
+    await handle.close();
+  }
+}
+
+async function removeScreenshotResidue(temporaryDirectory, absolute) {
+  await Promise.all([
+    temporaryDirectory ? rm(temporaryDirectory, { recursive: true, force: true }) : Promise.resolve(),
+    rm(absolute, { force: true }),
+  ]);
 }
 
 function resolveArtifactPath(artifactsDir, relativePath) {

package/library/actions/mobile/wallet/ensure_unlocked.mjs

@@ -1,4 +1,5 @@
 import { readFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
 import { bridgeCommand, runAdapter, selectBridgeStatusEntry } from '../platform/bridge.mjs';
 import { walletFixturePath } from '../../harness-exports.mjs';
 
@@ -108,7 +109,7 @@ async function waitForStableUnlocked(input, initialStatus, stableMs = 750) {
   return last;
 }
 
-runAdapter(async (input) => {
+export async function ensureUnlocked(input) {
   const before = await waitForTargetStatus(input, Number(input.node?.target_timeout_ms ?? 20000));
   if (!selectedAccount(before, input) && routeName(before, input) !== 'Login') {
     throw new Error(
@@ -153,4 +154,8 @@ runAdapter(async (input) => {
       proofPath: 'agentic-wallet-status-after-missing-login-input',
     };
   }
-});
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runAdapter(ensureUnlocked);
+}