react-native-tapline 1.4.0 → 1.5.0

package/dist/actions.d.ts

@@ -1,6 +1,7 @@
 import { type Entry, type Snapshot } from './inspect';
 import { type ElementSource } from './source';
 import { type AuditType } from './checks';
+import { type UxAction, type UxCheckName, type UxKind } from './uxcheck';
 import { type Fiber } from './fiber';
 import { type Frame, type LogEntry, type TaplineElement } from './types';
 export { tree } from './inspect';
@@ -60,7 +61,7 @@ export declare function labelOf(info: {
 /** What the caller means to do; a point target then picks only an element that does it. */
 type ActionHint = 'press' | 'longPress' | 'toggle' | 'scroll' | 'type';
 /** Resolve a protocol target to exactly one element, or throw not_found / ambiguous. */
-export declare function resolveTarget(raw: unknown, hint?: ActionHint): Promise<Resolved>;
+export declare function resolveTarget(raw: unknown, hint?: ActionHint, glassOnly?: boolean): Promise<Resolved>;
 /** The nearest listed element at or above a host fiber, for naming what covers a target. */
 export declare function describeHit(snapshot: Snapshot, hit: Fiber, actor?: Entry): string;
 /** `back`: what the back button or gesture does, on the focused screen; with a sheet open, closes the sheet. */
@@ -69,6 +70,15 @@ export declare function back(rawParams: unknown): Promise<{
     closed?: 'sheet';
     dryRun?: true;
 } & SettleOutcome>;
+/** What happened to a double tap's second tap, and how long after the first it came. */
+export type PressSecond = {
+    done: true;
+    afterMs: number;
+} | {
+    done: false;
+    reason: string;
+    afterMs: number;
+};
 /**
  * What `press` and `longPress` answer: the element, `closedKeyboard: true` when the keyboard was
  * closed first, and `forced` (the reason word) when `force` let through what the checks refuse.
@@ -86,6 +96,8 @@ export type PressResult = {
         x: number;
         y: number;
     };
+    /** With `again`: the second tap of a double tap. */
+    second?: PressSecond;
 } & SettleOutcome;
 export declare function press(params: unknown): Promise<PressResult>;
 export declare function longPress(params: unknown): Promise<PressResult>;
@@ -142,6 +154,28 @@ export type ScrollResult = {
     dryRun?: true;
 } & SettleOutcome;
 export declare function scroll(rawParams: unknown): Promise<ScrollResult>;
+interface ScrollState {
+    /** The real content offset; negative at rest when the system adds an inset. */
+    offset: {
+        x: number;
+        y: number;
+    };
+    /** The furthest offset a scrollTo can reach. */
+    max: {
+        x: number;
+        y: number;
+    };
+    visible: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * The scroll view's real offset, from where its content container sits inside it. On the new
+ * architecture `measureInWindow` includes the content offset, so scroll frame minus content frame
+ * is the offset. Null when either can't be measured (old architecture, nothing laid out).
+ */
+export declare function measureScrollState(entry: Entry): Promise<ScrollState | null>;
 export declare function toggle(rawParams: unknown): Promise<{
     element: TaplineElement;
     value: boolean;
@@ -190,6 +224,25 @@ export declare function audit(rawParams: unknown): Promise<{
     issues: AuditIssue[];
     checked: AuditType[];
 }>;
+export interface UxIssue {
+    kind: UxKind;
+    element: TaplineElement | null;
+    where?: AuditWhere;
+    problem: string;
+    basis: string;
+    at?: {
+        file: string;
+        line: number;
+        direct: boolean;
+    };
+}
+/** `ux_check {wayBack?, earlier?}` (AGENT-TOOLS 1.12 §17.3): the screen against the usability basics. */
+export declare function uxCheck(rawParams: unknown): Promise<{
+    issues: UxIssue[];
+    checked: UxCheckName[];
+    choices: number;
+    actions: UxAction[];
+}>;
 export declare function getLogs(rawParams: unknown): Promise<{
     entries: LogEntry[];
 }>;

package/dist/actions.js

@@ -15,10 +15,12 @@ exports.longPress = longPress;
 exports.setKeyboardControl = setKeyboardControl;
 exports.typeText = typeText;
 exports.scroll = scroll;
+exports.measureScrollState = measureScrollState;
 exports.toggle = toggle;
 exports.openURL = openURL;
 exports.inspect = inspect;
 exports.audit = audit;
+exports.uxCheck = uxCheck;
 exports.getLogs = getLogs;
 exports.reload = reload;
 exports.screenshotAvailable = screenshotAvailable;
@@ -30,7 +32,9 @@ const native_1 = require("./native");
 const inspect_1 = require("./inspect");
 const source_1 = require("./source");
 const closest_1 = require("./closest");
+const glassclip_1 = require("./glassclip");
 const checks_1 = require("./checks");
+const uxcheck_1 = require("./uxcheck");
 const alerts_1 = require("./alerts");
 const fiber_1 = require("./fiber");
 const logs_1 = require("./logs");
@@ -487,7 +491,7 @@ function inFrontLayer(matches) {
     return inAlert.length > 0 ? inAlert : matches;
 }
 /** Resolve a protocol target to exactly one element, or throw not_found / ambiguous. */
-async function resolveTarget(raw, hint) {
+async function resolveTarget(raw, hint, glassOnly = false) {
     const target = parseTarget(raw);
     const snapshot = (0, inspect_1.takeSnapshot)();
     if (target.kind === 'ref') {
@@ -531,7 +535,14 @@ async function resolveTarget(raw, hint) {
         }
         return { snapshot, entry: hit };
     }
-    const matches = inFrontLayer(matchEntries(snapshot, target));
+    let matches = inFrontLayer(matchEntries(snapshot, target));
+    // A journey in a user's eyes (§17.1): visible text matches only what shows on the glass, not what a scroll view
+    // clips or the keyboard covers (1.5 review, finding 11).
+    if (glassOnly && target.kind === 'text' && matches.length > 0) {
+        const scrollers = await (0, glassclip_1.measureScrollers)(snapshot);
+        const frames = await Promise.all(matches.map((entry) => (0, inspect_1.measureFiber)(entry.node.fiber)));
+        matches = matches.filter((entry, i) => (0, glassclip_1.visiblePartOnGlass)(snapshot, entry, frames[i] ?? null, scrollers) !== null);
+    }
     if (matches.length === 0)
         await refuseBehindSheet(snapshot, target);
     if (target.index !== undefined) {
@@ -935,7 +946,8 @@ function focusInput(entry, frame) {
 }
 async function pressLike(kind, rawParams) {
     const params = paramsOf(rawParams);
-    const { snapshot, entry } = await resolveTarget(params.target, kind);
+    const afterMs = kind === 'press' ? againAfter(params.again) : undefined;
+    const { snapshot, entry } = await resolveTarget(params.target, kind, params.noScroll === true);
     if (entry.tab) {
         if (kind === 'longPress')
             throw notActionable('no_action', `${describe(entry)} has no long-press action`);
@@ -977,7 +989,7 @@ async function pressLike(kind, rawParams) {
     if (params.force !== true) {
         // What doesn't depend on where the element is comes first: an open alert is answered before anything scrolls.
         assertNoBlockingAlert(planned.actor);
-        reach = await scrollIntoReach(snapshot, planned.actor, params.dryRun === true);
+        reach = await scrollIntoReach(snapshot, planned.actor, params.dryRun === true, params.noScroll === true);
         if (reach.scrolled) {
             const again = await reresolve(planned.actor, kind, params.target);
             current = again.snapshot;
@@ -1004,7 +1016,61 @@ async function pressLike(kind, rawParams) {
         if (own)
             callHandler('onPress', own, [pressEvent(actor.node.fiber, frame)]);
     }
-    return { element, ...(reach.scrolled ? { scrolled: true } : {}), ...keyboardNote(closedKeyboard), ...forced, ...(await settleOutcome()) };
+    const second = afterMs === undefined ? undefined : await pressAgain(actor, params, afterMs);
+    return {
+        element,
+        ...(reach.scrolled ? { scrolled: true } : {}),
+        ...keyboardNote(closedKeyboard),
+        ...forced,
+        ...(second !== undefined ? { second } : {}),
+        ...(await settleOutcome()),
+    };
+}
+/** `again`: a second tap this many milliseconds after the first (a stress double tap, AGENT-TOOLS 1.12 §17.4). */
+function againAfter(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 20 || raw > 1000) {
+        throw badParams('again must be milliseconds from 20 to 1000');
+    }
+    return Math.round(raw);
+}
+/**
+ * The second tap of a double tap, made `afterMs` after the first on whatever is there by then, as a finger would
+ * land: the app may have disabled or removed the control (that is the guard against a double submit working).
+ * It goes through the same checks as a tap; a refusal is the answer's `second`, never an error.
+ */
+async function pressAgain(first, params, afterMs) {
+    const started = Date.now();
+    await new Promise((resolve) => setTimeout(resolve, afterMs));
+    try {
+        const again = await reresolve(first, 'press', params.target, false);
+        const found = findActionable(again.snapshot, again.entry, 'press', false);
+        if (!found || found.info.disabled || again.entry.info.disabled) {
+            return { done: false, reason: found ? 'disabled' : 'no_action', afterMs: Date.now() - started };
+        }
+        // The second tap is refused as `changed` when the id, label or text is no longer what the first tap found: a
+        // control that renames itself ("Added 1") and a list row that was recycled are both another element now.
+        if (!sameTarget(first, again.entry))
+            return { done: false, reason: 'changed', afterMs: Date.now() - started };
+        const handler = (0, inspect_1.findHandler)(found.node, 'onPress');
+        if (!handler)
+            return { done: false, reason: 'no_action', afterMs: Date.now() - started };
+        const { frame } = await elementFor(found);
+        if (params.force !== true)
+            await assertReachable(again.snapshot, found, frame);
+        const at = Date.now() - started;
+        callHandler('onPress', handler, [pressEvent(found.node.fiber, frame)]);
+        return { done: true, afterMs: at };
+    }
+    catch (error) {
+        const reason = error instanceof types_1.TaplineError
+            ? error.code === 'not_actionable'
+                ? (error.message.split(':')[0] ?? error.code)
+                : error.code
+            : 'internal';
+        return { done: false, reason, afterMs: Date.now() - started };
+    }
 }
 /** Where a finger would land: the middle of the element (points, rounded). */
 function pointOf(frame) {
@@ -1129,9 +1195,9 @@ async function moveFocusAboveKeyboard(entry) {
 function keyboardNote(closed) {
     return closed ? { closedKeyboard: true } : {};
 }
-async function resolveInput(snapshot, rawTarget) {
+async function resolveInput(snapshot, rawTarget, glassOnly = false) {
     if (rawTarget !== undefined && rawTarget !== null) {
-        const { snapshot: snap, entry } = await resolveTarget(rawTarget, 'type');
+        const { snapshot: snap, entry } = await resolveTarget(rawTarget, 'type', glassOnly);
         const input = findActionable(snap, entry, 'type', true);
         if (!input)
             throw notActionable('no_action', `${describe(entry)} is not an input`);
@@ -1178,7 +1244,7 @@ async function typeText(rawParams) {
         throw badParams('text is required (or pass submit: true)');
     // Deleting from the end edits what is there, so it never replaces the whole text.
     const replace = params.replace !== false && !deleting;
-    let { snapshot, entry } = await resolveInput(null, params.target);
+    let { snapshot, entry } = await resolveInput(null, params.target, params.noScroll === true);
     if (entry.info.disabled)
         throw notActionable('disabled', `${describe(entry)} is not editable; ${ENABLE_FIRST}.`);
     // Off screen, in the tree: scroll it into view first (AGENT-TOOLS 1.12 §16.2; the policy ran before this
@@ -1187,7 +1253,7 @@ async function typeText(rawParams) {
     if (params.force !== true)
         assertNoBlockingAlert(entry);
     if (params.force !== true && !ownsInstance(entry, keyboard.focusedInput())) {
-        reach = await scrollIntoReach(snapshot, entry, params.dryRun === true);
+        reach = await scrollIntoReach(snapshot, entry, params.dryRun === true, params.noScroll === true);
         if (reach.scrolled) {
             let again;
             try {
@@ -1528,10 +1594,17 @@ function visiblePart(frame, screen) {
  * alert, under a bar) run afterwards, as for any element. Refused as `off_screen`, with the reason, when
  * no scroll can bring it on screen. `dry` predicts the point after the scroll and scrolls nothing.
  */
-async function scrollIntoReach(snapshot, entry, dry) {
+async function scrollIntoReach(snapshot, entry, dry, noScroll = false) {
     const frame = await (0, inspect_1.measureFiber)(entry.node.fiber);
     if (frame === null)
         return {};
+    // A journey in a user's eyes (`noScroll`, §17.1): nothing scrolls by itself. An element wholly off screen is refused.
+    if (noScroll) {
+        // On the glass, not just on screen: a scroll view clips it, the keyboard covers it (1.5 review, finding 11).
+        if ((0, glassclip_1.visiblePartOnGlass)(snapshot, entry, frame, await (0, glassclip_1.measureScrollers)(snapshot)) !== null)
+            return {};
+        throw notActionable('off_screen', `${describe(entry)} is off screen; in a journey nothing scrolls by itself: scroll the way a person would, then try again.`);
+    }
     // Partly on screen (over the edge, or under a bar): scrolled clear too, with one attempt; if that
     // can't be done the action goes on as before and the touch checks decide. Never refused for this.
     const partial = visiblePart(frame, snapshot.screen) !== null;
@@ -1627,7 +1700,7 @@ function refindTarget(entry, original) {
  * The same element after a scroll, from a fresh snapshot (the list may have laid out other rows on the
  * way). When a list unmounted the row, the ref is gone: it is found again by the original target.
  */
-async function reresolve(entry, hint, original) {
+async function reresolve(entry, hint, original, checkSame = true) {
     let found;
     try {
         found = await resolveTarget({ ref: (0, inspect_1.refFor)(entry.node.fiber) }, hint);
@@ -1640,21 +1713,24 @@ async function reresolve(entry, hint, original) {
             throw error;
         found = await resolveTarget(again, hint);
     }
-    assertSameTarget(entry, found.entry);
+    if (checkSame)
+        assertSameTarget(entry, found.entry);
     return found;
 }
+/** The same element by id, label and text, each on its own (a row can keep its id and label while its text changes). */
+function sameTarget(before, after) {
+    return before.info.testID === after.info.testID && before.info.label === after.info.label && before.info.text === after.info.text;
+}
 /**
  * After a scroll the element found again must still be the one the safety check saw: a list that recycles its rows
  * can hand the same component another row ("Continue" becomes "Delete account"). A changed id, label or text is
  * refused before anything is touched (Codex review of 1.4.0).
  */
 function assertSameTarget(before, after) {
-    // id, label and text each on their own: a row can keep its id and accessibility label while its text changes
+    if (sameTarget(before, after))
+        return;
     const was = { id: before.info.testID, name: labelOf(before.info) };
     const now = { id: after.info.testID, name: labelOf(after.info) };
-    const same = was.id === now.id && before.info.label === after.info.label && before.info.text === after.info.text;
-    if (same)
-        return;
     if (was.name === now.name) {
         was.name = before.info.text;
         now.name = after.info.text;
@@ -1887,7 +1963,7 @@ async function toggle(rawParams) {
     const params = paramsOf(rawParams);
     if (params.value !== undefined && typeof params.value !== 'boolean')
         throw badParams('value must be a boolean');
-    const first = await resolveTarget(params.target, 'toggle');
+    const first = await resolveTarget(params.target, 'toggle', params.noScroll === true);
     const plan = (snap, picked) => {
         const found = findActionable(snap, picked, 'toggle', true);
         if (!found)
@@ -1905,7 +1981,7 @@ async function toggle(rawParams) {
     let reach = {};
     if (params.force !== true) {
         assertNoBlockingAlert(planned.control);
-        reach = await scrollIntoReach(snapshot, planned.control, params.dryRun === true);
+        reach = await scrollIntoReach(snapshot, planned.control, params.dryRun === true, params.noScroll === true);
         if (reach.scrolled) {
             const again = await reresolve(planned.control, 'toggle', params.target);
             snapshot = again.snapshot;
@@ -2036,6 +2112,68 @@ async function audit(rawParams) {
     }
     return { issues, checked: [...types] };
 }
+/** `ux_check {wayBack?, earlier?}` (AGENT-TOOLS 1.12 §17.3): the screen against the usability basics. */
+async function uxCheck(rawParams) {
+    const params = paramsOf(rawParams);
+    if (params.wayBack !== undefined && typeof params.wayBack !== 'boolean')
+        throw badParams('wayBack must be true or false');
+    const earlierRaw = params.earlier;
+    let earlier;
+    if (earlierRaw !== undefined && earlierRaw !== null) {
+        if (!Array.isArray(earlierRaw))
+            throw badParams('earlier must be a list of {label, id?}');
+        earlier = [];
+        for (const item of earlierRaw) {
+            if (!(0, types_1.isRecord)(item) || typeof item.label !== 'string')
+                throw badParams('earlier must be a list of {label, id?}');
+            earlier.push({ label: item.label, ...(typeof item.id === 'string' && item.id !== '' ? { id: item.id } : {}) });
+        }
+    }
+    if (params.glass !== undefined && typeof params.glass !== 'boolean')
+        throw badParams('glass must be true or false');
+    const result = await (0, uxcheck_1.uxScreen)({
+        ...(params.glass === true ? { glass: true } : {}),
+        ...(params.wayBack === true ? { wayBack: true } : {}),
+        ...(earlier !== undefined ? { earlier } : {}),
+    });
+    let sources = [];
+    if (typeof __DEV__ !== 'undefined' && __DEV__) {
+        const fibers = result.findings.flatMap((f) => (f.entry !== null ? [f.entry.node.fiber] : []));
+        try {
+            sources = fibers.length > 0 ? await (0, source_1.sourcesOf)(fibers) : [];
+        }
+        catch {
+            sources = []; // Metro unreachable: the report still stands, without lines
+        }
+    }
+    let next = 0;
+    const issues = [];
+    for (const finding of result.findings) {
+        const source = finding.entry !== null ? sources[next++] : undefined;
+        let element = null;
+        if (finding.entry !== null) {
+            try {
+                element = (await elementFor(finding.entry, finding.frame)).element;
+            }
+            catch {
+                element = null;
+            }
+        }
+        const where = element === null && finding.entry !== null
+            ? whereOf({ type: 'description', entry: finding.entry, frame: finding.frame, problem: '', fix: '' })
+            : null;
+        const location = source?.location ?? null;
+        issues.push({
+            kind: finding.kind,
+            element,
+            ...(where !== null ? { where } : {}),
+            problem: finding.problem,
+            basis: finding.basis,
+            ...(location !== null ? { at: { file: location.file, line: location.line, direct: location.direct } } : {}),
+        });
+    }
+    return { issues, checked: result.checked, choices: result.choices, actions: result.actions };
+}
 async function getLogs(rawParams) {
     const params = paramsOf(rawParams);
     if (params.since !== undefined && typeof params.since !== 'number')