react-native-tapline 0.0.0-stage → 1.0.0

package/dist/register.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commitRevision = commitRevision;
+exports.onCommit = onCommit;
+exports.installHook = installHook;
+exports.getRoots = getRoots;
+exports.resetRegistry = resetRegistry;
+/**
+ * Import this FIRST in the app's entry file, before React / React Native:
+ *
+ *   import 'react-native-tapline/register';
+ *
+ * It installs a minimal React DevTools global hook (or wraps the existing one,
+ * chaining every call) so Tapline can see the app's fiber roots. This file must
+ * not import react or react-native.
+ */
+const fiber_1 = require("./fiber");
+const types_1 = require("./types");
+const WRAPPED = Symbol.for('tapline.hookWrapped');
+/** renderer id -> roots seen via onCommitFiberRoot */
+const rootsByRenderer = new Map();
+let installedHook = null;
+/** How many React commits have happened: the screen's revision, for the live viewer. */
+let revision = 0;
+const commitListeners = new Set();
+function committed() {
+    revision += 1;
+    for (const listener of commitListeners)
+        safely(() => listener(revision));
+}
+/** The number of React commits so far; it changes whenever the UI may have changed. */
+function commitRevision() {
+    return revision;
+}
+/** Called after every React commit with the new revision; returns a function that stops it. */
+function onCommit(listener) {
+    commitListeners.add(listener);
+    return () => {
+        commitListeners.delete(listener);
+    };
+}
+function record(rendererId, root) {
+    if (!(0, fiber_1.isFiberRoot)(root))
+        return;
+    let set = rootsByRenderer.get(rendererId);
+    if (!set) {
+        set = new Set();
+        rootsByRenderer.set(rendererId, set);
+    }
+    // A root with no children has been unmounted.
+    if (root.current.child === null)
+        set.delete(root);
+    else
+        set.add(root);
+}
+function forgetByFiber(fiber) {
+    if (!(0, fiber_1.isFiber)(fiber) || fiber.tag !== fiber_1.HostRoot)
+        return;
+    for (const set of rootsByRenderer.values()) {
+        for (const root of set) {
+            if (root.current === fiber || root.current.alternate === fiber || root === fiber.stateNode) {
+                set.delete(root);
+            }
+        }
+    }
+}
+function numberArg(value) {
+    return typeof value === 'number' ? value : 0;
+}
+function safely(fn) {
+    try {
+        fn();
+    }
+    catch {
+        // never break React because of Tapline
+    }
+}
+function wrap(hook, name, before) {
+    const previous = hook[name];
+    const wrapped = function (...args) {
+        safely(() => before(args));
+        return typeof previous === 'function' ? previous.apply(hook, args) : undefined;
+    };
+    hook[name] = wrapped;
+}
+function createHook() {
+    let nextId = 1;
+    const hook = {
+        supportsFiber: true,
+        renderers: new Map(),
+        inject(renderer) {
+            const id = nextId++;
+            hook.renderers?.set(id, renderer);
+            return id;
+        },
+        onCommitFiberRoot() { },
+        onCommitFiberUnmount() { },
+        onPostCommitFiberRoot() { },
+        checkDCE() { },
+        onScheduleFiberRoot() { },
+        setStrictMode() { },
+        sub() {
+            return () => { };
+        },
+        on() { },
+        off() { },
+        emit() { },
+        getFiberRoots(rendererId) {
+            return rootsByRenderer.get(rendererId) ?? new Set();
+        },
+    };
+    return hook;
+}
+/**
+ * Install (or wrap) the hook on `target` (default: globalThis). Idempotent per
+ * hook object. Returns the hook in effect.
+ */
+function installHook(target = globalThis) {
+    const holder = target;
+    const existing = holder.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+    let hook;
+    if ((0, types_1.isRecord)(existing)) {
+        hook = existing;
+        if (Object.prototype.hasOwnProperty.call(hook, WRAPPED)) {
+            installedHook = hook;
+            return hook;
+        }
+    }
+    else {
+        hook = createHook();
+        try {
+            Object.defineProperty(target, '__REACT_DEVTOOLS_GLOBAL_HOOK__', {
+                configurable: true,
+                enumerable: false,
+                writable: true,
+                value: hook,
+            });
+        }
+        catch {
+            holder.__REACT_DEVTOOLS_GLOBAL_HOOK__ = hook;
+        }
+    }
+    wrap(hook, 'onCommitFiberRoot', (args) => {
+        record(numberArg(args[0]), args[1]);
+        committed();
+    });
+    wrap(hook, 'onCommitFiberUnmount', (args) => forgetByFiber(args[1]));
+    Object.defineProperty(hook, WRAPPED, { value: true, enumerable: false });
+    installedHook = hook;
+    return hook;
+}
+/** All live fiber roots known to Tapline. */
+function getRoots() {
+    const found = new Set();
+    for (const set of rootsByRenderer.values())
+        for (const root of set)
+            found.add(root);
+    // An already-present DevTools hook may know roots committed before we wrapped it.
+    const hook = installedHook;
+    if (hook && hook.renderers instanceof Map && typeof hook.getFiberRoots === 'function') {
+        for (const id of hook.renderers.keys()) {
+            safely(() => {
+                const roots = hook.getFiberRoots?.(id);
+                if (roots instanceof Set) {
+                    for (const root of roots)
+                        if ((0, fiber_1.isFiberRoot)(root))
+                            found.add(root);
+                }
+            });
+        }
+    }
+    return [...found].filter((root) => root.current.child !== null);
+}
+/** Test helper: forget recorded roots and the installed-hook memory. */
+function resetRegistry() {
+    rootsByRenderer.clear();
+    installedHook = null;
+}
+installHook();
+//# sourceMappingURL=register.js.map

package/dist/register.js.map

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

package/dist/settle.d.ts

@@ -0,0 +1,27 @@
+/**
+ * AGENT-TOOLS §6: the screen counts as still after `quietMs` without a React commit, with a cap.
+ * Resolves with the milliseconds waited. Native-driver animations don't commit, so the tree can be
+ * still while pixels move; that's fine for an element list.
+ */
+export declare function waitUntilStill(options: {
+    quietMs: number;
+    capMs: number;
+    onCommit: (listener: () => void) => () => void;
+    now: () => number;
+    /** Called when the wait ended at the cap, with the screen still changing. */
+    onCap?: () => void;
+}): Promise<number>;
+/**
+ * After the commits stop, a native-driver animation (a sheet sliding up) can still be moving.
+ * Polls `measure` every `pollMs` and resolves with the milliseconds waited once two readings in a
+ * row agree within 1 pt in x and y, or at `capMs`. A null reading (can't be measured) ends the wait.
+ */
+export declare function waitUntilSteady(measure: () => Promise<{
+    x: number;
+    y: number;
+} | null>, options: {
+    pollMs: number;
+    capMs: number;
+    now: () => number;
+    onCap?: () => void;
+}): Promise<number>;

package/dist/settle.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.waitUntilStill = waitUntilStill;
+exports.waitUntilSteady = waitUntilSteady;
+/**
+ * AGENT-TOOLS §6: the screen counts as still after `quietMs` without a React commit, with a cap.
+ * Resolves with the milliseconds waited. Native-driver animations don't commit, so the tree can be
+ * still while pixels move; that's fine for an element list.
+ */
+function waitUntilStill(options) {
+    const started = options.now();
+    return new Promise((resolve) => {
+        let done = false;
+        let quiet;
+        let unsubscribe = () => undefined;
+        const finish = () => {
+            if (done)
+                return;
+            done = true;
+            if (quiet !== undefined)
+                clearTimeout(quiet);
+            clearTimeout(cap);
+            unsubscribe();
+            resolve(Math.max(0, Math.min(options.capMs, options.now() - started)));
+        };
+        const cap = setTimeout(() => {
+            if (!done)
+                options.onCap?.();
+            finish();
+        }, options.capMs);
+        const restart = () => {
+            if (done)
+                return;
+            if (quiet !== undefined)
+                clearTimeout(quiet);
+            quiet = setTimeout(finish, options.quietMs);
+        };
+        unsubscribe = options.onCommit(restart);
+        restart();
+    });
+}
+/**
+ * After the commits stop, a native-driver animation (a sheet sliding up) can still be moving.
+ * Polls `measure` every `pollMs` and resolves with the milliseconds waited once two readings in a
+ * row agree within 1 pt in x and y, or at `capMs`. A null reading (can't be measured) ends the wait.
+ */
+async function waitUntilSteady(measure, options) {
+    const started = options.now();
+    const elapsed = () => Math.max(0, Math.min(options.capMs, options.now() - started));
+    if (options.capMs <= 0)
+        return 0;
+    let previous = await measure();
+    if (previous === null)
+        return 0;
+    for (;;) {
+        const left = options.capMs - (options.now() - started);
+        if (left <= 0) {
+            options.onCap?.();
+            return elapsed();
+        }
+        await new Promise((resolve) => setTimeout(resolve, Math.min(options.pollMs, left)));
+        const next = await measure();
+        if (next === null)
+            return elapsed();
+        if (Math.abs(next.x - previous.x) <= 1 && Math.abs(next.y - previous.y) <= 1)
+            return elapsed();
+        previous = next;
+    }
+}
+//# sourceMappingURL=settle.js.map

package/dist/settle.js.map

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

package/dist/storage.d.ts

@@ -0,0 +1,10 @@
+/** Where Tapline remembers the paired computer and this install's id. */
+export interface TaplineStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+/** expo-secure-store when the app has it (keychain on iOS), else null. */
+export declare function secureStoreStorage(): TaplineStorage | null;
+/** Kept only while the app runs. */
+export declare function memoryStorage(): TaplineStorage;

package/dist/storage.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.secureStoreStorage = secureStoreStorage;
+exports.memoryStorage = memoryStorage;
+const types_1 = require("./types");
+function isSecureStore(value) {
+    return ((0, types_1.isRecord)(value) &&
+        typeof value.getItemAsync === 'function' &&
+        typeof value.setItemAsync === 'function' &&
+        typeof value.deleteItemAsync === 'function');
+}
+/** expo-secure-store when the app has it (keychain on iOS), else null. */
+function secureStoreStorage() {
+    let loaded;
+    try {
+        loaded = require('expo-secure-store');
+    }
+    catch {
+        return null;
+    }
+    const store = (0, types_1.isRecord)(loaded) && isSecureStore(loaded.default) ? loaded.default : loaded;
+    if (!isSecureStore(store))
+        return null;
+    return {
+        getItem: (key) => store.getItemAsync(key),
+        setItem: (key, value) => store.setItemAsync(key, value),
+        removeItem: (key) => store.deleteItemAsync(key),
+    };
+}
+/** Kept only while the app runs. */
+function memoryStorage() {
+    const items = new Map();
+    return {
+        getItem: (key) => Promise.resolve(items.get(key) ?? null),
+        setItem: (key, value) => {
+            items.set(key, value);
+            return Promise.resolve();
+        },
+        removeItem: (key) => {
+            items.delete(key);
+            return Promise.resolve();
+        },
+    };
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":";;AAyBA,gDAcC;AAGD,sCAaC;AAvDD,mCAAmC;AAenC,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,CACL,IAAA,gBAAQ,EAAC,KAAK,CAAC;QACf,OAAO,KAAK,CAAC,YAAY,KAAK,UAAU;QACxC,OAAO,KAAK,CAAC,YAAY,KAAK,UAAU;QACxC,OAAO,KAAK,CAAC,eAAe,KAAK,UAAU,CAC5C,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,SAAgB,kBAAkB;IAChC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,KAAK,GAAG,IAAA,gBAAQ,EAAC,MAAM,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;IAC1F,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO;QACL,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC;QACzC,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC;QACvD,UAAU,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC;KAChD,CAAC;AACJ,CAAC;AAED,oCAAoC;AACpC,SAAgB,aAAa;IAC3B,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,OAAO;QACL,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;QACzD,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;YACtB,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACtB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QACD,UAAU,EAAE,CAAC,GAAG,EAAE,EAAE;YAClB,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAClB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/touches.d.ts

@@ -0,0 +1,15 @@
+/** At most one touch is passed on per this many milliseconds. */
+export declare const TOUCH_THROTTLE_MS = 500;
+export type TouchListener = (at: number) => void;
+/** Calls `listener` (with the touch time) for each real touch that passes the throttle; returns the unsubscribe. */
+export declare function onRealTouch(listener: TouchListener): () => void;
+/**
+ * A touch started on the app. Returns true when it was passed on to the listeners; false when
+ * nobody listens (Tapline stopped) or it came within `TOUCH_THROTTLE_MS` of the last passed one.
+ * A touch that is dropped is not lost: when its window ends, one `touch` report with the time of the
+ * latest dropped touch goes out (so a second touch a person made inside the window shows up too).
+ * Never throws.
+ */
+export declare function noteRealTouch(now: number): boolean;
+/** Forgets the throttle and every listener (tests). */
+export declare function resetTouches(): void;

package/dist/touches.js

@@ -0,0 +1,89 @@
+"use strict";
+// Real touches. Tapline never touches the screen itself (an agent's `tap` calls the element's handler),
+// so any touch that reaches the app's root is a person's finger, or another tool that makes real
+// touches. The wrapper around the app's root (alerts.tsx) calls `noteRealTouch`; the client listens
+// and tells the host, which then warns the agent that a person used the app.
+//
+// Limit: a React Native `Modal` is its own native window, so touches inside one never reach the
+// wrapper and are not seen.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOUCH_THROTTLE_MS = void 0;
+exports.onRealTouch = onRealTouch;
+exports.noteRealTouch = noteRealTouch;
+exports.resetTouches = resetTouches;
+/** At most one touch is passed on per this many milliseconds. */
+exports.TOUCH_THROTTLE_MS = 500;
+const listeners = new Set();
+let lastPassedAt = null;
+/** The time of the latest touch dropped in the current window; it is reported when the window ends. */
+let droppedAt = null;
+let trailing = null;
+function cancelTrailing() {
+    if (trailing !== null)
+        clearTimeout(trailing);
+    trailing = null;
+    droppedAt = null;
+}
+function emit(at) {
+    for (const listener of [...listeners]) {
+        try {
+            listener(at);
+        }
+        catch {
+            // a listener must never reach the app
+        }
+    }
+}
+/** The window ended with touches dropped in it: report the latest of them once. */
+function flushTrailing() {
+    trailing = null;
+    const at = droppedAt;
+    droppedAt = null;
+    if (at === null || lastPassedAt === null || listeners.size === 0)
+        return;
+    // The trailing report starts the next window, counted from where this one ended, so the rate
+    // stays at one per window however late the timer fires.
+    lastPassedAt += exports.TOUCH_THROTTLE_MS;
+    emit(at);
+}
+/** Calls `listener` (with the touch time) for each real touch that passes the throttle; returns the unsubscribe. */
+function onRealTouch(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0) {
+            lastPassedAt = null;
+            cancelTrailing();
+        }
+    };
+}
+/**
+ * A touch started on the app. Returns true when it was passed on to the listeners; false when
+ * nobody listens (Tapline stopped) or it came within `TOUCH_THROTTLE_MS` of the last passed one.
+ * A touch that is dropped is not lost: when its window ends, one `touch` report with the time of the
+ * latest dropped touch goes out (so a second touch a person made inside the window shows up too).
+ * Never throws.
+ */
+function noteRealTouch(now) {
+    if (listeners.size === 0)
+        return false;
+    // A clock that went backwards must not silence touches until it catches up.
+    if (lastPassedAt !== null && now >= lastPassedAt && now - lastPassedAt < exports.TOUCH_THROTTLE_MS) {
+        droppedAt = now;
+        if (trailing === null)
+            trailing = setTimeout(flushTrailing, lastPassedAt + exports.TOUCH_THROTTLE_MS - now);
+        return false;
+    }
+    // A touch that passes covers every earlier one: nothing is left to report at the end of a window.
+    cancelTrailing();
+    lastPassedAt = now;
+    emit(now);
+    return true;
+}
+/** Forgets the throttle and every listener (tests). */
+function resetTouches() {
+    listeners.clear();
+    lastPassedAt = null;
+    cancelTrailing();
+}
+//# sourceMappingURL=touches.js.map

package/dist/touches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"touches.js","sourceRoot":"","sources":["../src/touches.ts"],"names":[],"mappings":";AAAA,wGAAwG;AACxG,iGAAiG;AACjG,oGAAoG;AACpG,6EAA6E;AAC7E,EAAE;AACF,gGAAgG;AAChG,4BAA4B;;;AA0C5B,kCASC;AASD,sCAaC;AAGD,oCAIC;AA9ED,iEAAiE;AACpD,QAAA,iBAAiB,GAAG,GAAG,CAAC;AAIrC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAiB,CAAC;AAC3C,IAAI,YAAY,GAAkB,IAAI,CAAC;AACvC,uGAAuG;AACvG,IAAI,SAAS,GAAkB,IAAI,CAAC;AACpC,IAAI,QAAQ,GAAyC,IAAI,CAAC;AAE1D,SAAS,cAAc;IACrB,IAAI,QAAQ,KAAK,IAAI;QAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC9C,QAAQ,GAAG,IAAI,CAAC;IAChB,SAAS,GAAG,IAAI,CAAC;AACnB,CAAC;AAED,SAAS,IAAI,CAAC,EAAU;IACtB,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC;QACtC,IAAI,CAAC;YACH,QAAQ,CAAC,EAAE,CAAC,CAAC;QACf,CAAC;QAAC,MAAM,CAAC;YACP,sCAAsC;QACxC,CAAC;IACH,CAAC;AACH,CAAC;AAED,mFAAmF;AACnF,SAAS,aAAa;IACpB,QAAQ,GAAG,IAAI,CAAC;IAChB,MAAM,EAAE,GAAG,SAAS,CAAC;IACrB,SAAS,GAAG,IAAI,CAAC;IACjB,IAAI,EAAE,KAAK,IAAI,IAAI,YAAY,KAAK,IAAI,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO;IACzE,6FAA6F;IAC7F,wDAAwD;IACxD,YAAY,IAAI,yBAAiB,CAAC;IAClC,IAAI,CAAC,EAAE,CAAC,CAAC;AACX,CAAC;AAED,oHAAoH;AACpH,SAAgB,WAAW,CAAC,QAAuB;IACjD,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACxB,OAAO,GAAG,EAAE;QACV,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC3B,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACzB,YAAY,GAAG,IAAI,CAAC;YACpB,cAAc,EAAE,CAAC;QACnB,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,aAAa,CAAC,GAAW;IACvC,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,4EAA4E;IAC5E,IAAI,YAAY,KAAK,IAAI,IAAI,GAAG,IAAI,YAAY,IAAI,GAAG,GAAG,YAAY,GAAG,yBAAiB,EAAE,CAAC;QAC3F,SAAS,GAAG,GAAG,CAAC;QAChB,IAAI,QAAQ,KAAK,IAAI;YAAE,QAAQ,GAAG,UAAU,CAAC,aAAa,EAAE,YAAY,GAAG,yBAAiB,GAAG,GAAG,CAAC,CAAC;QACpG,OAAO,KAAK,CAAC;IACf,CAAC;IACD,kGAAkG;IAClG,cAAc,EAAE,CAAC;IACjB,YAAY,GAAG,GAAG,CAAC;IACnB,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,IAAI,CAAC;AACd,CAAC;AAED,uDAAuD;AACvD,SAAgB,YAAY;IAC1B,SAAS,CAAC,KAAK,EAAE,CAAC;IAClB,YAAY,GAAG,IAAI,CAAC;IACpB,cAAc,EAAE,CAAC;AACnB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,168 @@
+/** Wire-protocol and shared types (see docs/PROTOCOL.md, version 1). */
+export declare const PROTOCOL_VERSION = 1;
+export type ErrorCode = 'not_found' | 'ambiguous' | 'not_actionable' | 'unsupported' | 'bad_params' | 'timeout' | 'internal';
+export interface WireError {
+    code: ErrorCode;
+    message: string;
+    /** Candidate refs, only for `ambiguous`. */
+    refs?: string[];
+    /** The candidates as elements (role, id, actions, frame), only for `ambiguous`. */
+    candidates?: TaplineElement[];
+}
+/** An error that maps 1:1 onto a protocol error response. */
+export declare class TaplineError extends Error {
+    readonly code: ErrorCode;
+    readonly refs: string[] | undefined;
+    readonly candidates: TaplineElement[] | undefined;
+    constructor(code: ErrorCode, message: string, refs?: string[], candidates?: TaplineElement[]);
+    toWire(): WireError;
+}
+export interface Frame {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export type Action = 'press' | 'longPress' | 'type' | 'submit' | 'toggle' | 'scroll';
+export interface TaplineElement {
+    ref: string;
+    type: string;
+    role: string | null;
+    testID: string | null;
+    label: string | null;
+    /** The element's text, whitespace-collapsed; at most 2000 characters of it. */
+    text: string;
+    /** How many characters of the text were left out; absent when it is whole. */
+    textMore?: number;
+    /** TextInput content; null for everything else. */
+    value: string | null;
+    /** An empty TextInput's placeholder (AGENT-TOOLS v1.7); absent when the input has text or none. */
+    placeholder?: string;
+    /** Null only when the element could not be measured. */
+    frame: Frame | null;
+    actions: Action[];
+    disabled: boolean;
+    selected: boolean;
+    /** true / false / 'mixed' for checkable controls (Switch, checkbox role), else null. */
+    checked: boolean | 'mixed' | null;
+}
+export interface ScreenInfo {
+    width: number;
+    height: number;
+    scale: number;
+}
+export interface RouteInfo {
+    /** Route names from the outermost navigator to the focused screen, e.g. ["(tabs)", "nutrition"]. */
+    names: string[];
+    /** The focused screen's simple params (strings, numbers, booleans, null). */
+    params?: Record<string, string | number | boolean | null>;
+}
+/** What an element was before, for the fields that changed. */
+export type ChangedFields = Partial<Pick<TaplineElement, 'text' | 'label' | 'value' | 'placeholder' | 'checked' | 'selected' | 'disabled' | 'actions'>>;
+/** The difference from the previous `tree` call (only with `changes: true`). Refs of unchanged elements are kept. */
+export interface TreeChanges {
+    /** Whether the focused route is the same as before. */
+    sameRoute: boolean;
+    /** Refs of elements that are new. */
+    added: string[];
+    /** Elements that are gone, as they were (their refs no longer work). */
+    removed: TaplineElement[];
+    /** Elements whose text, value, state or actions changed, with the old values. */
+    changed: Array<{
+        ref: string;
+        was: ChangedFields;
+    }>;
+    /** Refs of elements that only moved. */
+    moved: string[];
+    /**
+     * Elements off screen (above or below it, before and now) whose text, label, value or state
+     * changed, as they are now and without a ref, with the old values. At most 5; absent when none.
+     */
+    offScreen?: Array<{
+        element: TaplineElement;
+        was: ChangedFields;
+    }>;
+    /** How many more changed off screen than `offScreen` holds; absent when none. */
+    offScreenMore?: number;
+    /** The software keyboard came up or went down since then; absent when it didn't, or isn't known. */
+    keyboard?: 'shown' | 'hidden';
+}
+/** An alert the app showed and nobody has answered yet. */
+export interface TreeAlert {
+    kind: 'alert' | 'prompt';
+    title: string;
+    message: string | null;
+    buttons: Array<{
+        text: string;
+        style: 'default' | 'cancel' | 'destructive';
+    }>;
+    /** Tapline's in-app stand-in (its buttons are elements to press) rather than the OS alert. */
+    standIn: boolean;
+}
+export interface TreeResult {
+    screen: ScreenInfo;
+    elements: TaplineElement[];
+    /** How many elements lie wholly above and below the screen (scroll to reach them); absent when none. */
+    offScreen?: {
+        above: number;
+        below: number;
+    };
+    /** Open alerts (Alert.alert / Alert.prompt) the app showed, oldest first. */
+    alerts?: TreeAlert[];
+    /** Network requests still running (fetch / XMLHttpRequest); absent when none. */
+    network?: {
+        inFlight: number;
+    };
+    /** True while the software keyboard is up; absent when it is down or isn't known. */
+    keyboard?: true;
+    /** The focused screen, when the app uses React Navigation (Expo Router included). */
+    route?: RouteInfo;
+    /** With `changes: true` and a previous tree: what changed since then. */
+    changes?: TreeChanges;
+}
+export type Target = {
+    ref: string;
+    index?: number;
+} | {
+    testID: string;
+    index?: number;
+} | {
+    label: string;
+    index?: number;
+} | {
+    text: string;
+    index?: number;
+} | {
+    x: number;
+    y: number;
+    index?: number;
+};
+export type LogLevel = 'log' | 'info' | 'warn' | 'error';
+export interface LogEntry {
+    level: LogLevel;
+    message: string;
+    ts: number;
+}
+export interface ErrorEventData {
+    message: string;
+    stack: string;
+    fatal: boolean;
+    ts: number;
+}
+export interface AppInfo {
+    name?: string;
+    id?: string;
+    version?: string;
+    build?: string;
+}
+export interface DeviceInfo {
+    platform: string;
+    osVersion: string;
+    model?: string;
+    name?: string;
+}
+export type Json = string | number | boolean | null | Json[] | {
+    [key: string]: Json;
+};
+export type UnknownRecord = Record<string, unknown>;
+export declare function isRecord(value: unknown): value is UnknownRecord;

package/dist/types.js

@@ -0,0 +1,32 @@
+"use strict";
+/** Wire-protocol and shared types (see docs/PROTOCOL.md, version 1). */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaplineError = exports.PROTOCOL_VERSION = void 0;
+exports.isRecord = isRecord;
+exports.PROTOCOL_VERSION = 1;
+/** An error that maps 1:1 onto a protocol error response. */
+class TaplineError extends Error {
+    code;
+    refs;
+    candidates;
+    constructor(code, message, refs, candidates) {
+        super(message);
+        this.name = 'TaplineError';
+        this.code = code;
+        this.refs = refs;
+        this.candidates = candidates;
+    }
+    toWire() {
+        const wire = { code: this.code, message: this.message };
+        if (this.refs)
+            wire.refs = this.refs;
+        if (this.candidates)
+            wire.candidates = this.candidates;
+        return wire;
+    }
+}
+exports.TaplineError = TaplineError;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA,wEAAwE;;;AAwLxE,4BAEC;AAxLY,QAAA,gBAAgB,GAAG,CAAC,CAAC;AAoBlC,6DAA6D;AAC7D,MAAa,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAY;IAChB,IAAI,CAAuB;IAC3B,UAAU,CAA+B;IAElD,YAAY,IAAe,EAAE,OAAe,EAAE,IAAe,EAAE,UAA6B;QAC1F,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED,MAAM;QACJ,MAAM,IAAI,GAAc,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QACnE,IAAI,IAAI,CAAC,IAAI;YAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACrC,IAAI,IAAI,CAAC,UAAU;YAAE,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QACvD,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAnBD,oCAmBC;AA8ID,SAAgB,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}