react-native-tapline 0.0.0-stage → 1.1.0

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"}

package/dist/wait.d.ts

@@ -0,0 +1,8 @@
+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: unknown): Promise<{
+    met: true;
+    waitedMs: number;
+}>;
+export {};

package/dist/wait.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setNetworkIdleProvider = setNetworkIdleProvider;
+exports.waitFor = waitFor;
+const inspect_1 = require("./inspect");
+const types_1 = require("./types");
+/**
+ * `waitFor`: polls the screen until an element appears (or is gone) and/or the network is
+ * quiet, so an agent waits for loading to finish instead of guessing a delay.
+ */
+const POLL_MS = 250;
+const DEFAULT_TIMEOUT_S = 10;
+const MAX_TIMEOUT_S = 30;
+let networkIdle = () => true;
+/** Where "the network is quiet" comes from (the network tracker; tests). Null restores "always quiet". */
+function setNetworkIdleProvider(provider) {
+    networkIdle = provider ?? (() => true);
+}
+function parse(raw) {
+    if (!(0, types_1.isRecord)(raw))
+        throw new types_1.TaplineError('bad_params', 'waitFor needs an object');
+    const pick = (key) => {
+        const value = raw[key];
+        return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+    };
+    const text = pick('text');
+    const testID = pick('testID');
+    const label = pick('label');
+    const wantsNetwork = raw.networkIdle === true;
+    if (text === undefined && testID === undefined && label === undefined && !wantsNetwork) {
+        throw new types_1.TaplineError('bad_params', 'waitFor needs text, testID, label or networkIdle');
+    }
+    const timeout = raw.timeout === undefined ? DEFAULT_TIMEOUT_S : raw.timeout;
+    if (typeof timeout !== 'number' || !(timeout > 0) || timeout > MAX_TIMEOUT_S) {
+        throw new types_1.TaplineError('bad_params', `timeout is in seconds, above 0 and at most ${MAX_TIMEOUT_S}`);
+    }
+    return {
+        ...(text !== undefined ? { text } : {}),
+        ...(testID !== undefined ? { testID } : {}),
+        ...(label !== undefined ? { label } : {}),
+        gone: raw.gone === true,
+        networkIdle: wantsNetwork,
+        timeoutMs: timeout * 1000,
+    };
+}
+function matches(entry, condition) {
+    const { info } = entry;
+    if (condition.testID !== undefined && info.testID !== condition.testID)
+        return false;
+    // As a `label` target matches: the element's own label, else its text.
+    if (condition.label !== undefined && (info.label ?? info.text).toLowerCase() !== condition.label.toLowerCase())
+        return false;
+    if (condition.text !== undefined && !info.text.toLowerCase().includes(condition.text.toLowerCase()))
+        return false;
+    return true;
+}
+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));
+        if (present === condition.gone)
+            return false;
+    }
+    if (condition.networkIdle) {
+        try {
+            if (!networkIdle())
+                return false;
+        }
+        catch {
+            // an unknown network state doesn't block the wait
+        }
+    }
+    return true;
+}
+function describe(condition) {
+    const what = condition.text !== undefined
+        ? `text "${condition.text}"`
+        : condition.testID !== undefined
+            ? `id "${condition.testID}"`
+            : condition.label !== undefined
+                ? `label "${condition.label}"`
+                : null;
+    // The words Tapwright uses too (AGENT-TOOLS §5): `id` as the agent writes it, "to disappear".
+    const element = what === null ? null : `${what} ${condition.gone ? 'to disappear' : 'to appear'}`;
+    return [element, condition.networkIdle ? 'the network to be quiet' : null].filter((part) => part !== null).join(' and ');
+}
+async function waitFor(raw) {
+    const condition = parse(raw);
+    const started = Date.now();
+    for (;;) {
+        if (satisfied(condition))
+            return { met: true, waitedMs: Date.now() - started };
+        const waited = Date.now() - started;
+        if (waited >= condition.timeoutMs) {
+            throw new types_1.TaplineError('timeout', `Waited ${Math.round(waited / 100) / 10} s for ${describe(condition)}; it didn't happen.`);
+        }
+        await new Promise((resolve) => setTimeout(() => resolve(), Math.min(POLL_MS, condition.timeoutMs - waited)));
+    }
+}
+//# sourceMappingURL=wait.js.map

package/dist/wait.js.map

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

package/expo-module.config.json

@@ -0,0 +1,7 @@
+{
+  "platforms": ["apple"],
+  "apple": {
+    "podspecPath": "TaplineNative.podspec",
+    "modules": ["TaplineNativeModule"]
+  }
+}

package/ios/TaplineNativeModule.swift

@@ -0,0 +1,79 @@
+import ExpoModulesCore
+import UIKit
+
+/// Tapline's native side (optional: the SDK works without it, through react-native-view-shot).
+///
+/// - `capture`: a JPEG of the app's window. With `fresh: false` it draws what is on screen now
+///   (`afterScreenUpdates: false`), so iOS isn't made to render a new frame for it: the live
+///   viewer can capture often without slowing the app.
+/// - `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.
+private enum TaplineWindows {
+  static func keyWindow() -> UIWindow? {
+    let scenes = UIApplication.shared.connectedScenes.compactMap { $0 as? UIWindowScene }
+    let scene = scenes.first { $0.activationState == .foregroundActive } ?? scenes.first
+    guard let windows = scene?.windows else { return nil }
+    return windows.first { $0.isKeyWindow } ?? windows.first
+  }
+
+  /// The view controllers presented over the root, front last.
+  static func presented(from root: UIViewController?) -> [UIViewController] {
+    var chain: [UIViewController] = []
+    var current = root?.presentedViewController
+    while let controller = current {
+      chain.append(controller)
+      current = controller.presentedViewController
+    }
+    return chain
+  }
+}
+
+public final class TaplineNativeModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("TaplineNative")
+
+    /// Base64 JPEG of the key window at `pixelWidth` pixels wide (the height keeps the window's
+    /// shape), or an empty string when there is no window to draw.
+    /// Only the drawing holds the main thread; the JPEG is made on a background queue, so the app's
+    /// own frames wait for the draw alone.
+    AsyncFunction("capture") { (pixelWidth: Double, quality: Double, fresh: Bool, promise: Promise) in
+      guard let window = TaplineWindows.keyWindow(), window.bounds.width > 0, pixelWidth > 0 else {
+        promise.resolve("")
+        return
+      }
+      let bounds = window.bounds
+      let size = CGSize(width: pixelWidth.rounded(), height: (pixelWidth * bounds.height / bounds.width).rounded())
+      let format = UIGraphicsImageRendererFormat()
+      format.scale = 1
+      format.opaque = true
+      let image = UIGraphicsImageRenderer(size: size, format: format).image { _ in
+        window.drawHierarchy(in: CGRect(origin: .zero, size: size), afterScreenUpdates: fresh)
+      }
+      let clamped = CGFloat(min(max(quality, 0.1), 1))
+      DispatchQueue.global(qos: .userInitiated).async {
+        promise.resolve(image.jpegData(compressionQuality: clamped)?.base64EncodedString() ?? "")
+      }
+    }.runOnQueue(.main)
+
+    /// 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)
+      for controller in chain.reversed() {
+        if let alert = controller as? UIAlertController {
+          return [
+            "kind": alert.preferredStyle == .actionSheet ? "actionSheet" : "alert",
+            "title": alert.title ?? "",
+            "message": alert.message ?? "",
+            "buttons": alert.actions.map { $0.title ?? "" },
+            "destructive": alert.actions.map { $0.style == .destructive },
+          ]
+        }
+        if controller is UIActivityViewController {
+          return ["kind": "share", "title": "", "message": "", "buttons": [String](), "destructive": [Bool]()]
+        }
+      }
+      return ["kind": "", "title": "", "message": "", "buttons": [String](), "destructive": [Bool]()]
+    }.runOnQueue(.main)
+  }
+}

package/metro.d.ts

@@ -0,0 +1,26 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+
+export type Middleware = (req: IncomingMessage, res: ServerResponse, next: () => void) => void;
+
+export interface TaplineMetroConfig {
+  serializer?: { getModulesRunBeforeMainModule?: (entryFilePath: string) => string[] } & Record<string, unknown>;
+  server?: { enhanceMiddleware?: (middleware: Middleware, server: unknown) => Middleware } & Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * Runs Tapline's `register` before the app's main module (only when Tapline is on:
+ * EXPO_PUBLIC_TAPLINE_ENABLED=1, or `enabled`), so no custom entry file is needed. It also answers
+ * `GET /tapline/offer` on Metro, so a development build finds the pairing offer a Tapline host on this
+ * computer opened (zero-QR pairing).
+ */
+export function withTapline<C extends TaplineMetroConfig>(config: C, options?: { enabled?: boolean }): C;
+
+/** The newest open offer in `dir` (`~/.tapline/offers`), or null. */
+export function readOffer(dir: string): { code: string; name: string; port: number; file: string; claimedBy: string | undefined } | null;
+
+/** The `/tapline/offer` middleware, reading offers from `dir`. */
+export function offerMiddleware(dir: string): Middleware;
+
+/** Private LAN, link-local or loopback. */
+export function isLocalNetwork(address: string | undefined): boolean;