react-native-tapline 0.0.0-stage → 1.0.0

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,10 @@
+export interface TaplineMetroConfig {
+  serializer?: { getModulesRunBeforeMainModule?: (entryFilePath: string) => string[] } & 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.
+ */
+export function withTapline<C extends TaplineMetroConfig>(config: C, options?: { enabled?: boolean }): C;

package/metro.js

@@ -0,0 +1,40 @@
+// @ts-check
+'use strict';
+
+const path = require('path');
+
+/**
+ * Metro config helper: runs Tapline's `register` before the app's main module, so the app
+ * doesn't need its own entry file just to import it first. Only when Tapline is on
+ * (EXPO_PUBLIC_TAPLINE_ENABLED=1 by default), so store builds stay untouched.
+ *
+ *   // metro.config.js
+ *   const { getDefaultConfig } = require('expo/metro-config');
+ *   const { withTapline } = require('react-native-tapline/metro');
+ *   module.exports = withTapline(getDefaultConfig(__dirname));
+ *
+ * The app still calls startTapline() (for example at the top of app/_layout.tsx).
+ *
+ * @template {{ serializer?: { getModulesRunBeforeMainModule?: (entryFilePath: string) => string[] } & Record<string, unknown> } & Record<string, unknown>} C
+ * @param {C} config
+ * @param {{ enabled?: boolean }} [options]
+ * @returns {C}
+ */
+function withTapline(config, options = {}) {
+  const enabled = options.enabled ?? process.env.EXPO_PUBLIC_TAPLINE_ENABLED === '1';
+  if (!enabled) return config;
+  // The same file the package's own index imports, so Metro has it in the bundle.
+  const register = path.join(__dirname, 'dist', 'register.js');
+  const serializer = config.serializer ?? {};
+  const previous = serializer.getModulesRunBeforeMainModule;
+  return {
+    ...config,
+    serializer: {
+      ...serializer,
+      /** @param {string} entryFilePath */
+      getModulesRunBeforeMainModule: (entryFilePath) => [...(previous ? previous(entryFilePath) : []), register],
+    },
+  };
+}
+
+module.exports = { withTapline };

package/package.json

@@ -1,6 +1,102 @@
 {
   "name": "react-native-tapline",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.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": {
+    "type": "git",
+    "url": "git+https://github.com/bo5amis/tapline.git",
+    "directory": "packages/react-native"
+  },
+  "homepage": "https://github.com/bo5amis/tapline/tree/main/packages/react-native#readme",
+  "bugs": {
+    "url": "https://github.com/bo5amis/tapline/issues"
+  },
+  "keywords": [
+    "react-native",
+    "expo",
+    "testing",
+    "mcp",
+    "ai-agent",
+    "e2e",
+    "ios"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "default": "./dist/register.js"
+    },
+    "./metro": {
+      "types": "./metro.d.ts",
+      "default": "./metro.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "register": [
+        "dist/register.d.ts"
+      ],
+      "metro": [
+        "metro.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "register.js",
+    "register.d.ts",
+    "metro.js",
+    "metro.d.ts",
+    "README.md",
+    "ios",
+    "expo-module.config.json",
+    "TaplineNative.podspec"
+  ],
+  "sideEffects": [
+    "./dist/register.js",
+    "./register.js"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "jest"
+  },
+  "peerDependencies": {
+    "expo-keep-awake": ">=12",
+    "expo-secure-store": ">=12",
+    "react": ">=18",
+    "react-native": ">=0.72",
+    "react-native-view-shot": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "expo-keep-awake": {
+      "optional": true
+    },
+    "expo-secure-store": {
+      "optional": true
+    },
+    "react-native-view-shot": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@react-native/babel-preset": "0.88.1",
+    "@react-native/jest-preset": "0.88.1",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.20.5",
+    "@types/react": "^19.1.1",
+    "@types/react-test-renderer": "^19.1.0",
+    "jest": "^29.7.0",
+    "react": "19.3.1",
+    "react-native": "0.88.1",
+    "react-test-renderer": "19.3.1",
+    "typescript": "^5.9.0"
+  }
+}

package/register.d.ts

@@ -0,0 +1 @@
+export * from './dist/register';

package/register.js

@@ -0,0 +1,3 @@
+// Fallback for bundlers that do not read package.json "exports":
+// `import 'react-native-tapline/register'` resolves to this file.
+require('./dist/register');