react-native-tapline 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tapline contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# react-native-tapline
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The in-app agent of [Tapline](https://github.com/bo5amis/tapline#readme): lets an AI agent on your computer see and
+drive **your own** React Native / Expo app on your test phone, on the same Wi-Fi as the
+computer. TypeScript, plus an optional Expo native module that any new build of an Expo app
+picks up by itself (faster live-view frames, and iOS alerts and the share sheet seen over the
+app); no config plugin. Full setup:
+[docs/setup.md](https://github.com/bo5amis/tapline/blob/main/docs/setup.md).
+
+## Use
+
+First line of the app's entry file (for Expo Router, your own `index.js` that then imports
+`expo-router/entry`):
+
+```js
+import 'react-native-tapline/register';
+import { startTapline } from 'react-native-tapline';
+
+startTapline({ enabled: process.env.EXPO_PUBLIC_TAPLINE_ENABLED === '1' });
+```
+
+- The build carries no address and no token, only the switch. Set it in development and
+  test builds only. With it off, Tapline does nothing at all.
+- With it on, the app pairs when a pairing link opens it
+  (`<scheme>://tapline/pair?url=…&code=…&name=…`, from the computer's QR code): it asks
+  "Connect for testing?", connects with the one-time code, and keeps the token the
+  computer sends back. From then on it reconnects to that computer whenever it's open
+  (a new try one second after each failed one). `<scheme>://tapline/forget` unpairs. It never throws
+  into the app.
+- Expo Router: add `app/+native-intent.ts` so the router leaves pairing links alone:
+
+  ```ts
+  import { isTaplineLink } from 'react-native-tapline';
+
+  export function redirectSystemPath({ path }: { path: string; initial: boolean }) {
+    return isTaplineLink(path) ? null : path;
+  }
+  ```
+
+- `expo-secure-store` (when installed) keeps the pairing in the keychain; without it the
+  pairing lasts until the app restarts, or pass `storage` (`getItem`, `setItem`,
+  `removeItem`, async). Each install also keeps a random id there, so the computer can
+  tell two phones apart.
+- Optional: `app: { name, id, version, build }` names the app for the host; `url` and
+  `token` connect straight to a host without pairing (a simulator on the same computer);
+  `stopTapline()` shuts it down. `react-native-view-shot` for screenshots.
+- The method functions (`tree`, `press`, `longPress`, `typeText`, `scroll`, `swipe`, `toggle`,
+  `openURL`, `getLogs`, `reload`, `screenshot`) are exported too, for tests or an in-app
+  debug screen.
+
+## How it works
+
+- `register` installs a minimal React DevTools hook (chaining any existing one) that
+  records the app's React roots. It must run before React loads.
+- The screen is read from the React tree: host views with text, an accessibility label,
+  a `testID` or a handler become elements. An element's type is the React Native
+  component around it (`Pressable`, `Button`, `TextInput`, `Switch`, `FlatList` …) or
+  your component's name. A `Text` that only repeats its button's label is folded into
+  the button.
+- Positions come from `measureInWindow` (old architecture: the host instance; new
+  architecture: its public instance, else the Fabric UI manager), 500 ms per element at
+  most; an element that can't be measured is kept, without a frame.
+- `press` calls the nearest `onPress` with a synthetic press event, and bubbles from a
+  non-actionable element to its nearest actionable parent. `type` calls the input's own
+  `onChange` and `onChangeText`, and sets the native text of uncontrolled inputs.
+  `scroll` uses the scroll view's `scrollTo` / `scrollToOffset` / `scrollToEnd`.
+- Refs (`e1`, `e2` …) are given by `tree`; after an action, elements still on screen keep
+  theirs and new ones count on from the highest, so an old ref never points at another
+  element. Refs in an `ambiguous` error are valid too.
+- `swipe` drags a synthetic finger through React Native's responder system (capture, then
+  bubble, with a touch history for `PanResponder`).
+- Requests run one at a time; each has 30 s.
+
+## Limits
+
+- Only the app's own UI: no system dialogs, keyboard, other apps or home screen.
+- Actions call handlers; they aren't touches. `swipe` reaches `PanResponder` and other
+  responder-based drags; gestures built on react-native-gesture-handler, pinch, and views
+  React doesn't render (sliders, maps, web view contents) are out of reach.
+- Release builds shorten component names: element types read best in development builds,
+  and `testID`s keep targeting reliable.
+- Checked on an iPhone with the new architecture (Expo 57, React Native 0.86) in a
+  development build. Not confirmed yet: the hook in release builds, and the scroll offset
+  after the user has scrolled a plain `ScrollView` by hand. On iOS the device model and name
+  aren't sent (the install id stands in).
+- Turn it on only in builds you test with: the computer it's paired with can drive the
+  app while it's connected.

package/TaplineNative.podspec

@@ -0,0 +1,14 @@
+Pod::Spec.new do |s|
+  s.name = 'TaplineNative'
+  s.version = '1.0.0'
+  s.summary = 'Tapline: frames without a forced render, and what iOS draws over the app'
+  s.license = { :type => 'MIT' }
+  s.author = 'Tapline'
+  s.homepage = 'https://github.com/tapline/tapline'
+  s.platforms = { :ios => '16.4' }
+  s.source = { :git => '' }
+  s.static_framework = true
+  s.dependency 'ExpoModulesCore'
+  s.swift_version = '5.9'
+  s.source_files = 'ios/**/*.swift'
+end

package/dist/actions.d.ts

@@ -0,0 +1,160 @@
+import { type Entry, type Snapshot } from './inspect';
+import { type Fiber } from './fiber';
+import { type LogEntry, type TaplineElement } from './types';
+export { tree } from './inspect';
+/** Tune how long the app must be free of React commits after an action, and the longest wait (AGENT-TOOLS §6). */
+export declare function configureActions(next: {
+    quietMs?: number;
+    capMs?: number;
+}): void;
+/** Runs `listener` when an action's handler has run, before the wait for the app to settle. */
+export declare function onActed(listener: () => void): () => void;
+/** What an action reports about its settle: the milliseconds, and the cap when the screen never went quiet. */
+export interface SettleOutcome {
+    settledMs: number;
+    /** Set only when the wait ended at the cap with the screen still changing (AGENT-TOOLS v1.3, "The cap"). */
+    settleCapMs?: number;
+}
+/** Waits until the app is still after an action; resolves with the milliseconds that took. */
+export declare function settle(): Promise<number>;
+/** Like `settle`, and says when the wait ended at the cap: spread it into an action's result. */
+export declare function settleOutcome(): Promise<SettleOutcome>;
+type ParsedTarget = {
+    kind: 'ref';
+    ref: string;
+    index?: number;
+} | {
+    kind: 'testID';
+    value: string;
+    index?: number;
+} | {
+    kind: 'label';
+    value: string;
+    index?: number;
+} | {
+    kind: 'text';
+    value: string;
+    index?: number;
+} | {
+    kind: 'point';
+    x: number;
+    y: number;
+    index?: number;
+};
+export declare function parseTarget(raw: unknown): ParsedTarget;
+export interface Resolved {
+    snapshot: Snapshot;
+    entry: Entry;
+}
+/**
+ * What a `label` target matches: the element's own accessibility label, else its text. iOS forms
+ * the label of an element that has none from the text inside it, and Tapwright reads that label, so
+ * `{label: "OK"}` finds a button that only shows "OK" in both tools.
+ */
+export declare function labelOf(info: {
+    label: string | null;
+    text: string;
+}): string;
+/** 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>;
+/** 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. */
+export declare function back(rawParams: unknown): Promise<{
+    route: string[];
+    closed?: 'sheet';
+} & SettleOutcome>;
+/**
+ * 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.
+ */
+export type PressResult = {
+    element: TaplineElement;
+    closedKeyboard?: true;
+    forced?: string;
+} & SettleOutcome;
+export declare function press(params: unknown): Promise<PressResult>;
+export declare function longPress(params: unknown): Promise<PressResult>;
+/** What the SDK asks of the keyboard and the focused input; replaceable so tests need no native side. */
+export interface KeyboardControl {
+    /** The instance of the text input that has focus, or null. */
+    focusedInput(): unknown;
+    /** Whether the software keyboard is up (true when React Native can't say). */
+    visible(): boolean;
+    /** Closes the keyboard without submitting (`Keyboard.dismiss()`). */
+    dismiss(): void;
+    /** Takes focus off `input`. */
+    blur(input: unknown): void;
+    /** The keyboard's top edge in window points, or null when it isn't known. */
+    top?(): number | null;
+    /**
+     * Gives a text input the focus, as a finger on it does. `instances` are the input's instances,
+     * public ones and its component's included (see `inputInstances`).
+     */
+    focus?(instances: unknown[]): void;
+}
+/** Inject the keyboard and focus access (tests); pass null to restore the default. */
+export declare function setKeyboardControl(next: KeyboardControl | null): void;
+export declare function typeText(rawParams: unknown): Promise<{
+    element: TaplineElement;
+    value: string;
+    closedKeyboard?: true;
+    forced?: string;
+} & SettleOutcome>;
+/** What `scroll` answers; `target`, `reached` and `unchanged` only with `to: "target"`. */
+export type ScrollResult = {
+    /** The scroll view that was scrolled. */
+    element: TaplineElement;
+    offset: {
+        x: number;
+        y: number;
+    };
+    moved: boolean;
+    /** The element that was scrolled to, where it is now. */
+    target?: TaplineElement;
+    /** False when the scroll views are as far as they go and the element still isn't clear. */
+    reached?: boolean;
+    /** The element was clear already: nothing was scrolled. */
+    unchanged?: true;
+} & SettleOutcome;
+export declare function scroll(rawParams: unknown): Promise<ScrollResult>;
+export declare function toggle(rawParams: unknown): Promise<{
+    element: TaplineElement;
+    value: boolean;
+    closedKeyboard?: true;
+    unchanged?: true;
+    forced?: string;
+} & SettleOutcome>;
+export declare function openURL(rawParams: unknown): Promise<SettleOutcome>;
+export declare function getLogs(rawParams: unknown): Promise<{
+    entries: LogEntry[];
+}>;
+export declare function reload(): Promise<Record<string, never>>;
+export declare function screenshotAvailable(): boolean;
+export declare function screenshot(rawParams: unknown): Promise<{
+    mime: string;
+    data: string;
+    width: number;
+    height: number;
+}>;
+/**
+ * `swipe`: a finger dragged from (x0, y0) to (x1, y1) over `seconds`, through React Native's own
+ * touch system: the views under the start point negotiate for it as they would for a finger
+ * (PanResponder, a sheet's swipe to close, a Pressable that gives way once the finger moves), and
+ * the winner gets the moves and the release with a real touch history. Gestures that
+ * react-native-gesture-handler or a native view handle (sliders, maps) don't go through it: they
+ * answer `no_action`, as does a start on a scroll view (`scroll` moves those).
+ */
+export declare function swipe(rawParams: unknown): Promise<{
+    element: TaplineElement | null;
+    from: {
+        x: number;
+        y: number;
+    };
+    to: {
+        x: number;
+        y: number;
+    };
+} & SettleOutcome>;