flowstride 1.0.20 → 1.0.21

package/dist/native/validation.d.ts

@@ -0,0 +1,107 @@
+import { z } from 'zod';
+import type { BrowserContextOptions } from 'playwright';
+import type { FlowstrideConfig } from '../types';
+export declare const name: z.ZodString;
+export declare const positive: z.ZodNumber;
+export declare const headers: z.ZodRecord<z.ZodString, z.ZodString>;
+export declare const contextOptions: z.ZodObject<{
+    acceptDownloads: z.ZodOptional<z.ZodBoolean>;
+    strictSelectors: z.ZodOptional<z.ZodBoolean>;
+    clientCertificates: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        origin: z.ZodString;
+        certPath: z.ZodOptional<z.ZodString>;
+        keyPath: z.ZodOptional<z.ZodString>;
+        pfxPath: z.ZodOptional<z.ZodString>;
+        passphrase: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    storageState: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        cookies: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            value: z.ZodString;
+            domain: z.ZodString;
+            path: z.ZodString;
+            expires: z.ZodNumber;
+            httpOnly: z.ZodBoolean;
+            secure: z.ZodBoolean;
+            sameSite: z.ZodEnum<{
+                Strict: "Strict";
+                Lax: "Lax";
+                None: "None";
+            }>;
+        }, z.core.$strict>>;
+        origins: z.ZodArray<z.ZodObject<{
+            origin: z.ZodString;
+            localStorage: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                value: z.ZodString;
+            }, z.core.$strict>>;
+            indexedDB: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>]>>;
+    baseURL: z.ZodOptional<z.ZodString>;
+    bypassCSP: z.ZodOptional<z.ZodBoolean>;
+    colorScheme: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        light: "light";
+        dark: "dark";
+        "no-preference": "no-preference";
+    }>>>;
+    contrast: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        "no-preference": "no-preference";
+        more: "more";
+    }>>>;
+    deviceScaleFactor: z.ZodOptional<z.ZodNumber>;
+    extraHTTPHeaders: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    forcedColors: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        none: "none";
+        active: "active";
+    }>>>;
+    hasTouch: z.ZodOptional<z.ZodBoolean>;
+    httpCredentials: z.ZodOptional<z.ZodObject<{
+        username: z.ZodString;
+        password: z.ZodString;
+        origin: z.ZodOptional<z.ZodString>;
+        send: z.ZodOptional<z.ZodEnum<{
+            always: "always";
+            unauthorized: "unauthorized";
+        }>>;
+    }, z.core.$strict>>;
+    geolocation: z.ZodOptional<z.ZodObject<{
+        latitude: z.ZodNumber;
+        longitude: z.ZodNumber;
+        accuracy: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    ignoreHTTPSErrors: z.ZodOptional<z.ZodBoolean>;
+    isMobile: z.ZodOptional<z.ZodBoolean>;
+    javaScriptEnabled: z.ZodOptional<z.ZodBoolean>;
+    locale: z.ZodOptional<z.ZodString>;
+    offline: z.ZodOptional<z.ZodBoolean>;
+    permissions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    proxy: z.ZodOptional<z.ZodObject<{
+        server: z.ZodString;
+        bypass: z.ZodOptional<z.ZodString>;
+        username: z.ZodOptional<z.ZodString>;
+        password: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    reducedMotion: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        reduce: "reduce";
+        "no-preference": "no-preference";
+    }>>>;
+    screen: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+    serviceWorkers: z.ZodOptional<z.ZodEnum<{
+        allow: "allow";
+        block: "block";
+    }>>;
+    timezoneId: z.ZodOptional<z.ZodString>;
+    userAgent: z.ZodOptional<z.ZodString>;
+    viewport: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export declare function validateContextOptions(value: unknown, browser?: string, root?: string): BrowserContextOptions;
+export declare function evidencePath(config: FlowstrideConfig, file: string): string;
+export declare function readProjectFile(config: FlowstrideConfig, file: string, maxSize?: number): Buffer;
+export declare function poll(read: () => Promise<boolean>, timeout: number, label: string): Promise<void>;

package/dist/native/validation.js

@@ -0,0 +1,84 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contextOptions = exports.headers = exports.positive = exports.name = void 0;
+exports.validateContextOptions = validateContextOptions;
+exports.evidencePath = evidencePath;
+exports.readProjectFile = readProjectFile;
+exports.poll = poll;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const zod_1 = require("zod");
+const projectPaths_1 = require("../utils/projectPaths");
+exports.name = zod_1.z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,79}$/, 'Use a simple name without path separators.');
+exports.positive = zod_1.z.number().int().min(1).max(2147483647);
+exports.headers = zod_1.z.record(zod_1.z.string(), zod_1.z.string());
+const size = zod_1.z.object({ width: exports.positive, height: exports.positive }).strict();
+// File-bearing options are handled explicitly; evidence paths cannot bypass project containment.
+exports.contextOptions = zod_1.z.object({
+    acceptDownloads: zod_1.z.boolean().optional(), strictSelectors: zod_1.z.boolean().optional(),
+    clientCertificates: zod_1.z.array(zod_1.z.object({ origin: zod_1.z.string().url(), certPath: zod_1.z.string().optional(), keyPath: zod_1.z.string().optional(), pfxPath: zod_1.z.string().optional(), passphrase: zod_1.z.string().optional() }).strict()).optional(),
+    storageState: zod_1.z.union([zod_1.z.string(), zod_1.z.object({ cookies: zod_1.z.array(zod_1.z.object({ name: zod_1.z.string(), value: zod_1.z.string(), domain: zod_1.z.string(), path: zod_1.z.string(), expires: zod_1.z.number(), httpOnly: zod_1.z.boolean(), secure: zod_1.z.boolean(), sameSite: zod_1.z.enum(['Strict', 'Lax', 'None']) }).strict()), origins: zod_1.z.array(zod_1.z.object({ origin: zod_1.z.string().url(), localStorage: zod_1.z.array(zod_1.z.object({ name: zod_1.z.string(), value: zod_1.z.string() }).strict()), indexedDB: zod_1.z.array(zod_1.z.unknown()).optional() }).strict()) }).strict()]).optional(),
+    baseURL: zod_1.z.string().url().optional(),
+    bypassCSP: zod_1.z.boolean().optional(), colorScheme: zod_1.z.enum(['light', 'dark', 'no-preference']).nullable().optional(),
+    contrast: zod_1.z.enum(['no-preference', 'more']).nullable().optional(),
+    deviceScaleFactor: zod_1.z.number().positive().optional(), extraHTTPHeaders: exports.headers.optional(),
+    forcedColors: zod_1.z.enum(['active', 'none']).nullable().optional(), hasTouch: zod_1.z.boolean().optional(),
+    httpCredentials: zod_1.z.object({ username: zod_1.z.string(), password: zod_1.z.string(), origin: zod_1.z.string().url().optional(), send: zod_1.z.enum(['always', 'unauthorized']).optional() }).strict().optional(),
+    geolocation: zod_1.z.object({ latitude: zod_1.z.number().min(-90).max(90), longitude: zod_1.z.number().min(-180).max(180), accuracy: zod_1.z.number().nonnegative().optional() }).strict().optional(),
+    ignoreHTTPSErrors: zod_1.z.boolean().optional(), isMobile: zod_1.z.boolean().optional(), javaScriptEnabled: zod_1.z.boolean().optional(),
+    locale: zod_1.z.string().min(1).optional(), offline: zod_1.z.boolean().optional(), permissions: zod_1.z.array(zod_1.z.string()).optional(),
+    proxy: zod_1.z.object({ server: zod_1.z.string().min(1), bypass: zod_1.z.string().optional(), username: zod_1.z.string().optional(), password: zod_1.z.string().optional() }).strict().optional(),
+    reducedMotion: zod_1.z.enum(['reduce', 'no-preference']).nullable().optional(), screen: size.optional(),
+    serviceWorkers: zod_1.z.enum(['allow', 'block']).optional(), timezoneId: zod_1.z.string().optional(),
+    userAgent: zod_1.z.string().optional(), viewport: size.nullable().optional(),
+}).strict();
+function validateContextOptions(value, browser = 'chromium', root = process.cwd()) {
+    const parsed = exports.contextOptions.parse(value ?? {});
+    if (typeof parsed.storageState === 'string')
+        parsed.storageState = (0, projectPaths_1.projectPath)(root, parsed.storageState);
+    for (const certificate of parsed.clientCertificates || [])
+        for (const key of ['certPath', 'keyPath', 'pfxPath'])
+            if (certificate[key])
+                certificate[key] = (0, projectPaths_1.projectPath)(root, certificate[key]);
+    if (browser === 'firefox' && parsed.isMobile)
+        throw new Error('Firefox does not support mobile emulation; use viewport and touch options instead.');
+    return parsed;
+}
+function evidencePath(config, file) {
+    const safe = exports.name.parse(file);
+    const root = config.projectRoot || process.cwd();
+    const dir = (0, projectPaths_1.projectPath)(root, config.artifactsDir || 'flowstride-artifacts');
+    node_fs_1.default.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return (0, projectPaths_1.projectPath)(root, node_path_1.default.join(dir, (0, projectPaths_1.artifactPrefix)(config.testFile) + safe));
+}
+function readProjectFile(config, file, maxSize = 20 * 1024 * 1024) {
+    const absolute = (0, projectPaths_1.projectPath)(config.projectRoot || process.cwd(), file);
+    if (!node_fs_1.default.statSync(absolute).isFile() || node_fs_1.default.statSync(absolute).size > maxSize)
+        throw new Error('Fixture must be a regular project file within the size limit.');
+    return node_fs_1.default.readFileSync(absolute);
+}
+async function poll(read, timeout, label) {
+    const deadline = Date.now() + exports.positive.parse(timeout);
+    let last;
+    for (;;) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            throw new Error(`Assertion timed out: ${label}`, { cause: last });
+        let timer;
+        try {
+            const ok = await Promise.race([read(), new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('Read timed out')), remaining); })]);
+            if (ok)
+                return;
+        }
+        catch (error) {
+            last = error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        await new Promise(resolve => setTimeout(resolve, Math.min(50, Math.max(0, deadline - Date.now()))));
+    }
+}

package/dist/parser/lexer.js

@@ -53,11 +53,22 @@ class Lexer {
                 let jsonStr = "";
                 let depth = 0;
                 let startLine = this.line;
+                let inString = false, escaped = false;
                 while (this.position < this.input.length) {
                     const c = this.input[this.position];
-                    if (c === "{")
+                    if (inString) {
+                        if (escaped)
+                            escaped = false;
+                        else if (c === "\\")
+                            escaped = true;
+                        else if (c === '"')
+                            inString = false;
+                    }
+                    else if (c === '"')
+                        inString = true;
+                    else if (c === "{")
                         depth++;
-                    if (c === "}")
+                    else if (c === "}")
                         depth--;
                     if (c === "\n")
                         this.line++;
@@ -217,7 +228,7 @@ class Lexer {
                         });
                         continue;
                     }
-                    else if (ident.includes(".") && !lowerIdent.startsWith("flow.")) {
+                    else if (/^flow\.(browser|assert|network|download|clock|stub|trace|har|a11y|component)\.[a-z]+$/i.test(ident) || (ident.includes(".") && !lowerIdent.startsWith("flow."))) {
                         tokens.push({
                             type: TokenType.ALIAS_COMMAND,
                             value: ident,
@@ -392,7 +403,7 @@ class Lexer {
                         line: this.line,
                     });
                 }
-                else if (ident.includes(".") && !lowerIdent.startsWith("flow.")) {
+                else if (/^flow\.(browser|assert|network|download|clock|stub|trace|har|a11y|component)\.[a-z]+$/i.test(ident) || (ident.includes(".") && !lowerIdent.startsWith("flow."))) {
                     tokens.push({
                         type: TokenType.ALIAS_COMMAND,
                         value: ident,

package/dist/parser/parser.js

@@ -242,7 +242,7 @@ class Parser {
             return {
                 id: `scenario_${this.scenarioCounter}_S${this.stepCounter++}`,
                 blockDescription: this.currentBlockDescription,
-                action: "plugin",
+                action: alias === "flow" ? "native" : "plugin",
                 payload: {
                     pluginAlias: alias,
                     pluginMethod: method,

package/dist/runner/flow_orchestrator.d.ts

@@ -4,6 +4,7 @@ export declare class FlowOrchestrator {
     private worker;
     private workerCount;
     private config?;
+    static readonly nativeBrowserProtocol = 2;
     static readonly nativeCIProtocol = 1;
     readonly nativeEventProtocol = 1;
     private wss;
@@ -12,6 +13,9 @@ export declare class FlowOrchestrator {
     private stepStatusRegistry;
     private pdfGenerator;
     private disconnectTimer;
+    private dashboardBrowser;
+    private closing;
+    private browserInfoByFile;
     constructor(worker: FlowWorker, workerCount?: number, config?: FlowstrideConfig | undefined);
     private forwardToDashboard;
     private executeTestRun;

package/dist/runner/flow_orchestrator.js

@@ -37,8 +37,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FlowOrchestrator = void 0;
+const dashboard_1 = require("../native/dashboard");
+const evidence_1 = require("../native/evidence");
+const distribution_1 = require("../ci/distribution");
 const localDashboard_1 = require("../security/localDashboard");
-const projectPaths_1 = require("../utils/projectPaths");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const http = __importStar(require("http"));
@@ -50,6 +52,7 @@ class FlowOrchestrator {
     worker;
     workerCount;
     config;
+    static nativeBrowserProtocol = 2;
     static nativeCIProtocol = 1;
     nativeEventProtocol = 1;
     wss = null;
@@ -58,6 +61,9 @@ class FlowOrchestrator {
     stepStatusRegistry = new Map();
     pdfGenerator;
     disconnectTimer = null;
+    dashboardBrowser = new dashboard_1.DashboardBrowser();
+    closing = false;
+    browserInfoByFile = new Map();
     constructor(worker, workerCount = 1, config) {
         this.worker = worker;
         this.workerCount = workerCount;
@@ -68,6 +74,10 @@ class FlowOrchestrator {
         });
     }
     forwardToDashboard(type, payload) {
+        if (type === 'BROWSER_INFO')
+            this.browserInfoByFile.set(payload.fileName, payload);
+        if (type === 'SUITE_START')
+            this.browserInfoByFile.clear();
         this.config?.onRunEvent?.({ type, payload });
         if (this.wss) {
             this.wss.clients.forEach((client) => {
@@ -78,7 +88,7 @@ class FlowOrchestrator {
     }
     async executeTestRun(targetPath) {
         this.forwardToDashboard("SUITE_START", {});
-        const filesToProcess = (0, projectPaths_1.discoverFlows)(targetPath);
+        const filesToProcess = (0, distribution_1.executionPlan)(targetPath, this.config).files;
         if (this.config)
             this.config.flowRoot = fs.statSync(targetPath).isDirectory() ? targetPath : path.dirname(targetPath);
         this.globalTestScenarios = [];
@@ -115,6 +125,8 @@ class FlowOrchestrator {
                     return;
                 }
                 res.setHeader('Cross-Origin-Resource-Policy', 'same-origin');
+                if ((0, evidence_1.serveDOMSnapshot)(req, res, this.config))
+                    return;
                 if (req.url && req.url.startsWith("/videos/")) {
                     let urlObj;
                     try {
@@ -229,6 +241,8 @@ class FlowOrchestrator {
             });
             this.wss = new ws_1.WebSocketServer({ server: this.httpServer, verifyClient: (info) => Boolean(info.origin) && (0, localDashboard_1.isLocalDashboardRequest)(info.req.headers.host, info.origin) });
             this.wss.on("connection", (ws) => {
+                for (const payload of this.browserInfoByFile.values())
+                    ws.send(JSON.stringify({ type: 'BROWSER_INFO', payload }));
                 if (this.disconnectTimer) {
                     clearTimeout(this.disconnectTimer);
                     this.disconnectTimer = null;
@@ -267,7 +281,7 @@ class FlowOrchestrator {
                     }
                 });
                 ws.on("close", () => {
-                    if (this.wss && this.wss.clients.size === 0) {
+                    if (!this.closing && this.wss && this.wss.clients.size === 0) {
                         this.disconnectTimer = setTimeout(async () => {
                             console.log(chalk_1.default.yellow("\n[Flowstride]: Dashboard disconnected. Shutting down framework..."));
                             this.worker.abort();
@@ -300,8 +314,8 @@ class FlowOrchestrator {
                             !!process.env.GITHUB_ACTIONS ||
                             !!process.env.FLOWSTRIDE_API_KEY;
                         if (!isStrictHeadless) {
-                            const { default: open } = await import("open");
-                            await open(localUrl);
+                            await this.dashboardBrowser.open(localUrl, this.config?.browser);
+                            console.log(`[Dashboard]: ${this.config?.browser === 'firefox' || this.config?.browser === 'webkit' ? this.config.browser : 'system default'} dashboard window; test browser reported after launch${this.config?.headless ? ' (headless tests)' : ''}.`);
                             console.log(chalk_1.default.yellow("[Dashboard]: Waiting for UI connection..."));
                             while (this.wss.clients.size === 0)
                                 await new Promise((r) => setTimeout(r, 250));
@@ -314,6 +328,7 @@ class FlowOrchestrator {
                         resolve(result);
                     }
                     catch (err) {
+                        await this.dashboardBrowser.close();
                         reject(err);
                     }
                 });
@@ -327,6 +342,8 @@ class FlowOrchestrator {
         this.worker.abort();
     }
     async close() {
+        this.closing = true;
+        await this.dashboardBrowser.close();
         if (this.disconnectTimer)
             clearTimeout(this.disconnectTimer);
         this.wss?.clients.forEach(client => client.terminate());

package/dist/runner/flow_worker.d.ts

@@ -19,10 +19,16 @@ export declare class FlowWorker extends EventEmitter {
     private store;
     private sessions;
     private pluginManager?;
+    static readonly nativeBrowserProtocol = 2;
     private isSilent;
     private isAborted;
     private bailTriggered;
     private isDebugHalted;
+    private native;
+    private attempt;
+    private maxAttempts;
+    private fallbackStream?;
+    private interceptedContexts;
     private currentStepContext;
     private currentFileName;
     private activeAudioPath;
@@ -46,6 +52,7 @@ export declare class FlowWorker extends EventEmitter {
     handleReplayRequest(payload: any): Promise<void>;
     abort(): void;
     runBatch(filesToProcess: string[]): Promise<void>;
+    private runScenarioWithRetries;
     private runScenario;
     private waitForPipeline;
     private executeStep;

package/dist/runner/flow_worker.js

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FlowWorker = void 0;
+const runtime_1 = require("../native/runtime");
 const deadline_1 = require("../ci/deadline");
 const replayRequest_1 = require("../utils/replayRequest");
 const projectPaths_1 = require("../utils/projectPaths");
@@ -57,10 +58,16 @@ class FlowWorker extends events_1.EventEmitter {
     store;
     sessions;
     pluginManager;
+    static nativeBrowserProtocol = 2;
     isSilent = process.env.FLOWSTRIDE_PARALLEL === "true";
     isAborted = false;
     bailTriggered = false;
     isDebugHalted = false;
+    native;
+    attempt = 1;
+    maxAttempts = 1;
+    fallbackStream;
+    interceptedContexts = new WeakSet();
     currentStepContext = "Initializing...";
     currentFileName = "System";
     activeAudioPath = undefined;
@@ -79,8 +86,12 @@ class FlowWorker extends events_1.EventEmitter {
         this.store = store;
         this.sessions = sessions;
         this.pluginManager = pluginManager;
+        this.native = new runtime_1.NativeRuntime(web, config);
+        this.web.onPageChanged = async () => { await this.startStreaming(); await this.setupNetworkInterception(); };
     }
     broadcast(type, payload) {
+        if (["STEP_ADD", "STEP_UPDATE", "LOG_EVENT"].includes(type))
+            payload = { ...payload, attempt: this.attempt, profile: this.web.activeProfile || "default" };
         const secrets = [this.config.machineToken || '', ...(this.dataGen?.sensitiveValues?.() || []), ...Object.entries(process.env).filter(([key]) => /password|token|secret|api.?key/i.test(key)).map(([, value]) => String(value)), ...Object.entries(this.localVariables).filter(([key]) => /password|passcode|token|secret|otp|api.?key/i.test(key)).map(([, value]) => String(value))];
         this.emit('worker_event', { type, payload: (0, redaction_1.redactWorkerPayload)(type, payload, secrets, this.config.ci === false) });
     }
@@ -394,7 +405,13 @@ class FlowWorker extends events_1.EventEmitter {
                     this.localBrowserSessions = {};
                     this.api.resetState();
                     this.dataGen = new data_generators_1.DataGenerators();
+                    await this.native.dispose();
                     await this.web.initialise(this.activeAudioPath);
+                    if (typeof this.web.getBrowserInfo === 'function') {
+                        const browser = this.web.getBrowserInfo();
+                        console.log(`[Browser]: ${browser.engine} ${browser.version}; ${browser.headless ? 'headless' : 'headed'}; ${fileName}`);
+                        this.broadcast('BROWSER_INFO', { ...browser, fileName });
+                    }
                     await this.startStreaming();
                     await this.setupNetworkInterception();
                     const content = fs.readFileSync(filePath, "utf8");
@@ -453,7 +470,7 @@ class FlowWorker extends events_1.EventEmitter {
                                 scenarioName: s.name,
                                 fileName: this.currentFileName,
                             });
-                            await this.runScenario(s, f.declarations);
+                            await this.runScenarioWithRetries(s, f.declarations);
                             if (this.isDebugHalted || this.bailTriggered)
                                 break;
                             await this.web
@@ -482,6 +499,7 @@ class FlowWorker extends events_1.EventEmitter {
                         const targetVideoPath = path.join(mockCloudDir, `${baseName}.webm`);
                         for (const message of this.web.pageErrors || [])
                             this.broadcast('BROWSER_ERROR', { message, fileName: this.currentFileName });
+                        await this.native.dispose();
                         await this.web.shutdown(targetVideoPath);
                         if (!this.isSilent)
                             console.log(chalk_1.default.gray(`      [Cloud Sync]: Video safely encoded and preserved for ${this.currentFileName}`));
@@ -505,6 +523,7 @@ class FlowWorker extends events_1.EventEmitter {
                         const targetVideoPath = path.join(mockCloudDir, `${baseName}.webm`);
                         for (const message of this.web.pageErrors || [])
                             this.broadcast('BROWSER_ERROR', { message, fileName: this.currentFileName });
+                        await this.native.dispose();
                         await this.web.shutdown(targetVideoPath);
                         if (!this.isSilent)
                             console.log(chalk_1.default.gray(`      [Cloud Sync]: Video safely encoded and preserved for ${this.currentFileName}`));
@@ -531,6 +550,7 @@ class FlowWorker extends events_1.EventEmitter {
                 try {
                     const directory = path.join(process.cwd(), '.flowstride', 'artifacts');
                     fs.mkdirSync(directory, { recursive: true });
+                    await this.native.dispose();
                     await this.web.shutdown(path.join(directory, (0, projectPaths_1.videoFileName)(this.currentFileName)));
                 }
                 catch (error) {
@@ -540,9 +560,52 @@ class FlowWorker extends events_1.EventEmitter {
             process.removeListener("SIGINT", sigintHandler);
         }
     }
+    async runScenarioWithRetries(scenario, declarations) {
+        this.maxAttempts = (this.config.retries || 0) + 1;
+        const baseline = this.maxAttempts > 1 ? await this.web.checkpointProfiles() : undefined;
+        const variables = this.maxAttempts > 1 ? structuredClone(this.localVariables) : {}, sessions = this.maxAttempts > 1 ? structuredClone(this.localBrowserSessions) : {};
+        const globals = this.maxAttempts > 1 ? structuredClone(FlowWorker.globalVariables) : {}, globalSessions = this.maxAttempts > 1 ? structuredClone(FlowWorker.globalBrowserSessions) : {};
+        const storeState = this.maxAttempts > 1 ? structuredClone(this.store.getAll?.()) : undefined;
+        const apiState = this.maxAttempts > 1 ? this.api.checkpointState?.() : undefined;
+        for (this.attempt = 1; this.attempt <= this.maxAttempts; this.attempt++) {
+            if (this.isAborted || this.isDebugHalted)
+                break;
+            if (this.attempt > 1) {
+                await this.native.dispose();
+                if (apiState)
+                    this.api.restoreState(apiState);
+                else
+                    this.api.resetState();
+                this.localVariables = structuredClone(variables);
+                this.localBrowserSessions = structuredClone(sessions);
+                FlowWorker.globalVariables = structuredClone(globals);
+                FlowWorker.globalBrowserSessions = structuredClone(globalSessions);
+                if (storeState) {
+                    this.store.clear();
+                    for (const [key, value] of Object.entries(structuredClone(storeState)))
+                        this.store.set(key, value);
+                }
+                await this.web.restoreProfiles(baseline);
+            }
+            const started = Date.now();
+            this.broadcast('SCENARIO_ATTEMPT', { fileName: this.currentFileName, scenario: scenario.name, attempt: this.attempt });
+            const errorIndex = this.web.pageErrors?.length || 0;
+            const completed = await this.runScenario(structuredClone(scenario), declarations);
+            const browserErrors = this.web.pageErrors?.slice(errorIndex) || [];
+            const passed = completed && (this.config.browserErrors === 'record' || !browserErrors.length);
+            this.broadcast('SCENARIO_RESULT', { fileName: this.currentFileName, scenario: scenario.name, attempt: this.attempt, status: this.isAborted ? 'interrupted' : passed ? 'passed' : 'failed', flaky: passed && this.attempt > 1, browserErrors, duration: Date.now() - started });
+            if (passed || this.isAborted || this.isDebugHalted)
+                break;
+            if (this.attempt < this.maxAttempts)
+                this.web.pageErrors?.splice(errorIndex);
+        }
+        this.attempt = 1;
+        this.maxAttempts = 1;
+    }
     async runScenario(scenario, globalDeclarations = []) {
         let hasScenarioFailed = false;
-        for (const step of scenario.steps) {
+        for (const originalStep of scenario.steps) {
+            const step = structuredClone(originalStep);
             if (this.isAborted)
                 break;
             const blockName = step.blockDescription.split(" ")[0];
@@ -597,11 +660,13 @@ class FlowWorker extends events_1.EventEmitter {
             try {
                 await this.executeStep(step.action, step.payload, scenario.declarations, globalDeclarations);
                 const stepContext = await this.captureStepContext(step.payload);
+                const domSnapshot = await this.native.captureDOM(step.id).catch(() => undefined);
                 spinner.succeed();
                 this.broadcast("STEP_UPDATE", {
                     id: step.id,
                     status: "passed",
                     screenshot: stepContext.screenshot,
+                    domSnapshot,
                     fileName: this.currentFileName,
                 });
                 if (step.isStop) {
@@ -616,6 +681,7 @@ class FlowWorker extends events_1.EventEmitter {
                 if (this.isAborted)
                     break;
                 const stepContext = await this.captureStepContext(step.payload);
+                const domSnapshot = await this.native.captureDOM(step.id).catch(() => undefined);
                 let strippedDom = "";
                 try {
                     const page = this.web.getPage();
@@ -637,6 +703,7 @@ class FlowWorker extends events_1.EventEmitter {
                         id: step.id,
                         status: "skipped",
                         screenshot: stepContext.screenshot,
+                        domSnapshot,
                         fileName: this.currentFileName,
                     });
                     continue;
@@ -684,15 +751,17 @@ class FlowWorker extends events_1.EventEmitter {
                     id: step.id,
                     status: "failed",
                     screenshot: stepContext.screenshot,
+                    domSnapshot,
                     fileName: this.currentFileName,
                 });
                 hasScenarioFailed = true;
-                if (this.config.bail && !this.bailTriggered) {
+                if (this.config.bail && this.attempt >= this.maxAttempts && !this.bailTriggered) {
                     this.bailTriggered = true;
                     this.broadcast('BAIL', { fileName: this.currentFileName, id: step.id });
                 }
             }
         }
+        return !hasScenarioFailed;
     }
     async waitForPipeline() {
         if (!this.activeAudioPath || !fs.existsSync(this.activeAudioPath)) {
@@ -739,6 +808,12 @@ class FlowWorker extends events_1.EventEmitter {
             ].join(", ");
         }
         switch (action) {
+            case 'native': {
+                const result = await (0, deadline_1.withDeadline)(this.native.execute(payload.pluginMethod, payload.data), this.config.timeout);
+                if (payload.saveAs)
+                    this.localVariables[payload.saveAs] = result;
+                break;
+            }
             case "extract":
                 if (["resBody", "resHeader", "cookie"].includes(payload.target)) {
                     this.processExtractions([
@@ -1181,6 +1256,9 @@ class FlowWorker extends events_1.EventEmitter {
     }
     async setupNetworkInterception() {
         const context = this.web.getPage().context();
+        if (this.interceptedContexts.has(context))
+            return;
+        this.interceptedContexts.add(context);
         context.on("response", async (response) => {
             const lockedFileName = this.currentFileName;
             const request = response.request();
@@ -1239,8 +1317,27 @@ class FlowWorker extends events_1.EventEmitter {
         });
     }
     async startStreaming() {
+        clearInterval(this.fallbackStream);
         if (this.config.ci)
             return;
+        if (this.config.browser && this.config.browser !== 'chromium') {
+            const page = this.web.getPage();
+            let busy = false;
+            this.fallbackStream = setInterval(async () => {
+                if (busy || page.isClosed())
+                    return;
+                busy = true;
+                try {
+                    this.broadcast('BROWSER_FRAME', { base64: (await page.screenshot({ type: 'jpeg', quality: 60 })).toString('base64'), fileName: this.currentFileName });
+                }
+                catch { }
+                finally {
+                    busy = false;
+                }
+            }, 250);
+            this.fallbackStream.unref();
+            return;
+        }
         const page = this.web.getPage();
         if (this.currentCdpSession) {
             await this.currentCdpSession.detach().catch(() => { });
@@ -1261,6 +1358,8 @@ class FlowWorker extends events_1.EventEmitter {
         });
     }
     async shutdown() {
+        clearInterval(this.fallbackStream);
+        await this.native.dispose();
         try {
             await this.web.shutdown();
         }

package/dist/types/index.d.ts

@@ -1,4 +1,14 @@
 export interface FlowstrideConfig {
+    browser?: 'chromium' | 'firefox' | 'webkit';
+    browserOptions?: import('playwright').BrowserContextOptions;
+    retries?: number;
+    failOnFlaky?: boolean;
+    trace?: boolean;
+    har?: boolean;
+    domSnapshots?: boolean;
+    shard?: string;
+    shardHistory?: string;
+    updateBaselines?: boolean;
     ci?: boolean;
     flowRoot?: string;
     projectRoot?: string;