@vostride/agent-qa-ios 0.1.21 → 0.2.2

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-import { PlatformAdapter, PlatformConfig, ObserveOptions, ScreenState, Action, ActionResult, ConsoleLogEntry } from '@vostride/agent-qa-core';
+import { PlatformAdapter, PlatformConfig, LiveStreamCapability, ObserveOptions, ActionsFor, ActionResult, ConsoleLogEntry } from '@vostride/agent-qa-runner';
+import { ScreenState } from '@vostride/agent-qa-schema';
 
-declare class IOSPlatformAdapter implements PlatformAdapter {
+declare class IOSPlatformAdapter implements PlatformAdapter<'ios'> {
     readonly platform: "ios";
     private driver;
     private lastRefs;
@@ -8,14 +9,28 @@ declare class IOSPlatformAdapter implements PlatformAdapter {
     private activeWebContext;
     private webContextChecked;
     private currentContext;
+    private liveStreamCapability;
     private consoleLogs;
     private consoleDrainIndex;
     private captureConsole;
     private bundleId;
+    private appRegistry;
+    private sessionSnapshotDepth;
+    private snapshotDepth;
+    private readsAtLoweredDepth;
+    private snapshotDepthWarned;
     setup(config: PlatformConfig): Promise<void>;
     cleanup(): Promise<void>;
+    /**
+     * 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;
     observe(_options?: ObserveOptions): Promise<ScreenState>;
-    execute(action: Action): Promise<ActionResult>;
+    execute(action: ActionsFor<'ios'>): Promise<ActionResult>;
     screenshot(): Promise<Buffer | undefined>;
     pollDeviceLogs(): Promise<void>;
     drainConsoleLogs(level?: string): ConsoleLogEntry[];
@@ -23,8 +38,91 @@ declare class IOSPlatformAdapter implements PlatformAdapter {
     private getWebContext;
     /** Invalidate the cached web context so next getWebContext() re-queries. */
     private invalidateWebContext;
+    private readForegroundBundleId;
+    private isBrowserSession;
     private ensureContext;
     private captureScreenshot;
+    private readIOSPageSource;
+    private countLoweredRead;
+    private tapAt;
+    private readRect;
+    /**
+     * The ref's own text-entry element: candidates of its XCUI type (selector built from the fixed
+     * type list only, never from app-supplied text) whose rect matches the observed bounds. Only a
+     * unique match is used; two or more matches, or none, ⇒ undefined. Position never selects.
+     */
+    private locateIOSTextTarget;
+    private readIOSFocusedIds;
+    /**
+     * WDA's typing taps an element that lacks keyboard focus and then sends keystrokes without
+     * re-checking focus, so they land wherever focus is. Text is typed only once the target (or
+     * a descendant) holds keyboard focus.
+     */
+    private confirmIOSKeyboardFocus;
+    private textInputRefusal;
+    /** Gate → own-element lookup → tap → keyboard-focus check shared by fill and clearText. */
+    private focusIOSTextTarget;
+    /** A non-empty empty-field hint (XCUITest placeholderValue); undefined when absent. */
+    private readIOSPlaceholder;
+    /** Read a focused element's `value` attribute; undefined when nothing is readable. */
+    private readIOSValue;
+    /**
+     * EXEC-01 iOS fill compound (D-05..D-08). From the SAME focused-element handle: (append) capture
+     * the prior value FIRST via getAttribute('value') then addValue, or (replace) setValue; RE-READ
+     * via getAttribute('value') on that same handle; verdict via compareFillReread. Secure fields
+     * (nativeType XCUIElementTypeSecureTextField) take the non-empty-only lane — the comparator yields
+     * length sentinels so no raw value enters the result (T-359-02); bullet masking is tolerated
+     * (A3/Pitfall 7 — never a length compare). On a passing re-read AND submit, a return/newline is
+     * delivered AFTER the re-read (D-07). Single typing attempt; a mismatch is success:false + §7.1.
+     *
+     * Append (437 FA-1, owner 2026-10-08): the XCUITest `value` attribute often lags after addValue,
+     * so a re-read equal to the prior cannot show the appended text. That fill is recorded unverified:
+     * never exact, and never a mismatch. Every fill records the shared verdict as `fillVerdict`.
+     * An empty field reads as its placeholder, so an append prior equal to it counts as empty.
+     *
+     * Return in a multi-line field adds a new line instead of submitting, so a multi-line submit is
+     * never sent and is recorded as such.
+     *
+     * An unreadable re-read is unverified and does not stop a requested Return, as on Android (D-09,
+     * D-10; owner 2026-10-09), but focus is confirmed once first and a Return is held as focus-lost
+     * when the field no longer has it (444.1 D-10).
+     */
+    private fillIOSCompound;
+    /**
+     * EXEC-02 platform primitives injected into the shared runner scroll loops (D-02/D-03). The swipe
+     * is a page-sized directional gesture (inverted to the finger direction) that reports unknown
+     * movement; nativeSearchScroll drives
+     * the XCUITest `mobile: scroll` predicateString rung over an injection-escaped target; readInterimTree
+     * is a light page-source parse — NO refMap mint, NO screenshot, lastRefs untouched.
+     */
+    private buildIOSScrollPrimitives;
+    /**
+     * EXEC-03 openApp (D-10/D-12, Pitfall 5). Resolve a human name to a bundle id (or validate an
+     * explicit bundleId) over the session-cached registry, then launch via activateApp. On real devices
+     * `mobile: listApps` enumerates the registry; on simulators it throws, leaving the registry
+     * unavailable — the appName lane then mints a structured §7.1 error directing to an explicit
+     * bundleId, and the bundleId lane validates without the registry (isAppInstalled / activateApp
+     * error conversion, A2). Never a best-guess launch (T-359-04); an invalid bundle never succeeds.
+     */
+    private openApp;
+    /**
+     * Explicit `{bundleId}` launch (D-12, A2). With a registry, validate membership; without one
+     * (simulator) validate via `driver.isAppInstalled` when the driver exposes it, otherwise attempt
+     * `activateApp` and convert a driver rejection into the structured §7.1 error. An invalid bundle
+     * NEVER returns success:true.
+     */
+    private openByBundleId;
+    /** 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 — webdriverio only, no
+     * child_process/simctl). `mobile: listApps` maps bundle ids → AppRegistryEntry with CFBundleName
+     * labels when present (D-10 — no per-app round-trips). It throws on simulators (Pitfall 5) ⇒ null,
+     * leaving enumeration unavailable WITHOUT crashing.
+     */
+    private enumerateApps;
+    /** Coerce a `mobile: listApps` result (bundle-id-keyed map, or an array of entries) into the registry. */
+    private mapListApps;
     private executeAction;
 }