@vostride/agent-qa-android 0.1.21 → 0.2.1

package/dist/index.d.cts

@@ -1,34 +1,161 @@
-import { PlatformAdapter, PlatformConfig, ObserveOptions, ScreenState, Action, ActionResult, ConsoleLogEntry } from '@vostride/agent-qa-core';
+import { PlatformAdapter, PlatformConfig, ObserveOptions, ActionsFor, ActionResult, ConsoleLogEntry, LiveStreamCapability, RecordingCapability } from '@vostride/agent-qa-runner';
+import { ScreenState } from '@vostride/agent-qa-schema';
 
-declare class AndroidPlatformAdapter implements PlatformAdapter {
+declare class AndroidPlatformAdapter implements PlatformAdapter<'android'> {
     readonly platform: "android";
     private driver;
     private lastRefs;
     private config;
     private activeWebContext;
     private currentContext;
-    private recordingEnabled;
-    private videoDir;
-    private videoPath;
+    private recordingCapability;
+    private liveStreamCapability;
     private consoleLogs;
     private consoleDrainIndex;
     private captureConsole;
     private appPackage;
     private appPid;
+    private appRegistry;
     setup(config: PlatformConfig): Promise<void>;
     cleanup(): Promise<void>;
     private hasSeenWebContext;
     observe(_options?: ObserveOptions): Promise<ScreenState>;
-    execute(action: Action): Promise<ActionResult>;
+    execute(action: ActionsFor<'android'>): Promise<ActionResult>;
     screenshot(): Promise<Buffer | undefined>;
     pollDeviceLogs(): Promise<void>;
     drainConsoleLogs(level?: string): ConsoleLogEntry[];
-    getVideoPath(): Promise<string | null>;
-    private stopAndSaveRecording;
+    /**
+     * 428 D-11: the labelled 1s snapshot preview, over `captureScreenshot()` — `takeScreenshot()`
+     * and nothing else. Never `screenshot()`: that one switches the Appium context, and a tick
+     * landing between a step's context switch and its command would run the command in the wrong
+     * context. Declared before the driver exists (a capture then answers `undefined`), so the
+     * composition's selection never falls through to `screenshot()`.
+     */
+    get liveStream(): LiveStreamCapability;
+    get recording(): RecordingCapability | undefined;
     private tryObserveWeb;
     private observeNative;
     private ensureContext;
     private captureScreenshot;
+    /** Read the live text of a focused element handle; undefined when nothing is readable. */
+    private readElementText;
+    private focusedMatches;
+    /** An empty field's getText() returns its hint (437 Pitfall 4), so a showing hint reads ''. */
+    private readFocusedValue;
+    /**
+     * The `mobile: shell` route of keyevent and openQuickSettings (437 D-18). A refusal by secure
+     * Appium is recorded as unavailable and any other driver error as failed; neither is a pass.
+     */
+    private runShell;
+    /** The one submit mechanism on every Android path (437 D-13); pressed once, never retried. */
+    private pressEnter;
+    /** 437 FA-2 (owner, 2026-10-08): line breaks into a single-line field are refused before typing. */
+    private refuseLineBreaks;
+    /**
+     * Native fill from the focused handle (437 D-08..D-10, D-12, D-13, D-15, D-17). Delivers once
+     * (addValue for append, setValue for replace), reads back from the same handle and records the
+     * shared verdict. An unknown append prior or an unreadable read-back is unverified, which never
+     * stops a requested Enter; a mismatch or a multi-line field holds it. A driver error during
+     * delivery ends the fill: nothing is typed again and no Enter follows. A secure field yields
+     * length sentinels only.
+     */
+    private fillNativeCompound;
+    /** The focused element handle, or undefined when UiAutomator2 reports none or the lookup fails. */
+    private focusedField;
+    /**
+     * 437 D-11 (WR-02): where the focused node is relative to the ref, judged by its read bounds.
+     * An unreadable or unparseable value is no evidence, so the native path stays (D-04, D-15).
+     * 444.1 D-07: 'elsewhere' needs positive evidence, the bounds of another observed field.
+     */
+    private focusIsElsewhere;
+    /** Ctrl+A then DEL as key input; clears only the view holding input focus (437 D-14). */
+    private clearByKeys;
+    /**
+     * The last-resort keyboard path (437 D-14): the tap left no focused handle. Replace clears by
+     * keys, the text goes through one `mobile: type` (Appium's Unicode IME, exact for every D-08
+     * text), and the value is read back only when a focused handle can be found afterwards. An
+     * append's prior value is unknown, so it is never better than unverified. The field's kind comes
+     * from the observed input-type (D-15): only positive evidence refuses line breaks or holds Enter.
+     */
+    private fillKeyboardPath;
+    /**
+     * Native and keyboard clearText (437 D-16): clearValue on the focused handle, or Ctrl+A then DEL
+     * when the tap left none, then the hint-aware read-back judged against the empty string. The
+     * caller has already checked that a focused handle is the referenced field (WR-02).
+     */
+    private clearNativeOrKeyboard;
+    private isSecure;
+    private settleClear;
+    /** A driver error while clearing ends the clear; it is never repeated. */
+    private interruptedClear;
+    /** A driver error during delivery ends the fill: nothing is typed again and no Enter follows. */
+    private interruptedFill;
+    /**
+     * The shared end of every Android fill (437 D-09, D-10, D-13, D-15, D-17): records the verdict
+     * and, when a submit was requested, holds Enter on a mismatch or a multi-line field and otherwise
+     * presses it once through `enter`.
+     */
+    private settleFill;
+    /** A real W3C touch tap in the WebView context at the ref's CSS-pixel centre (437 D-11). */
+    private trustedWebTap;
+    /** Whether the tap left an editable field focused at the ref's point; read-only. */
+    private probeWebFocus;
+    /** Polls the read-only probe until the tap's field holds focus; returns the last answer. */
+    private awaitWebFocus;
+    private readWebFieldValue;
+    /** Runs a driver call from NATIVE_APP and always returns to the active WebView context. */
+    private withNativeContext;
+    /** 437 D-11: a tap that left no editable field, or another field, focused writes nothing. */
+    private refuseFocus;
+    /**
+     * WebView clearText (437 D-11, D-16): the same tap and focus probe as the fill, W3C Ctrl+A and
+     * Backspace, then a read-back judged against the empty string. Never success without that check.
+     */
+    private clearWebViewField;
+    /**
+     * WebView fill as trusted input (437 D-11): a W3C tap on the ref, a read-only focus probe,
+     * W3C Ctrl+A and Backspace for replace, `mobile: type` from NATIVE_APP, a read-only read-back,
+     * and one `mobile: pressKey 66` from NATIVE_APP. No script writes the field or fires an event.
+     */
+    private fillWebViewCompound;
+    /**
+     * EXEC-02 platform primitives injected into the shared runner scroll loops (D-02/D-03; 436-02
+     * D-25). A native swipe is `mobile: scrollGesture` over the container (the ref's bounds, else the
+     * screen), whose boolean is the driver's own boundary signal; in a WebView the touch swipe is
+     * measured over every WebView scroller before and after (436-18), paired by identity (436-23).
+     * nativeSearchScroll drives the UiAutomator
+     * `UiScrollable.scrollIntoView` rung over an injection-escaped selector; readInterimTree is a
+     * light page-source parse — NO refMap mint, NO screenshot, lastRefs untouched.
+     */
+    private buildAndroidScrollPrimitives;
+    /**
+     * The WebView scrollers a touch swipe may have acted on (436-18 · D-25), read by the shared
+     * WEBVIEW_SCROLLERS_SCRIPT. The touch point cannot be mapped into the WebView's CSS coordinates,
+     * so the swipe is judged over all of them.
+     * 2026-10-08 (436-23): a frame in view reads unknown; members carry an identity and are paired
+     * by it; open shadow roots are walked; only on-screen element scrollers are members.
+     */
+    private readWebViewScrollers;
+    /**
+     * EXEC-03 openApp (D-10/D-11/D-12). Resolve a human name to a package id (or validate an
+     * explicit bundleId) over the session-cached registry, then launch via activateApp. On a
+     * resolution MISS the registry is re-enumerated exactly once (catches mid-run installs) before
+     * erroring with the resolver's candidate ids. Never a best-guess launch (T-359-04).
+     */
+    private openApp;
+    /** Return the cached registry, enumerating once on first use. Failed enumeration returns null (uncached). */
+    private ensureAppRegistry;
+    /**
+     * Enumerate installed apps through the driver only (ownership contract — no adb/child_process).
+     * `mobile: listApps` maps package ids → AppRegistryEntry (labels only when the same call carries
+     * them, D-10 — no per-package round-trips). On failure, fall back to `mobile: shell` pm-list ONLY
+     * when the AGENT_QA_ANDROID_USE_MOBILE_SHELL gate is '1' (Pitfall 4). Null = enumeration unavailable.
+     */
+    private enumerateApps;
+    /** Coerce a `mobile: listApps` result (package-id-keyed map, or an array of entries) into the registry. */
+    private mapListApps;
+    /** Parse `pm list packages` output ("package:com.foo\n…") into id-only registry entries. */
+    private parsePmListPackages;
     private executeAction;
 }
 

package/dist/index.d.ts

@@ -1,34 +1,161 @@
-import { PlatformAdapter, PlatformConfig, ObserveOptions, ScreenState, Action, ActionResult, ConsoleLogEntry } from '@vostride/agent-qa-core';
+import { PlatformAdapter, PlatformConfig, ObserveOptions, ActionsFor, ActionResult, ConsoleLogEntry, LiveStreamCapability, RecordingCapability } from '@vostride/agent-qa-runner';
+import { ScreenState } from '@vostride/agent-qa-schema';
 
-declare class AndroidPlatformAdapter implements PlatformAdapter {
+declare class AndroidPlatformAdapter implements PlatformAdapter<'android'> {
     readonly platform: "android";
     private driver;
     private lastRefs;
     private config;
     private activeWebContext;
     private currentContext;
-    private recordingEnabled;
-    private videoDir;
-    private videoPath;
+    private recordingCapability;
+    private liveStreamCapability;
     private consoleLogs;
     private consoleDrainIndex;
     private captureConsole;
     private appPackage;
     private appPid;
+    private appRegistry;
     setup(config: PlatformConfig): Promise<void>;
     cleanup(): Promise<void>;
     private hasSeenWebContext;
     observe(_options?: ObserveOptions): Promise<ScreenState>;
-    execute(action: Action): Promise<ActionResult>;
+    execute(action: ActionsFor<'android'>): Promise<ActionResult>;
     screenshot(): Promise<Buffer | undefined>;
     pollDeviceLogs(): Promise<void>;
     drainConsoleLogs(level?: string): ConsoleLogEntry[];
-    getVideoPath(): Promise<string | null>;
-    private stopAndSaveRecording;
+    /**
+     * 428 D-11: the labelled 1s snapshot preview, over `captureScreenshot()` — `takeScreenshot()`
+     * and nothing else. Never `screenshot()`: that one switches the Appium context, and a tick
+     * landing between a step's context switch and its command would run the command in the wrong
+     * context. Declared before the driver exists (a capture then answers `undefined`), so the
+     * composition's selection never falls through to `screenshot()`.
+     */
+    get liveStream(): LiveStreamCapability;
+    get recording(): RecordingCapability | undefined;
     private tryObserveWeb;
     private observeNative;
     private ensureContext;
     private captureScreenshot;
+    /** Read the live text of a focused element handle; undefined when nothing is readable. */
+    private readElementText;
+    private focusedMatches;
+    /** An empty field's getText() returns its hint (437 Pitfall 4), so a showing hint reads ''. */
+    private readFocusedValue;
+    /**
+     * The `mobile: shell` route of keyevent and openQuickSettings (437 D-18). A refusal by secure
+     * Appium is recorded as unavailable and any other driver error as failed; neither is a pass.
+     */
+    private runShell;
+    /** The one submit mechanism on every Android path (437 D-13); pressed once, never retried. */
+    private pressEnter;
+    /** 437 FA-2 (owner, 2026-10-08): line breaks into a single-line field are refused before typing. */
+    private refuseLineBreaks;
+    /**
+     * Native fill from the focused handle (437 D-08..D-10, D-12, D-13, D-15, D-17). Delivers once
+     * (addValue for append, setValue for replace), reads back from the same handle and records the
+     * shared verdict. An unknown append prior or an unreadable read-back is unverified, which never
+     * stops a requested Enter; a mismatch or a multi-line field holds it. A driver error during
+     * delivery ends the fill: nothing is typed again and no Enter follows. A secure field yields
+     * length sentinels only.
+     */
+    private fillNativeCompound;
+    /** The focused element handle, or undefined when UiAutomator2 reports none or the lookup fails. */
+    private focusedField;
+    /**
+     * 437 D-11 (WR-02): where the focused node is relative to the ref, judged by its read bounds.
+     * An unreadable or unparseable value is no evidence, so the native path stays (D-04, D-15).
+     * 444.1 D-07: 'elsewhere' needs positive evidence, the bounds of another observed field.
+     */
+    private focusIsElsewhere;
+    /** Ctrl+A then DEL as key input; clears only the view holding input focus (437 D-14). */
+    private clearByKeys;
+    /**
+     * The last-resort keyboard path (437 D-14): the tap left no focused handle. Replace clears by
+     * keys, the text goes through one `mobile: type` (Appium's Unicode IME, exact for every D-08
+     * text), and the value is read back only when a focused handle can be found afterwards. An
+     * append's prior value is unknown, so it is never better than unverified. The field's kind comes
+     * from the observed input-type (D-15): only positive evidence refuses line breaks or holds Enter.
+     */
+    private fillKeyboardPath;
+    /**
+     * Native and keyboard clearText (437 D-16): clearValue on the focused handle, or Ctrl+A then DEL
+     * when the tap left none, then the hint-aware read-back judged against the empty string. The
+     * caller has already checked that a focused handle is the referenced field (WR-02).
+     */
+    private clearNativeOrKeyboard;
+    private isSecure;
+    private settleClear;
+    /** A driver error while clearing ends the clear; it is never repeated. */
+    private interruptedClear;
+    /** A driver error during delivery ends the fill: nothing is typed again and no Enter follows. */
+    private interruptedFill;
+    /**
+     * The shared end of every Android fill (437 D-09, D-10, D-13, D-15, D-17): records the verdict
+     * and, when a submit was requested, holds Enter on a mismatch or a multi-line field and otherwise
+     * presses it once through `enter`.
+     */
+    private settleFill;
+    /** A real W3C touch tap in the WebView context at the ref's CSS-pixel centre (437 D-11). */
+    private trustedWebTap;
+    /** Whether the tap left an editable field focused at the ref's point; read-only. */
+    private probeWebFocus;
+    /** Polls the read-only probe until the tap's field holds focus; returns the last answer. */
+    private awaitWebFocus;
+    private readWebFieldValue;
+    /** Runs a driver call from NATIVE_APP and always returns to the active WebView context. */
+    private withNativeContext;
+    /** 437 D-11: a tap that left no editable field, or another field, focused writes nothing. */
+    private refuseFocus;
+    /**
+     * WebView clearText (437 D-11, D-16): the same tap and focus probe as the fill, W3C Ctrl+A and
+     * Backspace, then a read-back judged against the empty string. Never success without that check.
+     */
+    private clearWebViewField;
+    /**
+     * WebView fill as trusted input (437 D-11): a W3C tap on the ref, a read-only focus probe,
+     * W3C Ctrl+A and Backspace for replace, `mobile: type` from NATIVE_APP, a read-only read-back,
+     * and one `mobile: pressKey 66` from NATIVE_APP. No script writes the field or fires an event.
+     */
+    private fillWebViewCompound;
+    /**
+     * EXEC-02 platform primitives injected into the shared runner scroll loops (D-02/D-03; 436-02
+     * D-25). A native swipe is `mobile: scrollGesture` over the container (the ref's bounds, else the
+     * screen), whose boolean is the driver's own boundary signal; in a WebView the touch swipe is
+     * measured over every WebView scroller before and after (436-18), paired by identity (436-23).
+     * nativeSearchScroll drives the UiAutomator
+     * `UiScrollable.scrollIntoView` rung over an injection-escaped selector; readInterimTree is a
+     * light page-source parse — NO refMap mint, NO screenshot, lastRefs untouched.
+     */
+    private buildAndroidScrollPrimitives;
+    /**
+     * The WebView scrollers a touch swipe may have acted on (436-18 · D-25), read by the shared
+     * WEBVIEW_SCROLLERS_SCRIPT. The touch point cannot be mapped into the WebView's CSS coordinates,
+     * so the swipe is judged over all of them.
+     * 2026-10-08 (436-23): a frame in view reads unknown; members carry an identity and are paired
+     * by it; open shadow roots are walked; only on-screen element scrollers are members.
+     */
+    private readWebViewScrollers;
+    /**
+     * EXEC-03 openApp (D-10/D-11/D-12). Resolve a human name to a package id (or validate an
+     * explicit bundleId) over the session-cached registry, then launch via activateApp. On a
+     * resolution MISS the registry is re-enumerated exactly once (catches mid-run installs) before
+     * erroring with the resolver's candidate ids. Never a best-guess launch (T-359-04).
+     */
+    private openApp;
+    /** Return the cached registry, enumerating once on first use. Failed enumeration returns null (uncached). */
+    private ensureAppRegistry;
+    /**
+     * Enumerate installed apps through the driver only (ownership contract — no adb/child_process).
+     * `mobile: listApps` maps package ids → AppRegistryEntry (labels only when the same call carries
+     * them, D-10 — no per-package round-trips). On failure, fall back to `mobile: shell` pm-list ONLY
+     * when the AGENT_QA_ANDROID_USE_MOBILE_SHELL gate is '1' (Pitfall 4). Null = enumeration unavailable.
+     */
+    private enumerateApps;
+    /** Coerce a `mobile: listApps` result (package-id-keyed map, or an array of entries) into the registry. */
+    private mapListApps;
+    /** Parse `pm list packages` output ("package:com.foo\n…") into id-only registry entries. */
+    private parsePmListPackages;
     private executeAction;
 }