prompttest-mobile 1.5.1

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

@@ -0,0 +1,390 @@
+/**
+ * @module step-handlers
+ * @description
+ * StepHandler pattern (A-04) implementation for PromptTest.
+ *
+ * This module implements the Command/Strategy architectural pattern where each action
+ * type (e.g., TAP, SWIPE, VERIFY) is encapsulated in its own independent handler class.
+ * By isolating step execution logic into discrete classes, the PromptRunner becomes a
+ * thin dispatcher relying on an O(1) map lookup (see STEP_HANDLER_REGISTRY).
+ *
+ * Adding a new step type requires only implementing a new StepHandler class and
+ * registering it, ensuring the core execution engine remains untouched and adhering
+ * to the Open/Closed Principle.
+ */
+import { AndroidDriver } from './adb.js';
+import { MemoryEngine } from './memory.js';
+import { UiNode } from './crawler.js';
+import { PromptStep } from './prompt-runner.js';
+/**
+ * ExecutionContext provides shared resources and utility methods to StepHandlers.
+ * 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. */
+    memory: MemoryEngine;
+    /** Optional device serial number for targeting specific devices via ADB. */
+    serial?: string;
+    /** Device screen dimensions used for coordinate calculations. */
+    screenDimensions: {
+        width: number;
+        height: number;
+    };
+    /** Height of the navigation bar, used to prevent interacting with system overlays. */
+    navBarHeight: number;
+    /** Cached snapshot of the last known UI hierarchy to accelerate operations. */
+    lastHierarchy: {
+        xml: string;
+        flat: UiNode[];
+        timestamp: number;
+        hash?: string;
+    } | null;
+    /** Caches the provided hierarchy snapshot for subsequent steps. */
+    setLastHierarchy(h: {
+        xml: string;
+        flat: UiNode[];
+        timestamp: number;
+        hash?: string;
+    } | null): void;
+    /** Fetches a fresh UI hierarchy directly from the device. */
+    getCleanHierarchy(serial?: string): Promise<{
+        xml: string;
+        flat: UiNode[];
+    }>;
+    /** Polls for a specific target node until it appears or times out. */
+    waitForTarget(target: string, serial?: string, timeoutMs?: number, step?: PromptStep): Promise<{
+        flat: UiNode[];
+        matched: UiNode[];
+    }>;
+    /** Evaluates nodes against a natural language query or semantic pattern. */
+    matchNodes(nodes: UiNode[], query: string, step?: PromptStep): UiNode[];
+    /** Checks if a node is visible, scrolling the viewport if necessary. */
+    ensureInViewport(node: UiNode, serial?: string): Promise<boolean>;
+    /** Generates rich, contextual errors when a step fails. */
+    buildDiagnosticError(target: string, flat: UiNode[], context: string): Error;
+    /** Specialized locator for finding form inputs, prioritizing matching hints or labels. */
+    findTargetInputField(nodes: UiNode[], target: string, value?: string): UiNode | null;
+    /** Future steps in the current script, used for fast-forward lookahead optimizations. */
+    upcomingSteps?: PromptStep[];
+    /** Live mutable variables map for storing and interpolating $var values across steps. */
+    variables: Map<string, string>;
+    /** Stack tracking nested loop executions to prevent infinite recursion. */
+    loopStack: Array<{
+        current: number;
+        total: number;
+        variable?: string;
+    }>;
+    /** Callback to execute a sequence of child steps (e.g. inside IF or LOOP). */
+    executeChildSteps?(steps: PromptStep[], ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Represents the outcome of a StepHandler's execution.
+ */
+export interface StepResult {
+    /** Indicates if the step was bypassed because its desired state was already met. */
+    fastForwarded?: boolean;
+    /** Explanation for why the step was fast-forwarded or altered. */
+    reason?: string;
+    /** Number of upcoming steps to skip if fast-forwarded over multiple actions. */
+    skipCount?: number;
+}
+/**
+ * The base interface for all action handlers.
+ * Enforces a strict contract for dispatching PromptStep instructions.
+ */
+export interface StepHandler {
+    /** The specific PromptStep type this handler is responsible for (e.g., 'TAP'). */
+    readonly type: PromptStep['type'];
+    /**
+     * Executes the step using the provided context.
+     *
+     * @param step - The parsed step instruction to execute.
+     * @param ctx - The execution context providing driver and utility access.
+     * @returns A promise resolving to a StepResult, or void if standard execution completes.
+     * @throws Will throw if the step cannot be completed (e.g., element not found).
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<StepResult | void>;
+}
+/**
+ * Handles TAP actions by finding the target element and simulating a single touch event.
+ * Incorporates fast-forwarding and auto-scrolling optimizations.
+ */
+export declare class TapHandler implements StepHandler {
+    readonly type: "TAP";
+    /**
+     * Executes the TAP step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<StepResult | void>;
+}
+/**
+ * Handles LONG_PRESS actions by pressing and holding on a target element.
+ */
+export declare class LongPressHandler implements StepHandler {
+    readonly type: "LONG_PRESS";
+    /**
+     * Executes the LONG_PRESS step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles TYPE actions to input text into form fields.
+ * Manages focus, clearing existing text, and keyboard interactions.
+ */
+export declare class TypeHandler implements StepHandler {
+    readonly type: "TYPE";
+    /**
+     * Executes the TYPE step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<StepResult | void>;
+}
+/**
+ * Handles CLEAR actions to empty an input field.
+ * Locates the target input, taps to focus, and clears its contents.
+ */
+export declare class ClearHandler implements StepHandler {
+    readonly type: "CLEAR";
+    /**
+     * Executes the CLEAR step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles VERIFY actions to assert the presence or state of elements on the screen.
+ */
+export declare class VerifyHandler implements StepHandler {
+    readonly type: "VERIFY";
+    /**
+     * Executes the VERIFY step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<StepResult | void>;
+}
+/**
+ * Handles BACK actions by simulating a hardware back button press.
+ */
+export declare class BackHandler implements StepHandler {
+    readonly type: "BACK";
+    /**
+     * Executes the BACK step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(_step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles SCROLL actions to navigate through lists or pages.
+ */
+export declare class ScrollHandler implements StepHandler {
+    readonly type: "SCROLL";
+    /**
+     * Executes the SCROLL step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles SWIPE actions to perform directional swipe gestures on the screen or specific elements.
+ */
+export declare class SwipeHandler implements StepHandler {
+    readonly type: "SWIPE";
+    /**
+     * Executes the SWIPE step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles TOGGLE actions for checkboxes and switches, ensuring the element reaches the desired state.
+ */
+export declare class ToggleHandler implements StepHandler {
+    readonly type: "TOGGLE";
+    /**
+     * Executes the TOGGLE step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles SELECT actions to choose an option from a dropdown or picker modal.
+ */
+export declare class SelectHandler implements StepHandler {
+    readonly type: "SELECT";
+    /**
+     * Executes the SELECT step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles LAUNCH_APP actions by starting the application via its package name.
+ */
+export declare class LaunchAppHandler implements StepHandler {
+    readonly type: "LAUNCH_APP";
+    /**
+     * Executes the LAUNCH_APP step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles RESTART_APP actions by forcefully stopping and then relaunching the app.
+ */
+export declare class RestartAppHandler implements StepHandler {
+    readonly type: "RESTART_APP";
+    /**
+     * Executes the RESTART_APP step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles TERMINATE_APP actions by forcefully stopping the application.
+ */
+export declare class TerminateAppHandler implements StepHandler {
+    readonly type: "TERMINATE_APP";
+    /**
+     * Executes the TERMINATE_APP step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles CLEAR_DATA actions by wiping the application's local data and cache.
+ */
+export declare class ClearDataHandler implements StepHandler {
+    readonly type: "CLEAR_DATA";
+    /**
+     * Executes the CLEAR_DATA step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles GRANT_PERMISSION actions to grant specific runtime permissions to the app.
+ */
+export declare class GrantPermissionHandler implements StepHandler {
+    readonly type: "GRANT_PERMISSION";
+    /**
+     * Executes the GRANT_PERMISSION step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles DEEP_LINK actions by opening a URI scheme or Intent.
+ */
+export declare class DeepLinkHandler implements StepHandler {
+    readonly type: "DEEP_LINK";
+    /**
+     * Executes the DEEP_LINK step.
+     * @param step - The step instruction.
+     * @param ctx - The execution context.
+     */
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles WAIT actions by pausing execution for a specified duration.
+ */
+export declare class WaitHandler implements StepHandler {
+    readonly type: "WAIT";
+    /**
+     * Executes the WAIT step.
+     * @param step - The step instruction.
+     * @param _ctx - The execution context.
+     */
+    execute(step: PromptStep, _ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles conditional branching based on UI element presence.
+ * Executes thenSteps if visible, or elseSteps if present and element not found.
+ */
+export declare class ConditionalHandler implements StepHandler {
+    readonly type: "IF_VISIBLE";
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles iterative execution of child steps with loop bound protections.
+ */
+export declare class LoopHandler implements StepHandler {
+    readonly type: "LOOP";
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Polls for an element to appear or become enabled without failing immediately.
+ */
+export declare class WaitUntilHandler implements StepHandler {
+    readonly type: "WAIT_UNTIL";
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Sets dynamic variables in the execution context for interpolation into subsequent steps.
+ */
+export declare class SetVariableHandler implements StepHandler {
+    readonly type: "SET_VARIABLE";
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Executes hardware and connectivity controls (Wi-Fi, Airplane mode, Orientation, Notifications).
+ */
+export declare class DeviceStateHandler implements StepHandler {
+    readonly type: "DEVICE_STATE";
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Executes a sandboxed JavaScript snippet for runtime calculations or variable manipulation.
+ */
+export declare class RunJsHandler implements StepHandler {
+    readonly type: "RUN_JS";
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * Handles automatic capture and input of One-Time Passwords (OTP) and 2FA codes.
+ * Reads codes from mock environment variables or live ADB logcat streams.
+ */
+export declare class OtpHandler implements StepHandler {
+    readonly type: "ENTER_OTP";
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<StepResult | void>;
+}
+/**
+ * Handles HTTP requests and API assertions within a test flow.
+ * Capable of extracting JSON response fields into runtime $variables.
+ */
+export declare class ApiHandler implements StepHandler {
+    readonly type: "API_REQUEST";
+    execute(step: PromptStep, ctx: ExecutionContext): Promise<void>;
+    private resolveJsonPath;
+}
+/**
+ * Handles assertions on transactional emails delivered to users during testing.
+ */
+export declare class EmailHandler implements StepHandler {
+    readonly type: "EMAIL_ASSERT";
+    execute(step: PromptStep, _ctx: ExecutionContext): Promise<void>;
+}
+/**
+ * STEP_HANDLER_REGISTRY maps step types to their concrete handler implementations.
+ * Provides an O(1) lookup for dispatching steps in the PromptRunner.
+ */
+export declare const STEP_HANDLER_REGISTRY: Map<import("./runner-utils.js").PromptStepType, StepHandler>;

package/dist/lib/triage.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @module triage
+ * @description
+ * Auto-crash triage and privacy-safe GitHub bug report link generator for PromptTest.
+ * Provides passive, zero-telemetry 1-click issue reporting when unexpected
+ * internal framework crashes or unhandled exceptions occur.
+ */
+export interface TriageOptions {
+    errorMessage: string;
+    stack?: string;
+    command?: string;
+    exitCode?: number;
+    repoUrl?: string;
+}
+export interface TriageContext {
+    command?: string;
+    exitCode?: number;
+}
+/**
+ * Sanitizes stack traces and error messages by stripping personal user directories
+ * (e.g. C:\Users\username\... or /Users/username/...) to protect developer privacy.
+ *
+ * @param trace - The raw stack trace or log string.
+ * @returns Sanitized string with user home directories replaced by '~'.
+ */
+export declare function sanitizeStackTrace(trace?: string): string;
+/**
+ * Distinguishes whether an error is an expected test failure (e.g., assertion failed,
+ * element not found timeout) or an unexpected internal framework/runtime crash
+ * (TypeError, process panic, unhandled exception).
+ *
+ * @param error - The caught error or rejection reason.
+ * @returns true if the error represents an unexpected framework crash.
+ */
+export declare function isFrameworkCrash(error: unknown): boolean;
+/**
+ * Builds a sanitized, length-bounded pre-filled GitHub issue URL matching
+ * the 1_bug_report.yml template in prompttest-community.
+ *
+ * @param options - Error context and command details.
+ * @returns The fully-encoded GitHub issue URL.
+ */
+export declare function buildIssueUrl(options: TriageOptions): string;
+/**
+ * Renders a polite, non-intrusive diagnostic crash triage box in the console.
+ *
+ * @param error - The caught crash error.
+ * @param context - Additional execution context (e.g. command run, exit code).
+ */
+export declare function displayCrashTriage(error: unknown, context?: TriageContext): void;

package/dist/lib/wizard.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @module wizard
+ * @description
+ * Interactive guided CLI wizard for PromptTest.
+ * Auto-detects connected devices, identifies foreground apps, discovers existing
+ * test specifications, and guides developers through autonomous exploration,
+ * test recording, spec execution, and diagnostics with zero required CLI arguments.
+ */
+import { AndroidDriver, AndroidDevice } from './adb.js';
+import { PromptRunner } from './prompt-runner.js';
+export interface EnvironmentInfo {
+    device?: AndroidDevice;
+    serial?: string;
+    activePackage?: string;
+    isOnline: boolean;
+}
+export interface WizardOptions {
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+    driver?: AndroidDriver;
+    runner?: PromptRunner;
+}
+/**
+ * Automatically inspects ADB to detect online devices and active foreground application.
+ *
+ * @param driver - AndroidDriver instance to query.
+ * @returns Detected environment state.
+ */
+export declare function detectActiveEnvironment(driver?: AndroidDriver): Promise<EnvironmentInfo>;
+/**
+ * Scans the current workspace for existing plain-English test specs (*.txt, *.spec).
+ *
+ * @param baseDir - Root directory to search (defaults to process.cwd()).
+ * @returns Array of discovered relative spec paths.
+ */
+export declare function findExistingSpecs(baseDir?: string): string[];
+/**
+ * Starts the interactive guided CLI wizard.
+ *
+ * @param options - Configuration options for input/output streams and drivers.
+ */
+export declare function startInteractiveWizard(options?: WizardOptions): Promise<void>;

package/dist/lib/zip-util.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @module zip-util
+ * @description
+ * Lightweight, zero-dependency ZIP archive generator built using Node.js native zlib.
+ * Generates standard PKZIP archives containing files with deflation compression.
+ */
+export interface ZipEntry {
+    name: string;
+    data: Buffer;
+    date?: Date;
+}
+/**
+ * Calculates a standard CRC32 checksum for a buffer.
+ */
+export declare function crc32(buf: Buffer): number;
+/**
+ * Converts a JS Date into standard MS-DOS format (16-bit time, 16-bit date).
+ */
+export declare function dosDateTime(d?: Date): {
+    time: number;
+    date: number;
+};
+/**
+ * Packs an array of ZipEntry files into a standard PKZIP buffer using Deflate compression.
+ *
+ * @param entries - Array of file entries with names and data buffers.
+ * @returns A Buffer containing the valid ZIP archive.
+ */
+export declare function createZipArchive(entries: ZipEntry[]): Buffer;
+/**
+ * Saves a list of entries as a ZIP file to disk.
+ *
+ * @param filePath - Target file path on disk.
+ * @param entries - Array of zip entries.
+ */
+export declare function writeZipFile(filePath: string, entries: ZipEntry[]): Promise<void>;

package/docs/ARCHITECTURE.md

@@ -0,0 +1,154 @@
+# PromptTest Architecture & System Design
+
+PromptTest is a zero-code, AI-assisted Android test automation and visual QA framework. It drives native Android devices over ADB without requiring app instrumentation, agent binaries, or server daemons.
+
+---
+
+## 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. Current release boundaries are tracked in [PRODUCT_STATUS.md](PRODUCT_STATUS.md).
+
+```
+┌───────────────────────────────────────────────────────────┐
+│                    CLI & Runner Interface                 │
+│                 (bin/prompttest.ts, index.ts)             │
+└─────────────────────────────┬─────────────────────────────┘
+                              │
+┌─────────────────────────────▼─────────────────────────────┐
+│                    Compilation & Parsing                  │
+│       lib/runner-utils.ts (AST, Parser, Includes)         │
+│       lib/data-loader.ts  (Dynamic generators, CSV/JSON)  │
+└─────────────────────────────┬─────────────────────────────┘
+                              │
+┌─────────────────────────────▼─────────────────────────────┐
+│                   PromptRunner Orchestrator               │
+│                     (lib/prompt-runner.ts)                │
+└──────┬──────────────────────┬──────────────────────┬──────┘
+       │                      │                      │
+┌──────▼──────────────┐┌──────▼──────────────┐┌──────▼──────────────┐
+│ Modular Handlers    ││ Self-Healing & AI   ││ Device & Locking    │
+│ lib/step-handlers.ts││ lib/memory.ts       ││ lib/lock.ts         │
+│ (Wait, Tap, Type,   ││ lib/patterns.ts     ││ lib/adb.ts          │
+│  Cond, Loop, API,   ││ lib/ai/             ││ lib/ios-driver.ts   │
+│  OTP, Email, Check) ││ (LLM & Vision)      ││                     │
+└─────────────────────┘└─────────────────────┘└─────────────────────┘
+       │                      │                      │
+┌──────▼──────────────────────▼──────────────────────▼──────┐
+│              Visual Testing & Diagnostics                 │
+│          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 (HTTP / SSE Live Monitor)        │
+└───────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Core Modules & Responsibilities
+
+### 2.1 PromptRunner Orchestrator (`lib/prompt-runner.ts`)
+
+The `PromptRunner` class coordinates the full lifecycle of test execution:
+
+- **Device Provisioning & Locking**: Acquires exclusive locks (`lib/lock.ts`) from device pools or the default ADB device.
+- **Spec Resolution**: Loads script files, resolves data-driven iterations (`#!data`, `--iterations`, `--only-row`), expands modular includes (`#include <spec>`), and tokenizes AST step blocks.
+- **Step Execution Loop**: Delegates individual step execution to registered step handlers (`lib/step-handlers.ts`) while handling error collection, retry policies, screenshot capture, and timeout budgets.
+- **Reporting Hook Dispatch**: Triggers lifecycle callbacks (`onStep`, `onComplete`, `onError`) across reporters and live monitors.
+
+### 2.2 Runner Utilities & Parser (`lib/runner-utils.ts`)
+
+Extracted from the monolithic runner to ensure clean separation of concerns and maintainability:
+
+- `parsePrompt(prompt)`: Tokenizes raw natural language statements into typed `PromptStep` AST definitions with action, target, value, timeout, and regex parameters.
+- `assembleAstBlocks(lines)`: Assembles structured nested blocks (conditionals `IF...ELSE...ENDIF`, loops `LOOP...ENDLOOP`, wait-untils `WAIT_UNTIL...ENDWAIT`) into hierarchical AST trees.
+- `expandSpecIncludes(specPath, visited)`: Recursively resolves and flattens `#include <subspec.txt>` directives with circular dependency detection.
+- `buildDiagnosticError(...)`: Enriches execution failures with element dumps, screenshot paths, and suggested locator fixes.
+- `findTargetInputField(tree, label)` & `matchNodes(tree, query)`: Spatial and attribute-based UI hierarchy matching algorithms.
+
+### 2.3 Modular Step Handlers (`lib/step-handlers.ts`)
+
+Instead of an unwieldy switch-case statement, execution is delegated to decoupled, single-responsibility handlers:
+
+- **Primitive Action Handlers**: `WaitHandler`, `TapHandler`, `TypeHandler`, `VerifyHandler`, `SwipeHandler`, `KeyEventHandler`.
+- **Flow Control Handlers**: `ConditionalHandler` (boolean element visibility checks), `LoopHandler` (fixed or dynamic iteration loops), `WaitUntilHandler` (polling with timeout), `SetVariableHandler`, `RunJsHandler` (sandboxed JavaScript expressions via `node:vm`).
+- **Integration Handlers**:
+  - `OtpHandler`: Extracts verification codes from local mock stores, environment variables, or live SMS/email inboxes.
+  - `ApiHandler`: Dispatches synchronous REST/HTTP assertions (`status`, `jsonPath`, `headers`) directly within the test pipeline.
+  - `EmailHandler`: Asserts transactional email delivery and body content against test stores.
+- **State & Checkpoint Handlers**: `DeviceActionHandler` (network, airplane mode, orientation, notifications), `CheckpointHandler` (named state saves and rollback).
+
+### 2.4 Data-Driven Engine (`lib/data-loader.ts` & `lib/form-filler.ts`)
+
+- **Iterative Testing**: Loads parameter matrices from CSV, JSON, or inline `#!data` tables.
+- **Dynamic Generators**: In-line variable expansion for synthetic data generation:
+  - `$random.firstName`, `$random.lastName`, `$random.email`, `$random.phone`
+  - `$random.string(len)`, `$random.number(min, max)`
+  - `$uuid` (v4 UUID)
+  - `$seq.id` (monotonically incrementing sequence)
+  - `$date.now`, `$date.iso`, `$date.format(...)`
+  - `$calc(expression)`: Runtime arithmetic evaluation.
+
+### 2.5 Hardware & Device Layer (`lib/adb.ts`, `lib/lock.ts`, `lib/ios-driver.ts`)
+
+- `lib/adb.ts`: Wraps Android Debug Bridge commands (`shell input`, `uiautomator dump`, `screencap`, `install`, `forward`, Wi-Fi, airplane mode, orientation).
+- `lib/lock.ts`: File-locking (`flock`/lockfile) mechanism enabling parallel worker execution across multi-device test farms (`--device-pool dev1,dev2`) without device collision.
+- `lib/ios-driver.ts`: Implements `DriverInterface` for Apple iOS physical devices and Simulators via `idb` and `xcrun simctl`.
+
+### 2.6 Visual Baselines & Computer Vision (`lib/baseline.ts`, `lib/explorer.ts`)
+
+- 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.
+
+### 2.7 Self-Healing & Memory (`lib/memory.ts`, `lib/ai/`)
+
+- Persistent memory storage (`.prompttest/memory.json`) mapping natural language queries to confirmed UI element identifiers (`resource-id`, `content-desc`, text).
+- Autonomous self-healing: When an element locator shifts or fails, PromptTest queries the memory cache and fuzzy synonym dictionary (`lib/dictionary.ts`), falling back to optional LLM/Vision providers (`lib/ai/llm-provider.ts`) to repair the locator automatically.
+
+### 2.8 Observability & Reporting (`lib/reporter.ts`, `lib/live-server.ts`)
+
+- Multi-format report generation: Interactive standalone HTML dashboards with embedded base64 screenshots, JSON execution summaries, JUnit XML (for CI/CD pipelines like GitHub Actions and GitLab CI), and Markdown summaries.
+- Real-time event streaming (`lib/live-server.ts`) for browser dashboards and CI progress logs.
+
+---
+
+## 3. Execution Data Flow
+
+```
+[Spec File (.txt)]
+       │
+       ▼
+[expandSpecIncludes] ─── Flat Raw Prompt
+       │
+       ▼
+[DataLoader / Generators] ─── Bound Row Variables ($var)
+       │
+       ▼
+[assembleAstBlocks] ─── Hierarchical AST (PromptStep[])
+       │
+       ▼
+[PromptRunner.runStep] ─── Iterates AST nodes
+       │
+       ├─► [Acquire Device Lock]
+       ├─► [Capture Screen & Dump Hierarchy]
+       ├─► [Resolve Element via Memory / Crawler / AI]
+       ├─► [Dispatch to Handler (lib/step-handlers.ts)]
+       ├─► [Evaluate Baseline Diff if visual step]
+       └─► [Emit Events & Record Step Result]
+       │
+       ▼
+[Reporter.generateReport] ─── Output HTML / JSON / XML
+```
+
+---
+
+## 4. Design Principles & Non-Functional Guarantees
+
+1. **Zero Client Instrumentation**: Target mobile applications require no modified build flavors, no test SDKs, and no debugging permissions beyond standard ADB authorization.
+2. **Deterministic Flow Control**: Programmatic constructs (`IF`, `LOOP`, `WAIT_UNTIL`) execute with predictable time bounds and clear exit conditions.
+3. **Fail-Fast vs. Resilient Execution**: Controlled via CLI flags (`--fail-fast` vs. `--continue-on-failure`), allowing rapid iteration in development or broad test suite discovery in nightly CI runs.
+4. **Strict Modular Decoupling**: File sizes are capped (<1100 lines for core orchestrator), types are strictly enforced without `any` escapes, and modules communicate via well-typed TypeScript interfaces.