prompttest-mobile 1.5.1

package/dist/lib/logger.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Defines the available log severity levels.
+ * Priority increases from DEBUG to SILENT.
+ */
+export type LogLevel = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'SILENT';
+/**
+ * A utility class for handling formatted, level-filtered console output.
+ */
+export declare class Logger {
+    private currentLevel;
+    /**
+     * Initializes a new Logger instance.
+     * If an initialLevel is not provided, it falls back to the LOG_LEVEL environment variable,
+     * or defaults to 'INFO'.
+     *
+     * @param initialLevel An optional initial log level to override the default.
+     */
+    constructor(initialLevel?: LogLevel);
+    /**
+     * Updates the current log level threshold.
+     *
+     * @param level The new log level to apply.
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Gets the current log level threshold.
+     *
+     * @returns The currently active LogLevel.
+     */
+    getLevel(): LogLevel;
+    /**
+     * Determines if a specific log level is currently enabled based on the threshold.
+     *
+     * @param level The log level to check.
+     * @returns true if messages of this level should be output, false otherwise.
+     */
+    isLevelEnabled(level: LogLevel): boolean;
+    private isJsonMode;
+    private emitJson;
+    /**
+     * Logs a debug message to stdout. Formatted in gray or structured JSON.
+     *
+     * @param args The message or variables to log.
+     */
+    debug(...args: unknown[]): void;
+    /**
+     * Logs an informational message to stdout. No special formatting applied or structured JSON.
+     *
+     * @param args The message or variables to log.
+     */
+    info(...args: unknown[]): void;
+    /**
+     * Logs a warning message to stderr. Formatted in yellow or structured JSON.
+     *
+     * @param args The message or variables to log.
+     */
+    warn(...args: unknown[]): void;
+    /**
+     * Logs an error message to stderr. Formatted in red or structured JSON.
+     *
+     * @param args The message or variables to log.
+     */
+    error(...args: unknown[]): void;
+}
+/**
+ * A globally accessible singleton instance of Logger for use throughout the PromptTest codebase.
+ */
+export declare const logger: Logger;

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

@@ -0,0 +1,75 @@
+/**
+ * @module profiler
+ * @description
+ * Real-Time Mobile Performance & FPS Profiler (PF-01).
+ * Samples `dumpsys gfxinfo <pkg>` and `dumpsys meminfo <pkg>` during test execution,
+ * computes frame rendering statistics, jank percentages, and memory growth.
+ */
+import { AndroidDriver } from './adb.js';
+export interface FrameStats {
+    totalFrames: number;
+    jankyFrames: number;
+    jankPercentage: number;
+    p50Ms?: number;
+    p90Ms?: number;
+    p95Ms?: number;
+    p99Ms?: number;
+    missedVsync?: number;
+    slowUiThread?: number;
+}
+export interface MemorySample {
+    timestamp: number;
+    stepIndex?: number;
+    stepName?: string;
+    totalPssKb: number;
+    nativeHeapKb?: number;
+    javaHeapKb?: number;
+}
+export interface PerformanceReport {
+    packageName: string;
+    durationMs: number;
+    fpsCompliance: 'PASS' | 'WARN' | 'FAIL';
+    frames: FrameStats;
+    memory: {
+        startPssKb: number;
+        peakPssKb: number;
+        endPssKb: number;
+        deltaPssKb: number;
+        samples: MemorySample[];
+    };
+}
+/**
+ * Parses dumpsys gfxinfo stdout to extract frame counts, jank percentage, and percentile latencies.
+ */
+export declare function parseGfxInfo(stdout: string): FrameStats;
+/**
+ * Parses dumpsys meminfo stdout to extract Total PSS, Native Heap, and Java Heap values in KB.
+ */
+export declare function parseMemInfo(stdout: string): {
+    totalPssKb: number;
+    nativeHeapKb?: number;
+    javaHeapKb?: number;
+};
+/**
+ * PerformanceProfiler tracks real-time frame times, jank metrics, and memory growth.
+ */
+export declare class PerformanceProfiler {
+    private driver;
+    private serial?;
+    private packageName;
+    private startTime;
+    private memorySamples;
+    constructor(driver?: AndroidDriver, serial?: string);
+    /**
+     * Starts tracking performance for the target package.
+     */
+    start(packageName: string): Promise<void>;
+    /**
+     * Captures a discrete memory sample at a step transition.
+     */
+    sample(stepIndex: number, stepName: string): Promise<void>;
+    /**
+     * Finalizes tracking and returns the performance report.
+     */
+    stop(): Promise<PerformanceReport>;
+}