flowstride 1.0.20-rc.2 → 1.0.20

package/NATIVE_CI.md

@@ -1,155 +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. 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.
+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. 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.
+
+Generate a GitHub Actions workflow explicitly:
 
 ```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
+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; Pro 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; 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.
+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 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.
+- `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.

package/README.md

@@ -1,263 +1,88 @@
 # Flowstride
 
-**The next-generation, BDD-flavored End-to-End Testing Framework.**
+Flowstride OS is an open source framework for browser, API and manual testing. Write readable `.flow` tests, inspect execution in the local dashboard, or run headlessly in CI.
 
-Flowstride OS combines the human-readable structure of Behavior-Driven Development (BDD) with the raw execution power of Playwright. It allows QA engineers and developers to write robust, maintainable UI and API tests using an intuitive domain-specific language (DSL), while providing a rich, interactive React dashboard to monitor, debug, and replay test runs in real time.
+[Documentation](https://docs.flowstride.io/) · [Flowstride Cloud](https://cloud.flowstride.io/)
 
-[Documentation](https://docs.flowstride.io/)
+## Requirements
 
-## Native CI and game testing preview — 1.0.20-rc.2
+- Node.js 22.12 or newer.
+- Chromium installed through Flowstride for browser tests.
 
-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:
+## Get started
 
-```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?
-
-Traditional E2E frameworks force you to choose between highly technical code (which non-developers struggle to read) or rigid low-code tools (which lack flexibility). Flowstride bridges the gap:
-
-- **Plain-English Selectors**: Target elements spatially (`"Submit" near "Cancel"`) or by text, eliminating brittle CSS/XPath dependencies.
-- **Unified UI & API Testing**: Execute browser actions and REST/GraphQL API calls within the exact same scenario.
-- **Live Visual Dashboard**: Watch your tests run step-by-step, inspect DOM snapshots, trace network activity, and manually replay API requests directly from the UI.
-- **Built-in State Management**: Save and inject browser sessions (cookies, local storage) with a single command to bypass repetitive login steps.
-
----
-
-## Installation & Quick Start
-
-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):**
-
-```bash
-npm i flowstride --save-dev
-```
-
-**2. Initialize a new Flowstride workspace:**
+Install Flowstride in your project:
 
-```bash
+```sh
+npm install --save-dev flowstride
 npx flowstride init
+npx flowstride run flows/example.flow
 ```
 
-_(This creates the default directory structure (`/flows`, `/reports`, `/plugins`) and generates a `example.flow` sample file.)_
-
-**3. Install VS Code Extension (Highly Recommended):**
-
-To get the best developer experience, including syntax highlighting, auto-completion, and native IDE support for .flow files, install our official VS Code extension directly via the VS Code CLI.
+`init` creates the project folders and an example flow, and installs Chromium. You can also install the matching browser explicitly:
 
-Run the command below:
-
-```bash
-code --install-extension flowstride.flowstride-vscode
+```sh
+npx flowstride install
 ```
 
-_Alternatively, you can open the Extensions tab in VS Code and search for Flowstride Automation_
+An example flow:
 
-**4. Run your first test:**
+```text
+Feature: Home page
 
-```bash
-npx flowstride run
+Scenario: Show the sign-in form
 
-OR
+Given "Open the application"
+  flow.open "https://your-application.example/login";
 
-npx flowstride run flows/example.flow
+Then "The sign-in button is visible"
+  flow.expect visible "Sign in";
 ```
 
-_(This command executes your test while instantly booting up the local Flowstride Dashboard.)_
-
-**5. Login to Flowstride Cloud:**
+Replace the URL and assertion with values from your own application.
 
-Authenticate your local project with your Cloud account to unlock Cloud features after signing up at [cloud.flowstride.io](https://cloud.flowstride.io).
+## Native CI
 
-```bash
-npx flowstride login
+```sh
+npx flowstride run flows --ci
 ```
 
----
-
-## Execution data and Cloud integration
-
-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.
-
-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.
-
-Use test credentials, keep runtime state and artifacts out of source control,
-and choose CI artifact access and retention appropriate to the test data.
-
----
+CI runs headlessly, returns a nonzero exit code for failed or interrupted execution, and writes JSON and JUnit reports to `flowstride-artifacts` by default. Screenshots, videos and attachments are associated with their run.
 
-## The `.flow` Syntax
-
-Flowstride utilizes a custom `.flow` file extension. It seamlessly pairs descriptive BDD steps (Given, When, And, Then) with direct, executable `flow.` commands.
-
-Here is an example of a standard UI and API flow:
-
-```bash
-// Signing up a new user via API call.
-Given "User signup via API call"
-  flow.post "/api/signup" with reqBody
-  """
-  {
-      "firstName": "Mike",
-      "lastName": "Doe",
-      "dob": "1995-05-10",
-      "sex": "male",
-      "email": "user@flowstridemail.com",
-      "password": "$randomPassword"
-  }
-  """
-  flow.extract resBody "userId" as "newUserId"
-  flow.expect status "201"
-
-// Approving the new user from admin via API call
-When "A new signup user is approved by the Admin"
-  flow.post "/api/approve" with reqBody
-  """
-  {
-      "userId": "@newUserId"
-  }
-  """
-
-And "Confirm Status Code is 200"
-  flow.expect status "200"
-
-And "Confirm resBody message is successful"
-  flow.expect resBody "message" equals "User approved successfully"
-
-And "Confirm user status to be active"
-  flow.expect resBody "user.status" equals "active"
-
-// Using the newly registered user credentials to login via the UI
-When "User lands on home page"
-  flow.open "/login"
-
-And "User clicks on Log in, near Sign Up"
-  flow.click "Log in" near "Sign up"
-
-And "User inputs newly created credentials"
-  flow.type "Email" "user@flowstridemail.com"
-  flow.type "Password" "@randomPassword" // Reusing the random password from API call
-
-Then "Click on Login button"
-  flow.click button "Login"
+To generate a GitHub Actions workflow in an npm project with a committed lockfile:
 
+```sh
+npx flowstride ci init github
 ```
 
----
-
-## Command Reference
-
-### Browser Navigation & Context
-
-| Command    | Example                        | Description                                                      |
-| :--------- | :----------------------------- | :--------------------------------------------------------------- |
-| `open`     | `flow.open "https://site.com"` | Navigates the browser to the specified URL.                      |
-| `switchTo` | `flow.switchTo "next"`         | Switches to a new tab or window by title/URL or relation.        |
-| `close`    | `flow.close "Modal Title"`     | Geometrically calculates and clicks the close button of a modal. |
-
-### UI Actions
+Workflow generation is explicit; package installation does not create a workflow. See [NATIVE_CI.md](./NATIVE_CI.md) for configuration and browser-game testing.
 
-| Command      | Example                                   | Description                                                     |
-| :----------- | :---------------------------------------- | :-------------------------------------------------------------- |
-| `click`      | `flow.click "Submit"`                     | Clicks an element based on text, CSS, or spatial relation.      |
-| `forceClick` | `flow.forceClick "#hidden-btn"`           | Bypasses Playwright's actionability checks to force a click.    |
-| `type`       | `flow.type "Email" "test@test.com"`       | Types value into an input field matching the target.            |
-| `passcode`   | `flow.passcode "OTP" "123456"`            | Specifically handles split OTP/Passcode input arrays.           |
-| `select`     | `flow.select "Option 1" from "Dropdown"`  | Selects an option from a native select or custom portal.        |
-| `check`      | `flow.check "Terms and Conditions"`       | Checks a checkbox or radio button.                              |
-| `upload`     | `flow.upload "Avatar" "path/to/file.jpg"` | Uploads a local file to a file input element.                   |
-| `drag`       | `flow.drag "Item A" into "Zone B"`        | Drags a source element and drops it into a destination element. |
+## Local dashboard and manual testing
 
-### Assertions
+Interactive runs open a dashboard for execution, per-flow screen history, network inspection and API Replay. The local cURL preview remains redacted; its Copy control copies the original captured request when it is still available in the interactive debugger.
 
-| Command          | Example                                | Description                                            |
-| :--------------- | :------------------------------------- | :----------------------------------------------------- |
-| `expect visible` | `flow.expect visible "Success"`        | Asserts an element is attached to the DOM and visible. |
-| `expect text`    | `flow.expect text "Error"`             | Asserts specific text is present in the UI.            |
-| `expect value`   | `flow.expect value "Username" "admin"` | Asserts the input value of a targeted field.           |
+For visual manual test design and execution:
 
-### Session Management
-
-| Command        | Example                    | Description                                                                   |
-| :------------- | :------------------------- | :---------------------------------------------------------------------------- |
-| `save session` | `flow.save session "Auth"` | Captures current cookies/storage into memory (add `persist` to save to disk). |
-| `use session`  | `flow.use session "Auth"`  | Injects previously saved cookies/storage directly into the browser.           |
-
-### API Testing
-
-| Command                        | Example                                       | Description                                                        |
-| :----------------------------- | :-------------------------------------------- | :----------------------------------------------------------------- |
-| `get`, `post`, `put`, `delete` | `flow.post "/api/users" with reqBody "{...}"` | Executes HTTP requests natively via Undici.                        |
-| `extract`                      | `flow.extract resBody "token" as "jwt"`       | Parses API responses and saves data to a local or global variable. |
-| `expect status`                | `flow.expect status "200"`                    | Asserts the HTTP status code of the last API call.                 |
-
-_(For a complete list of commands, API assertions, and plugin integration rules, please see the official documentation)._
-
----
-
-## Interactive Dashboard
-
-Running a `.flow` file automatically boots the Flowstride Dashboard.
-
-- **Live Execution:** Watch tests execute in real-time with an integrated screencast.
-- **Step Diagnostics:** Click on any step (Pass or Fail) to view exact execution context, error stack traces, and a DOM snapshot with the target element highlighted.
-- **Network Interception:** View all intercepted XHR/Fetch requests. You can click **Replay** on any API log to independently re-execute the request from the Node.js backend natively.
-- **Soft Kill & Rerun:** Use the top navigation bar to seamlessly abort running tests, clear state, and restart execution without touching the terminal.
-
----
-
-## Flowstride OS vs. Enterprise
+```sh
+npx flowstride manual
+```
 
-**Flowstride OS** is free, fully featured, and highly capable for individual developers and standard QA teams.
+## Flowstride Pro
 
-**Flowstride Enterprise** (`flowstride.io`) unlocks advanced capabilities for massive-scale automation:
+Eligible Flowstride Cloud users install Pro through the authenticated private channel:
 
-- **Distributed Parallel Execution Grid**: Run thousands of tests simultaneously across dynamically spun-up workers.
-- **AI Auto-Healing**: Let AI automatically fix broken or outdated selectors during test execution based on DOM analysis.
-- **Automated FlowMail (OTP/2FA)**: Fully native email extraction (`flow.getOtp`) to bypass complex 2FA flows.
-- **High-Fidelity PDF Exports**: Programmatic, C-suite ready PDF report generation.
-- **Cloud Storage & History**: Store all your test runs in the cloud to access and reference them at any time.
-- **Native Integrations**: Seamlessly connect your testing workflows directly with Jira and Slack.
-- **Massive Team Collaboration**: Scale your operations by connecting with 70+ team members in a shared workspace.
+```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.
 
-## Contributing
+## Test data and artifacts
 
-We welcome contributions from the community! Whether you are fixing bugs, proposing new features, or improving documentation, please feel free to open an issue or submit a Pull Request.
+Flowstride redacts recognized credentials in logs and reports. Redaction cannot guarantee removal of arbitrary application data, and screenshots or videos can contain sensitive information. Use appropriate test data and restrict access to artifacts, persisted sessions and raw requests copied for debugging.
 
-When submitting a PR, please ensure you test your changes against the core parser (`src/parser/`) and the Playwright web adapter (`src/adapters/web/`).
+Keep `.flowstride/` and `flowstride-artifacts/` out of version control. CI Cloud reporting is disabled by default and requires explicit configuration and valid credentials.
 
 ## License
 
-This project is licensed under the [MIT License](LICENSE).
+MIT.

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

@@ -8,6 +8,8 @@ export declare class WebAdapter {
     private page;
     private discoveredPages;
     private dialogHandler;
+    private pendingSessionStorageRestore;
+    private clearSessionStorageRestore;
     constructor(config: FlowstrideConfig);
     getPage(): Page;
     initialise(audioInjectionPath?: string): Promise<void>;
@@ -15,11 +17,12 @@ export declare class WebAdapter {
     rejectDialog(): Promise<void>;
     injectAudio(filePath: string): Promise<void>;
     switchTo(target: string): Promise<void>;
-    injectStorage(cookies?: any[], localStorage?: Record<string, string>, fallbackDomain?: string): Promise<void>;
+    injectStorage(cookies?: any[], localStorage?: Record<string, string>, fallbackDomain?: string, sessionStorage?: Record<string, string>, storageOrigin?: string): Promise<void>;
     getState(): Promise<{
         cookies: any[];
         localStorage: Record<string, string>;
         sessionStorage: Record<string, string>;
+        storageOrigin?: string;
     }>;
     getCurrentUrl(): string;
     navigate(url: string): Promise<void>;