flowstride 1.0.20 → 1.0.22

package/NATIVE_BROWSER.md

@@ -0,0 +1,381 @@
+# Native browser workflows
+
+For API/UI composition, email OTP, iframe examples, audio-to-text, tables, variables and manual testing, start with [Core Flowstride workflows](NATIVE_WORKFLOWS.md).
+
+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.
+
+Set `BASE_URL` directly in a project `.env` file when you want a common application URL. String values in native `.flow` command payloads support environment templates. The JSON configuration loader does not generally expand `{{env.NAME}}` throughout arbitrary `browserOptions`; use supported native profile options for command-time credential interpolation.
+
+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).
+
+## Assertion results and `And`
+
+Native checks `flow.assert.that`, `flow.network.expect`, `flow.download.expect`,
+`flow.stub.expect`, `flow.a11y.scan` and `flow.a11y.match` can appear under
+`Then` or `And`. State-changing browser, route and clock commands belong under
+`Given` or `When`.
+
+```flow
+Then "The login button is ready"
+  flow.assert.that {
+    "role": "button",
+    "name": "Submit",
+    "condition": "enabled",
+    "timeout": 10000
+  };
+And "The heading is visible"
+  flow.assert.that {
+    "role": "heading",
+    "name": "Welcome",
+    "condition": "visible"
+  };
+```
+
+Terminal, CI JSON/JUnit and dashboard evidence retain individual lookup and
+condition results. A failing condition does not erase successful target checks.
+Missing prerequisites and later steps are marked not evaluated / not tested.
+Expected and observed values, timeout, profile and source location explain a
+failure. These child diagnostics do not count as extra test steps.
+
+All command failures retain the original adapter error, call log and nested
+causes, plus command, file/line and relevant target/resource. This applies to
+browser actions, APIs, plugins, sessions, games, audio and email workflows.
+Timeouts are reported as observed timeouts, without inventing a root cause when
+the application does not provide one. Secrets and terminal control characters
+are protected in diagnostics.

package/NATIVE_CI.md

@@ -12,9 +12,9 @@ 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. Linux runners may require system browser dependencies; the generated GitHub workflow handles installation for its runner.
+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.
 
-Eligible Pro 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 Pro installations and falls back to OS when Pro is unavailable.
+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:
 
@@ -32,7 +32,7 @@ Malformed configuration and unsafe output paths fail before execution. Configura
 
 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; Pro executes bail runs sequentially.
+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.
 
@@ -85,9 +85,9 @@ 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.
+Sessions capture cookies, local storage, session storage and the current HTTP(S) storage origin. Local storage and session storage are 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.
+Existing cookie/local-storage snapshots remain compatible. Older snapshots with Web Storage but no origin prefer the configured application `baseUrl` (including `BASE_URL`), then an available current HTTP(S) application page. Configure the intended base URL before restoring a legacy record. Restoration merges saved keys into storage. This is a single-origin storage snapshot.
 
 ## Interactive history and debugging
 
@@ -96,3 +96,15 @@ Each completed flow tab restores its own last captured screen. Selecting an earl
 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.
+
+## Runnable core workflow examples
+
+[Core Flowstride workflows](NATIVE_WORKFLOWS.md) covers API + UI, email OTP, iFrames, audio/transcripts, tables/cells, variables and manual testing. The [shared setup](examples/native-workflows/README.md) explains the local demo application's lifecycle and CI configuration.
+
+After `npm ci` and matching browser installation, a CI job can run a named local example with:
+
+```sh
+npx --no-install flowstride run workflow-examples/api-and-ui/flows/api-and-ui.flow --ci
+```
+
+In CI, `--no-install` makes a missing local Flowstride installation fail rather than fetching a package. Ordinary interactive commands use `npx flowstride`. Configure the local app through `webServer`, and exclude `negative/` examples and unconfigured service templates from your passing CI target.

package/NATIVE_WORKFLOWS.md

@@ -0,0 +1,44 @@
+# Core Flowstride workflows
+
+Flowstride can call an API, extract data from its response, use that data in a browser, and verify the application outcome in the same `.flow` test. It also supports table/cell targeting, browser sessions, microphone input and visual manual testing.
+
+The examples below use the normal Flowstride CLI. Their small HTTP server is a local demonstration application; it does not replace the test runner.
+
+## Choose a workflow
+
+| Workflow | What you will do | Availability |
+| --- | --- | --- |
+| [API + UI in one test](examples/native-workflows/api-and-ui/README.md) | Create a user through an API, sign in through the browser, then verify backend state | OS and Cloud; Chromium, Firefox, WebKit |
+| [API + UI + email OTP](examples/native-workflows/api-ui-otp/README.md) | Use FlowMail to retrieve a delivered code and complete application authentication | Cloud; a supported inbox and an application that sends OTP email |
+| [iFrames](examples/native-workflows/iframes/README.md) | Find a readable child-frame target, assert inside an explicit frame, and extend an action with a focused plugin | OS and Cloud; Chromium, Firefox, WebKit |
+| [Audio-to-text workflows](examples/native-workflows/audio-to-text/README.md) | Inject microphone audio, drive recording controls and check the resulting transcript | OS and Cloud; audio injection requires Chromium |
+| [Tables and cells](examples/native-workflows/tables-and-cells/README.md) | Search a table, click a specific row action, extract a cell and reuse its value on another page | OS and Cloud; Chromium, Firefox, WebKit |
+| [Variables, reuse and saved sessions](examples/native-workflows/variables-and-reuse/README.md) | Reuse generated/extracted values, understand scope, and restore saved browser state | OS and Cloud; Chromium, Firefox, WebKit |
+| [Manual testing](examples/native-workflows/manual-testing/README.md) | Load a design, execute its steps, record defects/results and reopen saved history | OS and Cloud; local Manual Workspace |
+
+Start with the [shared setup](examples/native-workflows/README.md). It installs Flowstride with `npm i flowstride`, copies the examples already included in the package, and starts a loopback-only demo application. No separate starter download is required.
+
+## OS and Cloud
+
+OS works locally without an account. To connect Cloud, run:
+
+```sh
+npx flowstride login
+```
+
+Use your Cloud developer token when prompted and accept the authenticated engine installation when offered. Cloud has free accounts; availability and usage allowances depend on the workspace feature and plan. Email OTP retrieval uses the Cloud FlowMail service. The other local examples do not need a Cloud service connection.
+
+The public CLI selects a compatible, authorized Cloud engine when available and retains OS fallback. A Cloud-only command still requires its Cloud service prerequisites.
+
+## Reading and running the examples
+
+- `flows/` contains runnable examples for the shared demo application.
+- `negative/` contains deliberate failures. Run them individually and expect a nonzero exit code.
+- `templates/` contains application-specific workflows. Configure the documented application, credentials and selectors before using them.
+- Manual designs are JSON files; a human performs their actions and records the result.
+
+Run the named file from its chapter. Running the whole example tree also discovers intentional failures and service-dependent templates.
+
+Each chapter explains its prerequisites, expected result, negative check and limitations. For browser profiles, native assertions, network mocking, downloads, traces/HAR, accessibility and component testing, use [NATIVE_BROWSER.md](NATIVE_BROWSER.md). For CI, reports and games, use [NATIVE_CI.md](NATIVE_CI.md).
+
+The maintained full reference is at [docs.flowstride.io](https://docs.flowstride.io/).

package/README.md

@@ -7,7 +7,7 @@ Flowstride OS is an open source framework for browser, API and manual testing. W
 ## Requirements
 
 - Node.js 22.12 or newer.
-- Chromium installed through Flowstride for browser tests.
+- A matching Chromium, Firefox or WebKit installation for browser tests. Chromium is the default; audio-file microphone injection requires Chromium.
 
 ## Get started
 
@@ -41,6 +41,13 @@ Then "The sign-in button is visible"
 
 Replace the URL and assertion with values from your own application.
 
+## Workflow guides
+
+- [Core workflows](./NATIVE_WORKFLOWS.md): API + UI, email OTP, iFrames, audio-to-text, tables/cells, variables and manual testing.
+- [Runnable examples and local setup](./examples/native-workflows/README.md).
+- [Native browser workflows](./NATIVE_BROWSER.md): profiles, assertions, network control, downloads, traces/HAR, accessibility and components.
+- [Native CI and games](./NATIVE_CI.md).
+
 ## Native CI
 
 ```sh
@@ -67,15 +74,15 @@ For visual manual test design and execution:
 npx flowstride manual
 ```
 
-## Flowstride Pro
+## Flowstride Cloud
 
-Eligible Flowstride Cloud users install Pro through the authenticated private channel:
+Flowstride Cloud users authenticate through the private installation channel:
 
 ```sh
 npx flowstride login
 ```
 
-The OS CLI selects a compatible, authorized Pro engine when available and falls back to OS when Pro cannot be used. Pro is distributed privately.
+The OS CLI selects a compatible, authorized Cloud engine when available and falls back to OS when the Cloud engine cannot be used. The Cloud engine is distributed privately.
 
 ## Test data and artifacts
 

package/dist/adapters/api/undici.d.ts

@@ -9,14 +9,24 @@ export declare class ApiAdapter {
     private config;
     private globalHeaders;
     private onUnauthorized?;
+    private unauthorizedStatus?;
+    private refreshing;
     private lastStatus;
     private lastBody;
     private lastHeaders;
     private lastResponseTime;
     constructor(config: FlowstrideConfig);
     setGlobalHeader(name: string, value: string): void;
-    setUnauthorizedHandler(handler: () => Promise<void>): void;
+    setUnauthorizedHandler(handler: () => Promise<void>, status?: number): void;
     getState(): ApiState;
+    checkpointState(): {
+        globalHeaders: Record<string, string>;
+        status: number | null;
+        body: any;
+        headers: Record<string, string | string[] | undefined> | null;
+        responseTime: number;
+    };
+    restoreState(snapshot: ReturnType<ApiAdapter['checkpointState']>): void;
     resetState(): void;
     get(path: string, headers?: {
         key: string;

package/dist/adapters/api/undici.js

@@ -6,6 +6,8 @@ class ApiAdapter {
     config;
     globalHeaders = {};
     onUnauthorized;
+    unauthorizedStatus;
+    refreshing = false;
     lastStatus = null;
     lastBody = null;
     lastHeaders = null;
@@ -16,8 +18,12 @@ class ApiAdapter {
     setGlobalHeader(name, value) {
         this.globalHeaders[name] = value;
     }
-    setUnauthorizedHandler(handler) {
+    setUnauthorizedHandler(handler, status) {
+        if (status !== undefined && status !== 401 && status !== 403) {
+            throw new Error('Authentication refresh status must be 401 or 403.');
+        }
         this.onUnauthorized = handler;
+        this.unauthorizedStatus = status;
     }
     getState() {
         if (this.lastStatus === null) {
@@ -30,6 +36,17 @@ class ApiAdapter {
             responseTime: this.lastResponseTime,
         };
     }
+    checkpointState() {
+        return structuredClone({ globalHeaders: this.globalHeaders, status: this.lastStatus, body: this.lastBody, headers: this.lastHeaders, responseTime: this.lastResponseTime });
+    }
+    restoreState(snapshot) {
+        const data = structuredClone(snapshot);
+        this.globalHeaders = data.globalHeaders;
+        this.lastStatus = data.status;
+        this.lastBody = data.body;
+        this.lastHeaders = data.headers;
+        this.lastResponseTime = data.responseTime;
+    }
     resetState() {
         this.lastStatus = null;
         this.lastBody = null;
@@ -104,8 +121,16 @@ class ApiAdapter {
             };
         };
         let res = await makeRequest();
-        if ((res.status === 401 || res.status === 403) && this.onUnauthorized) {
-            await this.onUnauthorized();
+        if ((res.status === 401 || res.status === 403) && this.onUnauthorized &&
+            !this.refreshing && (this.unauthorizedStatus === undefined || res.status === this.unauthorizedStatus)) {
+            // A refresh can use this adapter too. Never recursively refresh its own rejection.
+            this.refreshing = true;
+            try {
+                await this.onUnauthorized();
+            }
+            finally {
+                this.refreshing = false;
+            }
             Object.assign(requestHeaders, this.globalHeaders);
             res = await makeRequest();
         }

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

@@ -1,17 +1,37 @@
-import { Page } from "playwright";
+import { BrowserContext, Page } from "playwright";
 import { FlowstrideConfig } from "../../types";
 export declare class WebAdapter {
     private config;
+    activeProfile: string;
+    private profiles;
+    private contextOptions;
+    onPageChanged?: () => Promise<void>;
+    profileNames(): string[];
+    getContext(): BrowserContext;
+    createProfile(profileName: string, options?: unknown): Promise<void>;
+    useProfile(profileName: string): Promise<void>;
+    closeProfile(profileName: string): Promise<void>;
+    beginTrace(profileName?: string, file?: string): Promise<void>;
+    endTrace(profileName?: string): Promise<string>;
+    private finishProfile;
+    checkpointProfiles(): Promise<any>;
+    restoreProfiles(snapshot: any): Promise<void>;
     pageErrors: string[];
     private browser;
     private context;
     private page;
     private discoveredPages;
     private dialogHandler;
-    private pendingSessionStorageRestore;
+    private sessionStorageRestores;
+    private get pendingSessionStorageRestore();
     private clearSessionStorageRestore;
     constructor(config: FlowstrideConfig);
     getPage(): Page;
+    getBrowserInfo(): {
+        engine: string;
+        version: string;
+        headless: boolean;
+    };
     initialise(audioInjectionPath?: string): Promise<void>;
     acceptDialog(): Promise<void>;
     rejectDialog(): Promise<void>;