react-native-tapline 1.0.0 → 1.2.0

package/dist/actions.d.ts

@@ -1,4 +1,6 @@
 import { type Entry, type Snapshot } from './inspect';
+import { type ElementSource } from './source';
+import { type AuditType } from './checks';
 import { type Fiber } from './fiber';
 import { type LogEntry, type TaplineElement } from './types';
 export { tree } from './inspect';
@@ -65,6 +67,7 @@ export declare function describeHit(snapshot: Snapshot, hit: Fiber, actor?: Entr
 export declare function back(rawParams: unknown): Promise<{
     route: string[];
     closed?: 'sheet';
+    dryRun?: true;
 } & SettleOutcome>;
 /**
  * What `press` and `longPress` answer: the element, `closedKeyboard: true` when the keyboard was
@@ -74,6 +77,11 @@ export type PressResult = {
     element: TaplineElement;
     closedKeyboard?: true;
     forced?: string;
+    dryRun?: true;
+    point?: {
+        x: number;
+        y: number;
+    };
 } & SettleOutcome;
 export declare function press(params: unknown): Promise<PressResult>;
 export declare function longPress(params: unknown): Promise<PressResult>;
@@ -100,8 +108,10 @@ export declare function setKeyboardControl(next: KeyboardControl | null): void;
 export declare function typeText(rawParams: unknown): Promise<{
     element: TaplineElement;
     value: string;
+    secure?: true;
     closedKeyboard?: true;
     forced?: string;
+    dryRun?: true;
 } & SettleOutcome>;
 /** What `scroll` answers; `target`, `reached` and `unchanged` only with `to: "target"`. */
 export type ScrollResult = {
@@ -118,6 +128,8 @@ export type ScrollResult = {
     reached?: boolean;
     /** The element was clear already: nothing was scrolled. */
     unchanged?: true;
+    /** A dry run (AGENT-TOOLS 1.8 §11.4): resolved and checked, nothing scrolled. */
+    dryRun?: true;
 } & SettleOutcome;
 export declare function scroll(rawParams: unknown): Promise<ScrollResult>;
 export declare function toggle(rawParams: unknown): Promise<{
@@ -126,8 +138,38 @@ export declare function toggle(rawParams: unknown): Promise<{
     closedKeyboard?: true;
     unchanged?: true;
     forced?: string;
+    dryRun?: true;
+    point?: {
+        x: number;
+        y: number;
+    };
 } & SettleOutcome>;
 export declare function openURL(rawParams: unknown): Promise<SettleOutcome>;
+/**
+ * `inspect {target}` (Tapline 1.1, development builds): the element, the components that draw it, the line
+ * of the app's code that wrote it, and that component's props in short. From the screen to the code.
+ */
+export declare function inspect(rawParams: unknown): Promise<{
+    element: TaplineElement;
+    source: ElementSource;
+}>;
+export interface AuditIssue {
+    type: AuditType;
+    element: TaplineElement | null;
+    problem: string;
+    fix: string;
+    /** Where the app's code wrote the element (development builds), as Metro names the file. */
+    at?: {
+        file: string;
+        line: number;
+        direct: boolean;
+    };
+}
+/** `audit {types?}` (AGENT-TOOLS 1.8 §10): the screen's accessibility problems, each with its source line in development. */
+export declare function audit(rawParams: unknown): Promise<{
+    issues: AuditIssue[];
+    checked: AuditType[];
+}>;
 export declare function getLogs(rawParams: unknown): Promise<{
     entries: LogEntry[];
 }>;
@@ -157,4 +199,5 @@ export declare function swipe(rawParams: unknown): Promise<{
         x: number;
         y: number;
     };
+    dryRun?: true;
 } & SettleOutcome>;

package/dist/actions.js

@@ -17,6 +17,8 @@ exports.typeText = typeText;
 exports.scroll = scroll;
 exports.toggle = toggle;
 exports.openURL = openURL;
+exports.inspect = inspect;
+exports.audit = audit;
 exports.getLogs = getLogs;
 exports.reload = reload;
 exports.screenshotAvailable = screenshotAvailable;
@@ -26,6 +28,8 @@ const react_native_1 = require("react-native");
 const keyboard_1 = require("./keyboard");
 const native_1 = require("./native");
 const inspect_1 = require("./inspect");
+const source_1 = require("./source");
+const checks_1 = require("./checks");
 const alerts_1 = require("./alerts");
 const fiber_1 = require("./fiber");
 const logs_1 = require("./logs");
@@ -774,7 +778,7 @@ function requestCloseOf(host) {
 }
 /** `back`: what the back button or gesture does, on the focused screen; with a sheet open, closes the sheet. */
 async function back(rawParams) {
-    paramsOf(rawParams);
+    const dry = paramsOf(rawParams).dryRun === true;
     const snapshot = (0, inspect_1.takeSnapshot)();
     const current = (0, inspect_1.currentRoute)(snapshot.routes);
     // An open sheet is what back closes first (AGENT-TOOLS v1.4): the top Modal's own onRequestClose,
@@ -786,6 +790,8 @@ async function back(rawParams) {
         // a person taps that, so back does.
         const backdrop = onRequestClose ? null : await backdropOf(snapshot);
         if (backdrop) {
+            if (dry)
+                return { route: current?.chain ?? [], closed: 'sheet', dryRun: true, settledMs: 0 };
             callHandler('onPress', backdrop.onPress, [pressEvent(backdrop.entry.node.fiber, backdrop.frame)]);
             return { route: current?.chain ?? [], closed: 'sheet', ...(await settleOutcome()) };
         }
@@ -794,6 +800,8 @@ async function back(rawParams) {
             const shows = await frontLine(snapshot);
             throw notActionable('no_action', `the open sheet${shows !== undefined ? ` (in front: ${shows})` : ''} has nothing for back to call (its Modal has no onRequestClose); tap its close control.`);
         }
+        if (dry)
+            return { route: current?.chain ?? [], closed: 'sheet', dryRun: true, settledMs: 0 };
         callHandler('onRequestClose', onRequestClose, []);
         return { route: current?.chain ?? [], closed: 'sheet', ...(await settleOutcome()) };
     }
@@ -812,6 +820,8 @@ async function back(rawParams) {
     if (!canGoBack || typeof nav.goBack !== 'function') {
         throw notActionable('no_action', `Nothing to go back to from ${current.chain.join(' › ')}.`);
     }
+    if (dry)
+        return { route: current.chain, dryRun: true, settledMs: 0 };
     callHandler('goBack', nav.goBack, []);
     return { route: current.chain, ...(await settleOutcome()) };
 }
@@ -890,10 +900,14 @@ async function pressLike(kind, rawParams) {
     if (entry.tab) {
         if (kind === 'longPress')
             throw notActionable('no_action', `${describe(entry)} has no long-press action`);
+        if (params.dryRun === true)
+            return { element: (0, inspect_1.toElement)(entry, null), dryRun: true, settledMs: 0 };
         selectTab(snapshot, entry.tab);
         return { element: (0, inspect_1.toElement)(entry, null), ...keyboardNote(closeKeyboardFor(entry)), ...(await settleOutcome()) };
     }
     if (entry.navBack) {
+        if (params.dryRun === true)
+            return { element: (0, inspect_1.toElement)(entry, null), dryRun: true, settledMs: 0 };
         const { route: _route, ...outcome } = await back({});
         return { element: (0, inspect_1.toElement)(entry, null), ...outcome };
     }
@@ -916,6 +930,9 @@ async function pressLike(kind, rawParams) {
     }
     const { element, frame } = await elementFor(actor);
     const forced = await checkedOrForced(params.force === true, () => assertReachable(snapshot, actor, frame));
+    // A dry run (AGENT-TOOLS 1.8 §11.4): every check ran; nothing is touched.
+    if (params.dryRun === true)
+        return { element, dryRun: true, ...pointOf(frame), ...forced, settledMs: 0 };
     const closedKeyboard = closeKeyboardFor(actor);
     if (handler)
         callHandler(handlerName, handler, [pressEvent(actor.node.fiber, frame)]);
@@ -929,6 +946,10 @@ async function pressLike(kind, rawParams) {
     }
     return { element, ...keyboardNote(closedKeyboard), ...forced, ...(await settleOutcome()) };
 }
+/** Where a finger would land: the middle of the element (points, rounded). */
+function pointOf(frame) {
+    return frame ? { point: { x: Math.round(frame.x + frame.width / 2), y: Math.round(frame.y + frame.height / 2) } } : {};
+}
 function press(params) {
     return pressLike('press', params);
 }
@@ -1112,6 +1133,10 @@ async function typeText(rawParams) {
             await assertReachable(snapshot, entry, await (0, inspect_1.measureFiber)(entry.node.fiber));
         }
     });
+    if (params.dryRun === true) {
+        const { element } = await elementFor(entry);
+        return { element, value: (0, inspect_1.displayText)((0, inspect_1.currentInputValue)(entry.node)), dryRun: true, ...forced, settledMs: 0 };
+    }
     // Typing into the input that has focus leaves the keyboard alone. Another input above the keyboard
     // takes the focus with the keyboard up; one the keyboard covers closes it first.
     const closedKeyboard = !(await moveFocusAboveKeyboard(entry)) && closeKeyboardFor(entry);
@@ -1146,7 +1171,19 @@ async function typeText(rawParams) {
     }
     const outcome = await settleOutcome();
     const { element } = await elementFor(entry);
-    return { element: { ...element, value: (0, inspect_1.displayText)(next) }, value: (0, inspect_1.displayText)(next), ...keyboardNote(closedKeyboard), ...forced, ...outcome };
+    // A password field's text never leaves the app: one bullet per character, as iOS draws it.
+    const secure = (0, inspect_1.isSecureInput)(entry.node);
+    const shown = secure ? (0, inspect_1.maskSecret)(next) : (0, inspect_1.displayText)(next);
+    // An input that now holds text shows no placeholder (AGENT-TOOLS v1.7).
+    const { placeholder, ...rest } = element;
+    return {
+        element: { ...rest, ...(next === '' && placeholder !== undefined ? { placeholder } : {}), value: shown },
+        value: shown,
+        ...(secure ? { secure: true } : {}),
+        ...keyboardNote(closedKeyboard),
+        ...forced,
+        ...outcome,
+    };
 }
 const rememberedOffsets = new WeakMap();
 /** Objects that may expose scroll methods: host public instances first, then list class instances. */
@@ -1241,6 +1278,13 @@ async function scrollToTarget(params) {
             break;
         p = node.parent;
     }
+    if (params.dryRun === true) {
+        const first = scrollers[0];
+        const target = (await elementFor(wanted)).element;
+        if (!first)
+            return { element: target, target, offset: { x: 0, y: 0 }, moved: false, dryRun: true, settledMs: 0 };
+        return { element: (await elementFor(first)).element, target, offset: { x: 0, y: 0 }, moved: false, dryRun: true, settledMs: 0 };
+    }
     const { width, height } = snapshot.screen;
     const navBar = (0, inspect_1.nativeNavBar)(snapshot);
     const tabBar = (0, inspect_1.nativeTabBar)(snapshot);
@@ -1426,6 +1470,10 @@ async function scroll(rawParams) {
         entry = best;
         frame = bestFrame;
     }
+    if (params.dryRun === true) {
+        const { element } = await elementFor(entry, frame);
+        return { element, offset: { x: 0, y: 0 }, moved: false, dryRun: true, settledMs: 0 };
+    }
     const candidates = scrollCandidates(entry);
     const key = rememberKey(entry, candidates);
     const horizontal = (0, inspect_1.findProp)(entry.node, 'horizontal') === true;
@@ -1579,6 +1627,10 @@ async function toggle(rawParams) {
     const current = control.info.checked === true;
     const next = typeof params.value === 'boolean' ? params.value : !current;
     const forced = await checkedOrForced(params.force === true, async () => assertReachable(snapshot, control, await (0, inspect_1.measureFiber)(control.node.fiber)));
+    if (params.dryRun === true) {
+        const { element, frame } = await elementFor(control);
+        return { element, value: next, dryRun: true, ...pointOf(frame), ...forced, settledMs: 0 };
+    }
     if (typeof params.value === 'boolean' && control.info.checked === params.value) {
         // Already there: a person wouldn't touch it, so the handler isn't called and the keyboard stays.
         const { element } = await elementFor(control);
@@ -1617,6 +1669,56 @@ async function openURL(rawParams) {
     }
     return settleOutcome();
 }
+/**
+ * `inspect {target}` (Tapline 1.1, development builds): the element, the components that draw it, the line
+ * of the app's code that wrote it, and that component's props in short. From the screen to the code.
+ */
+async function inspect(rawParams) {
+    if (typeof __DEV__ === 'undefined' || !__DEV__) {
+        throw new types_1.TaplineError('unsupported', 'inspect needs a development build: release builds keep no source locations');
+    }
+    const params = paramsOf(rawParams);
+    const { entry } = await resolveTarget(params.target);
+    const [source] = await (0, source_1.sourcesOf)([entry.node.fiber]);
+    const { element } = await elementFor(entry);
+    return { element, source: source ?? { components: [], location: null, props: {} } };
+}
+/** `audit {types?}` (AGENT-TOOLS 1.8 §10): the screen's accessibility problems, each with its source line in development. */
+async function audit(rawParams) {
+    const params = paramsOf(rawParams);
+    const asked = params.types;
+    if (asked !== undefined && (!Array.isArray(asked) || asked.some((t) => typeof t !== 'string'))) {
+        throw badParams('types must be a list of audit types');
+    }
+    const known = new Set(checks_1.AUDIT_TYPES);
+    const types = new Set(asked === undefined ? checks_1.AUDIT_TYPES : checks_1.AUDIT_TYPES.filter((t) => asked.includes(t) && known.has(t)));
+    const findings = await (0, checks_1.auditScreen)(types);
+    let sources = [];
+    if (typeof __DEV__ !== 'undefined' && __DEV__) {
+        const fibers = 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 findings) {
+        const source = finding.entry !== null ? sources[next++] : undefined;
+        const element = finding.entry !== null ? (await elementFor(finding.entry, finding.frame)).element : null;
+        const location = source?.location ?? null;
+        issues.push({
+            type: finding.type,
+            element,
+            problem: finding.problem,
+            fix: finding.fix,
+            ...(location !== null ? { at: { file: location.file, line: location.line, direct: location.direct } } : {}),
+        });
+    }
+    return { issues, checked: [...types] };
+}
 async function getLogs(rawParams) {
     const params = paramsOf(rawParams);
     if (params.since !== undefined && typeof params.since !== 'number')
@@ -1802,6 +1904,12 @@ async function swipe(rawParams) {
         throw notActionable('no_action', `Nothing at (${x0}, ${y0}) to swipe on.`);
     const origin = start;
     const chain = hostChain(origin);
+    if (params.dryRun === true) {
+        // Who would take the drag is only known by asking the views, which can act on it: a dry run names what lies under the start.
+        const under = snapshot.entries.filter((entry) => chain.some((fiber) => (0, fiber_1.sameFiber)(fiber, entry.node.fiber))).pop();
+        const element = under ? (await elementFor(under)).element : null;
+        return { element, from: { x: x0, y: y0 }, to: { x: x1, y: y1 }, dryRun: true, settledMs: 0 };
+    }
     const begin = Date.now();
     const record = {
         touchActive: true,