vigthoria-cli 1.13.34 → 1.13.42

package/dist/utils/preview-screenshot-adapter.js

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
 import * as fs from 'node:fs';
+import { createServer } from 'node:http';
 import * as path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import WebSocket from 'ws';
@@ -12,7 +13,35 @@ const BROWSER_TIMEOUT_MS = 30_000;
 // Chromium creates short-lived files below TMPDIR while starting. Keep enough
 // room below the 108-byte POSIX sockaddr_un ceiling without rejecting normal
 // per-user Vigthoria roots (for example ~/.vigthoria/tmp/browser-*/scratch).
-const POSIX_BROWSER_SCRATCH_MAX_BYTES = 76;
+// Microsoft Edge adds a longer internal singleton suffix than Chromium; on
+// the production Linux host a 61-byte scratch path starts reliably while a
+// 66-byte path aborts before exposing DevTools. Fail closed before that abort.
+const POSIX_BROWSER_SCRATCH_MAX_BYTES = 61;
+function createIsolatedBrowserEnvironment(environment, platform, browserProfile, browserScratch) {
+    const additions = {
+        TMPDIR: browserScratch,
+        TMP: browserScratch,
+        TEMP: browserScratch,
+    };
+    if (platform !== 'win32') {
+        const xdgDirectories = {
+            XDG_CONFIG_HOME: path.join(browserProfile, 'xdg-config'),
+            XDG_CACHE_HOME: path.join(browserProfile, 'xdg-cache'),
+            XDG_DATA_HOME: path.join(browserProfile, 'xdg-data'),
+            XDG_RUNTIME_DIR: path.join(browserProfile, 'xdg-runtime'),
+        };
+        for (const directory of Object.values(xdgDirectories)) {
+            fs.mkdirSync(directory, { recursive: false, mode: 0o700 });
+        }
+        Object.assign(additions, xdgDirectories);
+    }
+    return safeChildProcessEnv(environment, additions);
+}
+export function assertPreviewBrowserSandboxUser(platform = process.platform, effectiveUserId = typeof process.getuid === 'function' ? process.getuid() : undefined) {
+    if (platform !== 'win32' && effectiveUserId === 0) {
+        throw new Error('browser proof requires an unprivileged OS account so the Chromium sandbox remains enabled; do not run the Vigthoria CLI as root');
+    }
+}
 export function resolvePreviewBrowserExecutable(environment = process.env, platform = process.platform, exists = fs.existsSync) {
     const candidates = platform === 'win32'
         ? [
@@ -90,6 +119,13 @@ async function terminateBrowserProcess(child, platform) {
     catch { /* group exited */ }
 }
 export const runPreviewBrowser = (executablePath, args, platform, environment = process.env) => new Promise((resolve, reject) => {
+    try {
+        assertPreviewBrowserSandboxUser(platform);
+    }
+    catch (error) {
+        reject(error);
+        return;
+    }
     const child = spawn(executablePath, [...args], {
         stdio: 'ignore',
         windowsHide: true,
@@ -240,6 +276,7 @@ function runtimeKeyDefinition(rawKey = '') {
         space: { key: ' ', code: 'Space', virtualKeyCode: 32, text: ' ' },
         spacebar: { key: ' ', code: 'Space', virtualKeyCode: 32, text: ' ' },
         enter: { key: 'Enter', code: 'Enter', virtualKeyCode: 13, text: '\r' },
+        tab: { key: 'Tab', code: 'Tab', virtualKeyCode: 9 },
         escape: { key: 'Escape', code: 'Escape', virtualKeyCode: 27 },
         esc: { key: 'Escape', code: 'Escape', virtualKeyCode: 27 },
         arrowup: { key: 'ArrowUp', code: 'ArrowUp', virtualKeyCode: 38 },
@@ -255,19 +292,53 @@ function runtimeKeyDefinition(rawKey = '') {
     }
     return null;
 }
-async function waitForRuntimeReady(client, sessionId) {
+export function runtimeKeyChordDefinition(rawKey = '') {
+    const parts = rawKey.trim().toLowerCase().replace(/\s+/g, '').split('+').filter(Boolean);
+    if (!parts.length)
+        return null;
+    const base = parts.at(-1) || '';
+    const aliases = {
+        shift: { key: 'Shift', code: 'ShiftLeft', virtualKeyCode: 16, bit: 8 },
+        control: { key: 'Control', code: 'ControlLeft', virtualKeyCode: 17, bit: 2 },
+        ctrl: { key: 'Control', code: 'ControlLeft', virtualKeyCode: 17, bit: 2 },
+        alt: { key: 'Alt', code: 'AltLeft', virtualKeyCode: 18, bit: 1 },
+        meta: { key: 'Meta', code: 'MetaLeft', virtualKeyCode: 91, bit: 4 },
+        cmd: { key: 'Meta', code: 'MetaLeft', virtualKeyCode: 91, bit: 4 },
+        command: { key: 'Meta', code: 'MetaLeft', virtualKeyCode: 91, bit: 4 },
+    };
+    const modifiers = [];
+    const seen = new Set();
+    for (const part of parts.slice(0, -1)) {
+        const modifier = aliases[part];
+        if (!modifier || seen.has(modifier.bit))
+            return null;
+        seen.add(modifier.bit);
+        modifiers.push(modifier);
+    }
+    const key = runtimeKeyDefinition(base);
+    if (!key || aliases[base])
+        return null;
+    return {
+        key,
+        modifiers,
+        modifierMask: modifiers.reduce((mask, modifier) => mask | modifier.bit, 0),
+    };
+}
+async function waitForRuntimeReady(client, sessionId, expectedUrl) {
     const deadline = Date.now() + 8_000;
     while (Date.now() < deadline) {
         const evaluated = await client.send('Runtime.evaluate', {
-            expression: 'document.readyState',
+            expression: '({ readyState: document.readyState, href: location.href })',
             returnByValue: true,
         }, sessionId);
-        const readyState = String(evaluated.result?.value || '');
-        if (readyState === 'interactive' || readyState === 'complete')
+        const observation = evaluated.result?.value || {};
+        const readyState = String(observation.readyState || '');
+        const currentUrl = String(observation.href || '');
+        if (currentUrl === expectedUrl && (readyState === 'interactive' || readyState === 'complete'))
             return;
         await new Promise((resolve) => setTimeout(resolve, 100));
     }
-    throw new Error('browser document did not become ready');
+    throw new Error('browser document did not become ready at the requested loopback URL');
 }
 async function readRuntimeBody(client, sessionId) {
     const evaluated = await client.send('Runtime.evaluate', {
@@ -276,6 +347,343 @@ async function readRuntimeBody(client, sessionId) {
     }, sessionId);
     return normalizeRuntimeBody(evaluated.result?.value);
 }
+async function evaluateRuntimeValue(client, sessionId, expression) {
+    const evaluated = await client.send('Runtime.evaluate', {
+        expression,
+        awaitPromise: true,
+        returnByValue: true,
+    }, sessionId);
+    if (evaluated.exceptionDetails) {
+        const description = evaluated.exceptionDetails.exception?.description
+            || evaluated.exceptionDetails.text
+            || 'browser scenario evaluation failed';
+        throw new Error(normalizeRuntimeBody(description));
+    }
+    return evaluated.result?.value;
+}
+async function focusRuntimeSelector(client, sessionId, selector) {
+    await evaluateRuntimeValue(client, sessionId, `(() => {
+    const selector = ${JSON.stringify(selector)};
+    const element = document.querySelector(selector);
+    if (!element) throw new Error('selector not found: ' + selector);
+    if (typeof element.focus !== 'function') throw new Error('element is not focusable: ' + selector);
+    element.focus();
+    return true;
+  })()`);
+}
+async function dispatchRuntimeKey(client, sessionId, rawKey) {
+    const chord = runtimeKeyChordDefinition(rawKey);
+    if (!chord)
+        throw new Error(`unsupported browser interaction key: ${rawKey}`);
+    let activeModifiers = 0;
+    for (const modifier of chord.modifiers) {
+        activeModifiers |= modifier.bit;
+        await client.send('Input.dispatchKeyEvent', {
+            type: 'keyDown', key: modifier.key, code: modifier.code,
+            windowsVirtualKeyCode: modifier.virtualKeyCode,
+            nativeVirtualKeyCode: modifier.virtualKeyCode,
+            modifiers: activeModifiers,
+        }, sessionId);
+    }
+    await client.send('Input.dispatchKeyEvent', {
+        type: 'keyDown', key: chord.key.key, code: chord.key.code,
+        windowsVirtualKeyCode: chord.key.virtualKeyCode,
+        nativeVirtualKeyCode: chord.key.virtualKeyCode,
+        modifiers: chord.modifierMask,
+        ...(chord.key.text && chord.modifierMask === 0
+            ? { text: chord.key.text, unmodifiedText: chord.key.text }
+            : {}),
+    }, sessionId);
+    await client.send('Input.dispatchKeyEvent', {
+        type: 'keyUp', key: chord.key.key, code: chord.key.code,
+        windowsVirtualKeyCode: chord.key.virtualKeyCode,
+        nativeVirtualKeyCode: chord.key.virtualKeyCode,
+        modifiers: chord.modifierMask,
+    }, sessionId);
+    for (const modifier of [...chord.modifiers].reverse()) {
+        activeModifiers &= ~modifier.bit;
+        await client.send('Input.dispatchKeyEvent', {
+            type: 'keyUp', key: modifier.key, code: modifier.code,
+            windowsVirtualKeyCode: modifier.virtualKeyCode,
+            nativeVirtualKeyCode: modifier.virtualKeyCode,
+            modifiers: activeModifiers,
+        }, sessionId);
+    }
+}
+export async function applyRuntimeStepAction(client, sessionId, step) {
+    const selector = String(step.selector || '').trim();
+    const value = String(step.value || '');
+    if (step.action === 'wait') {
+        const milliseconds = Math.max(0, Math.min(Number(value || step.wait_ms) || 0, 2_000));
+        if (milliseconds)
+            await new Promise((resolve) => setTimeout(resolve, milliseconds));
+        return;
+    }
+    if (step.action === 'reload') {
+        const currentUrl = String(await evaluateRuntimeValue(client, sessionId, 'location.href'));
+        await client.send('Page.reload', { ignoreCache: false }, sessionId);
+        await waitForRuntimeReady(client, sessionId, currentUrl);
+        return;
+    }
+    if (step.action === 'press') {
+        if (selector)
+            await focusRuntimeSelector(client, sessionId, selector);
+        await dispatchRuntimeKey(client, sessionId, value);
+        return;
+    }
+    if (step.action === 'assert')
+        return;
+    if (step.action === 'click'
+        && (step.offset_x_ratio !== undefined || step.offset_y_ratio !== undefined)) {
+        const point = await evaluateRuntimeValue(client, sessionId, `(() => {
+      const element = document.querySelector(${JSON.stringify(selector)});
+      if (!element) throw new Error('selector not found: ' + ${JSON.stringify(selector)});
+      const rect = element.getBoundingClientRect();
+      if (!(rect.width > 0 && rect.height > 0)) throw new Error('click target has no layout box: ' + ${JSON.stringify(selector)});
+      const clamp = (value) => Math.max(0.01, Math.min(Number(value), 0.99));
+      return {
+        x: rect.left + rect.width * clamp(${JSON.stringify(step.offset_x_ratio ?? 0.5)}),
+        y: rect.top + rect.height * clamp(${JSON.stringify(step.offset_y_ratio ?? 0.5)}),
+      };
+    })()`);
+        await client.send('Input.dispatchMouseEvent', {
+            type: 'mouseMoved', x: Number(point.x), y: Number(point.y), button: 'none', buttons: 0,
+        }, sessionId);
+        await client.send('Input.dispatchMouseEvent', {
+            type: 'mousePressed', x: Number(point.x), y: Number(point.y),
+            button: 'left', buttons: 1, clickCount: 1,
+        }, sessionId);
+        await client.send('Input.dispatchMouseEvent', {
+            type: 'mouseReleased', x: Number(point.x), y: Number(point.y),
+            button: 'left', buttons: 0, clickCount: 1,
+        }, sessionId);
+        return;
+    }
+    await evaluateRuntimeValue(client, sessionId, `(() => {
+    const step = ${JSON.stringify(step)};
+    const selector = String(step.selector || '');
+    const element = document.querySelector(selector);
+    if (!element) throw new Error('selector not found: ' + selector);
+    if (step.action === 'click') {
+      if (typeof element.click !== 'function') throw new Error('element is not clickable: ' + selector);
+      // HTMLElement.click() dispatches click handlers but does not reproduce
+      // the focus transfer of a real pointer click.  That left the previously
+      // filled search input active when a scenario clicked a native select or
+      // button, producing a false keyboard/focus failure.  Move focus first,
+      // as a trusted user click does, then dispatch the activation.
+      if (typeof element.focus === 'function') element.focus();
+      element.click();
+    } else if (step.action === 'fill') {
+      if (!('value' in element)) throw new Error('element cannot be filled: ' + selector);
+      element.focus();
+      element.value = String(step.value ?? '');
+      element.dispatchEvent(new InputEvent('input', { bubbles: true, inputType: 'insertText', data: String(step.value ?? '') }));
+      element.dispatchEvent(new Event('change', { bubbles: true }));
+    } else if (step.action === 'select') {
+      if (!(element instanceof HTMLSelectElement)) throw new Error('element is not a select: ' + selector);
+      element.value = String(step.value ?? '');
+      element.dispatchEvent(new Event('input', { bubbles: true }));
+      element.dispatchEvent(new Event('change', { bubbles: true }));
+    } else if (step.action === 'focus') {
+      if (typeof element.focus !== 'function') throw new Error('element is not focusable: ' + selector);
+      element.focus();
+    }
+    return true;
+  })()`);
+}
+export async function waitForRuntimeActionTarget(client, sessionId, selector, scenarioDeadline) {
+    const targetDeadline = Math.min(scenarioDeadline, Date.now() + 3_000);
+    while (Date.now() < targetDeadline) {
+        const exists = Boolean(await evaluateRuntimeValue(client, sessionId, `Boolean(document.querySelector(${JSON.stringify(selector)}))`));
+        if (exists)
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    throw new Error(`selector not found: ${selector}`);
+}
+export function runtimeAttributeExpectationFailures(step, snapshot) {
+    const failures = [];
+    const attribute = String(step.expect_attribute || '').trim();
+    const absentAttribute = String(step.expect_attribute_absent || '').trim();
+    if (attribute && absentAttribute && attribute.toLowerCase() === absentAttribute.toLowerCase()) {
+        return [`runtime contract cannot require attribute ${JSON.stringify(attribute)} to be both present and absent`];
+    }
+    if (step.expect_attribute_value !== undefined) {
+        const expectedValue = String(step.expect_attribute_value);
+        const expectedToken = expectedValue.trim().toLowerCase();
+        if (attribute.toLowerCase() === 'hidden' && ['false', '0', 'off', 'no', 'absent'].includes(expectedToken)) {
+            if (snapshot.attributeValue !== null) {
+                failures.push('HTML boolean attribute "hidden" should be absent for the visible/false state');
+            }
+        }
+        else if (attribute.toLowerCase() === 'hidden' && ['true', '1', 'on', 'yes', 'present', ''].includes(expectedToken)) {
+            if (snapshot.attributeValue === null) {
+                failures.push('HTML boolean attribute "hidden" should be present for the hidden/true state');
+            }
+        }
+        else if (snapshot.attributeValue !== expectedValue) {
+            failures.push(`attribute ${JSON.stringify(attribute)} expected ${JSON.stringify(expectedValue)}, got ${JSON.stringify(snapshot.attributeValue)}`);
+        }
+    }
+    else if (step.expect_attribute_token !== undefined) {
+        const expectedToken = String(step.expect_attribute_token).trim();
+        const actualTokens = String(snapshot.attributeValue || '').split(/\s+/).filter(Boolean);
+        if (!actualTokens.includes(expectedToken)) {
+            failures.push(`attribute ${JSON.stringify(attribute)} should contain token ${JSON.stringify(expectedToken)}; got ${JSON.stringify(snapshot.attributeValue)}`);
+        }
+    }
+    else if (step.expect_attribute_token_absent !== undefined) {
+        const absentToken = String(step.expect_attribute_token_absent).trim();
+        const actualTokens = String(snapshot.attributeValue || '').split(/\s+/).filter(Boolean);
+        if (actualTokens.includes(absentToken)) {
+            failures.push(`attribute ${JSON.stringify(attribute)} should not contain token ${JSON.stringify(absentToken)}; got ${JSON.stringify(snapshot.attributeValue)}`);
+        }
+    }
+    else if (attribute && snapshot.attributeValue === null) {
+        failures.push(`attribute ${JSON.stringify(attribute)} should be present`);
+    }
+    if (absentAttribute && snapshot.absentAttributeValue !== null) {
+        failures.push(`attribute ${JSON.stringify(absentAttribute)} should be absent`);
+    }
+    return failures;
+}
+export function runtimeVisibilityExpectationFailures(step, snapshot) {
+    if (step.expect_visible === true && !snapshot.visible)
+        return ['expected visible'];
+    if ((step.expect_hidden === true || step.expect_visible === false) && snapshot.visible) {
+        if (snapshot.hiddenAttribute || snapshot.hiddenProperty) {
+            return [
+                `expected hidden, but authored CSS overrides the HTML hidden state (computed display: ${JSON.stringify(snapshot.computedDisplay || 'unknown')}); `
+                    + 'add [hidden] { display: none !important; } or scope the visible display rule to :not([hidden])',
+            ];
+        }
+        return ['expected hidden'];
+    }
+    return [];
+}
+async function runtimeStepFailures(client, sessionId, step) {
+    const selector = String(step.expect_selector || step.selector || '').trim();
+    const focusWithinSelector = String(step.expect_focus_within || '').trim();
+    const snapshot = await evaluateRuntimeValue(client, sessionId, `(() => {
+    const selector = ${JSON.stringify(selector)};
+    const focusWithinSelector = ${JSON.stringify(focusWithinSelector)};
+    const nodes = selector ? Array.from(document.querySelectorAll(selector)) : [];
+    const element = nodes[0] || null;
+    const visible = element ? (() => {
+      const style = getComputedStyle(element);
+      const rect = element.getBoundingClientRect();
+      return style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0'
+        && rect.width > 0 && rect.height > 0;
+    })() : false;
+    const attribute = ${JSON.stringify(String(step.expect_attribute || '').trim())};
+    const absentAttribute = ${JSON.stringify(String(step.expect_attribute_absent || '').trim())};
+    const focusRoot = focusWithinSelector ? document.querySelector(focusWithinSelector) : null;
+    const activeElement = document.activeElement;
+    const activeDescriptor = activeElement ? (() => {
+      const tag = String(activeElement.tagName || '').toLowerCase();
+      const id = activeElement.id ? '#' + activeElement.id : '';
+      const classes = activeElement.classList && activeElement.classList.length
+        ? '.' + Array.from(activeElement.classList).slice(0, 3).join('.')
+        : '';
+      const label = activeElement.getAttribute && activeElement.getAttribute('aria-label');
+      return tag + id + classes + (label ? '[aria-label=' + JSON.stringify(label) + ']' : '');
+    })() : '<none>';
+    return {
+      count: nodes.length,
+      visible,
+      text: nodes.map((node) => String(
+        node instanceof HTMLElement ? node.innerText : (node.textContent || '')
+      )).join('\\n'),
+      canvasNonblank: element instanceof HTMLCanvasElement ? (() => {
+        try {
+          const context = element.getContext('2d', { willReadFrequently: true });
+          if (!context || element.width < 1 || element.height < 1) return false;
+          const pixels = context.getImageData(0, 0, element.width, element.height).data;
+          for (let offset = 3; offset < pixels.length; offset += 4) {
+            if (pixels[offset] !== 0) return true;
+          }
+          return false;
+        } catch { return false; }
+      })() : false,
+      value: element && 'value' in element ? String(element.value ?? '') : '',
+      attributeValue: element && attribute ? element.getAttribute(attribute) : null,
+      absentAttributeValue: element && absentAttribute ? element.getAttribute(absentAttribute) : null,
+      hiddenAttribute: Boolean(element && element.hasAttribute('hidden')),
+      hiddenProperty: Boolean(element && 'hidden' in element && element.hidden),
+      computedDisplay: element ? getComputedStyle(element).display : '',
+      focused: Boolean(element && element === document.activeElement),
+      focusWithin: Boolean(focusRoot && focusRoot.contains(document.activeElement)),
+      activeDescriptor,
+    };
+  })()`);
+    const failures = [];
+    if (step.expect_count !== undefined && snapshot.count !== Number(step.expect_count)) {
+        failures.push(`count expected ${Number(step.expect_count)}, got ${snapshot.count}`);
+    }
+    failures.push(...runtimeVisibilityExpectationFailures(step, snapshot));
+    if (step.expect_text !== undefined && !String(snapshot.text || '').includes(String(step.expect_text))) {
+        const actualText = String(snapshot.text || '').replace(/\s+/g, ' ').trim();
+        const boundedActual = actualText.length > 240 ? actualText.slice(0, 237) + '...' : actualText;
+        failures.push(`text missing ${JSON.stringify(String(step.expect_text))}; actual rendered text was ${JSON.stringify(boundedActual)}`);
+    }
+    if (step.expect_text_not !== undefined && String(snapshot.text || '').includes(String(step.expect_text_not))) {
+        const actualText = String(snapshot.text || '').replace(/\s+/g, ' ').trim();
+        const boundedActual = actualText.length > 240 ? actualText.slice(0, 237) + '...' : actualText;
+        failures.push(`text still contains forbidden pre-action value ${JSON.stringify(String(step.expect_text_not))}; actual rendered text was ${JSON.stringify(boundedActual)}`);
+    }
+    if (step.expect_canvas_nonblank === true && !snapshot.canvasNonblank) {
+        failures.push('expected canvas to contain rendered pixels, but it remained transparent/blank');
+    }
+    if (step.expect_value !== undefined && String(snapshot.value || '') !== String(step.expect_value)) {
+        failures.push(`value expected ${JSON.stringify(String(step.expect_value))}, got ${JSON.stringify(String(snapshot.value || ''))}`);
+    }
+    failures.push(...runtimeAttributeExpectationFailures(step, snapshot));
+    if (step.expect_focused === true && !snapshot.focused) {
+        failures.push(`expected ${JSON.stringify(selector)} to be focused; actual active element is ${JSON.stringify(snapshot.activeDescriptor)}`);
+    }
+    if (focusWithinSelector && !snapshot.focusWithin) {
+        failures.push(`focus is not within ${JSON.stringify(focusWithinSelector)}; actual active element is ${JSON.stringify(snapshot.activeDescriptor)}`);
+    }
+    return failures;
+}
+async function executeRuntimeScenario(client, sessionId, steps, timeoutMs) {
+    const failures = [];
+    let passed = 0;
+    const scenarioDeadline = Date.now() + Math.max(1_000, Math.min(timeoutMs, 120_000));
+    for (const [offset, step] of steps.entries()) {
+        const index = offset + 1;
+        try {
+            const actionSelector = String(step.selector || '').trim();
+            if (actionSelector && ['click', 'fill', 'select', 'focus', 'press'].includes(step.action)) {
+                await waitForRuntimeActionTarget(client, sessionId, actionSelector, scenarioDeadline);
+            }
+            await applyRuntimeStepAction(client, sessionId, step);
+            const waitMs = Math.max(0, Math.min(Number(step.wait_ms) || 0, 2_000));
+            if (waitMs && step.action !== 'wait')
+                await new Promise((resolve) => setTimeout(resolve, waitMs));
+            let assertions = await runtimeStepFailures(client, sessionId, step);
+            const assertionDeadline = Math.min(scenarioDeadline, Date.now() + 3_000);
+            while (assertions.length > 0 && Date.now() < assertionDeadline) {
+                await new Promise((resolve) => setTimeout(resolve, 100));
+                assertions = await runtimeStepFailures(client, sessionId, step);
+            }
+            if (assertions.length > 0) {
+                failures.push(`step ${index} (${step.action}): ${assertions.join('; ')}`);
+                break;
+            }
+            passed += 1;
+        }
+        catch (error) {
+            failures.push(`step ${index} (${step.action}): ${normalizeRuntimeBody(error instanceof Error ? error.message : String(error))}`);
+            break;
+        }
+        if (Date.now() >= scenarioDeadline && index < steps.length) {
+            failures.push(`scenario timed out after step ${index}`);
+            break;
+        }
+    }
+    return { passed, failures };
+}
 async function captureRuntimePng(client, sessionId) {
     const captured = await client.send('Page.captureScreenshot', {
         format: 'png',
@@ -288,6 +696,7 @@ async function captureRuntimePng(client, sessionId) {
     return Buffer.from(captured.data, 'base64');
 }
 export const runPreviewRuntimeBrowser = async (executablePath, args, platform, environment, screenshotPath, options) => {
+    assertPreviewBrowserSandboxUser(platform);
     const child = spawn(executablePath, [...args], {
         stdio: ['ignore', 'ignore', 'pipe'],
         windowsHide: true,
@@ -319,7 +728,18 @@ export const runPreviewRuntimeBrowser = async (executablePath, args, platform, e
                 runtimeErrors.push(normalizeRuntimeBody(description));
             }
             if (event.method === 'Log.entryAdded' && event.params?.entry?.level === 'error') {
-                runtimeErrors.push(normalizeRuntimeBody(event.params.entry.text || 'Browser console error'));
+                const entry = event.params.entry;
+                const entryUrl = String(entry.url || '').trim();
+                runtimeErrors.push(normalizeRuntimeBody(`${entry.text || 'Browser console error'}${entryUrl ? ` (${entryUrl})` : ''}`));
+            }
+            if (event.method === 'Network.responseReceived') {
+                const resourceType = String(event.params?.type || '');
+                const status = Number(event.params?.response?.status || 0);
+                const responseUrl = String(event.params?.response?.url || '').trim();
+                if (status >= 400
+                    && ['Document', 'Script', 'Fetch', 'XHR', 'Stylesheet'].includes(resourceType)) {
+                    runtimeErrors.push(normalizeRuntimeBody(`HTTP ${status} ${resourceType} request: ${responseUrl || 'unknown URL'}`));
+                }
             }
             if (event.method === 'Network.loadingFailed') {
                 const resourceType = String(event.params?.type || '');
@@ -340,27 +760,28 @@ export const runPreviewRuntimeBrowser = async (executablePath, args, platform, e
         }, sessionId);
         const entryUrl = String(args.at(-1) || '');
         await client.send('Page.navigate', { url: entryUrl }, sessionId);
-        await waitForRuntimeReady(client, sessionId);
+        await waitForRuntimeReady(client, sessionId, entryUrl);
         await new Promise((resolve) => setTimeout(resolve, 250));
         const initialBodyText = await readRuntimeBody(client, sessionId);
         const initialPng = await captureRuntimePng(client, sessionId);
-        const key = options.key ? runtimeKeyDefinition(options.key) : null;
-        if (options.key && !key)
-            throw new Error(`unsupported browser interaction key: ${options.key}`);
         let action;
-        if (key) {
-            action = `press:${key.code}`;
-            await client.send('Input.dispatchKeyEvent', {
-                type: 'keyDown', key: key.key, code: key.code,
-                windowsVirtualKeyCode: key.virtualKeyCode, nativeVirtualKeyCode: key.virtualKeyCode,
-                ...(key.text ? { text: key.text, unmodifiedText: key.text } : {}),
-            }, sessionId);
-            await client.send('Input.dispatchKeyEvent', {
-                type: 'keyUp', key: key.key, code: key.code,
-                windowsVirtualKeyCode: key.virtualKeyCode, nativeVirtualKeyCode: key.virtualKeyCode,
-            }, sessionId);
-        }
-        const waitMs = Math.max(250, Math.min(Number(options.waitMs) || 1_750, 5_000));
+        const steps = Array.isArray(options.steps) ? options.steps.slice(0, 64) : [];
+        let interactionStepsPassed = 0;
+        let interactionFailures = [];
+        if (steps.length > 0) {
+            action = `scenario:${steps.length}`;
+            const scenario = await executeRuntimeScenario(client, sessionId, steps, Number(options.timeoutMs) || 30_000);
+            interactionStepsPassed = scenario.passed;
+            interactionFailures = scenario.failures;
+        }
+        else if (options.key) {
+            const chord = runtimeKeyChordDefinition(options.key);
+            if (!chord)
+                throw new Error(`unsupported browser interaction key: ${options.key}`);
+            action = `press:${chord.key.code}`;
+            await dispatchRuntimeKey(client, sessionId, options.key);
+        }
+        const waitMs = steps.length > 0 ? 250 : Math.max(250, Math.min(Number(options.waitMs) || 1_750, 5_000));
         const deadline = Date.now() + waitMs;
         let finalBodyText = initialBodyText;
         while (Date.now() < deadline) {
@@ -380,6 +801,9 @@ export const runPreviewRuntimeBrowser = async (executablePath, args, platform, e
             bodyChanged: finalBodyText !== initialBodyText,
             visualChanged: !finalPng.equals(initialPng),
             runtimeErrors: Array.from(new Set(runtimeErrors.filter(Boolean))).slice(0, 12),
+            interactionStepsRequested: steps.length,
+            interactionStepsPassed,
+            interactionFailures,
         };
     }
     finally {
@@ -460,6 +884,126 @@ function isTransientBrowserFailure(result) {
         return false;
     return /(?:process exited with (?:SIG[A-Z]+|[1-9][0-9]*)|timed out|\bE(?:ACCES|PERM|BUSY|AGAIN)\b|resource temporarily unavailable)/i.test(result.error);
 }
+const PREVIEW_CONTENT_TYPES = {
+    '.css': 'text/css; charset=utf-8',
+    '.gif': 'image/gif',
+    '.html': 'text/html; charset=utf-8',
+    '.htm': 'text/html; charset=utf-8',
+    '.ico': 'image/x-icon',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.js': 'text/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml; charset=utf-8',
+    '.wasm': 'application/wasm',
+    '.webp': 'image/webp',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+};
+function isPathInside(rootPath, candidatePath) {
+    const relative = path.relative(rootPath, candidatePath);
+    return relative === '' || (relative !== '..'
+        && !relative.startsWith(`..${path.sep}`)
+        && !path.isAbsolute(relative));
+}
+async function startLoopbackPreviewServer(entryAbsolutePath, requestedWorkspaceRoot) {
+    const entryPath = fs.realpathSync(entryAbsolutePath);
+    const workspaceRoot = fs.realpathSync(requestedWorkspaceRoot || path.dirname(entryPath));
+    if (!isPathInside(workspaceRoot, entryPath) || !fs.statSync(entryPath).isFile()) {
+        throw new Error('runtime preview entry is outside the authoritative workspace');
+    }
+    let server;
+    return new Promise((resolve, reject) => {
+        server = createServer((request, response) => {
+            try {
+                if (request.method !== 'GET' && request.method !== 'HEAD') {
+                    response.writeHead(405, { Allow: 'GET, HEAD' });
+                    response.end();
+                    return;
+                }
+                const requestUrl = new URL(request.url || '/', 'http://127.0.0.1');
+                let decodedPath;
+                try {
+                    decodedPath = decodeURIComponent(requestUrl.pathname);
+                }
+                catch {
+                    response.writeHead(400);
+                    response.end();
+                    return;
+                }
+                if (decodedPath.includes('\0')) {
+                    response.writeHead(400);
+                    response.end();
+                    return;
+                }
+                // Chromium requests /favicon.ico even when the document declares no
+                // icon. That optional browser decoration is not application runtime
+                // evidence. Answer the absent implicit request without hiding an
+                // explicitly provided favicon or any missing script/style/module.
+                if (decodedPath === '/favicon.ico') {
+                    const explicitFavicon = path.resolve(workspaceRoot, 'favicon.ico');
+                    if (!fs.existsSync(explicitFavicon)) {
+                        response.writeHead(204, { 'Cache-Control': 'no-store' });
+                        response.end();
+                        return;
+                    }
+                }
+                const relativeRequest = decodedPath.replace(/^\/+/, '').split('/').join(path.sep);
+                const unresolved = path.resolve(workspaceRoot, relativeRequest);
+                if (!isPathInside(workspaceRoot, unresolved) || !fs.existsSync(unresolved)) {
+                    response.writeHead(404);
+                    response.end();
+                    return;
+                }
+                const resolved = fs.realpathSync(unresolved);
+                if (!isPathInside(workspaceRoot, resolved) || !fs.statSync(resolved).isFile()) {
+                    response.writeHead(404);
+                    response.end();
+                    return;
+                }
+                response.writeHead(200, {
+                    'Cache-Control': 'no-store',
+                    'Content-Type': PREVIEW_CONTENT_TYPES[path.extname(resolved).toLowerCase()] || 'application/octet-stream',
+                    'X-Content-Type-Options': 'nosniff',
+                });
+                if (request.method === 'HEAD') {
+                    response.end();
+                    return;
+                }
+                const stream = fs.createReadStream(resolved);
+                stream.once('error', () => response.destroy());
+                stream.pipe(response);
+            }
+            catch {
+                if (!response.headersSent)
+                    response.writeHead(404);
+                response.end();
+            }
+        });
+        server.on('clientError', (_error, socket) => socket.destroy());
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            if (!address || typeof address.port !== 'number') {
+                server.close();
+                reject(new Error('loopback runtime preview server did not bind an ephemeral port'));
+                return;
+            }
+            const relativeEntry = path.relative(workspaceRoot, entryPath)
+                .split(path.sep)
+                .map((segment) => encodeURIComponent(segment))
+                .join('/');
+            resolve({
+                entryUrl: `http://127.0.0.1:${address.port}/${relativeEntry}`,
+                close: () => new Promise((closeResolve, closeReject) => {
+                    server.close((error) => error ? closeReject(error) : closeResolve());
+                }),
+            });
+        });
+    });
+}
 /** Dependency-free system-browser adapter. No browser download or archive
  * extractor is shipped, and only fixed operating-system installation paths
  * are eligible.
@@ -529,9 +1073,13 @@ export class SystemBrowserScreenshotAdapter {
     }
     async captureRuntimeOnce(resolution, entryAbsolutePath, screenshotPath, options) {
         let browserProfile = null;
+        let previewServer = null;
         let result;
         try {
-            browserProfile = this.allocateTemp('browser-runtime-', 128 * 1024 * 1024);
+            // Chromium creates process-singleton sockets below this directory. Keep
+            // the managed leaf deliberately short so ordinary per-user temp roots
+            // retain enough POSIX socket-path budget for real interaction proof.
+            browserProfile = this.allocateTemp('br-', 128 * 1024 * 1024);
             const browserUserData = path.join(browserProfile, 'profile');
             const browserScratch = path.join(browserProfile, 'scratch');
             if (this.platform !== 'win32' && Buffer.byteLength(browserScratch) > POSIX_BROWSER_SCRATCH_MAX_BYTES) {
@@ -547,6 +1095,11 @@ export class SystemBrowserScreenshotAdapter {
                 if (error?.code !== 'ENOENT')
                     throw error;
             }
+            // Chromium blocks normal ES-module graphs loaded from file://. Use an
+            // ephemeral HTTP origin bound exclusively to loopback so the proof sees
+            // the same browser semantics as the user's local preview without
+            // exposing the workspace on the network.
+            previewServer = await startLoopbackPreviewServer(entryAbsolutePath, options.workspaceRoot);
             const args = [
                 '--headless=new',
                 '--disable-gpu',
@@ -559,17 +1112,13 @@ export class SystemBrowserScreenshotAdapter {
                 '--disable-sync',
                 '--metrics-recording-only',
                 '--proxy-server=http://127.0.0.1:9',
-                '--proxy-bypass-list=<-loopback>',
+                '--proxy-bypass-list=127.0.0.1;localhost',
                 '--remote-debugging-port=0',
                 `--user-data-dir=${browserUserData}`,
                 `--window-size=${SCREENSHOT_WIDTH},${SCREENSHOT_HEIGHT}`,
-                pathToFileURL(entryAbsolutePath).toString(),
+                previewServer.entryUrl,
             ];
-            const browserEnvironment = safeChildProcessEnv(this.environment, {
-                TMPDIR: browserScratch,
-                TMP: browserScratch,
-                TEMP: browserScratch,
-            });
+            const browserEnvironment = createIsolatedBrowserEnvironment(this.environment, this.platform, browserProfile, browserScratch);
             const observation = await this.runtimeRunner(resolution.executablePath, args, this.platform, browserEnvironment, screenshotPath, options);
             validatePng(screenshotPath);
             const runtimeErrors = observation.runtimeErrors.map((entry) => redactSensitiveText(entry)).slice(0, 12);
@@ -579,6 +1128,19 @@ export class SystemBrowserScreenshotAdapter {
             const reasons = [];
             if (runtimeErrors.length > 0)
                 reasons.push(`browser errors: ${runtimeErrors.join(' | ')}`);
+            const unresolvedRenderedValues = Array.from(new Set(observation.finalBodyText.match(/\b(?:undefined|null|NaN)\s*(?:%|°(?:C|F)?\b|(?:px|rem|em|vh|vw|ms)\b)/gi) || [])).slice(0, 8);
+            if (unresolvedRenderedValues.length > 0) {
+                reasons.push(`rendered output exposes unresolved data values: ${unresolvedRenderedValues.join(', ')}`);
+            }
+            const stringifiedDomNodes = Array.from(new Set(observation.finalBodyText.match(/\[object\s+(?:HTML|SVG)[A-Za-z0-9]*Element\]/g) || [])).slice(0, 8);
+            if (stringifiedDomNodes.length > 0) {
+                reasons.push(`rendered output exposes stringified DOM nodes: ${stringifiedDomNodes.join(', ')}`);
+            }
+            const interactionFailures = (observation.interactionFailures || [])
+                .map((entry) => redactSensitiveText(entry)).slice(0, 20);
+            if (interactionFailures.length > 0) {
+                reasons.push(`interaction failures: ${interactionFailures.join(' | ')}`);
+            }
             if (!expectedTextMatched)
                 reasons.push(`expected rendered text was not found after the interaction: ${redactSensitiveText(expectedText)}`);
             if (options.requireStateChange && !stateChanged) {
@@ -593,7 +1155,10 @@ export class SystemBrowserScreenshotAdapter {
                 bodyChanged: observation.bodyChanged,
                 visualChanged: observation.visualChanged,
                 runtimeErrors,
-                error: reasons.length > 0 ? `Direct-file browser runtime proof failed: ${reasons.join('; ')}.` : undefined,
+                interactionStepsRequested: Number(observation.interactionStepsRequested || 0),
+                interactionStepsPassed: Number(observation.interactionStepsPassed || 0),
+                interactionFailures,
+                error: reasons.length > 0 ? `Loopback HTTP browser runtime proof failed: ${reasons.join('; ')}.` : undefined,
             };
         }
         catch (error) {
@@ -608,6 +1173,22 @@ export class SystemBrowserScreenshotAdapter {
             };
         }
         finally {
+            if (previewServer) {
+                try {
+                    await previewServer.close();
+                }
+                catch (cleanupError) {
+                    try {
+                        fs.unlinkSync(screenshotPath);
+                    }
+                    catch { /* proof is invalid when cleanup is incomplete */ }
+                    result = {
+                        captured: false,
+                        passed: false,
+                        error: redactSensitiveText(`runtime preview server cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`),
+                    };
+                }
+            }
             if (browserProfile) {
                 try {
                     this.releaseTemp(browserProfile);
@@ -672,11 +1253,7 @@ export class SystemBrowserScreenshotAdapter {
                 '--allow-file-access-from-files',
                 pathToFileURL(entryAbsolutePath).toString(),
             ];
-            const browserEnvironment = safeChildProcessEnv(this.environment, {
-                TMPDIR: browserScratch,
-                TMP: browserScratch,
-                TEMP: browserScratch,
-            });
+            const browserEnvironment = createIsolatedBrowserEnvironment(this.environment, this.platform, browserProfile, browserScratch);
             await this.runner(resolution.executablePath, args, this.platform, browserEnvironment);
             validatePng(screenshotPath);
             result = { captured: true };