@vostride/agent-qa-android 0.2.3 → 0.2.4

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { PlatformAdapter, PlatformConfig, ObserveOptions, ActionsFor, ActionResult, ConsoleLogEntry, LiveStreamCapability, RecordingCapability } from '@vostride/agent-qa-runner';
+import { PlatformAdapter, PlatformConfig, ActionsFor, ActionResult, ConsoleLogEntry, LiveStreamCapability, RecordingCapability } from '@vostride/agent-qa-runner';
 import { ScreenState } from '@vostride/agent-qa-schema';
 
 declare class AndroidPlatformAdapter implements PlatformAdapter<'android'> {
@@ -19,18 +19,11 @@ declare class AndroidPlatformAdapter implements PlatformAdapter<'android'> {
     setup(config: PlatformConfig): Promise<void>;
     cleanup(): Promise<void>;
     private hasSeenWebContext;
-    observe(_options?: ObserveOptions): Promise<ScreenState>;
+    observe(): Promise<ScreenState>;
     execute(action: ActionsFor<'android'>): Promise<ActionResult>;
     screenshot(): Promise<Buffer | undefined>;
     pollDeviceLogs(): Promise<void>;
     drainConsoleLogs(level?: string): ConsoleLogEntry[];
-    /**
-     * 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;
@@ -40,49 +33,19 @@ declare class AndroidPlatformAdapter implements PlatformAdapter<'android'> {
     /** 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 ''. */
+    /** An empty field's getText() returns its hint, 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. */
+    /** The one submit mechanism on every Android path; 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). */
+    /** Ctrl+A then DEL as key input; clears only the view holding input focus. */
     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;
@@ -90,13 +53,8 @@ declare class AndroidPlatformAdapter implements PlatformAdapter<'android'> {
     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). */
+    /** A real W3C touch tap in the WebView context at the ref's CSS-pixel centre. */
     private trustedWebTap;
     /** Whether the tap left an editable field focused at the ref's point; read-only. */
     private probeWebFocus;
@@ -105,52 +63,14 @@ declare class AndroidPlatformAdapter implements PlatformAdapter<'android'> {
     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;
@@ -167,11 +87,6 @@ interface AndroidAdapterConfig extends PlatformConfig {
     avd?: string;
 }
 
-declare function createAndroidSession(config: AndroidAdapterConfig, farmSession?: {
-    hostname: string;
-    port: number;
-    path: string;
-    capabilities: Record<string, unknown>;
-}): Promise<WebdriverIO.Browser>;
+declare function createAndroidSession(config: AndroidAdapterConfig): Promise<WebdriverIO.Browser>;
 
 export { type AndroidAdapterConfig, AndroidPlatformAdapter, createAndroidSession };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { PlatformAdapter, PlatformConfig, ObserveOptions, ActionsFor, ActionResult, ConsoleLogEntry, LiveStreamCapability, RecordingCapability } from '@vostride/agent-qa-runner';
+import { PlatformAdapter, PlatformConfig, ActionsFor, ActionResult, ConsoleLogEntry, LiveStreamCapability, RecordingCapability } from '@vostride/agent-qa-runner';
 import { ScreenState } from '@vostride/agent-qa-schema';
 
 declare class AndroidPlatformAdapter implements PlatformAdapter<'android'> {
@@ -19,18 +19,11 @@ declare class AndroidPlatformAdapter implements PlatformAdapter<'android'> {
     setup(config: PlatformConfig): Promise<void>;
     cleanup(): Promise<void>;
     private hasSeenWebContext;
-    observe(_options?: ObserveOptions): Promise<ScreenState>;
+    observe(): Promise<ScreenState>;
     execute(action: ActionsFor<'android'>): Promise<ActionResult>;
     screenshot(): Promise<Buffer | undefined>;
     pollDeviceLogs(): Promise<void>;
     drainConsoleLogs(level?: string): ConsoleLogEntry[];
-    /**
-     * 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;
@@ -40,49 +33,19 @@ declare class AndroidPlatformAdapter implements PlatformAdapter<'android'> {
     /** 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 ''. */
+    /** An empty field's getText() returns its hint, 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. */
+    /** The one submit mechanism on every Android path; 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). */
+    /** Ctrl+A then DEL as key input; clears only the view holding input focus. */
     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;
@@ -90,13 +53,8 @@ declare class AndroidPlatformAdapter implements PlatformAdapter<'android'> {
     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). */
+    /** A real W3C touch tap in the WebView context at the ref's CSS-pixel centre. */
     private trustedWebTap;
     /** Whether the tap left an editable field focused at the ref's point; read-only. */
     private probeWebFocus;
@@ -105,52 +63,14 @@ declare class AndroidPlatformAdapter implements PlatformAdapter<'android'> {
     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;
@@ -167,11 +87,6 @@ interface AndroidAdapterConfig extends PlatformConfig {
     avd?: string;
 }
 
-declare function createAndroidSession(config: AndroidAdapterConfig, farmSession?: {
-    hostname: string;
-    port: number;
-    path: string;
-    capabilities: Record<string, unknown>;
-}): Promise<WebdriverIO.Browser>;
+declare function createAndroidSession(config: AndroidAdapterConfig): Promise<WebdriverIO.Browser>;
 
 export { type AndroidAdapterConfig, AndroidPlatformAdapter, createAndroidSession };