flowstride 1.0.18 → 1.0.20-rc.2

package/NATIVE_CI.md

@@ -0,0 +1,155 @@
+# 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. Naija Throne's current runner is unchanged;
+its migration is a separate acceptance step. 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.2.tgz
+# Optional: install the local matching Pro candidate after project dependencies.
+npm install --no-save /absolute/path/flowstride-pro-1.0.15-rc.1.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; its existing server-side security and
+storage limitations still apply. 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 and Naija Throne migration after local acceptance.
+No push, npm publication, Cloud archive replacement or Naija Throne migration
+is performed by building these candidates.
+
+## Candidate acceptance automation
+
+The repository's `Native CI acceptance` workflow tests Node 22 and 24 on Linux.
+It uses a checksum-pinned archive in `.github/fixtures`, checks its compiled engine
+against a fresh build, checks referenced dashboard assets, then installs that exact
+archive in a clean consumer. It exercises native browser installation, passing and
+deliberately failing game execution, media, server cleanup and workflow preservation.
+It also runs the native source suite, including delayed uploads and cancellation.
+The Pro archive belongs only in the private Pro repository.
+
+These jobs do not publish npm packages, replace the hosted Pro archive, deploy
+Cloud, or migrate application repositories. Native Cloud reporting stays opt-in.
+Qualification covers Chromium and emulated desktop/phone/landscape profiles.
+Physical Android/iOS devices, Safari/Firefox and other game engines are outside
+this candidate's verified support scope. Real Cloud licensing, reporting and
+video storage require a separate live acceptance run.
+
+## OSS npm preview release
+
+OSS `1.0.20-rc.2` requires Node.js 22.12.0+. Publish the verified archive under
+`next`; install with `npm install --save-dev flowstride@next` after publication.
+Use the release archive and checksum rather than rebuilding from a dirty checkout.
+The matching local Pro candidate remains `1.0.15-rc.1`; hosted Pro remains
+`1.0.14`. Complete authentication before reinstalling the local Pro candidate.
+The unchanged dashboard bundle is reused from the previously qualified rc.1
+archive; the engine is rebuilt from this source. The release input manifest
+records both that archive's checksum and the merged base commit.

package/README.md

@@ -6,6 +6,34 @@ Flowstride OS combines the human-readable structure of Behavior-Driven Developme
 
 [Documentation](https://docs.flowstride.io/)
 
+## Native CI and game testing preview — 1.0.20-rc.2
+
+This is an opt-in preview intended for the npm `next` tag. The default stable
+release remains available through `latest`. After the preview is published:
+
+```sh
+npm install --save-dev flowstride@next
+npx --no-install flowstride install
+npx --no-install flowstride run --ci
+```
+
+Node.js 22.12.0+ is required; acceptance covers the minimum version and current
+Node.js 22/24 on Linux, plus Node.js 24 on macOS. The preview adds native CI
+exit codes, JSON/JUnit reports, videos/screenshots, device profiles, explicit
+GitHub workflow generation, and supported canvas/Three.js testing APIs.
+See [native CI setup](NATIVE_CI.md) and [release notes](RELEASE_NOTES.md).
+
+For this preview, use OSS alone or manually install the matching private Pro
+`1.0.15-rc.1` candidate after project dependencies. Normal Cloud login still
+serves Pro `1.0.14`; signing in afterward can replace the preview's Pro package,
+and that older CLI does not support the new native commands. Cloud reporting
+and video-storage defects remain open. Native CI keeps Cloud reporting off by
+default. Managed Cloud execution remains retired.
+
+This release qualifies Chromium desktop and emulated phone/landscape profiles
+and browser-game fixtures. It does not establish physical-phone, Safari,
+Firefox, other game-engine, or complete application-game coverage.
+
 ---
 
 ## Why Flowstride?
@@ -21,7 +49,7 @@ Traditional E2E frameworks force you to choose between highly technical code (wh
 
 ## Installation & Quick Start
 
-Flowstride requires Node.js 18 or higher.
+Flowstride requires Node.js 22.12.0 or higher. Use a current patched Node.js 22 or 24 release.
 
 **1. Install globally (or as a dev dependency in your project):**
 
@@ -71,41 +99,20 @@ npx flowstride login
 
 ---
 
-## Privacy & Data Security
-
-Flowstride is designed with a **zero-trust, local-first architecture**. Whether you are testing internal microservices, staging environments, or production APIs, your sensitive data, PHI, and credentials remain strictly on your infrastructure.
-
-### Open Source Core: 100% Local Isolation
-
-The Open Source version of Flowstride operates entirely as an ephemeral, local execution engine.
-
-- **Air-Gapped Execution:** Flowstride does not "phone home." The OS runner executes strictly on your local machine or within your private CI/CD pipeline. There is no external Flowstride database storing your test payloads or network logs.
-
-- **Ephemeral Memory:** Flowstride is inherently stateless. API request headers, response bodies, and DOM snapshots exist only in Node.js RAM during execution. The millisecond the execution process terminates, all memory is wiped.
-
-- **The DevTools Analogy:** Our network interception works natively within Playwright's browser context routing. It is fundamentally identical to opening the Chrome DevTools "Network" tab locally. We do not act as an external Man-In-The-Middle (MITM) proxy.
-
-- **Opt-In Local State:** Artifacts saved to disk—such as execution videos (`.flowstride/mock-cloud/`) or explicitly persisted browser states (`.flowstride/sessions/`)—are written strictly to your local file system to mirror the functionality of tools like Postman. _(Note: We strongly recommend adding `.flowstride/` to your `.gitignore` to prevent accidental credential commits)._
-
-### Flowstride Enterprise: Secure Cloud Telemetry
-
-For teams using Flowstride Enterprise to aggregate multi-flow metrics, we maintain a strict metadata-only boundary.
-
-- **Metadata, Not Payloads:** When cloud sync is active, Flowstride routes only execution metadata to your team's dashboard (e.g., Workspace ID, execution duration, total steps, and pass/fail tallies). **Zero bytes** of request headers, bearer tokens, or JSON bodies are ever transmitted to Flowstride Cloud.
-
-- **Deep Debugging Stays Local:** The rich, interactive visual dashboard, including the JSON explorer and API Replay tools, runs on a dynamic, locally bound port on your machine. You get the UI of a modern cloud app with the security of a local binary.
-
-### CI/CD Leak Protection & Terminal Hygiene
-
-Standard testing frameworks do dump failing API requests, and response bodies directly into the terminal so developers can debug them. In a CI/CD environment, this is a massive security liability, as those secrets are permanently burned into plaintext Jenkins, GitHub Actions, or GitLab CI logs.
-
-Flowstride completely neutralizes this threat by architecturally separating execution output from diagnostic telemetry:
+## Execution data and Cloud integration
 
-1. **Clean Standard Output (`stdout`):** Flowstride's terminal output only displays high-level, human-readable BDD execution steps (e.g., `✔ Given "User lands on home page"` or `✖ Action Failed`). No JSON request bodies, `cURL` strings, or bearer tokens are ever printed to the terminal console.
+Tests run on your machine or CI runner. Native CI writes reports, screenshots,
+videos and attachments to the configured local artifact directory. Interactive
+API diagnostics are available in the local dashboard. These outputs can contain
+application data or credentials; automatic redaction is not guaranteed.
 
-2. **WebSocket Isolation:** All sensitive raw network data (payloads, headers, and responses) is emitted _exclusively_ over a secure, ephemeral WebSocket connection directly to the developer's local UI dashboard.
+Cloud login/licensing, FlowMail OTP retrieval and explicitly enabled Cloud
+reporting contact their configured services. Native CI leaves Cloud reporting
+off unless `cloudSync: true` is explicitly configured. Existing Cloud reporting
+and storage limitations remain documented in the preview release notes.
 
-3. **Total Evaporation:** Because CI/CD runners only capture `stdout` text and do not connect to local WebSockets, your highly sensitive diagnostic data simply evaporates the moment the pipeline execution ends. Your pipeline logs remain 100% free of plaintext secrets.
+Use test credentials, keep runtime state and artifacts out of source control,
+and choose CI artifact access and retention appropriate to the test data.
 
 ---
 

package/RELEASE_NOTES.md

@@ -0,0 +1,40 @@
+# Flowstride 1.0.20-rc.2 — npm preview
+
+Publish channel: `next`. This preview does not move `latest` and does not publish
+or replace the private Pro engine. The matching Pro candidate is `1.0.15-rc.1`.
+
+## Changes since rc.1
+
+- Require Node.js 22.12.0+ and align package, lockfile, CLI version and guides.
+- Add an explicit preview publication configuration targeting the public npm
+  registry and `next`, plus matching CLI-version/engine metadata checks.
+- Clarify preview installation, native CI/game scope and Cloud/Pro limitations.
+- Replace absolute privacy guarantees in the README with the actual data flow.
+- Rebuild the engine from the merged OSS source; reuse the unchanged dashboard
+  from the checksum-verified rc.1 archive. No runner or game behaviour changes.
+
+## Native features inherited from rc.1
+
+`flowstride run --ci`, `flowstride install [--with-deps]`,
+`flowstride ci init github`, supported plugin/game SDKs, canvas/Three.js bridges,
+Chromium desktop/phone/landscape profiles, JSON/JUnit reports and failure media,
+safe file-chooser handling and interrupted-run cleanup.
+
+## Known limits
+
+Cloud login still downloads Pro 1.0.14, which does not support these native
+commands. Test OSS alone, or authenticate first and then manually install the
+matching local Pro candidate. Project dependency installation can remove a
+no-save Pro package; install Pro afterward. Public-CLI native fallback remains
+available for absent, broken or incompatible Pro engines.
+
+Live Cloud reporting and video-storage issues are unresolved. Native CI keeps
+reporting off by default; this preview does not enable the retired managed
+runner. Application-specific game rules/fixtures remain application code.
+Physical phones, Safari/Firefox and other game engines are not qualified.
+
+## Publication
+
+Only the verified OSS archive should be published. Use the `next` tag explicitly;
+then verify `flowstride@next` and reinstall from npm in a disposable consumer.
+No npm publication is performed while preparing this candidate.

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;
@@ -25,6 +26,8 @@ export declare class WebAdapter {
     synthesizeCurl(method: string, url: string, headers: Record<string, string>, postData: string | null): string;
     private checkAmbiguity;
     close(targetText: string): Promise<void>;
+    extractText(selector: string, elementType?: string): Promise<string>;
+    extractValue(selector: string, elementType?: string): Promise<string>;
     click(selector: string, elementType?: string): Promise<void>;
     hover(selector: string, elementType?: string): Promise<void>;
     type(selector: string, value: string, elementType?: string): Promise<void>;
@@ -43,6 +46,7 @@ export declare class WebAdapter {
     expectValue(selector: string, val: string, elementType?: string): Promise<void>;
     expectTranscript(expectedText: string): Promise<void>;
     getAttribute(selector: string, attr: string, elementType?: string): Promise<string | null>;
+    private translateCoordinateSelector;
     private isRawCssSelector;
     private buildHeuristicSelector;
     private getLocator;

package/dist/adapters/web/playwright.js

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebAdapter = void 0;
+const playwright_1 = require("playwright");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const playwright_extra_1 = require("playwright-extra");
@@ -44,6 +45,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;
@@ -62,33 +64,36 @@ class WebAdapter {
             ? [
                 "--use-fake-ui-for-media-stream",
                 "--use-fake-device-for-media-stream",
-                "--disable-blink-features=AutomationControlled", // Cloudflare Mask
+                "--disable-blink-features=AutomationControlled",
             ]
             : [
                 "--window-size=1280,800",
                 "--use-fake-ui-for-media-stream",
                 "--use-fake-device-for-media-stream",
-                "--disable-blink-features=AutomationControlled", // Cloudflare Mask
+                "--disable-blink-features=AutomationControlled",
             ];
         if (audioInjectionPath) {
             launchArgs.push(`--use-file-for-fake-audio-capture=${audioInjectionPath}`);
         }
         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");
         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);
@@ -390,6 +395,18 @@ class WebAdapter {
         await this.page.mouse.up();
         await this.page.waitForTimeout(300);
     }
+    async extractText(selector, elementType) {
+        const loc = await this.getLocator(selector, elementType, false, false);
+        const targetLoc = await this.checkAmbiguity(loc, selector);
+        await targetLoc.waitFor({ state: "visible" });
+        return (await targetLoc.innerText()) || "";
+    }
+    async extractValue(selector, elementType) {
+        const loc = await this.getLocator(selector, elementType, false, false);
+        const targetLoc = await this.checkAmbiguity(loc, selector);
+        await targetLoc.waitFor({ state: "visible" });
+        return (await targetLoc.inputValue()) || "";
+    }
     async click(selector, elementType) {
         const loc = await this.getLocator(selector, elementType, false, false);
         const targetLoc = await this.checkAmbiguity(loc, selector);
@@ -402,7 +419,6 @@ class WebAdapter {
         const targetLoc = await this.checkAmbiguity(loc, selector);
         await targetLoc.waitFor({ state: "visible" });
         await targetLoc.scrollIntoViewIfNeeded();
-        // 1. Accessibility WAI-ARIA Hack (Focus)
         await targetLoc.focus({ timeout: 3000 }).catch(() => { });
         await targetLoc
             .evaluate((node) => {
@@ -410,21 +426,17 @@ class WebAdapter {
                 node.focus();
         })
             .catch(() => { });
-        // 2. Get Exact Center Coordinates for Physical Move
         let box = null;
         try {
             box = await targetLoc.boundingBox({ timeout: 3000 });
         }
-        catch (e) { } // Catch in case it mutated instantly during focus
+        catch (e) { }
         if (box) {
             const centerX = box.x + box.width / 2;
             const centerY = box.y + box.height / 2;
-            // Physically drag the mouse to the element to satisfy Hover Intent APIs
             await this.page.mouse.move(centerX, centerY, { steps: 5 });
         }
-        // 3. Playwright Native Hover Backup (Caught to prevent mutation crashes)
         await targetLoc.hover({ force: true, timeout: 3000 }).catch(() => { });
-        // 4. The Ultimate Wakeup Call: Synthesize Full Coordinate-Loaded Events
         await targetLoc
             .evaluate((node) => {
             const rect = node.getBoundingClientRect();
@@ -450,11 +462,9 @@ class WebAdapter {
             });
         })
             .catch(() => { });
-        // 5. We perform a programmatic click that won't trigger W3C navigation if handled by React toggles
         await targetLoc
             .click({ delay: 50, force: true, timeout: 3000 })
             .catch(() => { });
-        // 6. The Paint Buffer
         await this.page.waitForTimeout(600);
     }
     async type(selector, value, elementType) {
@@ -474,10 +484,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,11 +619,10 @@ class WebAdapter {
             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) {
@@ -902,7 +911,7 @@ class WebAdapter {
                 .replace(/[^\w\s]/g, "")
                 .replace(/\s+/g, " ");
             if (cleanBody.includes(cleanExpected)) {
-                return; // Assertion passed!
+                return;
             }
             await this.page.waitForTimeout(500);
         }
@@ -912,9 +921,32 @@ class WebAdapter {
         const loc = await this.getLocator(selector, elementType, true, true);
         return await loc.first().getAttribute(attr);
     }
+    translateCoordinateSelector(selector) {
+        const cleanSelector = selector.replace(/^['"]|['"]$/g, "").trim();
+        if (!cleanSelector)
+            return null;
+        const parts = cleanSelector.split(/\s+/);
+        const validTags = ["table", "tr", "th", "td"];
+        const isCoordinatePath = parts.every((part) => validTags.some((tag) => part.toLowerCase().startsWith(tag)));
+        if (!isCoordinatePath)
+            return null;
+        let translated = "";
+        for (let i = 0; i < parts.length; i++) {
+            const part = parts[i];
+            const match = part.match(/^([a-z]+)(?:\[(\d+)\])?$/i);
+            if (!match)
+                return null;
+            const tag = match[1];
+            const index = match[2] ? ` >> nth=${match[2]}` : "";
+            translated += (i > 0 ? " >> " : "") + tag + index;
+        }
+        return translated;
+    }
     isRawCssSelector(selector) {
         if (/\b(near|above|under|below|leftOf|rightOf|inside|in)\s+['"]/i.test(selector))
             return false;
+        if (selector.includes(">> nth="))
+            return true;
         if (/^[#\.\[]/.test(selector))
             return true;
         if (/^[a-zA-Z0-9]+\s*[\.\#:][a-zA-Z0-9_\-]+/.test(selector))
@@ -954,6 +986,9 @@ class WebAdapter {
             "iframe",
             "img",
             "svg",
+            "tr",
+            "th",
+            "td",
         ];
         if (htmlTags.includes(selector.toLowerCase()))
             return true;
@@ -995,27 +1030,35 @@ class WebAdapter {
         return `:is(${attributes}, ${partialActionable})`;
     }
     async getLocator(rawSelector, elementType, isForceAction = false, isAssertionOrAnchor = false, fuzzy = false) {
-        if (this.isRawCssSelector(rawSelector.trim())) {
-            let loc = this.page.locator(rawSelector);
+        const translatedRaw = this.translateCoordinateSelector(rawSelector);
+        const processingSelector = translatedRaw || rawSelector;
+        if (this.isRawCssSelector(processingSelector.trim())) {
+            let loc = this.page.locator(processingSelector);
             if (!isForceAction)
                 loc = loc.filter({ visible: true });
             return loc;
         }
-        let target = rawSelector;
+        let target = processingSelector;
         let relation = "";
         let anchor = "";
         const spatialRegex = /\b(near|above|under|below|leftOf|rightOf|inside|in)\s+(['"].*?['"])/i;
-        const match = rawSelector.match(spatialRegex);
+        const match = processingSelector.match(spatialRegex);
         if (match) {
-            target = rawSelector.substring(0, match.index).trim();
+            target = processingSelector.substring(0, match.index).trim();
             relation = match[1].toLowerCase();
             anchor = match[2];
         }
+        const translatedTarget = this.translateCoordinateSelector(target);
+        if (translatedTarget) {
+            target = translatedTarget;
+        }
         let arrayIndex = null;
-        const indexMatch = target.match(/\[(\d+)\]/);
-        if (indexMatch) {
-            arrayIndex = parseInt(indexMatch[1], 10);
-            target = target.replace(indexMatch[0], "").trim();
+        if (!translatedTarget) {
+            const indexMatch = target.match(/\[(\d+)\]/);
+            if (indexMatch) {
+                arrayIndex = parseInt(indexMatch[1], 10);
+                target = target.replace(indexMatch[0], "").trim();
+            }
         }
         const targetClean = target.replace(/^['"]|['"]$/g, "");
         const targetIsRaw = this.isRawCssSelector(targetClean);
@@ -1025,10 +1068,12 @@ class WebAdapter {
         let alternativeSelector = "";
         if (relation && anchor) {
             const anchorClean = anchor.replace(/^['"]|['"]$/g, "");
-            const anchorIsRaw = this.isRawCssSelector(anchorClean);
+            const translatedAnchor = this.translateCoordinateSelector(anchorClean);
+            const finalAnchorClean = translatedAnchor || anchorClean;
+            const anchorIsRaw = this.isRawCssSelector(finalAnchorClean);
             const anchorSelector = anchorIsRaw
-                ? anchorClean
-                : this.buildHeuristicSelector(anchorClean, undefined, true, fuzzy);
+                ? finalAnchorClean
+                : this.buildHeuristicSelector(finalAnchorClean, undefined, true, fuzzy);
             const anchorLoc = this.page.locator(anchorSelector).first();
             try {
                 if ((await anchorLoc.count()) > 0) {
@@ -1055,7 +1100,9 @@ class WebAdapter {
                     break;
                 case "inside":
                 case "in":
-                    alternativeSelector = `${anchorSelector}:has-text("${targetClean}")`;
+                    if (!anchorSelector.includes("nth=")) {
+                        alternativeSelector = `${anchorSelector}:has-text("${targetClean}")`;
+                    }
                     finalSelector = `${anchorSelector} >> ${finalSelector}`;
                     break;
             }

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;