vigthoria-cli 1.13.31 → 1.13.34

package/dist/utils/api.d.ts

@@ -254,6 +254,9 @@ export declare class APIClient {
     recoverAgentWorkspaceFiles(context?: Record<string, any>, streamedFiles?: Record<string, string>, expectedFiles?: string[]): void;
     normalizeAgentWorkspaceRelativePath(rawPath: string, rootPath?: string): string;
     private isExplicitSingleFileFrontendRequest;
+    private isFocusedAgentRepair;
+    private buildDirectFileRuntimeInteraction;
+    private buildAgentFinalPreviewContext;
     ensureAgentFrontendPolish(message?: string, context?: Record<string, any>): Promise<void>;
     private injectSectionBeforeFooter;
     private injectNavLink;

package/dist/utils/api.js

@@ -2225,19 +2225,25 @@ menu {
                 };
             }
             if (name === 'runtime_check') {
-                const previewResult = await this.executeV3ClientToolRequest({ ...event, name: 'preview_check', arguments: args }, context);
+                const previewArgs = { ...args };
+                delete previewArgs.expect_text;
+                const previewResult = await this.executeV3ClientToolRequest({ ...event, name: 'preview_check', arguments: previewArgs }, context);
                 if (!previewResult.success)
                     return previewResult;
                 const relativeTarget = target.relativePath && target.relativePath !== '.' ? target.relativePath : 'index.html';
-                const gate = await this.frontendPreviewService.runTemplateServicePreviewGate(`Verify the interactive frontend runtime at ${relativeTarget}.`, {
+                const runtimePrompt = String(context.rawPrompt || context.contextualPrompt || context.prompt
+                    || `Verify the interactive frontend runtime at ${relativeTarget}.`);
+                const gate = await this.frontendPreviewService.runTemplateServicePreviewGate(runtimePrompt, {
                     ...context,
                     targetPath: rootPath,
                     workspacePath: rootPath,
                     projectPath: rootPath,
-                    rawPrompt: `Verify the interactive frontend runtime at ${relativeTarget}.`,
+                    rawPrompt: runtimePrompt,
                     forceFrontendPreview: true,
                     localScreenshotProof: true,
+                    functionalRuntimeProof: true,
                     requireScreenshot: true,
+                    runtimeInteractionProof: this.buildDirectFileRuntimeInteraction(runtimePrompt, args),
                 });
                 if (!gate.passed || gate.artifacts?.screenshotCaptured !== true) {
                     return {
@@ -2251,7 +2257,8 @@ menu {
                     output: JSON.stringify({
                         entry: gate.entryPath || relativeTarget,
                         screenshotCaptured: true,
-                        proof: 'local-system-browser',
+                        proof: 'direct-file-system-browser-interaction',
+                        runtimeInteraction: gate.artifacts?.runtimeInteraction || null,
                     }),
                 };
             }
@@ -2561,12 +2568,62 @@ menu {
             || /\b[a-z0-9_./-]+\.html?\b[^.\n]{0,100}\b(?:only|alone)\b/i.test(request);
         return explicitOneFileLanguage;
     }
+    isFocusedAgentRepair(context = {}) {
+        const taskKinds = [
+            context.agentTaskType,
+            context.executionHints?.task_kind,
+            context.agentRoute?.taskKind,
+        ].map((value) => String(value || '').trim().toLowerCase());
+        return taskKinds.includes('repair');
+    }
+    buildDirectFileRuntimeInteraction(prompt, args = {}) {
+        const request = String(prompt || '');
+        const keyMatch = request.match(/\b(?:press|hit|tap)\s+(?:the\s+)?(?:key\s+)?(space(?:bar)?|enter|return|esc(?:ape)?|arrow\s*(?:up|down|left|right)|[a-z0-9])\b/i);
+        const rawKey = String(keyMatch?.[1] || '').replace(/\s+/g, '');
+        const keyAliases = {
+            return: 'Enter',
+            esc: 'Escape',
+            spacebar: 'Space',
+        };
+        const key = rawKey
+            ? (keyAliases[rawKey.toLowerCase()] || rawKey)
+            : undefined;
+        const expectText = String(args.expect_text || '').trim() || undefined;
+        return {
+            ...(key ? { key } : {}),
+            ...(expectText ? { expectText } : {}),
+            requireStateChange: Boolean(key),
+            waitMs: 1_750,
+        };
+    }
+    buildAgentFinalPreviewContext(message, context = {}) {
+        if (!this.isFocusedAgentRepair(context)) {
+            return context;
+        }
+        return {
+            ...context,
+            rawPrompt: context.rawPrompt || message,
+            forceFrontendPreview: true,
+            localScreenshotProof: true,
+            functionalRuntimeProof: true,
+            requireScreenshot: true,
+            runtimeInteractionProof: this.buildDirectFileRuntimeInteraction(String(context.rawPrompt || message || '')),
+        };
+    }
     async ensureAgentFrontendPolish(message = '', context = {}) {
         const rootPath = this.resolveAgentTargetPath(context);
         if (!rootPath || !fs.existsSync(rootPath)) {
             return;
         }
         const prompt = String(message || '');
+        // A focused repair owns only the evidence-proven source mutation. It is
+        // not authorization for the CLI to add responsive CSS, motion helpers, or
+        // fallback script files after the agent has finished. The final repair
+        // gate below still captures a real browser screenshot, but it must remain
+        // read-only with respect to the user's application files.
+        if (this.isFocusedAgentRepair(context)) {
+            return;
+        }
         const expectedFiles = this.extractExpectedWorkspaceFiles(message, context);
         const looksLikeFrontendTask = /(premium|polished|landing|site|page|dashboard|saas|frontend|ui|pricing|showcase|responsive|interactive|game|canvas)/i.test(prompt)
             || expectedFiles.some((filePath) => /\.(html|css|js)$/i.test(filePath));
@@ -3623,7 +3680,7 @@ document.addEventListener('DOMContentLoaded', () => {
                             this.recoverAgentWorkspaceFiles(executionContext, continuationData.files || {}, expectedFiles);
                             await this.waitForAgentWorkspaceSettle(executionContext, { expectedFiles });
                             await this.ensureAgentFrontendPolish(message, executionContext);
-                            const previewGate = await this.runTemplateServicePreviewGate(message, executionContext);
+                            const previewGate = await this.runTemplateServicePreviewGate(message, this.buildAgentFinalPreviewContext(message, executionContext));
                             const finalContextId = continuationData.context_id || data.context_id || response.headers.get('x-context-id') || requestExecutionContext.contextId || null;
                             return this.finalizeV3AgentWorkflowResponse(continuationData, {
                                 content: this.formatV3AgentResponse(continuationData) || this.formatV3AgentResponse(data),
@@ -3668,7 +3725,7 @@ document.addEventListener('DOMContentLoaded', () => {
                         }
                         await this.waitForAgentWorkspaceSettle(executionContext, { expectedFiles });
                         await this.ensureAgentFrontendPolish(message, executionContext);
-                        const previewGate = await this.runTemplateServicePreviewGate(message, executionContext);
+                        const previewGate = await this.runTemplateServicePreviewGate(message, this.buildAgentFinalPreviewContext(message, executionContext));
                         return this.finalizeV3AgentWorkflowResponse(data, {
                             content: this.formatV3AgentResponse(data),
                             taskId: data.task_id || null,
@@ -3699,7 +3756,7 @@ document.addEventListener('DOMContentLoaded', () => {
                             this.recoverAgentWorkspaceFiles(executionContext, error.partialData.files || {}, expectedFiles);
                             await this.waitForAgentWorkspaceSettle(executionContext, { expectedFiles });
                             await this.ensureAgentFrontendPolish(message, executionContext);
-                            const previewGate = await this.runTemplateServicePreviewGate(message, executionContext);
+                            const previewGate = await this.runTemplateServicePreviewGate(message, this.buildAgentFinalPreviewContext(message, executionContext));
                             return this.finalizeV3AgentWorkflowResponse(error.partialData, {
                                 content: this.formatV3AgentResponse(error.partialData) || 'V3 agent wrote workspace files before the request timed out waiting for a final summary.',
                                 taskId: error.partialData.task_id || null,
@@ -3766,7 +3823,7 @@ document.addEventListener('DOMContentLoaded', () => {
             if (appName) {
                 await this.waitForAgentWorkspaceSettle(executionContext, { expectedFiles: ['index.html', 'styles.css', 'scripts.js'] });
                 await this.ensureAgentFrontendPolish(message, executionContext);
-                const previewGate = await this.runTemplateServicePreviewGate(message, executionContext);
+                const previewGate = await this.runTemplateServicePreviewGate(message, this.buildAgentFinalPreviewContext(message, executionContext));
                 return this.finalizeV3AgentWorkflowResponse({}, {
                     content: `Recovered a local SaaS workspace scaffold for ${appName} after repeated V3 materialization failures.`,
                     taskId: null,

package/dist/utils/frontend-preview-service.d.ts

@@ -1,5 +1,5 @@
 import type { MutationJournalReport } from './mutation-journal.js';
-import type { PreviewScreenshotPort } from './preview-screenshot-adapter.js';
+import type { PreviewRuntimeInteractionResult, PreviewScreenshotPort } from './preview-screenshot-adapter.js';
 export interface FrontendPreviewGateResult {
     required: boolean;
     passed: boolean;
@@ -19,6 +19,7 @@ export interface FrontendPreviewGateResult {
         previewFileUrl?: string;
         screenshotCaptured?: boolean;
         screenshotError?: string;
+        runtimeInteraction?: PreviewRuntimeInteractionResult;
     };
     modes?: {
         design?: {

package/dist/utils/frontend-preview-service.js

@@ -272,6 +272,14 @@ export class FrontendPreviewService {
         const html = String(artifacts.html || '');
         const css = String(artifacts.css || '');
         const js = String(artifacts.js || '');
+        // runtime_check proves that an existing page can be opened by a real local
+        // browser. It is not a responsive-design audit. Requiring viewport metadata,
+        // stylesheets, and responsive CSS made focused JavaScript/CORS repairs fail
+        // even after Chromium produced the required screenshot. The screenshot and
+        // artifact persistence remain fail-closed in persistFrontendPreviewArtifacts.
+        if (options.functionalRuntime) {
+            return { ok: true, reasons: [] };
+        }
         if (!summary.hasViewportMeta) {
             reasons.push('missing viewport metadata');
         }
@@ -305,13 +313,30 @@ export class FrontendPreviewService {
             const screenshotPath = resolveWorkspacePath(rootPath, `.vigthoria/proof/preview/${baseName}.png`, { allowMissing: true });
             const entryAbsolutePath = resolveWorkspacePath(rootPath, previewGate.entryPath);
             const previewFileUrl = `file://${entryAbsolutePath}`;
-            const screenshot = await this.dependencies.screenshotAdapter.capture(entryAbsolutePath, screenshotPath);
+            const runtimeOptions = context.runtimeInteractionProof && typeof context.runtimeInteractionProof === 'object'
+                ? context.runtimeInteractionProof
+                : null;
+            const runtimeInteraction = runtimeOptions
+                ? (typeof this.dependencies.screenshotAdapter.captureRuntime === 'function'
+                    ? await this.dependencies.screenshotAdapter.captureRuntime(entryAbsolutePath, screenshotPath, runtimeOptions)
+                    : {
+                        captured: false,
+                        passed: false,
+                        error: 'required direct-file browser interaction adapter is unavailable',
+                    })
+                : null;
+            const screenshot = runtimeInteraction
+                || await this.dependencies.screenshotAdapter.capture(entryAbsolutePath, screenshotPath);
             const screenshotRequired = context.requireScreenshot === true;
-            const effectivePreviewGate = screenshotRequired && !screenshot.captured
+            const screenshotFailure = screenshotRequired && !screenshot.captured;
+            const runtimeFailure = runtimeInteraction !== null && !runtimeInteraction.passed;
+            const effectivePreviewGate = screenshotFailure || runtimeFailure
                 ? {
                     ...previewGate,
                     passed: false,
-                    error: `${previewGate.error ? `${previewGate.error} ` : ''}Required screenshot proof is unavailable: ${screenshot.error || 'capture failed'}.`,
+                    error: `${previewGate.error ? `${previewGate.error} ` : ''}${runtimeFailure
+                        ? (runtimeInteraction.error || 'Required direct-file browser interaction proof failed.')
+                        : `Required screenshot proof is unavailable: ${screenshot.error || 'capture failed'}.`}`,
                 }
                 : previewGate;
             const manifest = {
@@ -335,6 +360,16 @@ export class FrontendPreviewService {
                     captured: screenshot.captured,
                     error: screenshot.error || null,
                 },
+                runtimeInteraction: runtimeInteraction ? {
+                    passed: runtimeInteraction.passed,
+                    action: runtimeInteraction.action || null,
+                    initialBodyText: runtimeInteraction.initialBodyText || '',
+                    finalBodyText: runtimeInteraction.finalBodyText || '',
+                    bodyChanged: runtimeInteraction.bodyChanged === true,
+                    visualChanged: runtimeInteraction.visualChanged === true,
+                    runtimeErrors: runtimeInteraction.runtimeErrors || [],
+                    error: runtimeInteraction.error || null,
+                } : null,
             };
             fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
             return {
@@ -345,6 +380,7 @@ export class FrontendPreviewService {
                     previewFileUrl,
                     screenshotCaptured: screenshot.captured,
                     screenshotError: screenshot.error,
+                    ...(runtimeInteraction ? { runtimeInteraction } : {}),
                 },
             };
         }
@@ -415,7 +451,10 @@ export class FrontendPreviewService {
                 proofSource: 'local-screenshot-adapter',
             };
             const constrainedStatic = isConstrainedStaticFrontendRequest(String(context.rawPrompt || message || ''));
-            const visualProof = this.evaluateFrontendVisualProof(summary, artifacts, { constrainedStatic });
+            const visualProof = this.evaluateFrontendVisualProof(summary, artifacts, {
+                constrainedStatic,
+                functionalRuntime: context.functionalRuntimeProof === true,
+            });
             const localGate = {
                 required: true,
                 passed: visualProof.ok,
@@ -491,12 +530,18 @@ export class FrontendPreviewService {
                 const summary = payload?.summary || {};
                 const constrainedStatic = isConstrainedStaticFrontendRequest(String(context.rawPrompt || message || ''))
                     && modes?.production?.qualityTier === 'scope-complete';
-                const visualProof = this.evaluateFrontendVisualProof(summary, artifacts, { constrainedStatic });
-                const passed = payload?.success === true
-                    && modes?.design?.ready === true
-                    && modes?.live?.ready === true
-                    && modes?.production?.ready === true
-                    && visualProof.ok;
+                const functionalRuntime = context.functionalRuntimeProof === true;
+                const visualProof = this.evaluateFrontendVisualProof(summary, artifacts, {
+                    constrainedStatic,
+                    functionalRuntime,
+                });
+                const modeProofReady = functionalRuntime
+                    ? payload?.success === true && modes?.live?.ready === true
+                    : payload?.success === true
+                        && modes?.design?.ready === true
+                        && modes?.live?.ready === true
+                        && modes?.production?.ready === true;
+                const passed = modeProofReady && visualProof.ok;
                 const previewGate = {
                     required: true,
                     passed,

package/dist/utils/preview-screenshot-adapter.d.ts

@@ -1,17 +1,43 @@
+export type PreviewRuntimeInteractionOptions = {
+    key?: string;
+    expectText?: string;
+    requireStateChange?: boolean;
+    waitMs?: number;
+};
 export type PreviewScreenshotResult = {
     captured: boolean;
     error?: string;
 };
+export type PreviewRuntimeInteractionResult = PreviewScreenshotResult & {
+    passed: boolean;
+    action?: string;
+    initialBodyText?: string;
+    finalBodyText?: string;
+    bodyChanged?: boolean;
+    visualChanged?: boolean;
+    runtimeErrors?: string[];
+};
 export interface PreviewScreenshotPort {
     capture(entryAbsolutePath: string, screenshotPath: string): Promise<PreviewScreenshotResult>;
+    captureRuntime?(entryAbsolutePath: string, screenshotPath: string, options: PreviewRuntimeInteractionOptions): Promise<PreviewRuntimeInteractionResult>;
 }
 export type PreviewBrowserResolution = {
     executablePath: string;
     source: 'system';
 };
 export type PreviewBrowserRunner = (executablePath: string, args: readonly string[], platform: NodeJS.Platform, environment?: NodeJS.ProcessEnv) => Promise<void>;
+type PreviewRuntimeBrowserObservation = {
+    action?: string;
+    initialBodyText: string;
+    finalBodyText: string;
+    bodyChanged: boolean;
+    visualChanged: boolean;
+    runtimeErrors: string[];
+};
+export type PreviewRuntimeBrowserRunner = (executablePath: string, args: readonly string[], platform: NodeJS.Platform, environment: NodeJS.ProcessEnv, screenshotPath: string, options: PreviewRuntimeInteractionOptions) => Promise<PreviewRuntimeBrowserObservation>;
 export declare function resolvePreviewBrowserExecutable(environment?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, exists?: (candidate: string) => boolean): PreviewBrowserResolution | null;
 export declare const runPreviewBrowser: PreviewBrowserRunner;
+export declare const runPreviewRuntimeBrowser: PreviewRuntimeBrowserRunner;
 /** Dependency-free system-browser adapter. No browser download or archive
  * extractor is shipped, and only fixed operating-system installation paths
  * are eligible.
@@ -23,8 +49,11 @@ export declare class SystemBrowserScreenshotAdapter implements PreviewScreenshot
     private readonly platform;
     private readonly exists;
     private readonly runner;
-    constructor(environment?: NodeJS.ProcessEnv, allocateTemp?: (prefix: string, requestedMaxBytes?: number) => string, releaseTemp?: (directory: string) => void, platform?: NodeJS.Platform, exists?: (candidate: string) => boolean, runner?: PreviewBrowserRunner);
+    private readonly runtimeRunner;
+    constructor(environment?: NodeJS.ProcessEnv, allocateTemp?: (prefix: string, requestedMaxBytes?: number) => string, releaseTemp?: (directory: string) => void, platform?: NodeJS.Platform, exists?: (candidate: string) => boolean, runner?: PreviewBrowserRunner, runtimeRunner?: PreviewRuntimeBrowserRunner);
     capture(entryAbsolutePath: string, screenshotPath: string): Promise<PreviewScreenshotResult>;
+    captureRuntime(entryAbsolutePath: string, screenshotPath: string, options: PreviewRuntimeInteractionOptions): Promise<PreviewRuntimeInteractionResult>;
+    private captureRuntimeOnce;
     private captureOnce;
 }
 /** @deprecated Internal compatibility alias retained for older deep imports. */

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

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import WebSocket from 'ws';
 import { redactSensitiveText, safeChildProcessEnv } from './secret-policy.js';
 import { createRuntimeTempDirectory, removeRuntimeTempDirectory } from './runtime-temp.js';
 const SCREENSHOT_WIDTH = 800;
@@ -114,6 +115,278 @@ export const runPreviewBrowser = (executablePath, args, platform, environment =
             finish(new Error(`browser screenshot process exited with ${signal || code}`));
     });
 });
+class PreviewCdpClient {
+    socket;
+    nextId = 1;
+    pending = new Map();
+    eventListeners = new Set();
+    constructor(socket) {
+        this.socket = socket;
+        socket.on('message', (data) => {
+            let message;
+            try {
+                message = JSON.parse(data.toString());
+            }
+            catch {
+                return;
+            }
+            if (typeof message.id === 'number') {
+                const request = this.pending.get(message.id);
+                if (!request)
+                    return;
+                clearTimeout(request.timer);
+                this.pending.delete(message.id);
+                if (message.error)
+                    request.reject(new Error(message.error.message || 'DevTools command failed'));
+                else
+                    request.resolve(message.result || {});
+                return;
+            }
+            for (const listener of this.eventListeners)
+                listener(message);
+        });
+        socket.on('error', (error) => this.rejectPending(error));
+        socket.on('close', () => this.rejectPending(new Error('browser DevTools connection closed')));
+    }
+    onEvent(listener) {
+        this.eventListeners.add(listener);
+        return () => this.eventListeners.delete(listener);
+    }
+    send(method, params = {}, sessionId) {
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`browser DevTools command ${method} timed out`));
+            }, 7_500);
+            this.pending.set(id, { resolve, reject, timer });
+            this.socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }), (error) => {
+                if (!error)
+                    return;
+                const request = this.pending.get(id);
+                if (!request)
+                    return;
+                clearTimeout(request.timer);
+                this.pending.delete(id);
+                reject(error);
+            });
+        });
+    }
+    close() {
+        try {
+            this.socket.close();
+        }
+        catch { /* browser already exited */ }
+    }
+    rejectPending(error) {
+        for (const [id, request] of this.pending) {
+            clearTimeout(request.timer);
+            request.reject(error);
+            this.pending.delete(id);
+        }
+    }
+}
+function waitForDevToolsSocket(child) {
+    return new Promise((resolve, reject) => {
+        let buffer = '';
+        let settled = false;
+        const finish = (error, socketUrl) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            child.stderr?.off('data', onData);
+            child.off('error', onError);
+            child.off('exit', onExit);
+            if (error)
+                reject(error);
+            else
+                resolve(socketUrl);
+        };
+        const onData = (chunk) => {
+            buffer = `${buffer}${chunk.toString()}`.slice(-16_384);
+            const match = buffer.match(/DevTools listening on (ws:\/\/[^\s]+)/i);
+            if (match)
+                finish(undefined, match[1]);
+        };
+        const onError = (error) => finish(error);
+        const onExit = (code, signal) => finish(new Error(`browser runtime process exited before DevTools was ready with ${signal || code}`));
+        const timer = setTimeout(() => finish(new Error('browser DevTools endpoint did not become ready')), 10_000);
+        child.stderr?.on('data', onData);
+        child.once('error', onError);
+        child.once('exit', onExit);
+    });
+}
+function connectDevTools(socketUrl) {
+    return new Promise((resolve, reject) => {
+        const socket = new WebSocket(socketUrl, { perMessageDeflate: false });
+        const timer = setTimeout(() => {
+            try {
+                socket.terminate();
+            }
+            catch { /* connection never opened */ }
+            reject(new Error('browser DevTools WebSocket connection timed out'));
+        }, 7_500);
+        socket.once('open', () => { clearTimeout(timer); resolve(socket); });
+        socket.once('error', (error) => { clearTimeout(timer); reject(error); });
+    });
+}
+function normalizeRuntimeBody(value) {
+    return redactSensitiveText(String(value || '').replace(/\s+/g, ' ').trim()).slice(0, 4_000);
+}
+function runtimeKeyDefinition(rawKey = '') {
+    const normalized = rawKey.trim().toLowerCase().replace(/\s+/g, '');
+    const fixed = {
+        space: { key: ' ', code: 'Space', virtualKeyCode: 32, text: ' ' },
+        spacebar: { key: ' ', code: 'Space', virtualKeyCode: 32, text: ' ' },
+        enter: { key: 'Enter', code: 'Enter', virtualKeyCode: 13, text: '\r' },
+        escape: { key: 'Escape', code: 'Escape', virtualKeyCode: 27 },
+        esc: { key: 'Escape', code: 'Escape', virtualKeyCode: 27 },
+        arrowup: { key: 'ArrowUp', code: 'ArrowUp', virtualKeyCode: 38 },
+        arrowdown: { key: 'ArrowDown', code: 'ArrowDown', virtualKeyCode: 40 },
+        arrowleft: { key: 'ArrowLeft', code: 'ArrowLeft', virtualKeyCode: 37 },
+        arrowright: { key: 'ArrowRight', code: 'ArrowRight', virtualKeyCode: 39 },
+    };
+    if (fixed[normalized])
+        return fixed[normalized];
+    if (/^[a-z0-9]$/.test(normalized)) {
+        const upper = normalized.toUpperCase();
+        return { key: normalized, code: /[a-z]/.test(normalized) ? `Key${upper}` : `Digit${normalized}`, virtualKeyCode: upper.charCodeAt(0), text: normalized };
+    }
+    return null;
+}
+async function waitForRuntimeReady(client, sessionId) {
+    const deadline = Date.now() + 8_000;
+    while (Date.now() < deadline) {
+        const evaluated = await client.send('Runtime.evaluate', {
+            expression: 'document.readyState',
+            returnByValue: true,
+        }, sessionId);
+        const readyState = String(evaluated.result?.value || '');
+        if (readyState === 'interactive' || readyState === 'complete')
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    throw new Error('browser document did not become ready');
+}
+async function readRuntimeBody(client, sessionId) {
+    const evaluated = await client.send('Runtime.evaluate', {
+        expression: 'document.body ? document.body.innerText : ""',
+        returnByValue: true,
+    }, sessionId);
+    return normalizeRuntimeBody(evaluated.result?.value);
+}
+async function captureRuntimePng(client, sessionId) {
+    const captured = await client.send('Page.captureScreenshot', {
+        format: 'png',
+        fromSurface: true,
+        captureBeyondViewport: false,
+    }, sessionId);
+    if (typeof captured.data !== 'string' || captured.data.length === 0) {
+        throw new Error('browser DevTools did not return screenshot bytes');
+    }
+    return Buffer.from(captured.data, 'base64');
+}
+export const runPreviewRuntimeBrowser = async (executablePath, args, platform, environment, screenshotPath, options) => {
+    const child = spawn(executablePath, [...args], {
+        stdio: ['ignore', 'ignore', 'pipe'],
+        windowsHide: true,
+        env: safeChildProcessEnv(environment),
+        detached: platform !== 'win32',
+    });
+    let client = null;
+    const runtimeErrors = [];
+    try {
+        const socketUrl = await waitForDevToolsSocket(child);
+        client = new PreviewCdpClient(await connectDevTools(socketUrl));
+        const targets = await client.send('Target.getTargets');
+        const pageTarget = Array.isArray(targets.targetInfos)
+            ? targets.targetInfos.find((target) => target?.type === 'page')
+            : null;
+        if (!pageTarget?.targetId)
+            throw new Error('browser DevTools did not expose a page target');
+        const attached = await client.send('Target.attachToTarget', { targetId: pageTarget.targetId, flatten: true });
+        const sessionId = String(attached.sessionId || '');
+        if (!sessionId)
+            throw new Error('browser DevTools did not attach to the page target');
+        client.onEvent((event) => {
+            if (event.sessionId !== sessionId)
+                return;
+            if (event.method === 'Runtime.exceptionThrown') {
+                const description = event.params?.exceptionDetails?.exception?.description
+                    || event.params?.exceptionDetails?.text
+                    || 'Uncaught runtime exception';
+                runtimeErrors.push(normalizeRuntimeBody(description));
+            }
+            if (event.method === 'Log.entryAdded' && event.params?.entry?.level === 'error') {
+                runtimeErrors.push(normalizeRuntimeBody(event.params.entry.text || 'Browser console error'));
+            }
+            if (event.method === 'Network.loadingFailed') {
+                const resourceType = String(event.params?.type || '');
+                if (['Document', 'Script', 'Fetch', 'XHR', 'Stylesheet'].includes(resourceType)) {
+                    runtimeErrors.push(normalizeRuntimeBody(`Failed ${resourceType} request: ${event.params?.errorText || 'unknown browser error'}`));
+                }
+            }
+        });
+        await client.send('Page.enable', {}, sessionId);
+        await client.send('Runtime.enable', {}, sessionId);
+        await client.send('Log.enable', {}, sessionId);
+        await client.send('Network.enable', {}, sessionId);
+        await client.send('Emulation.setDeviceMetricsOverride', {
+            width: SCREENSHOT_WIDTH,
+            height: SCREENSHOT_HEIGHT,
+            deviceScaleFactor: 1,
+            mobile: false,
+        }, sessionId);
+        const entryUrl = String(args.at(-1) || '');
+        await client.send('Page.navigate', { url: entryUrl }, sessionId);
+        await waitForRuntimeReady(client, sessionId);
+        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 deadline = Date.now() + waitMs;
+        let finalBodyText = initialBodyText;
+        while (Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, 100));
+            finalBodyText = await readRuntimeBody(client, sessionId);
+            if (options.expectText && finalBodyText.includes(options.expectText))
+                break;
+            if (!options.expectText && options.requireStateChange && finalBodyText !== initialBodyText)
+                break;
+        }
+        const finalPng = await captureRuntimePng(client, sessionId);
+        fs.writeFileSync(screenshotPath, finalPng, { mode: 0o600 });
+        return {
+            action,
+            initialBodyText,
+            finalBodyText,
+            bodyChanged: finalBodyText !== initialBodyText,
+            visualChanged: !finalPng.equals(initialPng),
+            runtimeErrors: Array.from(new Set(runtimeErrors.filter(Boolean))).slice(0, 12),
+        };
+    }
+    finally {
+        client?.close();
+        await terminateBrowserProcess(child, platform);
+    }
+};
 function pngCrc32(data) {
     let crc = 0xffffffff;
     for (const byte of data) {
@@ -198,13 +471,15 @@ export class SystemBrowserScreenshotAdapter {
     platform;
     exists;
     runner;
-    constructor(environment = process.env, allocateTemp = createRuntimeTempDirectory, releaseTemp = removeRuntimeTempDirectory, platform = process.platform, exists = fs.existsSync, runner = runPreviewBrowser) {
+    runtimeRunner;
+    constructor(environment = process.env, allocateTemp = createRuntimeTempDirectory, releaseTemp = removeRuntimeTempDirectory, platform = process.platform, exists = fs.existsSync, runner = runPreviewBrowser, runtimeRunner = runPreviewRuntimeBrowser) {
         this.environment = environment;
         this.allocateTemp = allocateTemp;
         this.releaseTemp = releaseTemp;
         this.platform = platform;
         this.exists = exists;
         this.runner = runner;
+        this.runtimeRunner = runtimeRunner;
     }
     async capture(entryAbsolutePath, screenshotPath) {
         if (this.environment.VIGTHORIA_DISABLE_PREVIEW_SCREENSHOT === '1') {
@@ -227,6 +502,137 @@ export class SystemBrowserScreenshotAdapter {
         }
         return lastResult;
     }
+    async captureRuntime(entryAbsolutePath, screenshotPath, options) {
+        if (this.environment.VIGTHORIA_DISABLE_PREVIEW_SCREENSHOT === '1') {
+            return { captured: false, passed: false, error: 'runtime screenshot capture explicitly unavailable' };
+        }
+        const resolution = resolvePreviewBrowserExecutable(this.environment, this.platform, this.exists);
+        if (!resolution) {
+            return {
+                captured: false,
+                passed: false,
+                error: 'required system browser is unavailable; install Microsoft Edge, Chrome, or Chromium',
+            };
+        }
+        let lastResult = {
+            captured: false,
+            passed: false,
+            error: 'browser runtime proof was not attempted',
+        };
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            lastResult = await this.captureRuntimeOnce(resolution, entryAbsolutePath, screenshotPath, options);
+            if (lastResult.passed || !isTransientBrowserFailure(lastResult))
+                return lastResult;
+            await new Promise((resolve) => setTimeout(resolve, 500));
+        }
+        return lastResult;
+    }
+    async captureRuntimeOnce(resolution, entryAbsolutePath, screenshotPath, options) {
+        let browserProfile = null;
+        let result;
+        try {
+            browserProfile = this.allocateTemp('browser-runtime-', 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) {
+                throw new Error('managed browser temporary path is too long; configure a shorter dedicated VIGTHORIA_TEMP_DIR');
+            }
+            fs.mkdirSync(browserUserData, { recursive: false, mode: 0o700 });
+            fs.mkdirSync(browserScratch, { recursive: false, mode: 0o700 });
+            fs.mkdirSync(path.dirname(screenshotPath), { recursive: true, mode: 0o700 });
+            try {
+                fs.unlinkSync(screenshotPath);
+            }
+            catch (error) {
+                if (error?.code !== 'ENOENT')
+                    throw error;
+            }
+            const args = [
+                '--headless=new',
+                '--disable-gpu',
+                '--disable-dev-shm-usage',
+                '--hide-scrollbars',
+                '--no-first-run',
+                '--no-default-browser-check',
+                '--disable-background-networking',
+                '--disable-component-update',
+                '--disable-sync',
+                '--metrics-recording-only',
+                '--proxy-server=http://127.0.0.1:9',
+                '--proxy-bypass-list=<-loopback>',
+                '--remote-debugging-port=0',
+                `--user-data-dir=${browserUserData}`,
+                `--window-size=${SCREENSHOT_WIDTH},${SCREENSHOT_HEIGHT}`,
+                pathToFileURL(entryAbsolutePath).toString(),
+            ];
+            const browserEnvironment = safeChildProcessEnv(this.environment, {
+                TMPDIR: browserScratch,
+                TMP: browserScratch,
+                TEMP: 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);
+            const expectedText = String(options.expectText || '').trim();
+            const expectedTextMatched = !expectedText || observation.finalBodyText.includes(expectedText);
+            const stateChanged = observation.bodyChanged || observation.visualChanged;
+            const reasons = [];
+            if (runtimeErrors.length > 0)
+                reasons.push(`browser errors: ${runtimeErrors.join(' | ')}`);
+            if (!expectedTextMatched)
+                reasons.push(`expected rendered text was not found after the interaction: ${redactSensitiveText(expectedText)}`);
+            if (options.requireStateChange && !stateChanged) {
+                reasons.push(`${observation.action || 'requested interaction'} produced no DOM-text or visual change`);
+            }
+            result = {
+                captured: true,
+                passed: reasons.length === 0,
+                action: observation.action,
+                initialBodyText: observation.initialBodyText,
+                finalBodyText: observation.finalBodyText,
+                bodyChanged: observation.bodyChanged,
+                visualChanged: observation.visualChanged,
+                runtimeErrors,
+                error: reasons.length > 0 ? `Direct-file browser runtime proof failed: ${reasons.join('; ')}.` : undefined,
+            };
+        }
+        catch (error) {
+            try {
+                fs.unlinkSync(screenshotPath);
+            }
+            catch { /* no failed proof artifact */ }
+            result = {
+                captured: false,
+                passed: false,
+                error: redactSensitiveText(error instanceof Error ? error.message : String(error)),
+            };
+        }
+        finally {
+            if (browserProfile) {
+                try {
+                    this.releaseTemp(browserProfile);
+                }
+                catch {
+                    await new Promise((resolve) => setTimeout(resolve, 150));
+                    try {
+                        this.releaseTemp(browserProfile);
+                    }
+                    catch (cleanupError) {
+                        try {
+                            fs.unlinkSync(screenshotPath);
+                        }
+                        catch { /* proof is invalid when cleanup is incomplete */ }
+                        result = {
+                            captured: false,
+                            passed: false,
+                            error: redactSensitiveText(`browser profile cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`),
+                        };
+                    }
+                }
+            }
+        }
+        return result;
+    }
     async captureOnce(resolution, entryAbsolutePath, screenshotPath) {
         let browserProfile = null;
         let result;

package/install.ps1

@@ -5,7 +5,7 @@
 $ErrorActionPreference = "Stop"
 
 # Configuration
-$CLI_VERSION = "1.13.31"
+$CLI_VERSION = "1.13.34"
 $INSTALL_DIR = "$env:USERPROFILE\.vigthoria"
 $NPM_PACKAGE = "vigthoria-cli"
 $MANIFEST_URL = "https://extension.vigthoria.io/downloads/manifest.json"
@@ -32,7 +32,7 @@ function Assert-TrustedReleaseUrl([string]$Value) {
 function Resolve-ReleaseManifest {
     # The hosted path is enabled only when the packaged shared policy verifier
     # can validate strict metadata and the detached Ed25519 signature.
-    if (-not (Test-Path $RELEASE_RESOLVER)) { return }
+    if (-not $RELEASE_RESOLVER -or -not (Test-Path -LiteralPath $RELEASE_RESOLVER)) { return }
     try {
         $trustedManifest = Assert-TrustedReleaseUrl $MANIFEST_URL
         $resolvedJson = & node $RELEASE_RESOLVER $trustedManifest stable
@@ -166,7 +166,7 @@ function Install-VigthoriaCLI-NPM {
     Write-Host ""
     Write-Host "[INSTALL] Installing Vigthoria CLI..." -ForegroundColor Cyan
 
-    if ($HOSTED_TARBALL_SHA256) {
+    if ($HOSTED_TARBALL_SHA256 -and $RELEASE_INSTALLER -and (Test-Path -LiteralPath $RELEASE_INSTALLER)) {
         $releaseTemp = Join-Path (Get-VigthoriaTempRoot) ("install-" + [Guid]::NewGuid().ToString("N"))
         $releaseArchive = Join-Path $releaseTemp "candidate.tgz"
         try {
@@ -175,7 +175,7 @@ function Install-VigthoriaCLI-NPM {
             Invoke-WebRequest -Uri $trustedTarball -OutFile $releaseArchive -UseBasicParsing -MaximumRedirection 0 -TimeoutSec 60 -ErrorAction Stop
             $actualSha256 = (Get-FileHash -Path $releaseArchive -Algorithm SHA256).Hash.ToLowerInvariant()
             if ($actualSha256 -ne $HOSTED_TARBALL_SHA256) { throw "Release checksum mismatch" }
-            if (-not (Test-Path $RELEASE_INSTALLER)) { throw "Transactional release installer is unavailable" }
+            if (-not $RELEASE_INSTALLER -or -not (Test-Path -LiteralPath $RELEASE_INSTALLER)) { throw "Transactional release installer is unavailable" }
             & node $RELEASE_INSTALLER $releaseArchive $CLI_VERSION
             if ($LASTEXITCODE -ne 0) { throw "transactional installer exited with status $LASTEXITCODE" }
             Write-Host "[OK] Vigthoria CLI installed from the checksum-verified release!" -ForegroundColor Green
@@ -192,7 +192,7 @@ function Install-VigthoriaCLI-NPM {
     }
 
     try {
-        if (Test-Path $RELEASE_INSTALLER) {
+        if ($RELEASE_INSTALLER -and (Test-Path -LiteralPath $RELEASE_INSTALLER)) {
             & node $RELEASE_INSTALLER "$NPM_PACKAGE@$CLI_VERSION" $CLI_VERSION
             if ($LASTEXITCODE -ne 0) { throw "transactional installer exited with status $LASTEXITCODE" }
         } else {
@@ -215,7 +215,7 @@ function Install-VigthoriaCLI-Direct {
     $tarballPath = Join-Path $releaseTemp "candidate.tgz"
     try {
         if (-not $HOSTED_TARBALL_SHA256) { throw "Direct installation requires a signed manifest SHA-256" }
-        if (-not (Test-Path $RELEASE_INSTALLER)) { throw "Transactional release installer is unavailable" }
+        if (-not $RELEASE_INSTALLER -or -not (Test-Path -LiteralPath $RELEASE_INSTALLER)) { throw "Transactional release installer is unavailable" }
         New-Item -ItemType Directory -Path $releaseTemp -ErrorAction Stop | Out-Null
         $tarballUrl = Assert-TrustedReleaseUrl $HOSTED_TARBALL_URL
         Invoke-WebRequest -Uri $tarballUrl -OutFile $tarballPath -UseBasicParsing -MaximumRedirection 0 -TimeoutSec 60 -ErrorAction Stop

package/install.sh

@@ -26,7 +26,7 @@ else
 fi
 
 # Configuration
-CLI_VERSION="1.13.31"
+CLI_VERSION="1.13.34"
 INSTALL_DIR="$HOME/.vigthoria"
 MANIFEST_URL="${VIGTHORIA_UPDATE_MANIFEST_URL:-https://extension.vigthoria.io/downloads/manifest.json}"
 HOSTED_TARBALL_URL="https://extension.vigthoria.io/downloads/vigthoria-cli-${CLI_VERSION}.tgz"
@@ -257,7 +257,7 @@ install_cli() {
     mkdir -p "$INSTALL_DIR"
     
     # Option 1: Download and verify the exact hosted release package.
-    if [[ -n "$HOSTED_TARBALL_SHA256" ]]; then
+    if [[ -n "$HOSTED_TARBALL_SHA256" && -f "$RELEASE_INSTALLER" ]]; then
         echo "Downloading checksum-verified hosted release package..."
         VIGTHORIA_INSTALL_TEMP_ROOT="$(prepare_temp_root)" || return 1
         RELEASE_TMP_DIR="$(mktemp -d "$VIGTHORIA_INSTALL_TEMP_ROOT/install.XXXXXX")"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigthoria-cli",
-  "version": "1.13.31",
+  "version": "1.13.34",
   "description": "Vigthoria Coder CLI - AI-powered terminal coding assistant",
   "type": "module",
   "main": "dist/index.js",