flowstride 1.0.19 → 1.0.20-rc.6

package/NATIVE_CI.md

@@ -0,0 +1,179 @@
+# Native CI and browser-game candidate
+
+This candidate adds native CI and game APIs to both engines. Managed Cloud
+execution remains retired. Existing npm OSS / private Pro archive distribution
+and fallback remain supported. Consumer project migrations are managed separately. Native CI uses protocol 1.
+The public CLI selects compatible Pro engines or logs the reason and falls back
+to OSS. Older Pro CLIs may own the npm binary and do not understand the new
+commands; install both candidates when testing the Pro path.
+
+The candidates pin Playwright 1.59.1 in both engines; the native install command
+installs that engine's matching Chromium.
+
+## Local candidate check
+
+Use a disposable project first. Install the OSS archive, then the Pro archive if
+needed. Both candidates must be installed for testing the new Pro path. The
+currently hosted Cloud download still serves the existing release; this local
+candidate does not change that endpoint or its archive.
+
+```sh
+npm install --save-dev /absolute/path/flowstride-1.0.20-rc.6.tgz
+# Optional: install the local matching Pro candidate after project dependencies.
+npm install --no-save /absolute/path/flowstride-pro-1.0.15-rc.5.tgz
+npx --no-install flowstride install
+npx --no-install flowstride run --ci
+```
+
+Pro continues to require your normal valid developer credentials for licensed
+features. Installing Pro uses `--no-save`: another `npm ci` can remove it. Keep
+project dependency installation before Pro installation. An installed Pro package
+can own `node_modules/.bin/flowstride`; both that entry point and the public OSS
+entry point must be covered when checking fallback.
+
+The sample in `examples/native-game` uses a tiny local canvas game. Copy its
+files into a disposable project containing the installed candidates, then run
+the command above. `server.mjs` is the game fixture's HTTP server; it contains no
+Flowstride runner, adapter, worker, or CI orchestration code. A real application
+uses its normal development/start command instead.
+
+## Configuration
+
+`flowstride.config.json` supports `testDir`, `baseUrl`, `timeout`, `device`
+(`desktop`, `phone`, `landscape`), optional `viewport`, `pluginsDir`,
+`artifactsDir`, `recordVideo` (boolean), `browserErrors` (`fail` or `record`), and
+`webServer` (`command`, local readiness `url`, optional `cwd` and `timeout`).
+Malformed configuration and unsafe output paths fail before execution.
+
+Native CI is selected by `--ci` or a recognized CI environment. It runs without
+a dashboard server, returns nonzero for failed/incomplete/crashed execution,
+and writes latest `summary.json`/`junit.xml` reports at the configured artifact
+root. Media and attachments go into a unique run directory referenced by the
+summary, so local reruns retain history without mixing evidence.
+SIGINT/SIGTERM produce interrupted results. The run owns its optional local
+server and refuses an already-serving readiness URL.
+
+Cloud reporting is off by default in native CI. `cloudSync: true` explicitly
+allows existing authenticated reporting; matching Cloud deployment and configured media storage are required. Reporting and
+video status are written separately in the summary and `.flowstride/cloud-sync.json`;
+a reporting failure does not turn a passed test into a failed test. Normal interactive reporting and the restored
+Cloud URL overrides remain separate from retired managed execution.
+
+`npx flowstride ci init github` generates a workflow explicitly, never during
+installation, and refuses to overwrite it. It assumes an npm project with a
+committed lockfile. Other package managers and monorepos can use the composite
+action's install-command and working-directory inputs. The composite action is
+in the OSS repository's `action/` directory and becomes remotely usable only
+once that source is pushed. Pin its commit when configuring a consumer workflow.
+Pro jobs pass a developer token as a secret; dependency installation precedes
+Pro login/install, matching-browser installation, execution, and artifact upload.
+
+## Native game actions
+
+Register the built-in alias with `let game = "flowstride:game"`. It requires no
+custom plugin file. Available actions:
+
+- `tap`: canvas selector, x/y; relative coordinates by default, or `unit: "pixels"`.
+- `drag`/`swipe`: canvas, from/to coordinates, optional duration and input type.
+- `key`: key name and optional hold duration.
+- `checkpoint`: named screenshot, optionally of one canvas.
+- `snapshot` and `expectVisual`: canvas comparison with explicit minChange/maxChange.
+- `state`/`expectState`: exposed state, optional dotted path and expected equals.
+- `snapshotState`/`expectPreserved`: compare selected state across actions/reloads.
+- `fixture`: a named fixture registered by the application in explicit test mode.
+- `select`: a stable object ID resolved by the game bridge, then real pointer input.
+
+Visual checks establish pixel differences, not gameplay correctness; pair them
+with state or UI assertions. Mobile profiles emulate Chromium devices, not
+physical phones. Touch dragging currently uses Chromium CDP.
+
+For a generic browser game, import `registerGame` from
+`flowstride/dist/game/bridge.js` and supply readState and optional test-only
+fixtures. The function manages the browser bridge; no global setup is required
+in the test runner.
+
+## Three.js integration
+
+Import `registerThreeGame` from `flowstride/dist/game/three-bridge.js` in the game
+bundle. Register the live scene, camera, canvas, the application's own Vector3
+and Raycaster constructors, and an optional objects map keyed by stable IDs.
+Alternatively, assign `userData.flowstrideId` to scene objects. Optional local
+pick points use `userData.flowstridePickPoint: [x, y, z]`.
+
+The bridge projects the live object and raycasts the live scene; hidden,
+occluded, off-screen, covered or non-pickable objects fail explicitly. It creates
+no renderer or animation loop. Dispose the bridge when the scene is replaced.
+
+Optional `readState` provides observable state. `fixtures` are available only
+when the application explicitly registers with `testMode: true`; use that
+setting in dedicated test builds, never public production builds. Naija Throne
+still defines campaign-specific fixtures/rules, using these supported APIs.
+
+Custom plugins now receive `sdk.game`, `sdk.browser.page()`, and `sdk.run`
+(device, artifact directory and attach method), alongside the existing SDK.
+They need no global bridge or internal Flowstride class imports.
+
+## Validation before release
+
+Build both packages and run `npm run test:native`. For the optional live Three.js
+fixture set `FLOWSTRIDE_THREE_BUILD` to a Three.js build directory containing
+three.module.js and three.core.js. OSS CLI handoff tests use
+`FLOWSTRIDE_PRO_SOURCE` pointing at the built Pro package.
+
+Run the real archive install/handoff harness against both candidates, including
+missing/broken Pro and revoked-token fallback. Validate GitHub's Linux execution,
+real licensed download after local acceptance.
+No push, npm publication, Cloud archive replacement or Naija Throne migration
+is performed by building these candidates.
+
+## Combined candidate behavior
+
+Node.js 22.12 or newer is required. Flow discovery is recursive; `.first.flow`
+files run before ordinary files. Reports identify nested flows by their relative
+paths, and same-named videos receive distinct filenames. A failed scenario skips
+its remaining steps and continues to later scenarios. `--bail` stops later work;
+Pro executes bail runs sequentially. `only.Scenario:` selects that file's focus
+scenario and report planning uses the same selection.
+
+Configuration, plugin, environment, upload, vault and output paths must stay
+inside the project, including resolved symlinks. Move shared fixtures into the
+project rather than referring to external files. `FLOWSTRIDE_API_URL` takes
+precedence over `NEXTJS_WEBHOOK_URL`; the legacy completion suffix is normalized.
+Managed runner commands remain retired.
+
+Logs redact credential fields, known generated secrets and signed capabilities.
+Redaction cannot guarantee removal of arbitrary application data or visible
+secrets in screenshots/videos. Review artifact access and test data accordingly.
+
+The Pro installer rejects unsafe or incomplete archives, downloads above 32 MiB,
+and checksum mismatches. Older Cloud servers without checksum headers remain
+compatible and emit a warning; `FLOWSTRIDE_PRO_SHA256` can pin an expected digest.
+On failed npm installation the previous Pro directory and CLI launchers are
+restored. This is not a transaction over every project dependency npm may alter;
+use a disposable project for candidate acceptance.
+
+## Dashboard tab history
+
+Completed test tabs restore that file's last captured step by default. Selecting
+an earlier step remembers its history cursor separately for each file. A sidebar
+step also selects the owning tab. Return to Live applies only to the selected
+file, and a new suite/rerun clears old cursors and screens. Runner console and
+network panels show the selected file's records; the full Logs view retains
+suite-wide history. Flows/steps without screenshots show an explicit empty
+state rather than another flow's screen.
+
+Run `npm run test:dashboard:unit` for the Zustand store/history unit tests and
+`npm run test:dashboard` for those tests plus the real Chromium dashboard
+regression. The browser regression runs real local browser flows, then replays
+their worker events over WebSocket into the built dashboard. It also supplies
+explicit API-only/background-event fixtures. No live Cloud is required.
+
+### Local cURL debugging
+
+The interactive local dashboard keeps its cURL preview [REDACTED]. Copy raw cURL
+uses the original request held separately in local memory, including its headers
+and body. Other log fields stay redacted. Native CI and Cloud reporting continue redacting cURL and
+credentials. Raw cURL is not restored for already-redacted historical runs.
+The interactive runner binds to 127.0.0.1 and restricts HTTP Host/Origin and
+WebSocket Origin to its own loopback address and port. Raw commands remain in
+local debugger memory and IPC; they are not written to CI or Cloud reports.

package/dist/adapters/web/playwright.d.ts

@@ -2,6 +2,7 @@ import { Page } from "playwright";
 import { FlowstrideConfig } from "../../types";
 export declare class WebAdapter {
     private config;
+    pageErrors: string[];
     private browser;
     private context;
     private page;

package/dist/adapters/web/playwright.js

@@ -37,6 +37,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebAdapter = void 0;
+const projectPaths_1 = require("../../utils/projectPaths");
+const playwright_1 = require("playwright");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const playwright_extra_1 = require("playwright-extra");
@@ -44,6 +46,7 @@ const puppeteer_extra_plugin_stealth_1 = __importDefault(require("puppeteer-extr
 playwright_extra_1.chromium.use((0, puppeteer_extra_plugin_stealth_1.default)());
 class WebAdapter {
     config;
+    pageErrors = [];
     browser = null;
     context = null;
     page = null;
@@ -75,20 +78,23 @@ class WebAdapter {
         }
         this.browser = await playwright_extra_1.chromium.launch({
             headless: this.config.headless,
+            // Native CI finalizes videos before closing the browser on cancellation.
+            ...(this.config.ci ? { handleSIGINT: false, handleSIGTERM: false } : {}),
             args: launchArgs,
         });
-        const videoDir = path.join(process.cwd(), ".flowstride", "videos");
+        const videoDir = (0, projectPaths_1.projectPath)(process.cwd(), path.join('.flowstride', 'videos'));
         if (!fs.existsSync(videoDir))
             fs.mkdirSync(videoDir, { recursive: true });
-        const customUserAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
+        const profile = this.config.device === 'phone' || this.config.device === 'landscape'
+            ? { ...playwright_1.devices['Pixel 7'], viewport: this.config.device === 'landscape' ? { width: 844, height: 390 } : { width: 390, height: 844 } }
+            : { viewport: { width: 1280, height: 800 }, userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36' };
+        const viewport = this.config.viewport || profile.viewport;
         this.context = await this.browser.newContext({
-            viewport: null,
-            userAgent: customUserAgent,
-            recordVideo: {
-                dir: videoDir,
-                size: { width: 1280, height: 800 },
-            },
+            ...profile, viewport,
+            ...(this.config.recordVideo === false ? {} : { recordVideo: { dir: videoDir, size: viewport } }),
         });
+        this.pageErrors = [];
+        this.context.on('page', page => page.on('pageerror', error => this.pageErrors.push(error.message)));
         this.context.on("dialog", async (dialog) => {
             if (this.dialogHandler) {
                 await this.dialogHandler(dialog);
@@ -120,7 +126,7 @@ class WebAdapter {
         };
     }
     async injectAudio(filePath) {
-        const absolutePath = path.resolve(process.cwd(), filePath);
+        const absolutePath = (0, projectPaths_1.projectPath)(process.cwd(), filePath);
         if (!fs.existsSync(absolutePath)) {
             throw new Error(`Audio file not found at: ${absolutePath}`);
         }
@@ -269,7 +275,8 @@ class WebAdapter {
         });
     }
     synthesizeCurl(method, url, headers, postData) {
-        let curl = `curl -X ${method.toUpperCase()} '${url}'`;
+        const safeUrl = url.replace(/'/g, "'\\''");
+        let curl = `curl -X ${method.toUpperCase()} '${safeUrl}'`;
         for (const [key, value] of Object.entries(headers)) {
             if (key.startsWith(":"))
                 continue;
@@ -479,10 +486,10 @@ class WebAdapter {
             await targetLoc.evaluate((node) => node.blur());
             let actualValue = "";
             try {
-                actualValue = await targetLoc.inputValue({ timeout: 500 });
+                actualValue = await targetLoc.inputValue({ timeout: this.config.timeout });
             }
             catch {
-                actualValue = (await targetLoc.textContent({ timeout: 500 })) || "";
+                actualValue = (await targetLoc.textContent({ timeout: this.config.timeout })) || "";
             }
             const cleanActual = actualValue.replace(/[^a-zA-Z0-9]/g, "");
             const cleanExpected = value.replace(/[^a-zA-Z0-9]/g, "");
@@ -609,16 +616,15 @@ class WebAdapter {
         const targetLoc = await this.checkAmbiguity(loc, selector);
         await targetLoc.waitFor({ state: "visible" });
         await targetLoc.scrollIntoViewIfNeeded();
-        const absolutePath = path.resolve(process.cwd(), filePath);
+        const absolutePath = (0, projectPaths_1.projectPath)(process.cwd(), filePath);
         if (!fs.existsSync(absolutePath)) {
             throw new Error(`File Upload Error: Could not find the file at "${absolutePath}". Please ensure the file exists in your project directory.`);
         }
         try {
-            const fileChooserPromise = this.page.waitForEvent("filechooser", {
-                timeout: 5000,
-            });
-            await targetLoc.click();
-            const fileChooser = await fileChooserPromise;
+            const [fileChooser] = await Promise.all([
+                this.page.waitForEvent('filechooser', { timeout: this.config.timeout }),
+                targetLoc.click({ timeout: this.config.timeout }),
+            ]);
             await fileChooser.setFiles(absolutePath);
         }
         catch (e) {

package/dist/ci/config.d.ts

@@ -0,0 +1,3 @@
+import type { FlowstrideConfig } from '../types';
+export declare function isCIEnvironment(): boolean;
+export declare function loadNativeConfig(root: string, options: Record<string, any>): FlowstrideConfig;

package/dist/ci/config.js

@@ -0,0 +1,77 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCIEnvironment = isCIEnvironment;
+exports.loadNativeConfig = loadNativeConfig;
+const projectPaths_1 = require("../utils/projectPaths");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+function isCIEnvironment() {
+    return ['FLOWSTRIDE_NATIVE_CI', 'CI', 'GITHUB_ACTIONS', 'GITLAB_CI', 'CIRCLECI', 'JENKINS_URL', 'FLOWSTRIDE_API_KEY']
+        .some(key => !!process.env[key] && process.env[key] !== 'false' && process.env[key] !== '0');
+}
+function loadNativeConfig(root, options) {
+    const file = (0, projectPaths_1.projectPath)(root, options.config || 'flowstride.config.json');
+    let input = {};
+    if (node_fs_1.default.existsSync(file)) {
+        input = JSON.parse(node_fs_1.default.readFileSync(file, 'utf8'));
+        if (!input || typeof input !== 'object' || Array.isArray(input))
+            throw new Error('Flowstride configuration must be an object.');
+    }
+    else if (options.config)
+        throw new Error(`Configuration not found: ${file}`);
+    const config = { ...input, projectRoot: node_path_1.default.resolve(root), timeout: input.timeout ?? 30000, headless: input.headless ?? true,
+        ci: !!options.ci || isCIEnvironment(), bail: options.bail || input.bail || false, device: options.device ?? input.device ?? 'desktop',
+        artifactsDir: input.artifactsDir ?? 'flowstride-artifacts', testDir: input.testDir ?? 'flows',
+        defaultDialogBehavior: input.defaultDialogBehavior ?? 'dismiss',
+        recordVideo: input.recordVideo ?? true, browserErrors: input.browserErrors ?? 'fail',
+        isCloudSyncActive: options.isCloudSyncActive ?? false, machineToken: options.machineToken ?? null,
+        workspaceId: options.workspaceId ?? null, manifest: options.manifest ?? null };
+    if (config.ci && input.cloudSync !== true)
+        config.isCloudSyncActive = false;
+    if (options.headless || config.ci)
+        config.headless = true;
+    else if (options.headed)
+        config.headless = false;
+    if (process.env.BASE_URL)
+        config.baseUrl = process.env.BASE_URL;
+    if (!Number.isSafeInteger(config.timeout) || config.timeout < 1)
+        throw new Error('timeout must be a positive integer.');
+    if (!['desktop', 'phone', 'landscape'].includes(config.device))
+        throw new Error('device must be desktop, phone, or landscape.');
+    for (const key of ['headless', 'recordVideo', 'bail'])
+        if (config[key] !== undefined && typeof config[key] !== 'boolean')
+            throw new Error(`${key} must be boolean.`);
+    if (!['fail', 'record'].includes(config.browserErrors))
+        throw new Error('browserErrors must be fail or record.');
+    for (const key of ['artifactsDir', 'testDir', 'pluginsDir']) {
+        if (config[key] === undefined)
+            continue;
+        if (typeof config[key] !== 'string' || !config[key].trim())
+            throw new Error(`${key} must be a nonempty path.`);
+        const resolved = (0, projectPaths_1.projectPath)(root, config[key]);
+        const relative = node_path_1.default.relative(root, resolved);
+        if ((key === 'artifactsDir' && !relative) || relative === '..' || relative.startsWith(`..${node_path_1.default.sep}`) || node_path_1.default.isAbsolute(relative))
+            throw new Error(`${key} must be a directory inside the project.`);
+        config[key] = resolved;
+    }
+    if (config.viewport && (!Number.isSafeInteger(config.viewport.width) || config.viewport.width < 1 || !Number.isSafeInteger(config.viewport.height) || config.viewport.height < 1))
+        throw new Error('viewport requires positive integer width and height.');
+    if (config.webServer) {
+        const server = config.webServer;
+        if (typeof server.command !== 'string' || !server.command.trim() || typeof server.url !== 'string')
+            throw new Error('webServer requires command and url.');
+        const url = new URL(server.url);
+        if (!['http:', 'https:'].includes(url.protocol) || !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))
+            throw new Error('webServer readiness URL must use local HTTP(S).');
+        if (server.timeout !== undefined && (!Number.isSafeInteger(server.timeout) || server.timeout < 1))
+            throw new Error('webServer.timeout must be positive.');
+        server.cwd = (0, projectPaths_1.projectPath)(root, server.cwd || '.');
+        const relative = node_path_1.default.relative(root, server.cwd);
+        if (relative === '..' || relative.startsWith(`..${node_path_1.default.sep}`) || node_path_1.default.isAbsolute(relative))
+            throw new Error('webServer.cwd must be inside the project.');
+    }
+    return config;
+}

package/dist/ci/deadline.d.ts

@@ -0,0 +1,2 @@
+/** Bound asynchronous plugin work while observing late rejections safely. */
+export declare function withDeadline<T>(operation: Promise<T> | T, timeout: number): Promise<T>;

package/dist/ci/deadline.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withDeadline = withDeadline;
+/** Bound asynchronous plugin work while observing late rejections safely. */
+async function withDeadline(operation, timeout) {
+    let timer;
+    try {
+        return await Promise.race([Promise.resolve(operation), new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error(`Flowstride step exceeded its ${timeout}ms timeout.`)), timeout);
+            })]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/ci/init.d.ts

@@ -0,0 +1 @@
+export declare function initCI(provider: string): void;

package/dist/ci/init.js

@@ -0,0 +1,21 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initCI = initCI;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const config_1 = require("./config");
+function initCI(provider) {
+    if (provider !== 'github')
+        throw new Error('Supported provider: github.');
+    const file = node_path_1.default.resolve('.github/workflows/flowstride.yml');
+    if (node_fs_1.default.existsSync(file))
+        throw new Error('Flowstride workflow already exists; it was not overwritten.');
+    const artifacts = node_path_1.default.relative(process.cwd(), (0, config_1.loadNativeConfig)(process.cwd(), {}).artifactsDir);
+    const parent = node_path_1.default.dirname(file);
+    node_fs_1.default.mkdirSync(parent, { recursive: true });
+    node_fs_1.default.writeFileSync(file, `name: Flowstride\non:\n  push:\n  pull_request:\n  workflow_dispatch:\npermissions:\n  contents: read\njobs:\n  test:\n    runs-on: ubuntu-latest\n    timeout-minutes: 20\n    steps:\n      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262\n        with:\n          persist-credentials: false\n      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020\n        with:\n          node-version: 24\n          cache: npm\n      - run: npm ci\n      - name: Install matching browser dependencies\n        run: npx --no-install flowstride install --with-deps\n      - name: Run native Flowstride\n        run: npx --no-install flowstride run --ci\n      - name: Retain test evidence\n        if: always()\n        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02\n        with:\n          name: flowstride-results\n          path: ${JSON.stringify(artifacts + "/")}\n          retention-days: 14\n`, { flag: 'wx' });
+    console.log(`Created ${file}. Commit it when ready. This template uses the project-locked Flowstride installation.`);
+}

package/dist/ci/runtime.d.ts

@@ -0,0 +1,19 @@
+import type { FlowstrideConfig } from '../types';
+export interface NativeRunResult {
+    protocol: 1;
+    engine: string;
+    status: 'passed' | 'failed' | 'interrupted';
+    duration: number;
+    artifactsDir: string;
+    files: string[];
+    steps: any[];
+    errors: string[];
+    metrics: {
+        total: number;
+        passed: number;
+        failed: number;
+        skipped: number;
+        incomplete: number;
+    };
+}
+export declare function runNativeCI(worker: any, orchestrator: any, target: string, config: FlowstrideConfig, engine: string): Promise<NativeRunResult>;

package/dist/ci/runtime.js

@@ -0,0 +1,203 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runNativeCI = runNativeCI;
+const node_crypto_1 = require("node:crypto");
+const projectPaths_1 = require("../utils/projectPaths");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const promises_1 = require("node:timers/promises");
+const lexer_1 = require("../parser/lexer");
+const parser_1 = require("../parser/parser");
+function safeName(name) { return name.replace(/[^a-zA-Z0-9_.-]/g, '_').slice(0, 120) + '-' + (0, node_crypto_1.createHash)('sha256').update(name).digest('hex').slice(0, 12); }
+function xml(value) { return String(value).replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '').replace(/[<>&"']/g, char => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;', "'": '&apos;' }[char])); }
+async function runNativeCI(worker, orchestrator, target, config, engine) {
+    const started = Date.now();
+    const artifactRoot = config.artifactsDir;
+    node_fs_1.default.mkdirSync(artifactRoot, { recursive: true });
+    const directory = node_fs_1.default.mkdtempSync(node_path_1.default.join(artifactRoot, 'run-'));
+    config.artifactsDir = directory;
+    const steps = new Map();
+    const completed = new Set();
+    const errors = [];
+    const planned = new Map();
+    let bailed = false;
+    let expected = 0;
+    let files = [];
+    let server;
+    let interrupted = false;
+    const interrupt = () => { interrupted = true; worker.abort(); orchestrator.abort?.(); };
+    const event = (data) => {
+        if (!data?.payload)
+            return;
+        const p = data.payload;
+        if (data.type === 'BAIL')
+            bailed = true;
+        if (data.type === 'LOG_EVENT' && p.status === 'error') {
+            const active = [...steps.values()].reverse().find(step => step.fileName === p.fileName && step.status === 'running');
+            if (active)
+                active.error = p.details?.rawError || p.summary;
+        }
+        if (data.type === 'STEP_UPDATE' || data.type === 'STEP_ADD') {
+            const key = `${p.fileName}:${p.id}`;
+            steps.set(key, { ...steps.get(key), ...p, screenshot: undefined });
+            if (p.status === 'failed' && typeof p.screenshot === 'string') {
+                const match = p.screenshot.match(/^data:image\/(png|jpeg);base64,(.+)$/s) || (/^[A-Za-z0-9+/=\r\n]+$/.test(p.screenshot) ? ['', 'jpeg', p.screenshot] : null);
+                if (match)
+                    node_fs_1.default.writeFileSync(node_path_1.default.join(directory, `${safeName(p.fileName)}-${safeName(p.id)}.${match[1] === 'jpeg' ? 'jpg' : 'png'}`), Buffer.from(match[2], 'base64'));
+            }
+        }
+        if (data.type === 'FILE_COMPLETE' || data.type === 'FILE_FAILED')
+            completed.add(p.fileName);
+        if (data.type === 'FILE_FAILED' && ![...steps.values()].some(step => step.fileName === p.fileName && step.status === 'failed'))
+            errors.push(`${p.fileName}: ${p.error || 'Execution failed'}`);
+        if (data.type === 'BROWSER_ERROR' && config.browserErrors !== 'record')
+            errors.push(`Browser: ${p.message}`);
+        if (data.type === 'CLOUD_SYNC')
+            config.cloudSyncResult = p;
+        if (data.type === 'WORKER_ERROR')
+            errors.push(p.message || 'Worker failed');
+    };
+    // Modern orchestrators forward child-process events here; the worker listener
+    // also supports older compatible Pro packages. Step maps make duplicates harmless.
+    config.onRunEvent = event;
+    if (orchestrator.nativeEventProtocol !== 1)
+        worker.on('worker_event', event);
+    process.on('SIGINT', interrupt);
+    process.on('SIGTERM', interrupt);
+    try {
+        files = (0, projectPaths_1.discoverFlows)(target, config.projectRoot || process.cwd());
+        config.flowRoot = node_fs_1.default.statSync(target).isDirectory() ? target : node_path_1.default.dirname(target);
+        if (!files.length)
+            throw new Error('No .flow tests found.');
+        for (const file of files) {
+            const features = (0, projectPaths_1.selectedFeatures)(new parser_1.Parser(new lexer_1.Lexer(node_fs_1.default.readFileSync(file, 'utf8')).tokenise()).parse());
+            for (const feature of features)
+                for (const scenario of feature.scenarios)
+                    for (const step of scenario.steps) {
+                        const fileName = (0, projectPaths_1.flowIdentity)(file, config.flowRoot);
+                        planned.set(`${fileName}:${step.id}`, { id: step.id, description: step.blockDescription, command: step.action, fileName, status: 'skipped', reason: 'bail' });
+                    }
+            expected += features.reduce((n, feature) => n + feature.scenarios.reduce((m, scenario) => m + scenario.steps.length, 0), 0);
+        }
+        if (!expected)
+            throw new Error('No executable test steps found.');
+        if (config.webServer) {
+            const settings = config.webServer;
+            const probe = async () => { try {
+                return (await fetch(settings.url, { signal: AbortSignal.timeout(1000) })).ok;
+            }
+            catch {
+                return false;
+            } };
+            if (await probe())
+                throw new Error('webServer readiness URL is already serving; refusing to test an unowned server.');
+            const output = node_fs_1.default.openSync(node_path_1.default.join(directory, 'web-server.log'), 'a');
+            try {
+                server = (0, node_child_process_1.spawn)(settings.command, { cwd: settings.cwd, shell: true, detached: process.platform !== 'win32', stdio: ['ignore', output, output] });
+            }
+            finally {
+                node_fs_1.default.closeSync(output);
+            }
+            let spawnError;
+            server.on('error', error => { spawnError = error; });
+            const deadline = Date.now() + (settings.timeout ?? 30000);
+            while (!(await probe())) {
+                if (interrupted)
+                    throw new Error('Run interrupted during server startup.');
+                if (spawnError)
+                    throw spawnError;
+                if (server.exitCode !== null || server.signalCode !== null)
+                    throw new Error('webServer exited before readiness.');
+                if (Date.now() > deadline)
+                    throw new Error('webServer readiness timed out.');
+                await (0, promises_1.setTimeout)(100);
+            }
+        }
+        if (interrupted)
+            throw new Error('Run interrupted before execution.');
+        const ok = await orchestrator.start(target);
+        if (ok === false && ![...steps.values()].some(step => step.status === 'failed'))
+            errors.push('Engine reported a failed run.');
+    }
+    catch (error) {
+        errors.push(error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        try {
+            await worker.shutdown();
+        }
+        catch (error) {
+            errors.push(`Cleanup failed: ${String(error)}`);
+        }
+        try {
+            await orchestrator.close?.();
+        }
+        catch (error) {
+            errors.push(`Orchestrator cleanup failed: ${String(error)}`);
+        }
+        if (server?.pid) {
+            const stop = (signal) => { try {
+                process.kill(process.platform === 'win32' ? server.pid : -server.pid, signal);
+            }
+            catch (error) {
+                if (error.code !== 'ESRCH')
+                    errors.push(`Server cleanup: ${error.message}`);
+            } };
+            stop('SIGTERM');
+            await Promise.race([new Promise(resolve => server.once('exit', () => resolve())), (0, promises_1.setTimeout)(1000)]);
+            // Terminate remaining descendants even if the shell exited first.
+            stop('SIGKILL');
+        }
+        worker.off('worker_event', event);
+        delete config.onRunEvent;
+        process.off('SIGINT', interrupt);
+        process.off('SIGTERM', interrupt);
+    }
+    if (interrupted)
+        errors.push('Run interrupted.');
+    if (bailed)
+        for (const [key, step] of planned)
+            if (!steps.has(key))
+                steps.set(key, step);
+    const results = [...steps.values()];
+    const terminal = results.filter(step => ['passed', 'failed', 'skipped', 'not_tested'].includes(step.status));
+    const incomplete = Math.max(0, expected - terminal.length);
+    for (const file of files)
+        if (!bailed && !completed.has((0, projectPaths_1.flowIdentity)(file, config.flowRoot)))
+            errors.push(`Incomplete file: ${(0, projectPaths_1.flowIdentity)(file, config.flowRoot)}`);
+    if (results.some(step => !['passed', 'failed', 'skipped', 'not_tested'].includes(step.status)))
+        errors.push('Unfinished test steps.');
+    if (terminal.length > expected)
+        errors.push('Engine produced an unexpected step count.');
+    const metrics = { total: expected, passed: results.filter(s => s.status === 'passed').length,
+        failed: results.filter(s => s.status === 'failed').length, skipped: results.filter(s => ['skipped', 'not_tested'].includes(s.status)).length, incomplete };
+    const result = { cloudSync: config.cloudSyncResult, protocol: 1, engine, status: interrupted ? 'interrupted' : errors.length || metrics.failed || incomplete ? 'failed' : 'passed',
+        duration: Date.now() - started, artifactsDir: directory, files: files.map(file => (0, projectPaths_1.flowIdentity)(file, config.flowRoot)), steps: results, errors, metrics };
+    // Existing workers finalize videos into these locations. Copy only run files,
+    // never the project directory or credentials.
+    if (config.recordVideo !== false)
+        for (const file of files) {
+            for (const folder of ['artifacts', 'mock-cloud']) {
+                const video = node_path_1.default.join(process.cwd(), '.flowstride', folder, (0, projectPaths_1.videoFileName)((0, projectPaths_1.flowIdentity)(file, config.flowRoot)));
+                if (node_fs_1.default.existsSync(video) && node_fs_1.default.statSync(video).mtimeMs >= started) {
+                    node_fs_1.default.copyFileSync(video, node_path_1.default.join(directory, node_path_1.default.basename(video)));
+                    break;
+                }
+            }
+        }
+    config.artifactsDir = artifactRoot;
+    node_fs_1.default.writeFileSync(node_path_1.default.join(artifactRoot, 'summary.json'), JSON.stringify(result, null, 2));
+    const cases = results.map(step => `<testcase classname="${xml(step.fileName)}" name="${xml(step.description || step.id)}">${step.status === 'failed' ? `<failure message="${xml(step.error || 'Test step failed')}"/>` : ['skipped', 'not_tested'].includes(step.status) ? '<skipped/>' : ''}</testcase>`);
+    for (const error of errors)
+        cases.push(`<testcase name="execution"><error message="${xml(error)}"/></testcase>`);
+    if (incomplete)
+        cases.push(`<testcase name="completion"><failure message="${incomplete} incomplete steps"/></testcase>`);
+    node_fs_1.default.writeFileSync(node_path_1.default.join(artifactRoot, 'junit.xml'), `<?xml version="1.0"?><testsuite name="Flowstride" tests="${cases.length}" failures="${metrics.failed + (incomplete ? 1 : 0)}" errors="${errors.length}" skipped="${metrics.skipped}">${cases.join('')}</testsuite>`);
+    if (process.env.GITHUB_STEP_SUMMARY)
+        node_fs_1.default.appendFileSync(process.env.GITHUB_STEP_SUMMARY, `\n### Flowstride · ${config.device}\nResult: **${result.status}** (${engine})\n\nPassed: ${metrics.passed}; failed: ${metrics.failed}; skipped: ${metrics.skipped}; incomplete: ${metrics.incomplete}.\n`);
+    return result;
+}