react-native-tapline 1.4.0 → 1.6.0

package/dist/uxcheck.js

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASIS_WAY_BACK = exports.BASIS_DEAD_END = exports.BASIS_NAMING = exports.BASIS_ICON = exports.BASIS_THUMB = exports.BASIS_MAIN = exports.BASIS_CHOICES = exports.NEAR = exports.CLEAR_MARGIN = exports.TALL_SCREEN = exports.MAX_CHOICES = void 0;
+exports.sameActionDifferentName = sameActionDifferentName;
+exports.looksLikeMessage = looksLikeMessage;
+exports.uxScreen = uxScreen;
+const checks_1 = require("./checks");
+const fiber_1 = require("./fiber");
+const glassclip_1 = require("./glassclip");
+const inspect_1 = require("./inspect");
+/** More competing choices than this on one screen is flagged (Hick's law). */
+exports.MAX_CHOICES = 7;
+/** A phone at least this tall (points) has a top third out of the thumb's reach. */
+exports.TALL_SCREEN = 700;
+/** The top-ranked action must be this many times as prominent as the next to count as clear. */
+exports.CLEAR_MARGIN = 1.5;
+/** A filled button counts this many times its area. */
+const FILL_WEIGHT = 2;
+/** A fill needs this contrast against what is behind it to count as filled. */
+const FILL_CONTRAST = 1.5;
+/** An action this far (points) from a message counts as near it. */
+exports.NEAR = 160;
+/** A primary-looking button is a filled one at least this share of the screen width wide. */
+const PRIMARY_WIDTH = 0.4;
+exports.BASIS_CHOICES = `best practice: Hick's law, more than ${exports.MAX_CHOICES} choices`;
+exports.BASIS_MAIN = 'best practice: one clear main action per screen';
+exports.BASIS_THUMB = 'best practice: thumb zone, main actions belong in the lower part of a tall screen';
+exports.BASIS_ICON = 'best practice: an icon-only button needs an accessibility label';
+exports.BASIS_NAMING = 'best practice: name the same action the same way on every screen';
+exports.BASIS_DEAD_END = 'best practice: an error or empty state says what to do next';
+exports.BASIS_WAY_BACK = 'house rule: every screen has a way back';
+/* -------------------------------------------------------------------------- */
+/* Pure measurements                                                           */
+/* -------------------------------------------------------------------------- */
+const SYNONYMS = [
+    ['save', 'done', 'submit', 'confirm', 'apply', 'ok'],
+    ['cancel', 'dismiss', 'close', 'back'],
+    ['delete', 'remove', 'trash', 'discard'],
+    ['add', 'new', 'create'],
+    ['edit', 'change', 'modify', 'update'],
+    ['log in', 'login', 'sign in'],
+    ['sign up', 'register', 'create account', 'join'],
+    ['next', 'continue'],
+    ['search', 'find'],
+];
+function normalise(label) {
+    return label.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+function groupOf(label) {
+    return SYNONYMS.findIndex((group) => group.includes(label));
+}
+/** Names that are two names for one action: the same group of synonyms, but not the same words. */
+function sameActionDifferentName(a, b) {
+    const x = normalise(a);
+    const y = normalise(b);
+    if (x === y || x === '' || y === '')
+        return false;
+    const group = groupOf(x);
+    return group >= 0 && group === groupOf(y);
+}
+const MESSAGE = /\b(error|errors|failed|failure|couldn['’]t|could not|can['’]t|cannot|something went wrong|nothing|empty)\b|^\s*no\s+\S/i;
+/** Text that reads like an error or an empty-state message. */
+function looksLikeMessage(text) {
+    return MESSAGE.test(text);
+}
+const BACK_NAME = /^(go back|back|close|cancel|dismiss|×|✕|✖|‹|<|x)$|^(back|close)\b/i;
+const BACK_ID = /(^|[-_.])(back|close|dismiss)([-_.]|$)/i;
+function nameOf(entry) {
+    const { label, text } = entry.info;
+    return (label !== null && label !== '' ? label : text).trim();
+}
+function isBackControl(entry) {
+    if (entry.navBack === true || entry.tab !== undefined)
+        return true;
+    if (!(0, checks_1.isTapTarget)(entry))
+        return false;
+    const id = entry.info.testID;
+    return BACK_NAME.test(nameOf(entry)) || (id !== null && BACK_ID.test(id));
+}
+/** The opaque fill of a button: its own background, else its parent's, if it stands out from what is behind. */
+function fillOf(nodes, node) {
+    let current = node;
+    for (let level = 0; current && level < 2; level++) {
+        const raw = (0, checks_1.flatStyle)((0, fiber_1.propsOf)(current.fiber).style).backgroundColor;
+        const color = raw !== undefined && raw !== null ? (0, checks_1.parseColor)(raw) : null;
+        if (color !== null && color.a >= 1) {
+            const above = current.parent >= 0 ? nodes[current.parent] : undefined;
+            const behind = above !== undefined ? (0, checks_1.backgroundBehind)(nodes, above) : { found: false };
+            const reference = behind.found ? behind.color : { r: 255, g: 255, b: 255, a: 1 };
+            return (0, checks_1.contrastRatio)(color, reference) >= FILL_CONTRAST;
+        }
+        current = current.parent >= 0 ? nodes[current.parent] : undefined;
+    }
+    return false;
+}
+/* -------------------------------------------------------------------------- */
+/* The check                                                                   */
+/* -------------------------------------------------------------------------- */
+async function uxScreen(options = {}) {
+    const snapshot = (0, inspect_1.takeSnapshot)();
+    const { screen, nodes } = snapshot;
+    const candidates = snapshot.entries.filter((entry) => entry.info.interesting && !entry.tab);
+    const frames = await Promise.all(candidates.map((entry) => (0, inspect_1.measureFiber)(entry.node.fiber)));
+    const scrollers = options.glass === true ? await (0, glassclip_1.measureScrollers)(snapshot) : null;
+    const measured = [];
+    candidates.forEach((entry, i) => {
+        const frame = frames[i] ?? null;
+        if (frame === null || !(0, inspect_1.isOnScreen)(frame, screen))
+            return;
+        // In a user's eyes, what a scroll view clips or the keyboard covers isn't there for the check either.
+        if (scrollers !== null && (0, glassclip_1.visiblePartOnGlass)(snapshot, entry, frame, scrollers) === null)
+            return;
+        measured.push({ entry, frame });
+    });
+    const findings = [];
+    const add = (kind, item, problem, basis) => {
+        findings.push({ kind, entry: item?.entry ?? null, frame: item?.frame ?? null, problem, basis });
+    };
+    const checked = ['choices', 'main_action', 'thumb_reach', 'icon_only', 'cut_off_text', 'contrast', 'target_size', 'dead_end'];
+    // 1. Competing choices.
+    const taps = measured.filter((item) => (0, checks_1.isTapTarget)(item.entry));
+    if (taps.length > exports.MAX_CHOICES) {
+        add('choices', null, `${taps.length} choices compete for attention on this screen (more than ${exports.MAX_CHOICES})`, exports.BASIS_CHOICES);
+    }
+    // 2. One clear main action.
+    const buttons = taps
+        .filter((item) => item.entry.info.actions.includes('press') && !item.entry.info.actions.includes('toggle') && nameOf(item.entry) !== '')
+        .map((item) => {
+        const filled = fillOf(nodes, item.entry.node);
+        return { item, filled, score: item.frame.width * item.frame.height * (filled ? FILL_WEIGHT : 1) };
+    })
+        .sort((a, b) => b.score - a.score);
+    const [first, second] = buttons;
+    if (first !== undefined && second !== undefined && first.score < second.score * exports.CLEAR_MARGIN) {
+        const a = nameOf(first.item.entry);
+        const b = nameOf(second.item.entry);
+        if (first.filled && second.filled) {
+            add('main_action', first.item, `two actions look equally important: ${JSON.stringify(a)} and ${JSON.stringify(b)}`, exports.BASIS_MAIN);
+        }
+        else {
+            add('main_action', null, `no action stands out as the main one (largest: ${JSON.stringify(a)} and ${JSON.stringify(b)} are alike in size and look)`, exports.BASIS_MAIN);
+        }
+    }
+    // 3. Primary-looking buttons in the top third of a tall screen.
+    if (screen.height >= exports.TALL_SCREEN) {
+        for (const candidate of buttons) {
+            const { frame } = candidate.item;
+            if (!candidate.filled || frame.width < screen.width * PRIMARY_WIDTH)
+                continue;
+            if (frame.y + frame.height / 2 < screen.height / 3) {
+                add('thumb_reach', candidate.item, `a main-looking button sits in the top third of a ${(0, checks_1.num)(screen.height)} pt tall screen, out of easy thumb reach`, exports.BASIS_THUMB);
+            }
+        }
+    }
+    // 4. Icon-only buttons with no label; then cut-off text, contrast and target size (as audit).
+    for (const item of measured)
+        if ((0, checks_1.noName)(item) !== null)
+            add('icon_only', item, 'icon-only button with no accessibility label', exports.BASIS_ICON);
+    for (const item of measured) {
+        const truncated = (0, checks_1.maybeTruncated)(item, nodes);
+        if (truncated !== null)
+            add('cut_off_text', item, truncated, 'measured');
+        const cut = (0, checks_1.cutOff)(item, screen.width);
+        if (cut !== null)
+            add('cut_off_text', item, `it ${cut}`, 'measured');
+        const contrast = (0, checks_1.contrastOf)(item, nodes);
+        if (contrast !== null) {
+            add('contrast', item, `contrast ${(0, checks_1.num)(contrast.ratio)}:1 is below ${(0, checks_1.num)(contrast.required)}:1 (${contrast.foreground} on ${contrast.background})`, 'measured');
+        }
+        const systemSwitch = item.entry.info.type === 'Switch' && item.frame.width >= checks_1.MIN_TARGET && item.frame.height >= 24;
+        if ((0, checks_1.smallTarget)(item) !== null && !systemSwitch) {
+            add('target_size', item, `tap area ${(0, checks_1.num)(item.frame.width)}x${(0, checks_1.num)(item.frame.height)} pt is smaller than ${checks_1.MIN_TARGET}x${checks_1.MIN_TARGET}`, 'measured');
+        }
+    }
+    // 5. The same action named differently on screens seen in this journey.
+    const actions = taps.flatMap((item) => {
+        const label = nameOf(item.entry);
+        const id = item.entry.info.testID;
+        return label === '' ? [] : [{ label, ...(id !== null && id !== '' ? { id } : {}) }];
+    });
+    if (options.earlier !== undefined) {
+        checked.push('naming');
+        const told = new Set();
+        for (const item of taps) {
+            const label = nameOf(item.entry);
+            if (label === '')
+                continue;
+            const id = item.entry.info.testID;
+            const before = options.earlier.find((e) => normalise(e.label) !== normalise(label) && ((id !== null && id !== '' && e.id === id) || sameActionDifferentName(e.label, label)));
+            if (before === undefined)
+                continue;
+            const key = `${normalise(before.label)}|${normalise(label)}`;
+            if (told.has(key))
+                continue;
+            told.add(key);
+            add('naming', item, `the same action is ${JSON.stringify(label)} here and ${JSON.stringify(before.label)} on an earlier screen`, exports.BASIS_NAMING);
+        }
+    }
+    // 6. An error or empty state that doesn't say what to do next.
+    for (const item of measured) {
+        const { node, info } = item.entry;
+        if (!node.isText || info.text === '' || !looksLikeMessage(info.text))
+            continue;
+        if (taps.some((tap) => tap === item || (0, checks_1.isAncestor)(nodes, tap.entry.node, node)))
+            continue;
+        const near = taps.some((tap) => {
+            const gap = Math.max(tap.frame.y - (item.frame.y + item.frame.height), item.frame.y - (tap.frame.y + tap.frame.height), 0);
+            return gap <= exports.NEAR;
+        });
+        if (!near)
+            add('dead_end', item, 'it reports a problem or an empty state, and nothing near it says what to do next', exports.BASIS_DEAD_END);
+    }
+    // 7. House rule: a way back.
+    if (options.wayBack === true) {
+        checked.push('way_back');
+        const reachable = snapshot.entries.some((entry) => isBackControl(entry) && (entry.tab !== undefined || entry.navBack === true || measured.some((m) => m.entry === entry)));
+        if (!reachable)
+            add('way_back', null, 'no back button, close control or tab bar is visible', exports.BASIS_WAY_BACK);
+    }
+    return { findings, checked, choices: taps.length, actions };
+}
+//# sourceMappingURL=uxcheck.js.map

package/dist/uxcheck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uxcheck.js","sourceRoot":"","sources":["../src/uxcheck.ts"],"names":[],"mappings":"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"}

package/dist/wait.d.ts

@@ -1,6 +1,11 @@
 type IdleProvider = () => boolean;
 /** Where "the network is quiet" comes from (the network tracker; tests). Null restores "always quiet". */
 export declare function setNetworkIdleProvider(provider: IdleProvider | null): void;
+export declare function waitFor(raw: {
+    once: true;
+} & Record<string, unknown>): Promise<{
+    found: boolean;
+}>;
 export declare function waitFor(raw: unknown): Promise<{
     met: true;
     waitedMs: number;

package/dist/wait.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.setNetworkIdleProvider = setNetworkIdleProvider;
 exports.waitFor = waitFor;
+const glassclip_1 = require("./glassclip");
 const inspect_1 = require("./inspect");
 const types_1 = require("./types");
 /**
@@ -35,10 +36,12 @@ function parse(raw) {
         throw new types_1.TaplineError('bad_params', `timeout is in seconds, above 0 and at most ${MAX_TIMEOUT_S}`);
     }
     return {
+        once: raw.once === true,
         ...(text !== undefined ? { text } : {}),
         ...(testID !== undefined ? { testID } : {}),
         ...(label !== undefined ? { label } : {}),
         gone: raw.gone === true,
+        glass: raw.glass === true,
         networkIdle: wantsNetwork,
         timeoutMs: timeout * 1000,
     };
@@ -54,9 +57,34 @@ function matches(entry, condition) {
         return false;
     return true;
 }
-function satisfied(condition) {
+/** Whether an element matching the condition is there now (and, with `glass`, shows on the glass). */
+async function presentNow(condition) {
+    const snapshot = (0, inspect_1.takeSnapshot)();
+    const found = snapshot.entries.filter((entry) => entry.info.interesting && matches(entry, condition));
+    if (!condition.glass)
+        return found.length > 0;
+    // A container's text holds everything inside it, clipped or not: only the innermost matches say what shows.
+    const innermost = found.filter((entry) => !found.some((other) => {
+        if (other === entry)
+            return false;
+        for (let p = other.node.parent; p >= 0; p = snapshot.nodes[p]?.parent ?? -1)
+            if (p === entry.node.index)
+                return true;
+        return false;
+    }));
+    // The scroll views are measured once for this poll, not once per candidate.
+    const scrollers = innermost.length > 0 ? await (0, glassclip_1.measureScrollers)(snapshot) : new Map();
+    for (const entry of innermost) {
+        // A native tab has no frame to measure: it is on the glass.
+        const frame = entry.tab ? null : await (0, inspect_1.measureFiber)(entry.node.fiber);
+        if ((0, glassclip_1.visiblePartOnGlass)(snapshot, entry, frame, scrollers) !== null)
+            return true;
+    }
+    return false;
+}
+async function satisfied(condition) {
     if (condition.text !== undefined || condition.testID !== undefined || condition.label !== undefined) {
-        const present = (0, inspect_1.takeSnapshot)().entries.some((entry) => entry.info.interesting && matches(entry, condition));
+        const present = await presentNow(condition);
         if (present === condition.gone)
             return false;
     }
@@ -85,9 +113,12 @@ function describe(condition) {
 }
 async function waitFor(raw) {
     const condition = parse(raw);
+    // Same matching as the polling path below, so the two never disagree about one screen.
+    if (condition.once)
+        return { found: await satisfied(condition) };
     const started = Date.now();
     for (;;) {
-        if (satisfied(condition))
+        if (await satisfied(condition))
             return { met: true, waitedMs: Date.now() - started };
         const waited = Date.now() - started;
         if (waited >= condition.timeoutMs) {

package/dist/wait.js.map

@@ -1 +1 @@
-{"version":3,"file":"wait.js","sourceRoot":"","sources":["../src/wait.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"wait.js","sourceRoot":"","sources":["../src/wait.ts"],"names":[],"mappings":"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"}

package/ios/TaplineNativeModule.swift

@@ -9,6 +9,7 @@ import UIKit
 /// - `cover`: what UIKit presents over the app that React Native doesn't draw: an alert or action
 ///   sheet (`UIAlertController`, also the one `Alert.alert` shows) and the share sheet
 ///   (`UIActivityViewController`), with what an agent needs to name it.
+/// - `setAnimationSpeed`: the speed of every window's layer, for fast-forwarded animations (1 is normal).
 private enum TaplineWindows {
   static func keyWindow() -> UIWindow? {
     let scenes = UIApplication.shared.connectedScenes.compactMap { $0 as? UIWindowScene }
@@ -17,6 +18,52 @@ private enum TaplineWindows {
     return windows.first { $0.isKeyWindow } ?? windows.first
   }
 
+  /// Every window of the app's scenes (the key window and any other the app or UIKit opened).
+  static func allWindows() -> [UIWindow] {
+    UIApplication.shared.connectedScenes.compactMap { $0 as? UIWindowScene }.flatMap { $0.windows }
+  }
+
+  /// The speed the app's windows should have now (1 is normal); new windows get it too (see `setSpeed`).
+  private static var wanted: Float = 1
+  private static var visibleObserver: NSObjectProtocol?
+
+  /// Gives one window's layer `speed` without a jump or a freeze (Apple's QA1673 pattern for changing a layer's
+  /// timing). Changing `speed` alone moves the layer's local time, which stops repeating animations (an
+  /// ActivityIndicator) after a few flips. So the local time now is read first and kept: it becomes the time offset,
+  /// counted from now.
+  private static func apply(_ speed: Float, to window: UIWindow) {
+    let layer = window.layer
+    guard layer.speed != speed else { return }
+    let now = CACurrentMediaTime()
+    let local = layer.convertTime(now, from: nil)
+    CATransaction.begin()
+    CATransaction.setDisableActions(true)
+    layer.speed = speed
+    layer.timeOffset = local
+    layer.beginTime = now
+    CATransaction.commit()
+  }
+
+  /// Sets every window's layer speed (1 is normal) from any thread. While the speed is not 1, a window that
+  /// becomes visible later (React Native's alert window, a scene's window) gets it too; at 1 the observer goes.
+  static func setSpeed(_ speed: Float) {
+    let run = {
+      wanted = speed
+      for window in allWindows() { apply(speed, to: window) }
+      if speed != 1 {
+        if visibleObserver == nil {
+          visibleObserver = NotificationCenter.default.addObserver(forName: UIWindow.didBecomeVisibleNotification, object: nil, queue: .main) { note in
+            if let window = note.object as? UIWindow { apply(wanted, to: window) }
+          }
+        }
+      } else if let observer = visibleObserver {
+        NotificationCenter.default.removeObserver(observer)
+        visibleObserver = nil
+      }
+    }
+    if Thread.isMainThread { run() } else { DispatchQueue.main.async(execute: run) }
+  }
+
   /// The view controllers presented over the root, front last.
   static func presented(from root: UIViewController?) -> [UIViewController] {
     var chain: [UIViewController] = []
@@ -56,6 +103,20 @@ public final class TaplineNativeModule: Module {
       }
     }.runOnQueue(.main)
 
+    /// Sets the speed of the app's windows' layers (PLAN-1.6 F4; the trick EarlGrey and KIF use). 1 is normal; a
+    /// larger number makes every UIKit and Core Animation animation in those windows (native-stack pushes, sheets,
+    /// alerts) finish that many times sooner. Windows that open while the speed is not 1 get it as they appear.
+    /// Timers and JavaScript are not touched. The JavaScript side puts 1 back on `normal`, on a disconnect and when
+    /// the session ends.
+    AsyncFunction("setAnimationSpeed") { (speed: Double) in
+      let safe = speed.isFinite ? min(max(speed, 1), 1000) : 1
+      TaplineWindows.setSpeed(Float(safe))
+    }.runOnQueue(.main)
+
+    // A JavaScript reload (or a new runtime) makes a new module: the windows are never left fast-forwarded.
+    OnCreate { TaplineWindows.setSpeed(1) }
+    OnDestroy { TaplineWindows.setSpeed(1) }
+
     /// What UIKit shows in front of the app: `kind` is "alert", "actionSheet", "share" or "" (nothing).
     AsyncFunction("cover") { () -> [String: Any] in
       let chain = TaplineWindows.presented(from: TaplineWindows.keyWindow()?.rootViewController)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-tapline",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Tapline in-app agent: lets AI agents see and drive your own React Native / Expo app on a test phone on the same Wi-Fi.",
   "license": "MIT",
   "repository": {