prompttest 1.3.0

package/dist/lib/memory.d.ts

@@ -0,0 +1,259 @@
+/**
+ * Represents a stored association between a test action and a specific on-screen element.
+ */
+export interface LearnedMapping {
+    /** The normalized natural language intent string that led to this mapping */
+    canonicalIntent: string;
+    /** The action type being performed */
+    action: 'TAP' | 'TYPE' | 'VERIFY';
+    /** The literal text, content descriptor, or resource ID of the matched element */
+    matchedIdentifier: string;
+    /** How the matched identifier is exposed on the Android element */
+    matchType: 'text' | 'contentDesc' | 'resourceId';
+    /** Probability score [0.0 - 1.0] of this mapping being correct */
+    confidence: number;
+    /** Number of consecutive times this mapping succeeded */
+    successCount: number;
+    /** Number of consecutive times this mapping failed */
+    failCount: number;
+    /** Total lifetime successful interactions with this mapping */
+    totalSuccesses: number;
+    /** Sliding window of recent interaction outcomes ('PASS' | 'FAIL') */
+    recentOutcomes: ('PASS' | 'FAIL')[];
+    /** ISO 8601 timestamp of the last time this mapping was updated or used */
+    lastUpdated: string;
+    /** ISO 8601 timestamp when this element was last observed on screen */
+    lastSeenTs: string;
+    /** Originating locator this element was healed from during autonomous self-healing */
+    healedFrom?: string;
+}
+/**
+ * Represents a stored screen state fingerprint with elements, crawl status, and safe actions (LN-01, AX-07).
+ */
+export interface ScreenMemoryEntry {
+    lastSeenTs: string;
+    elements: string[];
+    crawled?: boolean;
+    crawledAt?: string;
+    safeActions?: string[];
+}
+/**
+ * Represents a cached natural language intent expansion into actionable PromptTest steps (LN-03).
+ */
+export interface IntentExpansionEntry {
+    intent: string;
+    steps: string[];
+    learnedAt: string;
+    usageCount: number;
+}
+/**
+ * Persisted JSON schema for storing memory data per Android package.
+ */
+export interface AppMemoryData {
+    /** The Android application package name (or "global") */
+    packageName: string;
+    /** Schema version for migration handling */
+    version: number;
+    /** ISO 8601 timestamp of the last update to this package's memory */
+    lastUpdated: string;
+    /** Dictionary of composite keys to learned mappings */
+    mappings: Record<string, LearnedMapping>;
+    /** Optional screen-hash index mapping screen fingerprints to element keys and crawl status (LN-01, AX-07) */
+    screens?: Record<string, ScreenMemoryEntry>;
+    /** Optional macro intent expansion cache (LN-03) */
+    intents?: Record<string, IntentExpansionEntry>;
+}
+/**
+ * The MemoryEngine handles loading, resolving, recording, and persisting
+ * learned test actions to improve performance and reliability.
+ */
+export declare class MemoryEngine {
+    private memoryDir;
+    private currentPackage;
+    private mappings;
+    private screens;
+    private intents;
+    private dirty;
+    private locale;
+    /**
+     * Sets the active locale for taxonomy lookup.
+     */
+    setLocale(locale: string): void;
+    /**
+     * Gets the active locale.
+     */
+    getLocale(): string;
+    /**
+     * Initializes the memory engine.
+     * @param customMemoryDir Optional directory path to store memory files. Defaults to a standard memory directory.
+     */
+    constructor(customMemoryDir?: string);
+    private cleanPackageName;
+    private static readonly SCHEMA_VERSION;
+    /**
+     * Initializes memory for a specific Android package, loading its existing mappings from disk.
+     * @param packageName The Android package name to load.
+     * @returns A promise that resolves when initialization is complete.
+     */
+    init(packageName: string): Promise<void>;
+    /**
+     * Resolves a deterministic canonical query for synonymous terms (LN-02).
+     */
+    getCanonicalQuery(query: string): string;
+    private buildKey;
+    /**
+     * Resolves a learned mapping for a specific action and query intent.
+     * Supports synonym-canonical resolution so equivalent phrasings resolve to the same mapping (LN-02).
+     * @param action The action type (e.g., 'TAP', 'TYPE').
+     * @param query The natural language query intent.
+     * @returns The learned mapping if found, otherwise undefined.
+     */
+    resolve(action: string, query: string): LearnedMapping | undefined;
+    /**
+     * Returns an ordered list of search candidates:
+     * 0. Screen-specific learned element identifier (if screenHash provided & verified) (LN-01)
+     * 1. The learned element identifier (if verified memory exists) (LN-02)
+     * 2. The literal query itself
+     * 3. Seed dictionary synonyms
+     *
+     * @param action The action being performed.
+     * @param query The natural language query to match.
+     * @param locale Optional locale override. Defaults to engine active locale.
+     * @param screenHash Optional screen hash fingerprint for whole-screen lookup.
+     * @returns Array of candidate strings to search for on screen.
+     */
+    getAllCandidates(action: string, query: string, locale?: string, screenHash?: string): string[];
+    /**
+     * Records a successful element interaction into persistent memory.
+     *
+     * @param action The action performed.
+     * @param query The initial query intent.
+     * @param matchedIdentifier The actual identifier matched on screen.
+     * @param matchType The type of match (text, contentDesc, resourceId).
+     * @param confidence Initial confidence score for the new mapping.
+     */
+    recordSuccess(action: string, query: string, matchedIdentifier: string, matchType: 'text' | 'contentDesc' | 'resourceId', confidence?: number, healedFrom?: string, screenHash?: string): void;
+    /**
+     * Associates a learned element mapping key with a screen hash fingerprint (LN-01).
+     * @param screenHash The unique hash fingerprint of the UI screen.
+     * @param elementKey The memory key of the learned mapping.
+     */
+    associateScreenElement(screenHash: string, elementKey: string): void;
+    /**
+     * Retrieves all learned elements associated with a specific screen hash (LN-01).
+     * Enables whole-screen fast-forwarding on recognized screens.
+     * @param screenHash The unique hash fingerprint of the screen.
+     * @returns Array of LearnedMapping objects known to exist on this screen.
+     */
+    getScreenElements(screenHash: string): LearnedMapping[];
+    /**
+     * Retrieves raw screen index data for reporting and inspection.
+     */
+    getScreenIndex(): Record<string, ScreenMemoryEntry>;
+    /**
+     * Marks a screen hash fingerprint as crawled and records verified safe actions (AX-07).
+     * @param screenHash The unique hash fingerprint of the screen.
+     * @param safeActions Optional array of action labels verified safe on this screen.
+     */
+    markScreenCrawled(screenHash: string, safeActions?: string[]): void;
+    /**
+     * Queries whether a screen fingerprint was previously crawled offline (AX-07).
+     * @param screenHash The unique hash fingerprint of the screen.
+     * @returns true if the screen was previously explored and marked crawled.
+     */
+    isScreenCrawled(screenHash: string): boolean;
+    /**
+     * Retrieves screen memory entry for a specific screen hash.
+     */
+    getScreenMemory(screenHash: string): ScreenMemoryEntry | undefined;
+    /**
+     * Retrieves the number of unique screens marked as crawled (AX-07).
+     */
+    getCrawledScreensCount(): number;
+    /**
+     * Caches a resolved natural language macro intent expansion into actionable PromptTest steps (LN-03).
+     * @param intent The natural language intent text (e.g. "log in with default credentials").
+     * @param steps Array of actionable PromptTest step strings.
+     */
+    recordIntentExpansion(intent: string, steps: string[]): void;
+    /**
+     * Retrieves a cached natural language intent expansion if available (LN-03).
+     * Increments usage count upon cache hit.
+     * @param intent The natural language intent text.
+     * @returns Array of step strings or undefined if not cached.
+     */
+    getIntentExpansion(intent: string): string[] | undefined;
+    /**
+     * Checks whether a macro intent expansion exists in persistent memory (LN-03).
+     */
+    hasIntentExpansion(intent: string): boolean;
+    /**
+     * Retrieves total count of cached macro intent expansions (LN-03).
+     */
+    getIntentExpansionsCount(): number;
+    /**
+     * Records an interaction failure for a learned mapping.
+     * Employs sliding-window decay over the last 5 interactions.
+     * A mapping is pruned only if 3 or more recent interactions failed or confidence drops below 0.20.
+     *
+     * @param action The action that failed.
+     * @param query The natural language query intent that failed.
+     */
+    recordFailure(action: string, query: string): void;
+    /**
+     * Applies stale-mapping decay for elements not observed recently (LN-05).
+     * Reduces confidence of mappings whose lastSeenTs is older than thresholdDays.
+     * Does NOT delete them outright, preserving knowledge with demoted confidence.
+     *
+     * @param thresholdDays Number of days of inactivity before decaying (defaults to CONFIG.memory.staleThresholdDays).
+     * @returns Number of mappings decayed.
+     */
+    decayStaleMappings(thresholdDays?: number): number;
+    /**
+     * Asynchronously commits learned knowledge to disk.
+     * @returns A promise that resolves when the save operation completes.
+     */
+    save(): Promise<void>;
+    /**
+     * Exports learned mappings to a designated JSON file for sharing across CI or developers.
+     * @param destFilePath Optional destination file path. Defaults to memory/<package>-export.json
+     * @returns The resolved destination file path.
+     */
+    exportMemory(destFilePath?: string): Promise<string>;
+    /**
+     * Imports learned mappings from a JSON export file into the current knowledge base.
+     * Merges imported mappings with existing knowledge, retaining higher-confidence entries.
+     * @param sourceFilePath Path to the JSON file to import.
+     * @returns Number of mappings successfully imported or merged.
+     */
+    importMemory(sourceFilePath: string): Promise<number>;
+    /**
+     * Retrieves all learned mappings for the current package.
+     * @returns An array of all learned mappings.
+     */
+    getMappingsList(): LearnedMapping[];
+    /**
+     * Gets memory statistics for the current package.
+     * @returns An object containing total mappings, package name, lifetime successes, and average confidence.
+     */
+    getStats(): {
+        totalMappings: number;
+        totalScreens: number;
+        crawledScreens: number;
+        totalIntents: number;
+        package: string;
+        totalSuccesses: number;
+        averageConfidence: number;
+    };
+    /**
+     * Clears the memory mappings for a specific package, deleting the associated file.
+     * @param packageName Optional package name to clear. Defaults to current package.
+     * @returns A promise resolving to true if a file was deleted, false otherwise.
+     */
+    clear(packageName?: string): Promise<boolean>;
+}
+/**
+ * Global singleton instance of the MemoryEngine.
+ * Used throughout the framework to access the persistent knowledge base.
+ */
+export declare const memoryEngine: MemoryEngine;

package/dist/lib/patterns.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Centralized Regex & Matching Patterns for PromptTest
+ *
+ * Provides unified, reusable regular expressions and string extraction helpers
+ * for prompt instruction parsing, XML hierarchy parsing, and UI element matching.
+ * This file serves as the central pattern repository for all text normalization,
+ * variable interpolation, and string similarity operations across the framework.
+ */
+/**
+ * Removes leading step numbers, bullets e.g. "1. ", "10. ", "- ", "* "
+ * @type {RegExp}
+ */
+export declare const STEP_PREFIX_REGEX: RegExp;
+/**
+ * Robust extraction of text wrapped in either double quotes ("..."), single quotes ('...'),
+ * or bare tokens.
+ * Correctly handles apostrophes inside double quotes (e.g. "Today's Schedule")
+ * and double quotes inside single quotes (e.g. 'Press "OK"').
+ *
+ * @param {string} text - The input text from which to extract the quoted token.
+ * @returns {string} The extracted text without the wrapping quotes, or trimmed text if unquoted.
+ */
+export declare function extractQuotedText(text: string): string;
+/**
+ * Helper to get value from a captured token match (checking group indices)
+ *
+ * @param {(string | undefined)[]} groups - Array of captured regex groups to check.
+ * @returns {string} The first non-empty, defined capture group string.
+ */
+export declare function resolveTokenMatch(groups: (string | undefined)[]): string;
+/**
+ * Dynamic variable interpolation helper
+ *
+ * @param {string} text - The raw text containing variable placeholders to interpolate.
+ * @param {Record<string, string>} [customVars] - Optional map of custom variables to inject.
+ * @returns {string} The text with all variables resolved and interpolated.
+ */
+export declare function interpolateVariables(text: string, customVars?: Record<string, string>): string;
+/**
+ * Collection of regular expressions used to parse natural language prompt instructions
+ * into actionable test steps.
+ * @type {Record<string, RegExp>}
+ */
+export declare const PROMPT_ACTION_PATTERNS: {
+    /** TAP / CLICK: e.g. Tap 'Sign In', Click "Today's Schedule", Tap on 'rajesh.verma', Press button 'Submit' */
+    TAP: RegExp;
+    /** ORDINAL TAP: e.g. Tap 1st 'View', Click 2nd "Export", Tap last 'Delete' */
+    ORDINAL_TAP: RegExp;
+    /** RELATIVE PROXIMITY TAP: e.g. Tap 'Delete' next to 'Rohan Gupta', Click 'Edit' near 'Batch 1' */
+    PROXIMITY_TAP: RegExp;
+    /** CLEAR INPUT: e.g. Clear 'Email', Empty field 'Enter your password', Clear text in 'Search' */
+    CLEAR: RegExp;
+    /** LONG PRESS: e.g. Long press 'Mid-Term Examination Schedule', Press and hold 'Message' */
+    LONG_PRESS: RegExp;
+    /** TYPE / ENTER: e.g. Type 'ramesh@coachconnect.app' into 'Email' */
+    TYPE: RegExp;
+    /** VERIFY / ASSERT: e.g. Verify 'Apex Coaching Academy' is visible, Verify error message "Email is required" is not visible */
+    VERIFY: RegExp;
+    /** BACK: e.g. Press back, Go back, Navigate back, Back */
+    BACK: RegExp;
+    /** SCROLL TO: e.g. Scroll to 'Apex Coaching Academy', Scroll down to 'Submit', Swipe up to 'Top' */
+    SCROLL_TO: RegExp;
+    /** SCROLL / SWIPE: e.g. Scroll down, Swipe up, Swipe left on 'Card' */
+    SCROLL: RegExp;
+    /** DIRECTIONAL SWIPE: e.g. Swipe left, Swipe right, Swipe left on 'Carousel' */
+    DIRECTIONAL_SWIPE: RegExp;
+    /** TOGGLE / CHECK / UNCHECK: e.g. Toggle 'Remember Me', Check 'I agree', Turn on 'Notifications' */
+    TOGGLE: RegExp;
+    /** SELECT DROPDOWN / PICKER: e.g. Select 'Grade 10' from 'Class Dropdown' */
+    SELECT_DROPDOWN: RegExp;
+    /** APP LIFECYCLE: Launch / Open */
+    LAUNCH_APP: RegExp;
+    /** APP LIFECYCLE: Restart / Relaunch */
+    RESTART_APP: RegExp;
+    /** APP LIFECYCLE: Terminate / Close / Force Stop */
+    TERMINATE_APP: RegExp;
+    /** APP LIFECYCLE: Clear App Data */
+    CLEAR_DATA: RegExp;
+    /** APP LIFECYCLE: Grant Permission */
+    GRANT_PERMISSION: RegExp;
+    /** DEEP LINK: e.g. Open deep link 'myapp://batches/10' */
+    DEEP_LINK: RegExp;
+    /** WAIT: e.g. Wait 3s, Wait 5 seconds, Wait 2 */
+    WAIT: RegExp;
+    /** WAIT UNTIL: e.g. Wait until 'Welcome' is visible, Wait for "Submit" is enabled up to 10s */
+    WAIT_UNTIL: RegExp;
+    /** CONDITIONAL IF: e.g. If 'Allow' is visible, If 'Skip' is present */
+    IF_VISIBLE: RegExp;
+    /** CONDITIONAL ELSE */
+    ELSE: RegExp;
+    /** BLOCK TERMINATOR: End, End if, End loop, fi, done */
+    END: RegExp;
+    /** LOOP: e.g. Loop 5 times, Repeat 3 */
+    LOOP: RegExp;
+    /** FOR EACH: e.g. For each item in 'Settings List', For each 'Order Card' */
+    FOR_EACH: RegExp;
+    /** VARIABLE ASSIGNMENT: e.g. Set $username = 'admin', Set $email = $RANDOM_EMAIL */
+    SET_VARIABLE: RegExp;
+    /** DEVICE STATE: Wi-Fi on/off */
+    DEVICE_WIFI: RegExp;
+    /** DEVICE STATE: Airplane mode on/off */
+    DEVICE_AIRPLANE: RegExp;
+    /** DEVICE STATE: Orientation portrait/landscape */
+    DEVICE_ORIENTATION: RegExp;
+    /** DEVICE STATE: Notification shade */
+    DEVICE_NOTIFICATIONS: RegExp;
+    /** SPEC MODULARITY: Include / Run subflow */
+    INCLUDE_SPEC: RegExp;
+    /** JS HOOK: e.g. Run JS: vars.counter = 5 */
+    RUN_JS: RegExp;
+    /** OTP / 2FA CAPTURE: e.g. Enter verification code just sent, Enter OTP into 'Code Field' */
+    ENTER_OTP: RegExp;
+    /** API REQUEST: e.g. API GET 'https://api.example.com/status' assert status 200 */
+    API_REQUEST: RegExp;
+    /** EMAIL ASSERT: e.g. Assert email to 'user@test.com' with subject 'Welcome' contains 'Verify' */
+    EMAIL_ASSERT: RegExp;
+    /** OPTIONAL SUFFIX CHECK: (optional) or (if present) */
+    OPTIONAL_SUFFIX: RegExp;
+    /** Fallback TAP with any quotes */
+    FALLBACK_QUOTED_TAP: RegExp;
+};
+/**
+ * Collection of regular expressions used for parsing Android UI Automator XML hierarchies.
+ * @type {Record<string, RegExp>}
+ */
+export declare const XML_HIERARCHY_PATTERNS: {
+    /** Outer <hierarchy> ... </hierarchy> wrapper */
+    HIERARCHY_ROOT: RegExp;
+    /** Individual XML node tag opening / self-closing / closing */
+    NODE_TAG: RegExp;
+    /** XML attribute key-value pairs (key="value") */
+    ATTR_KEY_VALUE: RegExp;
+    /** Android element bounds string: [x1,y1][x2,y2] */
+    BOUNDS_RECT: RegExp;
+};
+/**
+ * Unescapes standard XML and numeric character entities (e.g. &#128680; -> 🚨)
+ * present in Android UI Automator hierarchy dumps.
+ *
+ * @param {string} text - The XML text to unescape.
+ * @returns {string} The unescaped string with standard characters.
+ */
+export declare function unescapeXml(text: string): string;
+/**
+ * Normalizes text for resilient matching:
+ * - Unescapes XML entities (&amp; -> &)
+ * - Trims whitespace
+ * - Converts to lower case
+ * - Normalizes curly single/double quotes to straight quotes
+ *
+ * @param {string} str - The string to normalize.
+ * @returns {string} The normalized, stripped string.
+ */
+export declare function normalizeText(str: string): string;
+/**
+ * Flexible text containment check that is resilient to case, icon prefixes,
+ * XML entity escaping (&amp; vs &), and punctuation differences.
+ *
+ * @param {string} needle - The expected text or subset to look for.
+ * @param {string} haystack - The full text to search within.
+ * @returns {boolean} True if the haystack contains the needle.
+ */
+export declare function matchesText(needle: string, haystack: string): boolean;
+/**
+ * Common keywords used to identify form submission buttons or actions.
+ * @type {string[]}
+ */
+export declare const SUBMIT_KEYWORDS: string[];
+/**
+ * Semantic keywords indicating primary user actions or interactive elements.
+ * @type {string[]}
+ */
+export declare const ACTION_KEYWORDS: string[];
+/**
+ * Computes the Levenshtein distance between two strings.
+ *
+ * @param {string} s1 - The first string to compare.
+ * @param {string} s2 - The second string to compare.
+ * @returns {number} The edit distance between the two strings.
+ */
+export declare function levenshteinDistance(s1: string, s2: string): number;
+/**
+ * Computes a normalized similarity score between 0.0 (completely different) and 1.0 (identical).
+ *
+ * @param {string} s1 - The first string to compare.
+ * @param {string} s2 - The second string to compare.
+ * @returns {number} A score representing the similarity of the strings.
+ */
+export declare function stringSimilarity(s1: string, s2: string): number;
+/**
+ * Searches a list of candidates and returns the top closest matches above a given similarity threshold.
+ *
+ * @param {string} query - The target string to search for.
+ * @param {string[]} candidates - The array of candidate strings to search against.
+ * @param {number} [limit=3] - The maximum number of matches to return.
+ * @param {number} [threshold=0.35] - The minimum similarity score required to be considered a match.
+ * @returns {{ text: string; score: number }[]} An array of objects containing matching text and their scores.
+ */
+export declare function findClosestMatches(query: string, candidates: string[], limit?: number, threshold?: number): {
+    text: string;
+    score: number;
+}[];

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

@@ -0,0 +1,100 @@
+import { AndroidDriver } from './adb.js';
+import { QaReportData, Reporter } from './reporter.js';
+import { MemoryEngine } from './memory.js';
+import { CheckpointManager } from './checkpoint.js';
+import { BaselineManager } from './baseline.js';
+import { SemanticResolver } from './ai/index.js';
+import { type PromptStep, type PromptStepType, type RunOptions } from './runner-utils.js';
+export type { PromptStep, PromptStepType, RunOptions };
+/**
+ * Core engine responsible for parsing test specs and coordinating execution
+ * on an Android device using the provided driver and services.
+ */
+export declare class PromptRunner {
+    private driver;
+    private memory;
+    private reporter;
+    private checkpoints;
+    private baselines;
+    private lastHierarchy;
+    private screenDimensions;
+    private navBarHeight;
+    /**
+     * Initializes a new instance of the PromptRunner.
+     * Uses dependency injection for core services, defaulting to singletons if omitted.
+     *
+     * @param driver - The Android ADB driver for device communication.
+     * @param memory - The memory engine for storing and retrieving learned locators.
+     * @param reporter - The reporting engine for test results.
+     * @param checkpoints - Manager for test step checkpoints and resuming.
+     * @param baselines - Manager for visual baseline testing.
+     */
+    constructor(driver?: AndroidDriver, memory?: MemoryEngine, reporter?: Reporter, checkpoints?: CheckpointManager, baselines?: BaselineManager, semanticResolver?: SemanticResolver);
+    private semanticResolver;
+    private healEnabled;
+    private activeLocale;
+    private runtimeVariables;
+    private loopStack;
+    /**
+     * Recursively expands `INCLUDE '<path>'` directives within a spec file.
+     * Resolves paths relative to current spec directory and guards against circular recursion.
+     *
+     * @param specFilePath - Path to the root spec file.
+     * @param visitedFiles - Set of visited absolute file paths in the recursion stack.
+     * @returns The fully expanded spec string.
+     * @throws SpecRecursionError if circular spec inclusion is detected.
+     */
+    expandSpecIncludes(specFilePath: string, visitedFiles?: Set<string>): string;
+    /**
+     * Expands high-level macro steps in a test spec into concrete primitive actions.
+     *
+     * @param specText - Original spec text containing potential high-level intents.
+     * @param resolver - Optional custom semantic resolver.
+     * @returns The expanded specification string and count of expanded steps.
+     */
+    expandSpec(specText: string, resolver?: SemanticResolver): Promise<{
+        expanded: string;
+        stepsAdded: number;
+    }>;
+    /**
+     * Parses a multi-line, plain-English test specification into a structured array of actionable steps.
+     * Understands variable interpolation, optional steps, flow control blocks (IF, LOOP), and all action types.
+     *
+     * @param promptText - The raw plain-English spec to parse.
+     * @param customVars - Optional key-value pairs for string interpolation.
+     * @returns An array of parsed PromptStep objects structured into an execution AST.
+     */
+    parsePrompt(promptText: string, customVars?: Record<string, string>): PromptStep[];
+    /**
+     * Executes a plain-English test spec against the connected Android device.
+     * Handles device locking, memory loading, sequential execution, checkpointing,
+     * error recovery, and final report generation.
+     *
+     * @param specFilePath - The absolute or relative path to the plain-English spec file.
+     * @param pkgOrOptions - The target app package name (legacy) or a RunOptions configuration object.
+     * @param legacySerial - The target device serial number (legacy support).
+     * @returns A promise that resolves to the final QA report data upon completion or failure.
+     * @throws Error if the spec file does not exist.
+     */
+    runSpec(specFilePath: string, pkgOrOptions?: string | RunOptions, legacySerial?: string): Promise<QaReportData>;
+    private getCleanHierarchy;
+    /**
+     * Expectation-driven dynamic polling: waits for an element matching target to appear on screen.
+     * Proceeds as soon as the element exists without waiting for blind static sleeps.
+     */
+    private ensureInViewport;
+    private waitForTarget;
+    private buildDiagnosticError;
+    executeStep(step: PromptStep, serial?: string, upcomingSteps?: PromptStep[]): Promise<{
+        fastForwarded?: boolean;
+        reason?: string;
+        skipCount?: number;
+    } | void>;
+    private findTargetInputField;
+    private matchNodes;
+}
+/**
+ * A singleton instance of the PromptRunner.
+ * Pre-configured with default dependencies for convenient global usage across the framework.
+ */
+export declare const promptRunner: PromptRunner;

package/dist/lib/recorder.d.ts

@@ -0,0 +1,115 @@
+import { AndroidDriver } from './adb.js';
+/**
+ * Configuration options for the recording session.
+ */
+export interface RecordOptions {
+    /**
+     * If true, the recorder will append new captured steps to the existing test spec file
+     * rather than overwriting or creating a new file.
+     */
+    append?: boolean;
+}
+/**
+ * Represents a discrete user interaction event captured during the session.
+ */
+export interface RecordedEvent {
+    /** The generated plain-English instruction for this event. */
+    stepText: string;
+    /** The exact epoch timestamp (in milliseconds) when this event occurred. */
+    timestamp: number;
+}
+/**
+ * The core engine that listens to device input and transforms raw interaction telemetry
+ * into semantic PromptTest step instructions.
+ */
+export declare class AutonomousRecorder {
+    private driver;
+    private deviceLock;
+    private isRecording;
+    private recordedSteps;
+    private existingSteps;
+    private existingFileHeader;
+    private lastHierarchyFlat;
+    private lastScreenTitle;
+    private visitedScreens;
+    private targetPackage;
+    private isAppendMode;
+    private resolvedOutputPath;
+    private activeInput;
+    private geteventProcess;
+    private isRefreshingHierarchy;
+    private targetSerial;
+    private touchMaxX;
+    private touchMaxY;
+    private displayWidth;
+    private displayHeight;
+    private lastTapTimestamp;
+    private lastRecordedTapTarget;
+    private inFlightTapQueue;
+    private lastScrollTimestamp;
+    private lastScrollDirection;
+    private inputDebounceTimer;
+    private logcatEventProcess;
+    private logcatCrashProcess;
+    private hierarchyStale;
+    private hierarchyCacheTime;
+    private currentScreenName;
+    private sessionScreenSections;
+    private sessionStartTime;
+    private screenshotDir;
+    private screenshotCounter;
+    private crashDetected;
+    private lastScreenTransitionTime;
+    /**
+     * Initializes a new AutonomousRecorder.
+     * @param driver An optional AndroidDriver instance to use. If omitted, the default singleton is used.
+     */
+    constructor(driver?: AndroidDriver);
+    private extractBrandSlug;
+    /**
+     * Starts an interactive real-time recording session on the target Android device.
+     * Automatically detects the active app, starts capturing gestures and key events,
+     * monitors screen transitions, and writes out a plain-text spec.
+     *
+     * @param outputSpecPath Optional file path to save the generated test spec to.
+     * @param serial Optional serial number of the target device to record from.
+     * @param options Additional recording configuration options.
+     * @returns A promise that resolves when the recording session concludes.
+     */
+    startRecording(outputSpecPath?: string, serial?: string, options?: RecordOptions): Promise<void>;
+    private startEventStream;
+    private cleanLabel;
+    private handleScroll;
+    private handleSwipe;
+    private handleLongPressAt;
+    private handleTapAt;
+    private handleKeyPress;
+    private scheduleInputDebounce;
+    private flushActiveInput;
+    private syncActiveInputText;
+    private recordInputText;
+    private startLogcatScreenWatcher;
+    private startLogcatCrashWatcher;
+    private captureSessionScreenshot;
+    private triggerAsyncHierarchyRefresh;
+    private doHierarchyRefresh;
+    private detectAndLogTransientAlerts;
+    private refreshHierarchySync;
+    private isIconGlyph;
+    private cleanDialogOrCompoundLabel;
+    private isCardMetadataSubtitle;
+    private findPrimaryCardTitle;
+    private resolveActionLabel;
+    private getCurrentStepNumber;
+    private detectAndLogScreenHeader;
+    private resolveFieldLabel;
+    private isPlaceholderText;
+    private saveSpec;
+    private saveReport;
+    private printExitSummary;
+}
+/**
+ * Pre-instantiated global singleton instance of the AutonomousRecorder.
+ * Use this for starting recording sessions without managing class instances manually.
+ */
+export declare const autonomousRecorder: AutonomousRecorder;