flowstride 1.0.20-rc.6 → 1.0.20

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. 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.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; 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; 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.

package/README.md

@@ -1,256 +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
 
----
+- Node.js 22.12 or newer.
+- Chromium installed through Flowstride for browser tests.
 
-## Why Flowstride?
+## Get started
 
-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:
+Install Flowstride in your project:
 
-- **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 18 or higher.
-
-**1. Install globally (or as a dev dependency in your project):**
-
-```bash
-npm i flowstride --save-dev
-```
-
-**2. Initialize a new Flowstride workspace:**
-
-```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.
-
-Run the command below:
+`init` creates the project folders and an example flow, and installs Chromium. You can also install the matching browser explicitly:
 
-```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
 ```
 
----
-
-## Privacy & Data Security
-
-Flowstride is designed with a **zero-trust, local-first architecture**. Whether you are testing internal microservices, staging environments, or production APIs, your sensitive data, PHI, and credentials remain strictly on your infrastructure.
-
-### Open Source Core: 100% Local Isolation
-
-The Open Source version of Flowstride operates entirely as an ephemeral, local execution engine.
-
-- **Air-Gapped Execution:** Flowstride does not "phone home." The OS runner executes strictly on your local machine or within your private CI/CD pipeline. There is no external Flowstride database storing your test payloads or network logs.
-
-- **Ephemeral Memory:** Flowstride is inherently stateless. API request headers, response bodies, and DOM snapshots exist only in Node.js RAM during execution. The millisecond the execution process terminates, all memory is wiped.
-
-- **The DevTools Analogy:** Our network interception works natively within Playwright's browser context routing. It is fundamentally identical to opening the Chrome DevTools "Network" tab locally. We do not act as an external Man-In-The-Middle (MITM) proxy.
-
-- **Opt-In Local State:** Artifacts saved to disk—such as execution videos (`.flowstride/mock-cloud/`) or explicitly persisted browser states (`.flowstride/sessions/`)—are written strictly to your local file system to mirror the functionality of tools like Postman. _(Note: We strongly recommend adding `.flowstride/` to your `.gitignore` to prevent accidental credential commits)._
-
-### Flowstride Enterprise: Secure Cloud Telemetry
-
-For teams using Flowstride Enterprise to aggregate multi-flow metrics, we maintain a strict metadata-only boundary.
-
-- **Metadata, Not Payloads:** When cloud sync is active, Flowstride routes only execution metadata to your team's dashboard (e.g., Workspace ID, execution duration, total steps, and pass/fail tallies). **Zero bytes** of request headers, bearer tokens, or JSON bodies are ever transmitted to Flowstride Cloud.
-
-- **Deep Debugging Stays Local:** The rich, interactive visual dashboard, including the JSON explorer and API Replay tools, runs on a dynamic, locally bound port on your machine. You get the UI of a modern cloud app with the security of a local binary.
-
-### CI/CD Leak Protection & Terminal Hygiene
-
-Standard testing frameworks do dump failing API requests, and response bodies directly into the terminal so developers can debug them. In a CI/CD environment, this is a massive security liability, as those secrets are permanently burned into plaintext Jenkins, GitHub Actions, or GitLab CI logs.
-
-Flowstride completely neutralizes this threat by architecturally separating execution output from diagnostic telemetry:
-
-1. **Clean Standard Output (`stdout`):** Flowstride's terminal output only displays high-level, human-readable BDD execution steps (e.g., `✔ Given "User lands on home page"` or `✖ Action Failed`). No JSON request bodies, `cURL` strings, or bearer tokens are ever printed to the terminal console.
+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.
 
-2. **WebSocket Isolation:** All sensitive raw network data (payloads, headers, and responses) is emitted _exclusively_ over a secure, ephemeral WebSocket connection directly to the developer's local UI dashboard.
-
-3. **Total Evaporation:** Because CI/CD runners only capture `stdout` text and do not connect to local WebSockets, your highly sensitive diagnostic data simply evaporates the moment the pipeline execution ends. Your pipeline logs remain 100% free of plaintext secrets.
-
----
-
-## 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
+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                                                      |
-| :--------- | :----------------------------- | :--------------------------------------------------------------- |
-| `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. |
+## Local dashboard and manual testing
 
-### UI Actions
+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                                                     |
-| :----------- | :---------------------------------------- | :-------------------------------------------------------------- |
-| `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. |
+For visual manual test design and execution:
 
-### Assertions
-
-| 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.           |
-
-### 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>;