flowstride 1.0.19 → 1.0.20-rc.2

package/dist/game/sdk.js

@@ -0,0 +1,255 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GameSDK = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const strict_1 = __importDefault(require("node:assert/strict"));
+const promises_1 = require("node:timers/promises");
+class GameSDK {
+    page;
+    config;
+    snapshots = new Map();
+    states = new Map();
+    constructor(page, config) {
+        this.page = page;
+        this.config = config;
+    }
+    timeout() { return this.config.timeout; }
+    async bridgeReady(method) {
+        await this.page().waitForFunction(method => {
+            const bridge = window.__FLOWSTRIDE_GAME__;
+            return !!bridge && (!method || typeof bridge[method] === 'function');
+        }, method, { timeout: this.timeout() });
+    }
+    async point(options) {
+        const canvas = this.page().locator(options.canvas || 'canvas');
+        await canvas.waitFor({ state: 'visible', timeout: this.timeout() });
+        const box = await canvas.boundingBox();
+        if (!box || box.width <= 0 || box.height <= 0)
+            throw new Error('Canvas has no usable bounds.');
+        let { x, y } = options;
+        if (!Number.isFinite(x) || !Number.isFinite(y))
+            throw new Error('Canvas coordinates must be finite.');
+        if ((options.unit || 'relative') === 'relative') {
+            x *= box.width;
+            y *= box.height;
+        }
+        else if (options.unit !== 'pixels')
+            throw new Error('Coordinate unit must be relative or pixels.');
+        if (x < 0 || x >= box.width || y < 0 || y >= box.height)
+            throw new Error('Canvas coordinate is outside its bounds.');
+        const point = { x: box.x + x, y: box.y + y };
+        await canvas.evaluate((element, point) => {
+            if (document.elementFromPoint(point.x, point.y) !== element)
+                throw new Error('Canvas target is covered or outside the viewport.');
+        }, point);
+        return point;
+    }
+    touch(options) {
+        const input = options.input || (this.config.device === 'desktop' ? 'mouse' : 'touch');
+        if (!['mouse', 'touch'].includes(input))
+            throw new Error('input must be mouse or touch.');
+        return input === 'touch';
+    }
+    async tap(options) {
+        const point = await this.point(options);
+        if (this.touch(options))
+            await this.page().touchscreen.tap(point.x, point.y);
+        else
+            await this.page().mouse.click(point.x, point.y);
+    }
+    async drag(options) {
+        const from = await this.point({ ...options, ...options.from });
+        const to = await this.point({ ...options, ...options.to });
+        const duration = options.duration ?? 250;
+        if (!Number.isFinite(duration) || duration < 0 || duration > this.timeout())
+            throw new Error('Invalid gesture duration.');
+        if (this.touch(options)) {
+            const session = await this.page().context().newCDPSession(this.page());
+            try {
+                await session.send('Input.dispatchTouchEvent', { type: 'touchStart', touchPoints: [from] });
+                for (let i = 1; i <= 10; i++) {
+                    await session.send('Input.dispatchTouchEvent', { type: 'touchMove', touchPoints: [{ x: from.x + (to.x - from.x) * i / 10, y: from.y + (to.y - from.y) * i / 10 }] });
+                    await (0, promises_1.setTimeout)(duration / 10);
+                }
+            }
+            finally {
+                try {
+                    await session.send('Input.dispatchTouchEvent', { type: 'touchEnd', touchPoints: [] });
+                }
+                finally {
+                    await session.detach();
+                }
+            }
+        }
+        else {
+            await this.page().mouse.move(from.x, from.y);
+            await this.page().mouse.down();
+            try {
+                for (let i = 1; i <= 10; i++) {
+                    await this.page().mouse.move(from.x + (to.x - from.x) * i / 10, from.y + (to.y - from.y) * i / 10);
+                    await (0, promises_1.setTimeout)(duration / 10);
+                }
+            }
+            finally {
+                await this.page().mouse.up();
+            }
+        }
+    }
+    async swipe(options) { return this.drag({ ...options, input: 'touch' }); }
+    async key(options) {
+        const key = typeof options === 'string' ? options : options.key;
+        const duration = typeof options === 'string' ? 0 : options.duration ?? 0;
+        if (typeof key !== 'string' || !key || !Number.isFinite(duration) || duration < 0 || duration > this.timeout())
+            throw new Error('Invalid key or duration.');
+        const keys = key === '+' ? [key] : key.split('+');
+        const pressed = [];
+        try {
+            for (const part of keys) {
+                await this.page().keyboard.down(part);
+                pressed.push(part);
+            }
+            if (duration)
+                await (0, promises_1.setTimeout)(duration);
+        }
+        finally {
+            const released = await Promise.allSettled(pressed.reverse().map(part => this.page().keyboard.up(part)));
+            if (released.some(result => result.status === 'rejected'))
+                throw new Error('Failed to release game keyboard input.');
+        }
+    }
+    async checkpoint(options) {
+        const name = typeof options === 'string' ? options : options.name;
+        if (typeof name !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(name))
+            throw new Error('Checkpoint name must use letters, digits, underscores or hyphens.');
+        const directory = this.config.artifactsDir || node_path_1.default.resolve('flowstride-artifacts');
+        node_fs_1.default.mkdirSync(directory, { recursive: true });
+        const prefix = this.config.testFile ? this.config.testFile.replace(/[^a-zA-Z0-9_.-]/g, '_') + '-' : '';
+        const file = node_path_1.default.join(directory, prefix + name + '.png');
+        if (typeof options === 'object' && options.canvas)
+            await this.page().locator(options.canvas).screenshot({ path: file });
+        else
+            await this.page().screenshot({ path: file });
+        return file;
+    }
+    async snapshot(options) {
+        if (!options?.name || typeof options.name !== 'string')
+            throw new Error('snapshot requires a name.');
+        const buffer = await this.page().locator(options.canvas || 'canvas').screenshot();
+        this.snapshots.set(options.name, buffer);
+    }
+    async difference(before, after) {
+        return this.page().evaluate(async ({ before, after }) => {
+            async function pixels(data) {
+                const image = new Image();
+                image.src = 'data:image/png;base64,' + data;
+                await image.decode();
+                const canvas = document.createElement('canvas');
+                canvas.width = image.width;
+                canvas.height = image.height;
+                const context = canvas.getContext('2d');
+                context.drawImage(image, 0, 0);
+                return { data: context.getImageData(0, 0, canvas.width, canvas.height).data, width: canvas.width, height: canvas.height };
+            }
+            const a = await pixels(before), b = await pixels(after);
+            if (a.width !== b.width || a.height !== b.height)
+                throw new Error('Visual comparison dimensions differ.');
+            let changed = 0;
+            for (let i = 0; i < a.data.length; i += 4)
+                if (Math.abs(a.data[i] - b.data[i]) + Math.abs(a.data[i + 1] - b.data[i + 1]) + Math.abs(a.data[i + 2] - b.data[i + 2]) + Math.abs(a.data[i + 3] - b.data[i + 3]) > 60)
+                    changed++;
+            return changed / (a.width * a.height);
+        }, { before: before.toString('base64'), after: after.toString('base64') });
+    }
+    async expectVisual(options) {
+        let before;
+        if (options.baseline)
+            before = node_fs_1.default.readFileSync(node_path_1.default.resolve(options.baseline));
+        else
+            before = this.snapshots.get(options.name);
+        if (!before)
+            throw new Error('Visual snapshot or baseline is missing.');
+        const ratio = await this.difference(before, await this.page().locator(options.canvas || 'canvas').screenshot());
+        const min = options.minChange ?? 0, max = options.maxChange ?? (options.minChange === undefined ? 0 : 1);
+        if (![min, max].every(Number.isFinite) || min < 0 || max > 1 || min > max)
+            throw new Error('Visual change thresholds must satisfy 0 <= min <= max <= 1.');
+        (0, strict_1.default)(ratio >= min && ratio <= max, `Canvas changed by ${ratio}; expected between ${min} and ${max}.`);
+        return ratio;
+    }
+    async state(options = {}) {
+        await this.bridgeReady('readState');
+        return this.page().evaluate(async (field) => {
+            const bridge = window.__FLOWSTRIDE_GAME__;
+            if (!bridge?.readState)
+                throw new Error('Game state bridge is not registered.');
+            let value = await bridge.readState();
+            for (const part of field?.split('.') || []) {
+                if (['__proto__', 'constructor', 'prototype'].includes(part) || value == null || !Object.hasOwn(value, part))
+                    throw new Error(`Game state field is unavailable: ${field}`);
+                value = value[part];
+            }
+            return value;
+        }, options.path);
+    }
+    async expectState(options) {
+        if (!options || !Object.hasOwn(options, 'equals'))
+            throw new Error('expectState requires equals.');
+        const deadline = Date.now() + this.timeout();
+        let actual;
+        let observed = false;
+        do {
+            try {
+                actual = await this.state(options);
+                observed = true;
+                strict_1.default.deepStrictEqual(actual, options.equals);
+                return;
+            }
+            catch { }
+            await (0, promises_1.setTimeout)(50);
+        } while (Date.now() < deadline);
+        if (!observed)
+            throw new Error('Game state was not readable before the timeout.');
+        strict_1.default.deepStrictEqual(actual, options.equals, `Game state did not reach the expected value: ${options.path || 'root'}`);
+    }
+    async snapshotState(options) {
+        if (!options?.name)
+            throw new Error('snapshotState requires name.');
+        this.states.set(options.name, { path: options.path, value: await this.state(options) });
+    }
+    async expectPreserved(options) {
+        if (!this.states.has(options.name))
+            throw new Error('State snapshot missing.');
+        const snapshot = this.states.get(options.name);
+        strict_1.default.deepStrictEqual(await this.state({ path: options.path ?? snapshot.path }), snapshot.value, 'Game state changed.');
+    }
+    async fixture(options) {
+        await this.bridgeReady();
+        return this.page().evaluate(async ({ name, data }) => {
+            const bridge = window.__FLOWSTRIDE_GAME__;
+            if (!bridge?.testMode || !Object.hasOwn(bridge.fixtures || {}, name) || typeof bridge.fixtures[name] !== 'function')
+                throw new Error('Named fixture is unavailable in this environment.');
+            return bridge.fixtures[name](data);
+        }, { name: options.name, data: options.data });
+    }
+    async select(options) {
+        if (typeof options?.id !== 'string' || !options.id.trim())
+            throw new Error('select requires a nonempty game object ID.');
+        await this.bridgeReady('locate');
+        const point = await this.page().evaluate(async (id) => {
+            const bridge = window.__FLOWSTRIDE_GAME__;
+            if (!bridge?.locate)
+                throw new Error('Game object bridge is not registered.');
+            return bridge.locate(id);
+        }, options.id);
+        if (!Number.isFinite(point.x) || !Number.isFinite(point.y))
+            throw new Error('Invalid object coordinates.');
+        if (this.touch(options))
+            await this.page().touchscreen.tap(point.x, point.y);
+        else
+            await this.page().mouse.click(point.x, point.y);
+    }
+}
+exports.GameSDK = GameSDK;

package/dist/game/three-bridge.d.ts

@@ -0,0 +1,18 @@
+/** Browser-side integration. Import from flowstride/dist/game/three-bridge.
+ * The application supplies its own Three.js constructors; no second Three.js
+ * runtime, scene reconstruction, renderer or animation loop is created. */
+export interface ThreeGameBridgeOptions {
+    scene: any;
+    camera: any;
+    canvas: HTMLCanvasElement;
+    Vector3: new (...args: any[]) => any;
+    Raycaster: new (...args: any[]) => any;
+    objects?: Record<string, any>;
+    readState?: () => unknown;
+    testMode?: boolean;
+    fixtures?: Record<string, (data: unknown) => unknown>;
+}
+export declare function registerThreeGame(options: ThreeGameBridgeOptions): {
+    registerObject(id: string, object: any): void;
+    dispose(): void;
+};

package/dist/game/three-bridge.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerThreeGame = registerThreeGame;
+function registerThreeGame(options) {
+    if (!(options.canvas instanceof HTMLCanvasElement))
+        throw new Error('A live game canvas is required.');
+    const objects = new Map(Object.entries(options.objects || {}));
+    const locate = (id) => {
+        let object = objects.get(id);
+        if (!object)
+            options.scene.traverse((candidate) => { if (candidate.userData?.flowstrideId === id) {
+                if (object)
+                    throw new Error(`Duplicate game object ID: ${id}`);
+                object = candidate;
+            } });
+        if (!object)
+            throw new Error(`Game object not found: ${id}`);
+        let cursor = object;
+        while (cursor) {
+            if (cursor.visible === false)
+                throw new Error(`Game object is hidden: ${id}`);
+            cursor = cursor.parent;
+        }
+        options.scene.updateMatrixWorld(true);
+        options.camera.updateMatrixWorld(true);
+        options.camera.updateProjectionMatrix();
+        const local = object.userData?.flowstridePickPoint;
+        const point = local ? object.localToWorld(new options.Vector3(...local)) : object.getWorldPosition(new options.Vector3());
+        point.project(options.camera);
+        if (![point.x, point.y, point.z].every(Number.isFinite) || Math.abs(point.x) > 1 || Math.abs(point.y) > 1 || Math.abs(point.z) > 1)
+            throw new Error(`Game object is outside the camera: ${id}`);
+        const ray = new options.Raycaster();
+        ray.layers.mask = options.camera.layers.mask;
+        ray.setFromCamera({ x: point.x, y: point.y }, options.camera);
+        const hits = ray.intersectObjects(options.scene.children, true);
+        const front = hits.find((hit) => { let node = hit.object; while (node) {
+            if (node.visible === false)
+                return false;
+            node = node.parent;
+        } return true; });
+        cursor = front?.object;
+        while (cursor && cursor !== object)
+            cursor = cursor.parent;
+        if (!cursor)
+            throw new Error(`Game object is occluded or not pickable: ${id}`);
+        const rect = options.canvas.getBoundingClientRect();
+        const x = rect.left + (point.x + 1) * rect.width / 2, y = rect.top + (1 - point.y) * rect.height / 2;
+        if (!rect.width || !rect.height || x < 0 || y < 0 || x >= innerWidth || y >= innerHeight || document.elementFromPoint(x, y) !== options.canvas)
+            throw new Error(`Game object is covered or outside the viewport: ${id}`);
+        return { x, y };
+    };
+    const bridge = { locate, readState: options.readState, testMode: options.testMode === true,
+        fixtures: options.testMode === true ? options.fixtures || {} : {} };
+    window.__FLOWSTRIDE_GAME__ = bridge;
+    return { registerObject(id, object) { if (!id || objects.has(id))
+            throw new Error('Game object ID must be unique and nonempty.'); objects.set(id, object); },
+        dispose() { if (window.__FLOWSTRIDE_GAME__ === bridge)
+            delete window.__FLOWSTRIDE_GAME__; } };
+}

package/dist/runner/flow_orchestrator.d.ts

@@ -4,6 +4,8 @@ export declare class FlowOrchestrator {
     private worker;
     private workerCount;
     private config?;
+    static readonly nativeCIProtocol = 1;
+    readonly nativeEventProtocol = 1;
     private wss;
     private httpServer;
     private globalTestScenarios;
@@ -13,6 +15,8 @@ export declare class FlowOrchestrator {
     constructor(worker: FlowWorker, workerCount?: number, config?: FlowstrideConfig | undefined);
     private forwardToDashboard;
     private executeTestRun;
-    start(targetPath: string): Promise<void>;
+    start(targetPath: string): Promise<boolean>;
+    abort(): void;
+    close(): Promise<void>;
     private handleExportPdfRequest;
 }

package/dist/runner/flow_orchestrator.js

@@ -48,6 +48,8 @@ class FlowOrchestrator {
     worker;
     workerCount;
     config;
+    static nativeCIProtocol = 1;
+    nativeEventProtocol = 1;
     wss = null;
     httpServer = null;
     globalTestScenarios = [];
@@ -64,6 +66,7 @@ class FlowOrchestrator {
         });
     }
     forwardToDashboard(type, payload) {
+        this.config?.onRunEvent?.({ type, payload });
         if (this.wss) {
             this.wss.clients.forEach((client) => {
                 if (client.readyState === 1)
@@ -76,10 +79,18 @@ class FlowOrchestrator {
         let filesToProcess = [];
         const stats = fs.statSync(targetPath);
         if (stats.isDirectory()) {
-            filesToProcess = fs
+            const allFlowFiles = fs
                 .readdirSync(targetPath)
-                .filter((f) => f.endsWith(".flow"))
+                .filter((f) => f.endsWith(".flow"));
+            const priorityQueue = allFlowFiles
+                .filter((f) => f.endsWith(".first.flow"))
+                .sort()
                 .map((f) => path.join(targetPath, f));
+            const standardQueue = allFlowFiles
+                .filter((f) => !f.endsWith(".first.flow"))
+                .sort()
+                .map((f) => path.join(targetPath, f));
+            filesToProcess = [...priorityQueue, ...standardQueue];
         }
         else {
             filesToProcess = [targetPath];
@@ -103,10 +114,14 @@ class FlowOrchestrator {
         this.worker.on("worker_event", listener);
         await this.worker.runBatch(filesToProcess);
         this.worker.off("worker_event", listener);
-        this.forwardToDashboard("RUN_COMPLETE", { status: "success" });
+        const passed = ![...this.stepStatusRegistry.values()].some(status => ['failed', 'running', 'not_tested'].includes(status));
+        this.forwardToDashboard("RUN_COMPLETE", { status: passed ? 'success' : 'failed' });
+        return passed;
     }
     async start(targetPath) {
         try {
+            if (this.config?.ci)
+                return await this.executeTestRun(targetPath);
             this.httpServer = http.createServer((req, res) => {
                 res.setHeader("Access-Control-Allow-Origin", "*");
                 if (req.url && req.url.startsWith("/videos/")) {
@@ -304,8 +319,8 @@ class FlowOrchestrator {
                         else {
                             console.log(chalk_1.default.gray("[Dashboard]: Headless mode active. Bypassing UI auto-launch..."));
                         }
-                        await this.executeTestRun(targetPath);
-                        resolve(undefined);
+                        const result = await this.executeTestRun(targetPath);
+                        resolve(result);
                     }
                     catch (err) {
                         reject(err);
@@ -317,11 +332,20 @@ class FlowOrchestrator {
             throw e;
         }
     }
+    abort() {
+        this.worker.abort();
+    }
+    async close() {
+        if (this.disconnectTimer)
+            clearTimeout(this.disconnectTimer);
+        this.wss?.clients.forEach(client => client.terminate());
+        this.wss?.close();
+        this.httpServer?.close();
+    }
     async handleExportPdfRequest(testScenariosFromUI) {
         try {
-            const spinner = (0, ora_1.default)(chalk_1.default.blue("Compiling high-fidelity PDF report...")).start();
+            const spinner = (0, ora_1.default)(chalk_1.default.blue("Compiling high fidelity PDF report...")).start();
             const pdfPath = await this.pdfGenerator.generateTestcasePdf(testScenariosFromUI);
-            // Convert the saved PDF to base64 to trigger the native browser download UI
             const pdfBuffer = fs.readFileSync(pdfPath);
             const base64Data = pdfBuffer.toString("base64");
             this.forwardToDashboard("EXPORT_PDF_RES", { base64: base64Data });

package/dist/runner/flow_worker.js

@@ -364,6 +364,10 @@ class FlowWorker extends events_1.EventEmitter {
         this.isAborted = false;
         this.isDebugHalted = false;
         const sigintHandler = async () => {
+            if (this.config.ci) {
+                this.abort();
+                return;
+            }
             if (!this.isSilent) {
                 console.log(chalk_1.default.yellow("\n[Flowstride]: Process interrupted. Gracefully shutting down..."));
             }
@@ -373,7 +377,8 @@ class FlowWorker extends events_1.EventEmitter {
                 await this.web.shutdown();
             }
             catch (e) { }
-            process.exit(0);
+            if (!this.config.ci)
+                process.exit(0);
         };
         process.once("SIGINT", sigintHandler);
         try {
@@ -397,6 +402,7 @@ class FlowWorker extends events_1.EventEmitter {
                 try {
                     const fileName = path.basename(filePath);
                     this.currentFileName = fileName;
+                    this.config.testFile = fileName;
                     this.localVariables = {};
                     this.localBrowserSessions = {};
                     this.api.resetState();
@@ -471,20 +477,24 @@ class FlowWorker extends events_1.EventEmitter {
                                 .getPage()
                                 .waitForLoadState("networkidle", { timeout: 4000 })
                                 .catch(() => { });
-                            await new Promise((resolve) => setTimeout(resolve, 2000));
+                            if (!this.config.ci)
+                                await new Promise((resolve) => setTimeout(resolve, 2000));
                         }
                     }
                     if (this.isAborted)
                         break;
                     if (!this.isSilent)
                         console.log(chalk_1.default.gray("\n[Execution]: Finalizing browser actions..."));
-                    await new Promise((resolve) => setTimeout(resolve, 2000));
+                    if (!this.config.ci)
+                        await new Promise((resolve) => setTimeout(resolve, 2000));
                     try {
                         const baseName = this.currentFileName.replace(".flow", "");
                         const mockCloudDir = path.join(process.cwd(), ".flowstride", "mock-cloud");
                         if (!fs.existsSync(mockCloudDir))
                             fs.mkdirSync(mockCloudDir, { recursive: true });
                         const targetVideoPath = path.join(mockCloudDir, `${baseName}.webm`);
+                        for (const message of this.web.pageErrors || [])
+                            this.broadcast('BROWSER_ERROR', { message, fileName: this.currentFileName });
                         await this.web.shutdown(targetVideoPath);
                         if (!this.isSilent)
                             console.log(chalk_1.default.gray(`      [Cloud Sync]: Video safely encoded and preserved for ${this.currentFileName}`));
@@ -506,6 +516,8 @@ class FlowWorker extends events_1.EventEmitter {
                         if (!fs.existsSync(mockCloudDir))
                             fs.mkdirSync(mockCloudDir, { recursive: true });
                         const targetVideoPath = path.join(mockCloudDir, `${baseName}.webm`);
+                        for (const message of this.web.pageErrors || [])
+                            this.broadcast('BROWSER_ERROR', { message, fileName: this.currentFileName });
                         await this.web.shutdown(targetVideoPath);
                         if (!this.isSilent)
                             console.log(chalk_1.default.gray(`      [Cloud Sync]: Video safely encoded and preserved for ${this.currentFileName}`));
@@ -518,7 +530,7 @@ class FlowWorker extends events_1.EventEmitter {
                     });
                 }
             }
-            if (!this.isSilent && !this.isAborted) {
+            if (!this.config.ci && !this.isSilent && !this.isAborted) {
                 if (this.isDebugHalted) {
                     console.log(chalk_1.default.cyan("\n[Execution]: Test suite halted by debug flag."));
                 }
@@ -528,6 +540,16 @@ class FlowWorker extends events_1.EventEmitter {
             }
         }
         finally {
+            if (this.config.ci && this.isAborted) {
+                try {
+                    const directory = path.join(process.cwd(), '.flowstride', 'artifacts');
+                    fs.mkdirSync(directory, { recursive: true });
+                    await this.web.shutdown(path.join(directory, this.currentFileName.replace(/\.flow$/, '') + '.webm'));
+                }
+                catch (error) {
+                    this.broadcast('WORKER_ERROR', { message: error.message });
+                }
+            }
             process.removeListener("SIGINT", sigintHandler);
         }
     }
@@ -1196,6 +1218,8 @@ class FlowWorker extends events_1.EventEmitter {
         });
     }
     async startStreaming() {
+        if (this.config.ci)
+            return;
         const page = this.web.getPage();
         if (this.currentCdpSession) {
             await this.currentCdpSession.detach().catch(() => { });

package/dist/runner/plugin_manager.d.ts

@@ -8,6 +8,7 @@ export declare class PluginManager {
     private store;
     private apiProxy;
     private dbProxy;
+    private game;
     constructor(config: FlowstrideConfig, web: WebAdapter, store: TemporaryStore, apiProxy: ApiProxy);
     execute(actionName: string, args: any, saveAs?: string): Promise<any>;
 }

package/dist/runner/plugin_manager.js

@@ -32,8 +32,14 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PluginManager = void 0;
+const deadline_1 = require("../ci/deadline");
+const node_fs_1 = __importDefault(require("node:fs"));
+const sdk_1 = require("../game/sdk");
 const path = __importStar(require("path"));
 const db_proxy_1 = require("../sdk/db_proxy");
 class PluginManager {
@@ -42,12 +48,14 @@ class PluginManager {
     store;
     apiProxy;
     dbProxy;
+    game;
     constructor(config, web, store, apiProxy) {
         this.config = config;
         this.web = web;
         this.store = store;
         this.apiProxy = apiProxy;
         this.dbProxy = new db_proxy_1.DbProxy();
+        this.game = new sdk_1.GameSDK(() => this.web.getPage(), this.config);
     }
     async execute(actionName, args, saveAs) {
         const lastDotIndex = actionName.lastIndexOf(".");
@@ -56,6 +64,16 @@ class PluginManager {
         }
         const pluginFile = actionName.substring(0, lastDotIndex);
         const functionName = actionName.substring(lastDotIndex + 1);
+        if (pluginFile === 'flowstride:game') {
+            const actions = ['tap', 'drag', 'swipe', 'key', 'checkpoint', 'snapshot', 'expectVisual', 'state', 'expectState', 'snapshotState', 'expectPreserved', 'fixture', 'select'];
+            if (!actions.includes(functionName))
+                throw new Error(`Unknown native game action: ${functionName}`);
+            const operation = this.game[functionName](args);
+            const result = this.config.ci ? await (0, deadline_1.withDeadline)(operation, this.config.timeout) : await operation;
+            if (saveAs)
+                this.store.set(saveAs, result);
+            return result;
+        }
         let fullPath;
         if (pluginFile.includes("/") || pluginFile.includes("\\")) {
             fullPath = path.resolve(process.cwd(), `${pluginFile}.ts`);
@@ -84,6 +102,19 @@ class PluginManager {
                 throw new Error(`Plugin function "${functionName}" not found in ${fullPath}`);
             }
             const sdk = {
+                game: this.game,
+                browser: { page: () => this.web.getPage() },
+                run: { device: this.config.device || 'desktop', artifactsDir: this.config.artifactsDir || path.resolve('flowstride-artifacts'),
+                    attach: (name, data) => {
+                        if (!/^[a-zA-Z0-9_.-]+$/.test(name) || name === '.' || name === '..')
+                            throw new Error('Attachment name must be a simple filename.');
+                        const directory = this.config.artifactsDir || path.resolve('flowstride-artifacts');
+                        node_fs_1.default.mkdirSync(directory, { recursive: true });
+                        const prefix = this.config.testFile ? this.config.testFile.replace(/[^a-zA-Z0-9_.-]/g, '_') + '-' : '';
+                        const file = path.join(directory, prefix + name);
+                        node_fs_1.default.writeFileSync(file, data);
+                        return file;
+                    } },
                 api: {
                     get: (url, headers) => this.apiProxy.get(url, headers),
                     post: (url, body, headers) => this.apiProxy.post(url, body, headers),
@@ -150,7 +181,8 @@ class PluginManager {
                         .substring(2, 2 + length),
                 },
             };
-            const result = await action(sdk, args);
+            const operation = action(sdk, args);
+            const result = this.config.ci ? await (0, deadline_1.withDeadline)(operation, this.config.timeout) : await operation;
             if (saveAs) {
                 this.store.set(saveAs, result);
             }

package/dist/types/index.d.ts

@@ -1,4 +1,31 @@
 export interface FlowstrideConfig {
+    ci?: boolean;
+    device?: 'desktop' | 'phone' | 'landscape';
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    testDir?: string;
+    artifactsDir?: string;
+    recordVideo?: boolean;
+    browserErrors?: 'fail' | 'record';
+    webServer?: {
+        command: string;
+        url: string;
+        cwd?: string;
+        timeout?: number;
+    };
+    testFile?: string;
+    onRunEvent?: (event: any) => void;
+    bail?: boolean;
+    isCloudSyncActive?: boolean;
+    machineToken?: string | null;
+    workspaceId?: string | null;
+    manifest?: {
+        plan?: string;
+        maxWorkers?: number | 'unlimited';
+        [key: string]: any;
+    } | null;
     baseUrl?: string;
     timeout: number;
     headless: boolean;
@@ -46,6 +73,15 @@ export interface SessionDefinition {
     };
 }
 export interface FlowstrideSDK {
+    game: import('../game/sdk').GameSDK;
+    browser: {
+        page: () => import('playwright').Page;
+    };
+    run: {
+        device: string;
+        artifactsDir: string;
+        attach: (name: string, data: string | Buffer) => string;
+    };
     api: {
         get: (url: string, headers?: Record<string, string>) => Promise<any>;
         post: (url: string, body: any, headers?: Record<string, string>) => Promise<any>;