prompttest 1.4.0 → 1.5.0

package/dist/lib/adaptive-timing.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @module adaptive-timing
+ * @description Device-Aware Adaptive Dynamic Waiting & Auto-Profiling.
+ *
+ * Automatically balances test timing between ultra-fast physical devices (USB 3.0)
+ * and resource-constrained CI emulators (software-rendered VMs in GitHub Actions).
+ *
+ * Implements exponential backoff condition-driven polling with instant short-circuiting:
+ * fast devices finish immediately upon event completion, while slow emulators receive
+ * adaptive headroom without CPU exhaustion.
+ */
+import type { AndroidDriver } from './adb.js';
+export interface DeviceProfile {
+    /** Whether the target device is an emulator / virtual device */
+    isEmulator: boolean;
+    /** Whether the process is executing inside a CI / CD environment (e.g. GitHub Actions) */
+    isCI: boolean;
+    /** Calculated dynamic velocity multiplier (1.0 = real device, 1.5 = local emulator, 2.5 = CI) */
+    velocityMultiplier: number;
+    /** Default timeout ceiling for UI element detection */
+    defaultTimeoutMs: number;
+    /** Extended timeout ceiling for multi-step transitions and cold loads */
+    extendedTimeoutMs: number;
+    /** Minimum stability duration for dual-sample quiescence verification */
+    quiescenceSettleMs: number;
+    /** Initial polling interval in milliseconds */
+    initialPollMs: number;
+    /** Maximum backoff polling interval in milliseconds */
+    maxPollIntervalMs: number;
+}
+/**
+ * Probes the connected device and host runtime to construct an adaptive timing profile.
+ * Cached per session so that subsequent steps reuse the profiled characteristics.
+ *
+ * @param driver - Android driver instance
+ * @param serial - Optional target device serial
+ */
+export declare function profileDeviceEnvironment(driver: AndroidDriver, serial?: string): Promise<DeviceProfile>;
+/**
+ * Resets the cached device profile (primarily used in testing).
+ */
+export declare function resetDeviceProfile(): void;
+/**
+ * Polls an asynchronous condition using adaptive backoff with immediate short-circuiting.
+ *
+ * Fast devices short-circuit the instant the condition returns a truthy value.
+ * Slow emulators receive backoff polling that preserves CPU cycles for rendering.
+ *
+ * @param checkFn - Async callback returning a truthy value when the condition is met.
+ * @param timeoutMs - Maximum duration to wait before giving up.
+ * @param initialIntervalMs - Starting interval between checks.
+ * @param maxIntervalMs - Cap for the backoff interval.
+ * @returns The resolved value of the condition, or throws a timeout Error.
+ */
+export declare function pollWithAdaptiveBackoff<T>(checkFn: () => Promise<T | null | undefined | false>, timeoutMs: number, initialIntervalMs?: number, maxIntervalMs?: number): Promise<T>;

package/dist/lib/adb.d.ts

@@ -406,6 +406,7 @@ export declare class AndroidDriver {
     }, localDestPath: string, serial?: string): Promise<string>;
     /**
      * Checks if the virtual software keyboard (IME) is currently active and visible on screen.
+     * Uses fast shell grep filtering across Android IME & Window properties with resilient fallbacks.
      * @param serial Optional target device serial.
      * @returns Promise resolving to true if virtual keyboard is displayed.
      */

package/dist/lib/jail-guard.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @module jail-guard
+ * @description Zero-Overhead In-Memory App Boundary Guardian for PromptTest.
+ *
+ * Enforces strict package boundary isolation to guarantee that automation
+ * NEVER sends touch, text, or gesture events into third-party personal apps
+ * (e.g. banking apps, email, browsers) or home screen launchers.
+ *
+ * Operates directly on the in-memory parsed hierarchy (UiNode.packageName)
+ * with 0 ms additional ADB overhead in normal operation.
+ */
+import type { UiNode } from './crawler.js';
+import type { AndroidDriver } from './adb.js';
+/**
+ * Registry of known Android OEM launchers and desktop interfaces.
+ */
+export declare const KNOWN_LAUNCHER_PACKAGES: readonly string[];
+/**
+ * Registry of allowed Android system overlay and framework packages
+ * (keyboards, permission dialogs, autofill, package installer).
+ */
+export declare const KNOWN_SYSTEM_PACKAGES: readonly string[];
+/**
+ * Checks if a given package name corresponds to a known launcher or desktop interface.
+ */
+export declare function isLauncherPackage(pkg: string): boolean;
+/**
+ * Checks if a given package name corresponds to an allowed Android system overlay.
+ */
+export declare function isAllowedSystemPackage(pkg: string): boolean;
+/**
+ * Determines whether a specific node's package belongs to the target app under test
+ * or an allowed system overlay (keyboard, permission prompt, system UI).
+ *
+ * @param nodePackage - The package name of the UI node being interacted with.
+ * @param targetPackage - The target application package under test (if specified).
+ */
+export declare function isTargetOrAllowedSystem(nodePackage?: string, targetPackage?: string): boolean;
+/**
+ * Extracts the primary / foreground package from a flattened list of UiNodes.
+ * Evaluates non-system, interactive nodes first, then falls back to the root node.
+ */
+export declare function detectScreenPackage(nodes: UiNode[]): string | null;
+/**
+ * Guards the app boundary: If an escape is detected (screen belongs to a launcher or foreign app),
+ * it blocks further actions, prevents unsafe back-presses on launchers, and brings the target app
+ * back to the foreground.
+ *
+ * @param nodes - In-memory UI nodes from current hierarchy dump.
+ * @param targetPackage - The expected target application package.
+ * @param driver - Android driver instance for containment recovery.
+ * @param serial - Optional target device serial.
+ * @returns Details on whether an escape occurred and whether recovery succeeded.
+ */
+export declare function guardAppBoundary(nodes: UiNode[], targetPackage: string, driver: AndroidDriver, serial?: string): Promise<{
+    escaped: boolean;
+    recovered: boolean;
+    currentPackage: string | null;
+}>;

package/dist/lib/prompt-runner.d.ts

@@ -19,6 +19,7 @@ export declare class PromptRunner {
     private lastHierarchy;
     private screenDimensions;
     private navBarHeight;
+    private targetPackage;
     /**
      * Initializes a new instance of the PromptRunner.
      * Uses dependency injection for core services, defaulting to singletons if omitted.

package/dist/lib/quiescence.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @module quiescence
+ * @description Dynamic Screen Quiescence & Idling Sentinel for PromptTest.
+ *
+ * Implements self-synchronizing stability detection inspired by Playwright's networkidle
+ * and Android Espresso's IdlingResource. Replaces fragile static timers with dual-sample
+ * layout stabilization and active in-flight loading sentinel checks.
+ */
+import type { UiNode } from './crawler.js';
+import type { ExecutionContext } from './step-handlers.js';
+export interface QuiescenceResult {
+    /** Whether the screen reached verified stability before the timeout */
+    settled: boolean;
+    /** Milliseconds elapsed during stabilization */
+    durationMs: number;
+    /** Final structural hash of the quiescent screen */
+    finalHash: string;
+    /** Flattened UI nodes of the quiescent screen */
+    flat: UiNode[];
+}
+/**
+ * Inspects a flattened UI hierarchy to detect active in-flight network spinners,
+ * shimmers, progress bars, or server-waiting indicators.
+ *
+ * @param nodes - Flattened array of UiNodes
+ * @returns Status indicating whether loading is in progress and why.
+ */
+export declare function isLoadingInProgress(nodes: UiNode[]): {
+    loading: boolean;
+    reason?: string;
+};
+/**
+ * Dynamically waits until the application screen achieves 100% quiescence:
+ * 1. All active loading indicators and spinners have vanished.
+ * 2. Two consecutive UI hierarchy snapshots yield matching structural hashes.
+ *
+ * Exits immediately once settled, saving seconds on fast devices while providing
+ * dynamic patience for slow network requests or cloud emulators.
+ *
+ * @param ctx - Execution context providing driver and hierarchy access.
+ * @param timeoutMs - Maximum wait ceiling (defaults to 4500ms).
+ * @param sampleIntervalMs - Interval between stability probe samples (defaults to 150ms).
+ */
+export declare function waitForQuiescence(ctx: ExecutionContext, timeoutMs?: number, sampleIntervalMs?: number): Promise<QuiescenceResult>;

package/dist/lib/step-handlers.d.ts

@@ -21,6 +21,8 @@ import { PromptStep } from './prompt-runner.js';
  * It encapsulates the driver instance, state cache, and common UI interaction logic.
  */
 export interface ExecutionContext {
+    /** Target application package name under test (used for jail guard containment). */
+    targetPackage?: string;
     /** The ADB-based Android UI driver used to interact with the device. */
     driver: AndroidDriver;
     /** Memory engine used to record and learn resilient locators over time. */

package/docs/ARCHITECTURE.md

@@ -6,7 +6,7 @@ PromptTest is a zero-code, AI-assisted Android test automation and visual QA fra
 
 ## 1. High-Level Architecture Overview
 
-PromptTest operates on a modular layered architecture where test scripts written in natural language or AST-driven directives are compiled, bound to live or synthetic data, executed against connected devices via an isolated locking layer, and reported with visual diffs and interactive HTML reports.
+PromptTest operates on a modular layered architecture where test scripts written in natural language or AST-driven directives are compiled, bound to live or synthetic data, executed against connected devices via an isolated locking layer, and reported with visual diffs and interactive HTML reports. Current release boundaries are tracked in [PRODUCT_STATUS.md](PRODUCT_STATUS.md).
 
 ```
 ┌───────────────────────────────────────────────────────────┐
@@ -35,14 +35,14 @@ PromptTest operates on a modular layered architecture where test scripts written
        │                      │                      │
 ┌──────▼──────────────────────▼──────────────────────▼──────┐
 │              Visual Testing & Diagnostics                 │
-│          lib/baseline.ts (SSIM / Perceptual Diff)         │
+│          lib/baseline.ts (pixelmatch / PNG Diff)          │
 │          lib/explorer.ts (Autonomous Crawler)             │
 └─────────────────────────────┬─────────────────────────────┘
                               │
 ┌─────────────────────────────▼─────────────────────────────┐
 │                 Reporting & Observability                 │
 │       lib/reporter.ts (HTML, JSON, JUnit XML, Markdown)   │
-│       lib/live-server.ts (SSE / WebSocket Live Dash)      │
+│       lib/live-server.ts (HTTP / SSE Live Monitor)        │
 └───────────────────────────────────────────────────────────┘
 ```
 
@@ -100,7 +100,7 @@ Instead of an unwieldy switch-case statement, execution is delegated to decouple
 
 ### 2.6 Visual Baselines & Computer Vision (`lib/baseline.ts`, `lib/explorer.ts`)
 
-- Pixel-by-pixel perceptual diffing and Structural Similarity Index Measure (SSIM) algorithms.
+- Pixel-level image diffing using `pixelmatch` and PNG decoding via `pngjs`.
 - Configurable failure thresholds (e.g. `diffThreshold: 0.02` for 2% variance).
 - Automatic bounding box masking for dynamic regions (e.g. status bar clocks, live feeds) to eliminate false positives in visual regression testing.
 

package/docs/CLI_CONTRACT.md

@@ -0,0 +1,131 @@
+# PromptTest CLI Contract
+
+**Contract date:** 2026-09-22  
+**Package:** `prompttest` 1.3.5
+
+This document describes the currently shipped CLI and SDK integration surfaces. It is intended for CI consumers and desktop clients. It does not promise functionality that is only planned or hardware-unvalidated.
+
+## Compatibility Rules
+
+- Existing public exports and command behavior are additive-compatible within a major version.
+- Consumers should use exported types and documented fields rather than parsing terminal text.
+- Report fields may gain optional properties. Existing required fields will not be removed without a breaking release.
+- Hardware operations require ADB and a reachable Android device or emulator.
+
+## Exit Codes
+
+| Code | Name                 | Meaning                                                           |
+| ---: | -------------------- | ----------------------------------------------------------------- |
+|    0 | `SUCCESS`            | Run completed successfully.                                       |
+|    1 | `TEST_FAILED`        | An assertion, locator, or test step failed.                       |
+|    2 | `DEVICE_UNAVAILABLE` | ADB/device connection or device availability failed.              |
+|    3 | `CONFIG_ERROR`       | A spec, configuration, argument, or include reference is invalid. |
+|    4 | `LOCKED`             | The target device is locked by another PromptTest process.        |
+
+CI integrations should use these codes instead of matching human-readable output.
+
+## Report Model
+
+The canonical report is JSON with this shape:
+
+```ts
+interface QaReportData {
+  packageName: string;
+  deviceId: string;
+  startTime: string;
+  endTime: string;
+  durationSeconds: number;
+  totalSteps: number;
+  passedSteps: number;
+  failedSteps: number;
+  skippedSteps: number;
+  warnSteps: number;
+  errorsDetected: string[];
+  videoPath?: string;
+  steps: AuditStep[];
+}
+
+interface AuditStep {
+  stepIndex: number;
+  timestamp: string;
+  phase: string;
+  description: string;
+  action: string;
+  status: 'PASS' | 'WARN' | 'FAIL' | 'SKIPPED';
+  target?: string;
+  screenshotPath?: string;
+  durationMs?: number;
+  triageBundle?: string;
+  videoOffsetMs?: number;
+  details?: Record<string, unknown>;
+}
+```
+
+Supported serializers are JSON, Markdown, JUnit XML, and HTML. JSON is the machine-readable source of truth; the other formats are views of the same run.
+
+## Output Conventions
+
+The default output directory is `output/` in the working directory. Common artifacts include:
+
+- `<name>-results.json`
+- `<name>-report.md`
+- `<name>-report.html`
+- `<name>-junit.xml`
+- Failure triage folders or ZIPs containing screenshots, hierarchy XML, logcat, and match scores
+- Baselines under `output/baselines/`
+- Checkpoints under `output/checkpoints/`
+- Optional MP4 recordings referenced by `videoPath`
+
+Paths in report fields are relative to the report/output directory unless the producer explicitly returns an absolute path.
+
+## Live Engine Protocol
+
+The live server is started with `prompttest serve [port]` or `startLiveServer()`. Defaults:
+
+- Host: `127.0.0.1`
+- Port: `4040`
+- Transport: HTTP plus Server-Sent Events
+- Event stream: `GET /events`
+- Report view: `GET /` or `GET /report`
+
+The current server has no authentication and sends permissive CORS headers. It must be treated as a local trusted-process interface. Do not bind it to a non-loopback host or expose it outside a controlled machine without adding authentication and access controls.
+
+### Stable read endpoints
+
+- `GET /api/devices` returns connected device metadata.
+- `GET /api/screen-state?deviceId=<id>&hierarchy=true|false` returns a screenshot, foreground package, and optional flattened UI elements.
+- `GET /api/specs` lists local `.txt` and `.spec` files.
+- `GET /api/specs/<name>` reads a spec file.
+- `GET /api/reports` lists generated reports.
+- `GET /api/reports/<name>` reads a report detail.
+- `GET /api/baselines` lists available baselines.
+- `GET /api/baselines/masks` lists baseline masks.
+- `GET /api/report` and `GET /results.json` return the current report data.
+
+### Mutating endpoints
+
+These endpoints control a connected device or write local files and should only be called by an explicit local user action:
+
+- `POST /api/tap` with `{ x, y, deviceId? }`
+- `POST /api/type` with `{ text, deviceId? }`
+- `POST /api/key` with `{ keyCode, deviceId? }`
+- `POST /api/wake` with `{ deviceId? }`
+- `POST /api/specs` with `{ name, content }`
+- `POST /api/action` with `{ step, deviceId? }`
+- `POST /api/run` with `{ specName? | spec?, deviceId?, saveBaseline?, compareBaseline? }`
+- Baseline approval, comparison, upload, mask, clear, and delete endpoints under `/api/baselines/*`
+
+### SSE events
+
+Clients connecting to `/events` may receive:
+
+- `step`: step number, instruction, status, duration, and optional error
+- `complete`: final `QaReportData`
+- `error`: an error message payload
+- Heartbeat comments every 15 seconds
+
+Clients must reconnect and tolerate duplicate or missing transient events; the final report is authoritative.
+
+## Studio Boundary
+
+The CLI owns device control, test execution, report generation, and artifact storage. A Studio client owns presentation, browsing, device selection, and desktop packaging. Studio must not duplicate locator resolution or report aggregation logic. Any new endpoint or event should be added here with a compatibility note and an integration test.

package/docs/CLI_STUDIO_CONTRACT.md

@@ -0,0 +1,123 @@
+# CLI and Studio Contract
+
+**Contract version:** `1`  
+**CLI package:** `prompttest` 1.3.5  
+**Status:** Current implementation contract, verified 2026-09-22
+
+This document defines the integration surface between the PromptTest CLI engine and a desktop or browser Studio client. The CLI remains independently usable; Studio consumes this contract and must not reimplement device control, test execution, report generation, or baseline comparison.
+
+## Engine Startup
+
+Start the engine with:
+
+```bash
+prompttest serve [port]
+```
+
+The default port is `4040`. The server binds to `127.0.0.1` by default. Programmatic consumers can call `startLiveServer({ port, host, outputDir, specsDir })`.
+
+The server is not an authenticated remote control plane. It exposes device actions, screenshots, UI hierarchy data, specifications, reports, and baselines. Keep the default loopback binding; do not expose the server on a network interface without adding authentication and authorization first.
+
+## Exit Codes
+
+| Code | Meaning                                       |
+| ---: | --------------------------------------------- |
+|  `0` | Successful execution                          |
+|  `1` | Test assertion or locator failure             |
+|  `2` | Device unavailable, offline, or unauthorized  |
+|  `3` | Invalid configuration, spec, or CLI arguments |
+|  `4` | Device lock contention                        |
+
+Studio should display the error message and preserve the numeric exit code when it starts the CLI as a child process.
+
+## Report Contract
+
+The canonical report is JSON. The current `QaReportData` shape is:
+
+```json
+{
+  "packageName": "com.example.app",
+  "deviceId": "emulator-5554",
+  "startTime": "2026-09-22T00:00:00.000Z",
+  "endTime": "2026-09-22T00:00:03.000Z",
+  "durationSeconds": 3,
+  "totalSteps": 2,
+  "passedSteps": 1,
+  "failedSteps": 1,
+  "skippedSteps": 0,
+  "warnSteps": 0,
+  "errorsDetected": [],
+  "videoPath": "login-recording.mp4",
+  "steps": []
+}
+```
+
+Each step can contain `stepIndex`, `timestamp`, `phase`, `description`, `action`, `target`, `status`, `screenshotPath`, `durationMs`, `triageBundle`, `videoOffsetMs`, and `details`.
+
+Supported report serializers are `json`, `md`, `junit`, and `html`. JSON is the integration source of truth. File names use the selected base name:
+
+- `<name>-results.json`
+- `<name>-report.md`
+- `<name>-junit.xml`
+- `<name>-report.html`
+
+## SSE Events
+
+Connect to `GET /events` with an `EventSource`. Events currently emitted are:
+
+- `step`: step number, instruction, status, duration, and optional error
+- `complete`: final `QaReportData`
+- `error`: an error message object
+
+Clients should tolerate unknown future events and reconnect after a dropped connection. The server sends comment heartbeats approximately every 15 seconds.
+
+## HTTP Routes
+
+All successful JSON responses include `success: true` where applicable. Errors use `success: false` and an `error` string.
+
+### Devices and live device state
+
+- `GET /api/devices`: connected device list
+- `GET /api/screen-state?deviceId=<id>&hierarchy=true|false`: screenshot, foreground package, and UI elements
+- `POST /api/tap`: `{ "x": number, "y": number, "deviceId"?: string }`
+- `POST /api/type`: `{ "text": string, "deviceId"?: string }`
+- `POST /api/key`: `{ "keyCode": number|string, "deviceId"?: string }`
+- `POST /api/wake`: `{ "deviceId"?: string }`
+
+### Specifications and execution
+
+- `GET /api/specs`: list `.txt` and `.spec` files
+- `GET /api/specs/<name>` or `GET /api/spec?name=<name>`: read a specification
+- `POST /api/specs` or `POST /api/spec`: `{ "name": string, "content": string }`
+- `POST /api/action`: `{ "step": string, "deviceId"?: string }`
+- `POST /api/run`: `{ "specName"?: string, "spec"?: string, "deviceId"?: string, "saveBaseline"?: boolean, "compareBaseline"?: boolean }`
+
+`/api/run` starts execution asynchronously. Use SSE and report endpoints to observe completion.
+
+### Reports and baselines
+
+- `GET /api/reports`: list available report artifacts
+- `GET /api/reports/<name>` or `GET /api/report-detail?name=<name>`: retrieve report details
+- `GET /api/report` or `GET /results.json`: retrieve the current JSON report
+- `GET /api/baselines`: list baseline images and metadata
+- `POST /api/baselines/compare`: compare an image against a baseline
+- `POST /api/baselines/approve`: approve a baseline result
+- `POST /api/baselines/clear`: clear baseline data
+- `POST /api/baselines/delete-step`: remove a step baseline
+- `POST /api/baselines/upload`: upload a baseline image
+- `GET /api/baselines/masks`: list baseline masks
+- `POST /api/baselines/masks`: create or update a baseline mask
+
+The exact request bodies for baseline management should be generated from the CLI client implementation until a schema is added in a future contract version.
+
+## Artifact Rules
+
+The CLI owns artifact creation under `output/` by default. Studio should display and download paths returned by reports rather than copying large screenshots or videos into JSON. Triage artifacts may include screenshots, hierarchy XML, logcat, match scores, a manifest, and a ZIP archive. A video path and failure offset do not imply that a clipped video snippet exists.
+
+## Compatibility Rules
+
+- Existing public SDK exports and CLI flags are additive and semver-protected.
+- Studio must tolerate missing optional fields and unknown JSON fields.
+- Studio must not assume Android hardware is available during engine startup.
+- A failed run is not an engine crash; inspect the report and exit code separately.
+- Contract changes require a version update, documentation update, and package smoke-test coverage.

package/docs/PERFORMANCE_BASELINE.md

@@ -0,0 +1,71 @@
+# PromptTest Performance Baseline
+
+**Measured:** 2026-09-22  
+**Package:** `prompttest` 1.3.5  
+**Environment:** macOS, Node.js 24.13.0, no ADB device required
+
+This is a reproducible CI and package-size baseline. Synthetic timings are health signals, not physical-device performance claims.
+
+## Current Measurements
+
+- Offline test suite: 39 test files, 337 tests passing
+- Test wall time: approximately 14 seconds in the current environment
+- CLI bundle: approximately 332 KB
+- SDK bundle: approximately 316 KB
+- Engine bundle: approximately 316 KB
+- Runtime dependencies: `chalk`, `pixelmatch`, `pngjs`
+- Supported Node.js range: `>=18.0.0`
+
+## Existing Benchmark Coverage
+
+`tests/performance-benchmark.test.ts` and `lib/benchmark.ts` cover:
+
+- Synthetic screenshot allocation timing
+- Synthetic UI hierarchy timing
+- Matching latency across a synthetic 1,000-node hierarchy
+- Percentile calculation and summary metrics
+- Hierarchy hashing and structural diffing
+- Verify-handler cache reuse
+- Reporter screenshot-buffer cleanup
+- PromptRunner benchmark mode
+
+Run the offline benchmark tests with:
+
+```bash
+npx vitest run tests/performance-benchmark.test.ts
+```
+
+Run the complete offline suite with:
+
+```bash
+npm test
+```
+
+## Required Hardware Measurements
+
+The following values must be collected on representative Android emulator and physical-device configurations before making performance promises:
+
+- ADB screenshot p50/p95 latency
+- `uiautomator dump` p50/p95 latency
+- Hierarchy dumps per visited screen
+- Screenshots per exploration state
+- Peak RSS for a 50-screen exploration
+- HTML report size with and without embedded screenshots
+- Triage ZIP size
+- Aggregation time for large output directories
+- Video-enabled versus video-disabled run time
+
+Hardware results should include device model, Android version, screen size, Node version, iteration count, and whether the device is USB, Wi-Fi, or emulator. Do not compare synthetic benchmark timings directly with ADB measurements.
+
+## Release Guardrails
+
+Any new runtime dependency or report-embedding behavior should be evaluated against:
+
+- Published tarball size
+- Installed unpacked size
+- Cold CLI startup time
+- Peak memory during report generation
+- Existing offline test duration
+- Node 18 compatibility
+
+The npm package should remain independently usable without Studio or a running server.

package/docs/PRODUCT_STATUS.md

@@ -0,0 +1,56 @@
+# PromptTest Product Status
+
+**Status date:** 2026-09-22  
+**Package:** `prompttest` 1.3.5
+
+This document is the current status index for the PromptTest CLI. Older implementation plans and the internal SRS are historical context, not release requirements.
+
+## Status Definitions
+
+- **Released:** Implemented, tested in the repository, and included in the published package.
+- **Implemented:** Present in the CLI, but physical-device or cross-platform validation may still be incomplete.
+- **Planned:** Intended work that is not part of the current release contract.
+- **Studio:** Requires the separate desktop application; that source is not part of this repository.
+
+## Current CLI Contract
+
+### Released or implemented
+
+- Android execution through ADB
+- Natural-language prompt parsing and structured flow control
+- Device locking and device-pool support
+- Data-driven runs and dynamic test data
+- Visual baselines using `pixelmatch` and PNG decoding
+- Markdown, JSON, JUnit, and HTML reporting
+- Failure triage artifacts and optional video recording
+- Autonomous exploration with DFS traversal and safety modes
+- Optional AI providers, disabled unless configured
+- HTTP/SSE live monitoring server
+- CI workflow generation through `init-ci`
+- Committed offline quality CI and scheduled emulator CI workflows
+- npm package and standalone distribution build paths
+
+### Implemented with validation limits
+
+- iOS driver interfaces require external Apple tooling and need a documented real-device acceptance matrix.
+- Autonomous exploration is unit-tested and fixture-tested; coverage across physical applications is not implied.
+- The emulator workflow is configured but requires a successful GitHub Actions run before hardware support is release-validated.
+- Live-server consumers must use the documented loopback and artifact-access contract.
+- Hardware tests require ADB, an emulator, or a connected device and are not part of the offline default test guarantee.
+
+### Planned or deferred
+
+- Performance benchmark evidence and output-retention limits
+- Stronger subprocess isolation for untrusted JavaScript specifications
+- Locale packs and broader non-English resolution
+- Spec scaffolding and a dedicated profiler
+- Offline licensing and report watermarking
+- Hosted collaboration, cloud reporting, and multi-device orchestration
+
+## CLI and Studio Boundary
+
+The CLI owns device control, execution, comparison, report generation, and artifact contracts. A separate Studio application may consume those contracts for device selection, live views, report browsing, packaging, and desktop workflows. Studio release status must be tracked in its own repository and must not be represented as CLI completion.
+
+## npm Compatibility Policy
+
+Changes to the CLI must preserve existing public exports and behavior unless a versioned breaking change is explicitly planned. Every release should pass typecheck, lint, offline tests, package verification, tarball installation smoke tests, and the supported Node.js compatibility checks before publication.

package/docs/USER_MANUAL.md

@@ -584,7 +584,7 @@ PromptTest can capture visual baselines and perform perceptual diffing to detect
 
 - `--save-baseline`: Saves the current screen layout as a visual baseline for future comparisons.
 - `--compare-baseline`: Compares the current screen layout against the saved baseline and fails if differences exceed the threshold.
-- `--baseline-threshold=N`: Adjusts the perceptual diffing tolerance (e.g., `--baseline-threshold=5` for 5%).
+- `--baseline-threshold=N`: Adjusts the diffing tolerance as a ratio from `0` to `1` (e.g., `--baseline-threshold=0.05` for 5%).
 
 ### Custom Reporters
 
@@ -615,7 +615,7 @@ PromptTest includes a cross-process, file-based mutex lock (`lib/lock.ts`) that
 PromptTest exposes a clean programmatic API using factory functions and a unified `DriverInterface`. Both Android and iOS drivers share the identical driver abstraction:
 
 ```typescript
-import { createPromptRunner, createAndroidDriver, createIosDriver } from 'prompttest';
+import { createPromptRunner, createAndroidDriver, IosDriver } from 'prompttest';
 
 async function runCrossPlatformTests() {
   // 🤖 Android Execution
@@ -624,9 +624,8 @@ async function runCrossPlatformTests() {
   const androidReport = await androidRunner.runSpec('specs/login.txt', 'com.example.app');
 
   // 🍎 iOS Execution (Simulator or Physical Device)
-  const iosDriver = createIosDriver({
+  const iosDriver = new IosDriver({
     udid: '00008101-001234567890',
-    bundleId: 'com.example.app',
   });
   const iosRunner = createPromptRunner(iosDriver);
   const iosReport = await iosRunner.runSpec('specs/login.txt', 'com.example.app');
@@ -760,6 +759,6 @@ PromptTest is a **fast UI-tree automation engine over ADB**. It "sees" what `uia
 
 ## 💡 Support & Contribution
 
-- **Repository**: [github.com/shriramsingh/promptTest](https://github.com/shriramsingh/promptTest)
-- **Issues & Requests**: [File an Issue](https://github.com/shriramsingh/promptTest/issues)
-- **License**: MIT
+- **Community Repository**: [github.com/shriramsingh/prompttest-community](https://github.com/shriramsingh/prompttest-community)
+- **Issues & Requests**: [File an Issue](https://github.com/shriramsingh/prompttest-community/issues)
+- **License**: Business Source License 1.1 (BSL 1.1)