prompttest 1.3.5 → 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-provisioner.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @module adb-provisioner
+ * @description
+ * Zero-dependency hardware discovery and ADB provisioning engine.
+ * Automatically discovers, validates, and provisions Android Debug Bridge (ADB)
+ * binaries across Windows, macOS, and Linux without requiring full Android Studio installation.
+ */
+export interface AdbDiagnosticInfo {
+    binaryPath: string;
+    isAvailable: boolean;
+    version?: string;
+    source: 'PROMPTTEST_OVERRIDE' | 'BUNDLED_LOCAL' | 'SYSTEM_PATH' | 'ANDROID_HOME' | 'STANDALONE_CACHE' | 'STANDARD_SDK' | 'FALLBACK';
+}
+/**
+ * Discovers the absolute or executable path to the ADB binary on the host system.
+ * Evaluates candidate locations in strict order of reliability:
+ * 1. Environment override (`PROMPTTEST_ADB_PATH`)
+ * 2. Bundled / Adjacent platform-tools (next to executable, app bundle, or current cwd)
+ * 3. System PATH lookup
+ * 4. Android SDK environment variables (`ANDROID_HOME`, `ANDROID_SDK_ROOT`)
+ * 5. Standard platform installation paths
+ * 6. Standalone user cache (`~/.prompttest/platform-tools/adb`)
+ */
+export declare function getAdbBinary(): string;
+/**
+ * Checks whether the resolved ADB binary is executable and operational.
+ *
+ * @param customPath Optional custom binary path to verify.
+ */
+export declare function isAdbAvailable(customPath?: string): boolean;
+/**
+ * Returns full diagnostics about ADB availability and resolution origin.
+ */
+export declare function getAdbDiagnostics(): AdbDiagnosticInfo;
+/**
+ * Resets cached ADB path (useful for testing and runtime environment shifts).
+ */
+export declare function resetAdbCache(): void;
+/**
+ * Automatically downloads and provisions official platform-tools if ADB is missing.
+ */
+export declare function downloadPlatformToolsFallback(customDestDir?: string): Promise<string>;
+/**
+ * Prompts the user for explicit permission to download official platform-tools if ADB is missing.
+ * Automatically approved if --download-adb, -y, or --yes flag is present in process.argv.
+ */
+export declare function promptUserForAdbDownload(): Promise<boolean>;
+/**
+ * Asserts that ADB is available, prompting for user permission before automated provisioning if missing.
+ *
+ * @param options.skipPrompt If true, bypasses the user prompt (e.g. when --download-adb flag is passed).
+ */
+export declare function ensureAdbProvisioned(options?: {
+    skipPrompt?: boolean;
+}): Promise<string>;

package/dist/lib/adb.d.ts

@@ -19,6 +19,29 @@ export interface AndroidDevice {
     /** The product name of the device (optional) */
     product?: string;
 }
+export interface DeviceMetrics {
+    battery?: {
+        level?: number;
+        temperatureC?: number;
+        status?: string;
+    };
+    display?: {
+        width?: number;
+        height?: number;
+        density?: number;
+    };
+    memory?: {
+        pssKb?: number;
+        privateDirtyKb?: number;
+        nativeHeapKb?: number;
+    };
+    graphics?: {
+        framesRendered?: number;
+        jankyFrames?: number;
+        percentile90Ms?: number;
+    };
+}
+export declare function parseDeviceMetrics(batteryOutput: string, displayOutput: string, memoryOutput: string, graphicsOutput: string): DeviceMetrics;
 /**
  * AndroidDriver is responsible for executing ADB commands and handling device interactions.
  * It manages the default targeted device, executes shell commands, extracts device state,
@@ -323,6 +346,11 @@ export declare class AndroidDriver {
      * @throws An Error if the device IP cannot be detected.
      */
     disconnectWifi(target?: string): Promise<string>;
+    pairWifi(target: string, pairingCode: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    getDeviceMetrics(serial?: string): Promise<DeviceMetrics>;
     /**
      * Streams the Android events logcat buffer in real-time.
      * Used for detecting screen transitions via wm_on_resume_called events.
@@ -378,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/baseline.d.ts

@@ -2,19 +2,33 @@
  * Rectangular region on the screen to ignore during visual comparison.
  */
 export interface MaskRegion {
-    /** The starting horizontal pixel coordinate. */
+    /** The starting horizontal pixel coordinate or relative float (0.0 - 1.0). */
     x: number;
-    /** The starting vertical pixel coordinate. */
+    /** The starting vertical pixel coordinate or relative float (0.0 - 1.0). */
     y: number;
-    /** Width of the region in pixels. */
+    /** Width of the region in pixels or relative float (0.0 - 1.0). */
     width: number;
-    /** Height of the region in pixels. */
+    /** Height of the region in pixels or relative float (0.0 - 1.0). */
     height: number;
+    /** Optional human-readable label for the ignored region (e.g., 'Status Bar', 'Clock'). */
+    label?: string;
 }
+/**
+ * Predefined tolerance and sensitivity presets for visual comparison.
+ */
+export type MatchingMode = 'strict' | 'moderate' | 'relaxed';
+export declare const MATCHING_MODES: Record<MatchingMode, {
+    threshold: number;
+    pixelmatchThreshold: number;
+    label: string;
+    description: string;
+}>;
 /**
  * Options for configuring visual baseline comparisons.
  */
 export interface BaselineCompareOptions {
+    /** Matching preset mode ('strict', 'moderate', 'relaxed'). Defaults to 'moderate'. */
+    mode?: MatchingMode;
     /** Override the maximum allowed diffRatio (0.0 to 1.0) before failing. */
     threshold?: number;
     /** Array of bounding boxes to mask out (e.g. dynamic clocks, battery, animations). */
@@ -61,6 +75,24 @@ export declare class BaselineManager {
     constructor(baselineDir?: string, threshold?: number);
     private filePath;
     private diffFilePath;
+    private masksFilePath;
+    /**
+     * Retrieves saved mask regions for a specific test step.
+     *
+     * @param specName The name of the test specification.
+     * @param stepIndex The 0-based index of the step within the spec.
+     * @returns Array of MaskRegion bounding boxes.
+     */
+    getMasks(specName: string, stepIndex: number): Promise<MaskRegion[]>;
+    /**
+     * Persists mask regions to disk for a specific test step.
+     *
+     * @param specName The name of the test specification.
+     * @param stepIndex The 0-based index of the step within the spec.
+     * @param masks Array of MaskRegion bounding boxes.
+     * @returns The file path where masks were stored.
+     */
+    saveMasks(specName: string, stepIndex: number, masks: MaskRegion[]): Promise<string>;
     /**
      * Saves a new screenshot as the baseline reference for a specific test step.
      * Uses an atomic write (via a temp file) to prevent partial writes.
@@ -96,14 +128,30 @@ export declare class BaselineManager {
     private fitToCanvas;
     /**
      * Masks specified rectangular regions in-place by setting their RGBA values to 0.
+     * Supports both pixel coordinates and relative fractional coordinates (0.0 to 1.0).
      */
     private applyMasks;
+    /**
+     * Overwrites the golden baseline with the current screenshot or a provided buffer.
+     *
+     * @param specName The name of the test specification.
+     * @param stepIndex The 0-based index of the step within the spec.
+     * @param screenshot Optional replacement buffer; if omitted, copies current run screenshot.
+     */
+    approveBaseline(specName: string, stepIndex: number, screenshot?: Buffer): Promise<string>;
     /**
      * Deletes all saved baseline, current, and diff images for a given spec.
      *
      * @param specName The name of the test specification to clear baselines for.
      */
     clearBaselines(specName: string): Promise<void>;
+    /**
+     * Deletes all saved baseline, current, diff images, and masks for a single specific step.
+     *
+     * @param specName The name of the test specification.
+     * @param stepIndex The 1-based step index to delete.
+     */
+    deleteStepBaseline(specName: string, stepIndex: number): Promise<void>;
 }
 /**
  * A globally accessible singleton instance of BaselineManager.

package/dist/lib/dfs-engine.d.ts

@@ -25,6 +25,28 @@ export interface NavigationFrame {
     actionTaken?: string;
     timestamp: number;
 }
+/**
+ * Telemetry event emitted by the DFS engine while traversing the state graph.
+ * Consumed by the Studio Auto-Pilot tab through the live-server SSE stream.
+ */
+export interface DfsTelemetryEvent {
+    /** Event category: executor action, screen discovery, safety block, defect, or completion. */
+    type: 'action' | 'state_change' | 'safety_block' | 'crash' | 'done';
+    /** Plain-English description. Action descriptions are spec-compatible instructions. */
+    description: string;
+    /** Canonical semantic hash of the screen the event occurred on. */
+    screenHash?: string;
+    /** Human-readable screen title (domain path) used to label the state-graph node. */
+    screenTitle?: string;
+    /** DFS depth of the screen the event occurred on. */
+    depth?: number;
+    /** Number of interactive candidate elements catalogued on the screen. */
+    elementCount?: number;
+    /** Number of unique screens discovered so far. */
+    discoveredScreens?: number;
+    /** Number of interaction steps consumed so far. */
+    totalSteps?: number;
+}
 export interface DfsEngineOptions {
     packageName: string;
     serial?: string;
@@ -36,6 +58,12 @@ export interface DfsEngineOptions {
     safetyBlacklist?: readonly (string | RegExp)[];
     screenshotPolicy?: 'all' | 'state-change' | 'failure-only';
     skipAlreadyCrawled?: boolean;
+    /** Optional telemetry sink invoked for every traversal event (Studio Auto-Pilot SSE). */
+    onStep?: (event: DfsTelemetryEvent) => void;
+    /** Optional abort flag checked between steps to terminate traversal gracefully. */
+    abortSignal?: {
+        aborted: boolean;
+    };
 }
 /**
  * Universal Hierarchical State-Graph DFS Engine (Universal Exploration Engine).
@@ -55,7 +83,22 @@ export declare class HierarchicalDfsEngine {
     devDefectsList: string[];
     safetyHitList: string[];
     externalSkippedList: string[];
+    /** Telemetry listener registered for the active traversal session. */
+    private stepListener?;
+    /** Abort flag registered for the active traversal session. */
+    private abortFlag?;
     constructor(driver?: AndroidDriver, reporter?: QaReporter, memory?: MemoryEngine);
+    /**
+     * Emits a telemetry event to the registered listener, defaulting the live counters.
+     * Screen depth and element counts are back-filled from the state-graph ledger so the
+     * Studio Auto-Pilot graph renders real hierarchy instead of a flat staircase.
+     * Listener failures are swallowed so observability can never break traversal.
+     *
+     * @param event - The traversal event to broadcast.
+     */
+    private emitStep;
+    /** Returns true when the active session has been aborted by the caller. */
+    private isAborted;
     /**
      * Captures UI hierarchy globally, intercepting and triaging any development error consoles,
      * LogBox overlays, warnings, info toasts, or ANRs before returning a clean app hierarchy.

package/dist/lib/explorer.d.ts

@@ -3,6 +3,36 @@ import { type SafetyMode, type UiNode } from './crawler.js';
 import { SemanticFormFiller } from './form-filler.js';
 import { QaReporter } from './reporter.js';
 import { MemoryEngine } from './memory.js';
+/**
+ * Represents a single autonomous exploration event, emitted as the explorer acts.
+ * Used for Studio SSE streaming via the /api/explore/* endpoints.
+ */
+export interface ExploreEvent {
+    /** Type of event: action taken, state change, safety block, crash intercepted, session done, or error. */
+    type: 'action' | 'state_change' | 'safety_block' | 'crash' | 'done' | 'error';
+    /** Monotonic step counter within this session. */
+    stepNumber: number;
+    /** Human-readable description of the event. */
+    description: string;
+    /** MD5-prefix hash of the screen hierarchy at this moment (for state-graph nodes). */
+    screenHash?: string;
+    /** Optional human-readable title for the screen (domain path) used to label the state-graph node. */
+    screenTitle?: string;
+    /** Optional traversal depth of the screen this event occurred on (DFS nesting level). */
+    depth?: number;
+    /** Optional number of interactive candidate elements catalogued on the screen. */
+    elementCount?: number;
+    /** Total discovered unique screens so far. */
+    discoveredScreens?: number;
+    /** Duration of the action in milliseconds. */
+    durationMs?: number;
+    /** Total step budget consumed so far. */
+    totalSteps?: number;
+    /** Package being explored. */
+    packageName?: string;
+    /** Auto-generated spec lines (only present on 'done' event). */
+    generatedSpec?: string;
+}
 /**
  * Configuration options for the AutonomousExplorer.
  */
@@ -31,6 +61,20 @@ export interface ExplorerOptions {
     stepBudget?: number;
     /** Screenshot policy ('state-change', 'failure-only', 'all') (AX-16). Default is 'state-change'. */
     screenshots?: 'state-change' | 'failure-only' | 'all';
+    /** Whether to record entire exploration session to an MP4 video (Phase 26). Default is false. */
+    video?: boolean;
+    /**
+     * Optional callback fired after every significant exploration event.
+     * Used by live-server to SSE-stream progress to Studio Auto-Pilot tab.
+     */
+    onStep?: (event: ExploreEvent) => void;
+    /**
+     * Optional abort signal. When set, the explorer checks this flag between steps
+     * and terminates the session gracefully if it becomes true.
+     */
+    abortSignal?: {
+        aborted: boolean;
+    };
 }
 /**
  * AutonomousExplorer implements the heuristic mobile crawler.

package/dist/lib/feedback.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @module feedback
+ * @description
+ * Direct in-CLI feedback and community suggestion portal for PromptTest.
+ * Collects user ratings, feature suggestions, or issue reports and generates
+ * 1-click pre-filled submissions to the public prompttest-community repository.
+ */
+export type FeedbackCategory = 'feature' | 'bug' | 'general';
+export interface FeedbackData {
+    rating?: number;
+    category: FeedbackCategory;
+    message: string;
+    author?: string;
+    environment?: string;
+}
+export interface FeedbackOptions {
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+    directMessage?: string;
+    category?: FeedbackCategory;
+}
+/**
+ * Constructs a pre-filled GitHub issue or discussion URL based on the feedback category.
+ *
+ * @param data - The user feedback payload.
+ * @returns The fully-encoded GitHub URL.
+ */
+export declare function buildFeedbackUrl(data: FeedbackData): string;
+/**
+ * Starts an interactive feedback collection session in the terminal.
+ *
+ * @param options - Stream and direct message options.
+ * @returns The generated pre-filled GitHub URL.
+ */
+export declare function startFeedbackSession(options?: FeedbackOptions): Promise<string>;

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/live-server.d.ts

@@ -8,6 +8,7 @@
  */
 import http from 'http';
 import { AuditStep, QaReportData } from './reporter.js';
+import { AndroidDriver } from './adb.js';
 export interface LiveServerOptions {
     /** The port number to listen on. Defaults to 4040 (or 0 for random available port). */
     port?: number;
@@ -15,10 +16,14 @@ export interface LiveServerOptions {
     host?: string;
     /** Directory where screenshots, recordings, and report artifacts are located. */
     outputDir?: string;
+    /** Directory containing test specifications. Defaults to process.cwd()/specs. */
+    specsDir?: string;
     /** Name of the test suite being executed. */
     suiteName?: string;
     /** Initial report data if available. */
     initialReport?: QaReportData;
+    /** Optional AndroidDriver instance for interactive device state and actions. */
+    driver?: AndroidDriver;
 }
 export interface LiveServerHandle {
     /** The underlying Node.js HTTP server instance. */

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/recorder.d.ts

@@ -23,6 +23,7 @@ export interface RecordedEvent {
  * into semantic PromptTest step instructions.
  */
 export declare class AutonomousRecorder {
+    onStep?: (step: string) => void;
     private driver;
     private deviceLock;
     private isRecording;
@@ -82,6 +83,29 @@ export declare class AutonomousRecorder {
      */
     private appendStep;
     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.
+     */
+    /**
+     * Starts a non-blocking recording session (used by both CLI and Live Server).
+     */
+    startSession(outputSpecPath?: string, serial?: string, options?: RecordOptions): Promise<void>;
+    /**
+     * Stops an active recording session, terminates background processes,
+     * releases device lock, and returns the recorded steps and file paths.
+     */
+    stopSession(): Promise<{
+        steps: string[];
+        specPath: string;
+        reportPath: string;
+    }>;
     /**
      * Starts an interactive real-time recording session on the target Android device.
      * Automatically detects the active app, starts capturing gestures and key events,

package/dist/lib/reporter.d.ts

@@ -31,6 +31,8 @@ export interface AuditStep {
     durationMs?: number;
     /** Relative path to the failure triage bundle directory if step failed. */
     triageBundle?: string;
+    /** Relative execution offset in milliseconds from start of run / video recording. */
+    videoOffsetMs?: number;
     /** Additional diagnostic data or context about the step. */
     details?: Record<string, unknown>;
 }

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