flowstride 1.0.20-rc.6 → 1.0.21

package/NATIVE_BROWSER.md

@@ -0,0 +1,341 @@
+# Native browser workflows
+
+OS and Cloud support these commands directly in `.flow` files. Existing commands, plugins and saved sessions continue to work. Use `flow.<area>.<action>` followed by a JSON object. Unknown actions and options fail explicitly.
+
+Keep both engine installations current when using these features. If an installed Cloud engine lacks the required capability protocol, the public runner warns and uses OS fallback for the run. Existing commands can still use an older compatible Cloud engine; Cloud-only services require a compatible Cloud installation.
+
+## Separate users in one test
+
+A **profile** is an independent browser context: its cookies, local storage, session storage, pages and permissions are separate. The original profile is named `default`. Creating a profile selects it; switching profiles returns to the page that user was using.
+
+```flow
+flow.browser.create {
+  "name": "customer",
+  "options": {
+    "locale": "en-GB",
+    "colorScheme": "dark"
+  }
+};
+flow.open "/login";
+flow.type input "Email" "{{env.CUSTOMER_EMAIL}}";
+flow.type input "Password" "{{env.CUSTOMER_PASSWORD}}";
+flow.click button "Sign in";
+flow.browser.create {
+  "name": "admin"
+};
+flow.open "/admin/login";
+flow.browser.use {
+  "name": "customer"
+};
+```
+
+`flow.save session "customer" persist;` still saves a snapshot of the **currently selected** profile. `flow.use session "customer";` still injects a saved snapshot into the current profile. Saving a snapshot does not create another live user. Sequential customer/admin scenarios remain valid without profiles; use profiles when the users must stay independently logged in.
+
+`flow.browser.close` closes a named profile. The `default` profile remains available until file completion. Profiles are reset between files. `flow.switchTo` still selects tabs within the current profile.
+
+## Browser selection and settings
+
+```sh
+npx flowstride install chromium firefox webkit
+npx flowstride run flows --browser firefox --ci
+```
+
+Use `--browser firefox` or `--browser webkit` to select the test engine. The terminal prints the verified engine and version after launch; the dashboard shows **Test browser**, and CI's `summary.json` includes the actual engine for each file. `install` downloads browser binaries and does not open a browser window.
+
+Interactive runs display the dashboard in a separate Firefox or WebKit window when either engine is selected. The dashboard remains in the system default browser for Chromium runs. Test pages run headlessly by default; add `--headed` to see the application's own browser window:
+
+```sh
+npx flowstride run flows --browser firefox --headed
+npx flowstride run flows --browser webkit --headed
+```
+
+CI forces headless execution and opens no dashboard. Firefox and WebKit keep their native user-agent unless you explicitly configure `browserOptions.userAgent`. WebKit is Safari's engine, rather than the installed Safari application.
+
+Chromium remains the default. Browser installation must match the installed Flowstride package. In Linux CI, add `--with-deps` to the install command. Browser support does not mean every operating-system/browser/device combination is qualified. Firefox does not support Playwright's mobile emulation setting; phone profiles use its viewport/touch settings without that flag. Chromium-specific game touch and audio-file injection still require Chromium.
+
+```json
+{
+  "browser": "chromium",
+  "browserOptions": {
+    "locale": "en-GB",
+    "timezoneId": "Europe/London",
+    "colorScheme": "dark",
+    "permissions": ["geolocation"],
+    "geolocation": {
+      "latitude": 6.5244,
+      "longitude": 3.3792
+    },
+    "serviceWorkers": "block"
+  }
+}
+```
+
+Validated settings include viewport/screen, device scale, touch/mobile emulation, locale/timezone, color/contrast/motion, JavaScript, HTTPS handling, CSP bypass, permissions/geolocation, offline mode, headers, HTTP credentials, proxy, downloads, strict selectors, storage state and project-local client certificate paths. Use `browserOptions` for the default profile and `options` in `flow.browser.create` for a separate profile. Secrets belong in environment variables or private local files.
+
+Runtime commands include `flow.browser.offline` with `value`, `flow.browser.permissions` with `permissions` and optional `origin`, `flow.browser.clearPermissions`, and `flow.browser.geolocation` with latitude/longitude. Recording paths are controlled by evidence settings, rather than arbitrary browser path options. JavaScript logger callbacks are not JSON DSL settings.
+
+## Assertions that wait for a condition
+
+```flow
+flow.assert.that {
+  "selector": "#order-status",
+  "condition": "text",
+  "value": "Approved",
+  "timeout": 10000
+};
+flow.assert.that {
+  "role": "button",
+  "name": "Submit",
+  "condition": "enabled"
+};
+flow.assert.that {
+  "selector": ".loading",
+  "condition": "visible",
+  "not": true
+};
+```
+
+Choose one CSS/Playwright `selector` or accessible `role` with an optional exact `name`. An optional `frame` selects an iframe. Conditions include:
+
+| Conditions | Expected input |
+| --- | --- |
+| `visible`, `hidden`, `attached`, `enabled`, `disabled`, `editable`, `checked`, `empty`, `focused`, `inViewport` | No value |
+| `text`, `containsText`, `value`, `id`, `accessibleName`, `accessibleDescription` | `value`, or `matches` and optional regex `flags` |
+| `values` | Array of selected option values |
+| `count` | Nonnegative integer `value` |
+| `attribute` | `attribute`; optional expected `value`; omit it to check presence |
+| `css`, `property` | `property` and expected `value` |
+| `url`, `title` | Expected `value` or regex `matches`; no selector needed |
+| `localStorage`, `sessionStorage` | `key` and expected string `value`, or `null` for absence |
+
+Text comparisons normalize whitespace. Assertions retry until `timeout` or the configured default; they do not repeatedly click or repeat requests. Existing `flow.expect` syntax remains supported.
+
+## Mock requests and wait for network events
+
+Use `serviceWorkers: "block"` when mocking an application that registers service workers. Mocking applies to browser traffic in the current profile; it does not intercept `flow.get` or other direct API commands.
+
+```flow
+flow.network.route {
+  "name": "customer-response",
+  "url": "**/api/customer",
+  "method": "GET",
+  "json": {
+    "name": "Documentation Reader"
+  },
+  "times": 1
+};
+flow.network.arm {
+  "name": "customer-request",
+  "url": "**/api/customer",
+  "kind": "response"
+};
+flow.click button "Load customer";
+flow.network.wait {
+  "name": "customer-request"
+};
+flow.network.expect {
+  "name": "customer-request",
+  "status": 200,
+  "path": "name",
+  "equals": "Documentation Reader"
+};
+```
+
+**Arm before the trigger, then wait.** This captures fast responses and prevents an unobserved timeout while a click is still finishing. Waiters are cleaned up on retry, file completion and shutdown.
+
+Routes accept one of `json`, text `body`, or a project-local `fixture`. Optional `status`, `headers`, `contentType`, `method` and positive `times` control the response. URL patterns support `*` within a path segment and `**` across segments.
+
+| Route `mode` | Behavior |
+| --- | --- |
+| `fulfill` (default) | Supply the configured response |
+| `abort` | Block the matching request |
+| `continue` | Send the real request; optional `request` changes URL, method, headers or body |
+| `patch` | Fetch the real response and merge configured JSON fields or replace its text body |
+
+Remove a route with `flow.network.unroute` and its `name`. Rules and captured events belong to the selected profile. `network.arm` also supports `kind: "request"`, a method, response status filter and timeout. `network.expect` checks status/method and captured body paths or a response/request `header`, using `equals` or `contains`.
+
+## Downloads
+
+```flow
+flow.download.arm {
+  "name": "invoice"
+};
+flow.click link "Download invoice";
+flow.download.save {
+  "name": "invoice",
+  "file": "downloads/invoice.json"
+};
+flow.download.expect {
+  "name": "invoice",
+  "filename": "invoice.json",
+  "minSize": 1,
+  "json": {
+    "paid": true
+  }
+};
+```
+
+The destination must stay inside the project and must not already exist. Assertions support the suggested `filename`, exact `size`, `minSize`, text `contains`, exact `json`, and a SHA-256 `sha256`. Content assertions have a size limit; use size/hash checks for larger downloads. Downloads do not need a custom plugin.
+
+## Control time and observe functions
+
+```flow
+flow.clock.install {
+  "time": "2026-01-01T00:00:00Z"
+};
+flow.open "/timer";
+flow.clock.runFor {
+  "milliseconds": 5000
+};
+```
+
+Clock commands include `pauseAt`, `resume`, `runFor`, `fastForward`, `setFixedTime` and `setSystemTime`. Date operations accept `time`; advancing accepts `milliseconds`. Install the clock before the application installs its timers. Time control affects the browser page, not the backend or operating-system clock.
+
+```flow
+flow.stub.install {
+  "name": "analytics",
+  "target": "analytics.track",
+  "mode": "spy"
+};
+flow.click button "Purchase";
+flow.stub.expect {
+  "name": "analytics",
+  "count": 1,
+  "args": ["purchase"]
+};
+flow.stub.restore {
+  "name": "analytics"
+};
+```
+
+A spy records calls and invokes the original function. Modes `return` and `throw` replace it with a configured `value` or `error`; `async: true` returns a promise. `beforeLoad: true` installs on the next document, for functions available before application initialization. It cannot replace a function that does not yet exist. `stub.expect` accepts `count`, `minCount`, arguments and timeout. Doubles belong to a page and are restored on cleanup.
+
+## Traces, HAR and DOM evidence
+
+```json
+{
+  "trace": true,
+  "har": true,
+  "domSnapshots": true,
+  "browserOptions": {
+    "serviceWorkers": "block"
+  }
+}
+```
+
+Trace ZIPs include browser actions, DOM snapshots and screenshots. HAR files capture HTTP requests and responses and finalize when their browser context closes. Evidence files include flow/profile names; retries retain earlier attempt videos/traces. A trace records browser operations; Flowstride assertion results and attempts are in `summary.json`.
+
+Use `flow.trace.start` (optional `name`) and `flow.trace.stop` for an explicitly bounded trace instead of automatic `trace: true`. Open a local ZIP with:
+
+```sh
+npx flowstride trace flowstride-artifacts/example-trace.zip
+```
+
+HAR replay uses a local recorded file:
+
+```flow
+flow.har.replay {
+  "file": "fixtures/customer.har",
+  "notFound": "abort"
+};
+flow.open "/customer";
+```
+
+An optional `url` limits matching; `notFound: "fallback"` allows unmatched real requests. Replay does not restore application databases or a WebSocket session.
+
+The dashboard preserves each step's profile and attempt, lets you choose earlier attempt screenshots, and links to optional DOM snapshots. DOM files are served as inert text. They do not rewind the live application or execute an earlier page.
+
+Traces, HAR, downloaded files and DOM/accessibility snapshots can contain application secrets or personal data. They remain local artifacts; these new formats are not automatically uploaded to Cloud. Choose private CI artifacts and an appropriate retention period.
+
+## Accessibility and ARIA baselines
+
+```flow
+flow.a11y.scan {
+  "name": "checkout",
+  "include": ["main"],
+  "tags": ["wcag2a", "wcag2aa"]
+};
+flow.a11y.snapshot {
+  "name": "checkout",
+  "selector": "main",
+  "baseline": "baselines/checkout.aria.yml"
+};
+```
+
+Scans use axe, write a structured report, and fail on violations by default. Options include `exclude`, explicit `rules`, `disableRules`, selected `impacts`, and `maxViolations`. Automated scans cover only part of accessibility; keyboard and assistive-technology review remain necessary.
+
+Snapshots compare the complete selected accessibility tree with a reviewed YAML baseline. `flow.a11y.match` compares an inline `yaml` string with the complete captured tree and retries until timeout. These are exact tree comparisons, not Playwright Test's partial snapshot matcher.
+
+Create or deliberately update a baseline locally with `--update-baselines`; the snapshot command must specify `baseline`. CI refuses updates. Review baseline changes before accepting them. To capture evidence without comparing or writing a baseline, omit `baseline`.
+
+## Component tests
+
+Flowstride starts and cleans up a local Vite harness. Keep your normal application framework packages installed in the project. Supported integrations are vanilla JavaScript factories, React components and Vue single-file components. Other frameworks need a dedicated integration and qualification.
+
+```flow
+flow.component.mount {
+  "framework": "react",
+  "module": "src/components/AccountButton.tsx",
+  "export": "default",
+  "props": {
+    "label": "Open account"
+  }
+};
+flow.click button "Open account";
+flow.assert.that {
+  "selector": "button",
+  "condition": "text",
+  "value": "Account opened"
+};
+flow.component.update {
+  "props": {
+    "label": "Updated account"
+  }
+};
+flow.component.unmount {};
+```
+
+An optional `css` array imports project styles. Supply required application providers through a small test component wrapper. The harness does not load your application Vite configuration, framework router, backend or production build automatically. Vanilla exports receive `(target, props)` and can return a DOM node or an object with `unmount()`.
+
+## Scenario retries and flaky outcomes
+
+```json
+{
+  "retries": 1,
+  "failOnFlaky": true
+}
+```
+
+Retries are disabled by default. A retry reruns the entire failed scenario, restores its starting browser profiles/storage and local variables, and retains previous attempt diagnostics. A later pass is marked `flaky`; `failOnFlaky` turns it into a failing CI outcome. Bail takes effect after the final failed attempt.
+
+Retries cannot undo backend writes, emails, payments, persistent files, or other external effects. Use idempotent test data and explicit application fixtures. Keep retries low while investigating unstable tests.
+
+## Browser matrices and multiple CI machines
+
+```sh
+npx flowstride ci init github --browsers chromium,firefox,webkit --shards 3
+```
+
+The generated workflow creates separate CI jobs with unique evidence names. It uses normal CI runners. Review project dependency/secrets setup as usual. Cancellation stops that job and records an interrupted result; it does not delete other machines' evidence.
+
+```sh
+npx flowstride run flows --ci --shard 1/3
+npx flowstride run flows --ci --shard 2/3
+npx flowstride run flows --ci --shard 3/3
+```
+
+Run each command on its assigned machine. Preserve its `summary.json` beside its `run-*` evidence folder. Collect all shards for **one browser configuration** into separate project directories and merge:
+
+```sh
+npx flowstride merge shard-1/summary.json shard-2/summary.json shard-3/summary.json
+```
+
+Merging rejects missing/duplicate shards, mixed source suites and mixed browser configurations. A failed or interrupted shard cannot become a passing merge. Setup `.first.flow` files execute independently on every machine, so setup must be safe to repeat. Metrics count actual shard executions, including repeated setup work.
+
+For later runs, use `--shard-history path/to/timings.json` from a previous complete merge. Every machine must use the same file: history assigns longer files first while preserving deterministic, disjoint standard-file coverage. There is no hosted scheduling service or shared in-memory state between machines.
+
+## Browser compatibility notes
+
+Chromium's current stealth behavior can override an explicitly requested locale. Use Firefox or WebKit for locale-sensitive checks and verify the observed language. For HAR playback in Firefox/WebKit, leave forced browser-offline mode unset and stop the real server to verify the recording; combining forced offline mode and HAR can reject navigation before fulfillment.
+
+The maintained command reference, browser compatibility guide and API-to-UI examples are available in the [Flowstride documentation](https://docs.flowstride.io/guide/native-browser-workflows).

package/NATIVE_CI.md

@@ -1,179 +1,98 @@
-# Native CI and browser-game candidate
+# Native CI and browser-game testing
 
-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.
+Flowstride runs `.flow` tests locally and in CI without a custom runner wrapper.
 
-The candidates pin Playwright 1.59.1 in both engines; the native install command
-installs that engine's matching Chromium.
+## Installation and execution
 
-## Local candidate check
+Use Node.js 22.12 or newer. Install Flowstride as a project dependency and commit the lockfile:
 
-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 flowstride
+npx flowstride install
+npx flowstride run flows --ci
+```
+
+In CI, use `npm ci` before browser installation and test execution. Browser installation uses the Chromium version matching the installed Flowstride engine by default. See [native browser workflows](NATIVE_BROWSER.md) for Firefox, WebKit and browser configuration. Linux runners may require system browser dependencies; the generated GitHub workflow handles installation for its runner.
+
+Cloud users authenticate using `npx flowstride login`. In CI, supply the developer token through the `FLOWSTRIDE_TOKEN` secret, never in committed files. Install project dependencies before login, then install the matching browser and run the tests. The OS CLI uses compatible, authorized Cloud engine installations and falls back to OS when the Cloud engine is unavailable.
+
+Generate a GitHub Actions workflow explicitly:
 
 ```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
+npx flowstride ci init github
+```
+
+The command requires an npm project with a committed lockfile and refuses to overwrite an existing workflow. It does not run automatically during installation.
+
+## Configuration and reports
+
+`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. Configuration, plugin, environment, upload, session and output paths must remain inside the project, including resolved symlinks.
+
+Native CI is selected by `--ci` or a recognized CI environment. It runs headlessly without a dashboard server and returns nonzero for failed, incomplete, crashed or interrupted execution. JSON and JUnit reports are written at the configured artifact root, which defaults to `flowstride-artifacts`. Media and attachments use a unique run directory referenced by the summary.
+
+Flow discovery is recursive. `.first.flow` files run before ordinary files. A failed scenario leaves its remaining steps untested and execution continues to later scenarios. `--bail` stops later work; the Cloud engine executes bail runs sequentially.
+
+An optional configured local web server is started and stopped with the run. Flowstride rejects a readiness URL that is already serving.
+
+Cloud reporting is disabled by default in native CI. Set `cloudSync: true` to enable authenticated reporting. Reporting and video status are recorded separately in the summary and `.flowstride/cloud-sync.json`; a reporting failure does not change a passed test into a failed test.
+
+## Browser-game actions
+
+Register the built-in alias:
+
+```text
+let game = "flowstride:game";
 ```
 
-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.
+The built-in game API provides:
+
+- `tap`: canvas selector and coordinates; relative coordinates by default, or `unit: "pixels"`.
+- `drag` and `swipe`: canvas, start/end 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.
+- `snapshot` and `expectVisual`: canvas comparison with explicit change thresholds.
+- `state` and `expectState`: exposed application state with optional dotted paths.
+- `snapshotState` and `expectPreserved`: compare selected state across actions or reloads.
+- `fixture`: a named fixture explicitly registered by the application in test mode.
+- `select`: a stable object ID resolved by a game bridge, followed by real pointer input.
+
+The package includes a small runnable example in `examples/native-game`. Its HTTP server serves the fixture application; it is not a custom test runner. Use your application's normal start command for your own game.
+
+Visual checks measure pixel differences. Pair them with state or UI assertions to verify gameplay behavior. Mobile profiles emulate Chromium devices; physical device testing is a separate qualification. Touch dragging currently uses Chromium CDP.
+
+## Application bridges
+
+For a generic browser game, import `registerGame` from `flowstride/dist/game/bridge.js`. Supply `readState` and optional test-only fixtures.
+
+For Three.js, import `registerThreeGame` from `flowstride/dist/game/three-bridge.js`. Register the live scene, camera, canvas, your application's `Vector3` and `Raycaster` constructors, and an optional map of stable object IDs. Alternatively, assign `userData.flowstrideId` to scene objects. Optional local pick points use `userData.flowstridePickPoint: [x, y, z]`.
+
+The bridge projects 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 replacing the scene.
+
+Application fixtures are available only when explicitly registered with `testMode: true`. Enable this in dedicated test builds, never public production builds. Your application still defines its own rules, observable state and fixtures.
+
+Custom plugins receive `sdk.game`, `sdk.browser.page()` and `sdk.run`, including artifact attachment support, alongside the existing SDK.
+
+## Assertions and browser sessions
+
+```text
+flow.expect attribute "#order" "data-state" "approved";
+flow.expect attribute "#order" "class" contains "selected";
+flow.save session "browser" persist;
+flow.use session "browser";
+```
+
+Attribute comparisons wait up to the configured timeout. Exact matching is case-sensitive; `contains` checks a substring. Missing attributes fail even when the expected value is empty.
+
+Sessions capture cookies, local storage, session storage and the current HTTP(S) storage origin. Session storage is restored immediately on the matching origin or before its first matching navigation. It is not seeded into unrelated origins. The initial seed is then removed so later application changes and reloads are preserved.
+
+Existing cookie/local-storage snapshots remain compatible. Older snapshots with session storage but no origin use the current application origin or configured `baseUrl`; open the application first or set `baseUrl` if neither is available. Restoration merges saved keys into storage. This is a single-origin storage snapshot.
+
+## Interactive history and debugging
+
+Each completed flow tab restores its own last captured screen. Selecting an earlier step remembers a separate history cursor for that file. Flows without screenshots show an empty state. New runs clear previous screens and cursors.
+
+The local cURL preview remains `[REDACTED]`. Copy uses the original captured request held in interactive debugger memory. Already-redacted historical data cannot be recovered. CI and Cloud reports retain redaction.
+
+Review artifact access and test data: credential redaction does not remove every possible application secret, and screenshots or videos can show sensitive information.