@phone-use/sdk 0.1.0 → 0.2.0

package/dist/testing.d.mts

@@ -1,4 +1,4 @@
-import { A as Snapshot, C as AlertAction, D as PressTarget, E as OpenAppResult, T as Capability, j as SnapshotNode, k as ScrollDirection, n as BaseDeviceBackend, w as BackendAlertResult } from "./backend-Cbr2tIN-.mjs";
+import { A as Snapshot, C as AlertAction, D as PressTarget, E as OpenAppResult, T as Capability, j as SnapshotNode, k as ScrollDirection, n as BaseDeviceBackend, w as BackendAlertResult } from "./backend-CkJkkw5Z.mjs";
 //#region src/exec.d.ts
 /** Per-call options an {@link ExecRunner} accepts. */
 type ExecOptions = {
@@ -13,7 +13,7 @@ type ExecResult = {
   stderr: string;
 };
 /**
- * The process-execution seam (docs/19: dependency-inject the spawn/exec runner
+ * The process-execution seam (dependency-inject the spawn/exec runner
  * so unit tests run without the real binaries). Runners are dumb: resolve on
  * exit 0, reject with the execFile error shape otherwise — error normalization
  * to PhoneUseError happens at the call site, once.
@@ -29,8 +29,8 @@ type FakeCall = {
   args: unknown[];
 };
 /**
- * The device-free test double the VPS test tier stands on (docs/20 item 2
- * verification protocol). Scripts a sequence of snapshot "screens"; records
+ * The device-free test double — runs anywhere, no simulator needed.
+ * Scripts a sequence of snapshot "screens"; records
  * every call; lets tests simulate screen transitions per action. Zero deps,
  * Node-only. Public via the `@phone-use/sdk/testing` subpath so harness tests
  * and third-party backend authors share it.
@@ -116,8 +116,8 @@ type ScriptedExecRunner = ExecRunner & {
   remaining(): number;
 };
 /**
- * The DI'd process runner for lifecycle tests (docs/19: dependency-inject the
- * spawn/exec runner). Takes an ordered script of steps; each call consumes the
+ * The DI'd process runner for lifecycle tests (the injectable counterpart to
+ * defaultExecRunner). Takes an ordered script of steps; each call consumes the
  * next step, optionally asserting the argv shape, and resolves/rejects in the
  * execFile-error shape defaultExecRunner produces.
  */

package/dist/testing.mjs

@@ -1,8 +1,8 @@
-import { n as BaseDeviceBackend, t as ALL_CAPABILITIES } from "./device-BzPnHvQy.mjs";
+import { n as BaseDeviceBackend, t as ALL_CAPABILITIES } from "./device-Xsy_LPUF.mjs";
 //#region src/testing.ts
 /**
-* The device-free test double the VPS test tier stands on (docs/20 item 2
-* verification protocol). Scripts a sequence of snapshot "screens"; records
+* The device-free test double — runs anywhere, no simulator needed.
+* Scripts a sequence of snapshot "screens"; records
 * every call; lets tests simulate screen transitions per action. Zero deps,
 * Node-only. Public via the `@phone-use/sdk/testing` subpath so harness tests
 * and third-party backend authors share it.
@@ -143,8 +143,8 @@ function screen(nodes, app = {}) {
 	};
 }
 /**
-* The DI'd process runner for lifecycle tests (docs/19: dependency-inject the
-* spawn/exec runner). Takes an ordered script of steps; each call consumes the
+* The DI'd process runner for lifecycle tests (the injectable counterpart to
+* defaultExecRunner). Takes an ordered script of steps; each call consumes the
 * next step, optionally asserting the argv shape, and resolves/rejects in the
 * execFile-error shape defaultExecRunner produces.
 */

package/dist/testing.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"testing.mjs","names":[],"sources":["../src/testing.ts"],"sourcesContent":["import { BaseDeviceBackend } from './backend.ts';\nimport type {\n  AlertAction,\n  BackendAlertResult,\n  Capability,\n  OpenAppResult,\n  PressTarget,\n  Rect,\n  ScrollDirection,\n  Snapshot,\n  SnapshotNode,\n} from './device.ts';\nimport { ALL_CAPABILITIES } from './device.ts';\n\n/** One scripted screen in a {@link FakeBackend} sequence (alias of Snapshot). */\nexport type FakeScreen = Snapshot;\n/** A recorded backend call: method name plus the arguments it received. */\nexport type FakeCall = { method: string; args: unknown[] };\n\n/**\n * The device-free test double the VPS test tier stands on (docs/20 item 2\n * verification protocol). Scripts a sequence of snapshot \"screens\"; records\n * every call; lets tests simulate screen transitions per action. Zero deps,\n * Node-only. Public via the `@phone-use/sdk/testing` subpath so harness tests\n * and third-party backend authors share it.\n */\nexport class FakeBackend extends BaseDeviceBackend {\n  /** Every backend call made, in order. */\n  readonly calls: FakeCall[] = [];\n  private screens: FakeScreen[];\n  private current = 0;\n  private readonly onAction: ((call: FakeCall, current: number) => number | undefined) | undefined;\n  private readonly failWith: ((call: FakeCall) => unknown) | undefined;\n\n  constructor(opts: {\n    screens: FakeScreen[];\n    name?: string;\n    capabilities?: Iterable<Capability>;\n    /** Return a new screen index to simulate a transition caused by the call. */\n    onAction?: (call: FakeCall, current: number) => number | undefined;\n    /** Throw for matching calls — return the error to throw, undefined to pass. */\n    failWith?: (call: FakeCall) => unknown;\n  }) {\n    super(opts.name ?? 'fake', opts.capabilities ?? ALL_CAPABILITIES);\n    if (!opts.screens.length) throw new Error('FakeBackend needs at least one screen');\n    this.screens = opts.screens;\n    this.onAction = opts.onAction;\n    this.failWith = opts.failWith;\n  }\n\n  /** Jump to screen `i` (throws when out of range). */\n  setScreen(i: number): void {\n    if (i < 0 || i >= this.screens.length) throw new Error(`no screen ${i}`);\n    this.current = i;\n  }\n\n  /** Index of the screen currently being served. */\n  get screenIndex(): number {\n    return this.current;\n  }\n\n  private record(method: string, ...args: unknown[]): FakeCall {\n    const call: FakeCall = { method, args };\n    this.calls.push(call);\n    const err = this.failWith?.(call);\n    if (err !== undefined) throw err;\n    const next = this.onAction?.(call, this.current);\n    if (next !== undefined) this.setScreen(next);\n    return call;\n  }\n\n  override snapshot(opts?: {\n    interactiveOnly?: boolean | undefined;\n    depth?: number | undefined;\n  }): Promise<Snapshot> {\n    this.record('snapshot', opts);\n    return Promise.resolve(this.screens[this.current]!);\n  }\n\n  override screenshot(opts: { path: string; overlayRefs?: boolean | undefined }): Promise<{ path: string }> {\n    this.record('screenshot', opts);\n    return Promise.resolve({ path: opts.path }); // records; writes nothing\n  }\n\n  override press(target: PressTarget): Promise<void> {\n    this.record('press', target);\n    return Promise.resolve();\n  }\n\n  override longPress(ref: string, durationMs?: number): Promise<void> {\n    this.record('longPress', ref, durationMs);\n    return Promise.resolve();\n  }\n\n  override fill(ref: string, text: string): Promise<void> {\n    this.record('fill', ref, text);\n    return Promise.resolve();\n  }\n\n  override typeText(text: string): Promise<void> {\n    this.record('typeText', text);\n    return Promise.resolve();\n  }\n\n  override pressKey(key: 'return'): Promise<void> {\n    this.record('pressKey', key);\n    return Promise.resolve();\n  }\n\n  override scroll(direction: ScrollDirection): Promise<void> {\n    this.record('scroll', direction);\n    return Promise.resolve();\n  }\n\n  override pan(x: number, y: number, dx: number, dy: number, durationMs?: number): Promise<void> {\n    this.record('pan', x, y, dx, dy, durationMs);\n    return Promise.resolve();\n  }\n\n  override waitForText(text: string, timeoutMs?: number): Promise<void> {\n    this.record('waitForText', text, timeoutMs);\n    return Promise.resolve();\n  }\n\n  override systemAlert(action: AlertAction): Promise<BackendAlertResult> {\n    this.record('systemAlert', action);\n    return Promise.resolve({ alert: null });\n  }\n\n  override home(): Promise<void> {\n    this.record('home');\n    return Promise.resolve();\n  }\n\n  override back(): Promise<void> {\n    this.record('back');\n    return Promise.resolve();\n  }\n\n  override openApp(opts: {\n    app?: string | undefined;\n    url?: string | undefined;\n    relaunch?: boolean | undefined;\n  }): Promise<OpenAppResult> {\n    this.record('openApp', opts);\n    const s = this.screens[this.current]!;\n    return Promise.resolve({ appName: s.appName, appBundleId: s.appBundleId });\n  }\n\n  override listApps(): Promise<string[]> {\n    this.record('listApps');\n    return Promise.resolve([]);\n  }\n\n  override closeSession(): Promise<void> {\n    this.record('closeSession');\n    return Promise.resolve();\n  }\n}\n\nconst DEFAULT_RECT: Rect = { x: 0, y: 100, width: 390, height: 44 };\n\n/** Fixture sugar: an element with sane defaults (Button role, on-screen rect). */\nexport function el(partial: Partial<SnapshotNode> & { ref: string }): SnapshotNode {\n  return { type: 'Button', label: '', rect: { ...DEFAULT_RECT }, ...partial };\n}\n\n/** Fixture sugar: a screen with an Application root so viewport detection works. */\nexport function screen(\n  nodes: SnapshotNode[],\n  app: { appName?: string | undefined; appBundleId?: string | undefined } = {},\n): FakeScreen {\n  const root: SnapshotNode = { type: 'Application', rect: { x: 0, y: 0, width: 390, height: 844 } };\n  return { nodes: [root, ...nodes], appName: app.appName, appBundleId: app.appBundleId };\n}\n\nexport type { ExecOptions, ExecResult, ExecRunner } from './exec.ts';\n\n/** One step in a {@link scriptedExecRunner} script — what the next exec call gets. */\nexport type ScriptedExecStep = {\n  /** Optional argv guard — the step throws if the call doesn't match. */\n  expectArgs?: ((file: string, args: string[]) => boolean) | undefined;\n  stdout?: string | undefined;\n  stderr?: string | undefined;\n  /** Nonzero → the call rejects with an execFile-shaped error. */\n  code?: number | undefined;\n  /** Simulate a runner timeout kill. */\n  killed?: boolean | undefined;\n};\n\n/** The runner {@link scriptedExecRunner} returns: an ExecRunner plus call inspection. */\nexport type ScriptedExecRunner = import('./exec.ts').ExecRunner & {\n  /** Every exec call made, in order. */\n  calls: { file: string; args: string[] }[];\n  /** Steps not yet consumed (assert 0 at test end for full-sequence checks). */\n  remaining(): number;\n};\n\n/**\n * The DI'd process runner for lifecycle tests (docs/19: dependency-inject the\n * spawn/exec runner). Takes an ordered script of steps; each call consumes the\n * next step, optionally asserting the argv shape, and resolves/rejects in the\n * execFile-error shape defaultExecRunner produces.\n */\nexport function scriptedExecRunner(steps: ScriptedExecStep[]): ScriptedExecRunner {\n  const queue = [...steps];\n  const calls: { file: string; args: string[] }[] = [];\n  const runner = (async (file: string, args: string[]) => {\n    calls.push({ file, args: [...args] });\n    const step = queue.shift();\n    if (!step) throw new Error(`scriptedExecRunner: unexpected call ${file} ${args.join(' ')}`);\n    if (step.expectArgs && !step.expectArgs(file, args)) {\n      throw new Error(`scriptedExecRunner: argv mismatch for ${file} ${args.join(' ')}`);\n    }\n    if (step.code !== undefined && step.code !== 0) {\n      const err = new Error(`Command failed: ${file} ${args.join(' ')}\\n${step.stderr ?? ''}`) as Error & {\n        code: number;\n        stdout: string;\n        stderr: string;\n        killed: boolean;\n      };\n      err.code = step.code;\n      err.stdout = step.stdout ?? '';\n      err.stderr = step.stderr ?? '';\n      err.killed = step.killed ?? false;\n      throw err;\n    }\n    if (step.killed) {\n      const err = new Error(`Command killed: ${file}`) as Error & { killed: boolean; signal: string };\n      err.killed = true;\n      err.signal = 'SIGTERM';\n      throw err;\n    }\n    return { stdout: step.stdout ?? '', stderr: step.stderr ?? '' };\n  }) as ScriptedExecRunner;\n  runner.calls = calls;\n  runner.remaining = () => queue.length;\n  return runner;\n}\n"],"mappings":"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"}
+{"version":3,"file":"testing.mjs","names":[],"sources":["../src/testing.ts"],"sourcesContent":["import { BaseDeviceBackend } from './backend.ts';\nimport type {\n  AlertAction,\n  BackendAlertResult,\n  Capability,\n  OpenAppResult,\n  PressTarget,\n  Rect,\n  ScrollDirection,\n  Snapshot,\n  SnapshotNode,\n} from './device.ts';\nimport { ALL_CAPABILITIES } from './device.ts';\n\n/** One scripted screen in a {@link FakeBackend} sequence (alias of Snapshot). */\nexport type FakeScreen = Snapshot;\n/** A recorded backend call: method name plus the arguments it received. */\nexport type FakeCall = { method: string; args: unknown[] };\n\n/**\n * The device-free test double — runs anywhere, no simulator needed.\n * Scripts a sequence of snapshot \"screens\"; records\n * every call; lets tests simulate screen transitions per action. Zero deps,\n * Node-only. Public via the `@phone-use/sdk/testing` subpath so harness tests\n * and third-party backend authors share it.\n */\nexport class FakeBackend extends BaseDeviceBackend {\n  /** Every backend call made, in order. */\n  readonly calls: FakeCall[] = [];\n  private screens: FakeScreen[];\n  private current = 0;\n  private readonly onAction: ((call: FakeCall, current: number) => number | undefined) | undefined;\n  private readonly failWith: ((call: FakeCall) => unknown) | undefined;\n\n  constructor(opts: {\n    screens: FakeScreen[];\n    name?: string;\n    capabilities?: Iterable<Capability>;\n    /** Return a new screen index to simulate a transition caused by the call. */\n    onAction?: (call: FakeCall, current: number) => number | undefined;\n    /** Throw for matching calls — return the error to throw, undefined to pass. */\n    failWith?: (call: FakeCall) => unknown;\n  }) {\n    super(opts.name ?? 'fake', opts.capabilities ?? ALL_CAPABILITIES);\n    if (!opts.screens.length) throw new Error('FakeBackend needs at least one screen');\n    this.screens = opts.screens;\n    this.onAction = opts.onAction;\n    this.failWith = opts.failWith;\n  }\n\n  /** Jump to screen `i` (throws when out of range). */\n  setScreen(i: number): void {\n    if (i < 0 || i >= this.screens.length) throw new Error(`no screen ${i}`);\n    this.current = i;\n  }\n\n  /** Index of the screen currently being served. */\n  get screenIndex(): number {\n    return this.current;\n  }\n\n  private record(method: string, ...args: unknown[]): FakeCall {\n    const call: FakeCall = { method, args };\n    this.calls.push(call);\n    const err = this.failWith?.(call);\n    if (err !== undefined) throw err;\n    const next = this.onAction?.(call, this.current);\n    if (next !== undefined) this.setScreen(next);\n    return call;\n  }\n\n  override snapshot(opts?: {\n    interactiveOnly?: boolean | undefined;\n    depth?: number | undefined;\n  }): Promise<Snapshot> {\n    this.record('snapshot', opts);\n    return Promise.resolve(this.screens[this.current]!);\n  }\n\n  override screenshot(opts: { path: string; overlayRefs?: boolean | undefined }): Promise<{ path: string }> {\n    this.record('screenshot', opts);\n    return Promise.resolve({ path: opts.path }); // records; writes nothing\n  }\n\n  override press(target: PressTarget): Promise<void> {\n    this.record('press', target);\n    return Promise.resolve();\n  }\n\n  override longPress(ref: string, durationMs?: number): Promise<void> {\n    this.record('longPress', ref, durationMs);\n    return Promise.resolve();\n  }\n\n  override fill(ref: string, text: string): Promise<void> {\n    this.record('fill', ref, text);\n    return Promise.resolve();\n  }\n\n  override typeText(text: string): Promise<void> {\n    this.record('typeText', text);\n    return Promise.resolve();\n  }\n\n  override pressKey(key: 'return'): Promise<void> {\n    this.record('pressKey', key);\n    return Promise.resolve();\n  }\n\n  override scroll(direction: ScrollDirection): Promise<void> {\n    this.record('scroll', direction);\n    return Promise.resolve();\n  }\n\n  override pan(x: number, y: number, dx: number, dy: number, durationMs?: number): Promise<void> {\n    this.record('pan', x, y, dx, dy, durationMs);\n    return Promise.resolve();\n  }\n\n  override waitForText(text: string, timeoutMs?: number): Promise<void> {\n    this.record('waitForText', text, timeoutMs);\n    return Promise.resolve();\n  }\n\n  override systemAlert(action: AlertAction): Promise<BackendAlertResult> {\n    this.record('systemAlert', action);\n    return Promise.resolve({ alert: null });\n  }\n\n  override home(): Promise<void> {\n    this.record('home');\n    return Promise.resolve();\n  }\n\n  override back(): Promise<void> {\n    this.record('back');\n    return Promise.resolve();\n  }\n\n  override openApp(opts: {\n    app?: string | undefined;\n    url?: string | undefined;\n    relaunch?: boolean | undefined;\n  }): Promise<OpenAppResult> {\n    this.record('openApp', opts);\n    const s = this.screens[this.current]!;\n    return Promise.resolve({ appName: s.appName, appBundleId: s.appBundleId });\n  }\n\n  override listApps(): Promise<string[]> {\n    this.record('listApps');\n    return Promise.resolve([]);\n  }\n\n  override closeSession(): Promise<void> {\n    this.record('closeSession');\n    return Promise.resolve();\n  }\n}\n\nconst DEFAULT_RECT: Rect = { x: 0, y: 100, width: 390, height: 44 };\n\n/** Fixture sugar: an element with sane defaults (Button role, on-screen rect). */\nexport function el(partial: Partial<SnapshotNode> & { ref: string }): SnapshotNode {\n  return { type: 'Button', label: '', rect: { ...DEFAULT_RECT }, ...partial };\n}\n\n/** Fixture sugar: a screen with an Application root so viewport detection works. */\nexport function screen(\n  nodes: SnapshotNode[],\n  app: { appName?: string | undefined; appBundleId?: string | undefined } = {},\n): FakeScreen {\n  const root: SnapshotNode = { type: 'Application', rect: { x: 0, y: 0, width: 390, height: 844 } };\n  return { nodes: [root, ...nodes], appName: app.appName, appBundleId: app.appBundleId };\n}\n\nexport type { ExecOptions, ExecResult, ExecRunner } from './exec.ts';\n\n/** One step in a {@link scriptedExecRunner} script — what the next exec call gets. */\nexport type ScriptedExecStep = {\n  /** Optional argv guard — the step throws if the call doesn't match. */\n  expectArgs?: ((file: string, args: string[]) => boolean) | undefined;\n  stdout?: string | undefined;\n  stderr?: string | undefined;\n  /** Nonzero → the call rejects with an execFile-shaped error. */\n  code?: number | undefined;\n  /** Simulate a runner timeout kill. */\n  killed?: boolean | undefined;\n};\n\n/** The runner {@link scriptedExecRunner} returns: an ExecRunner plus call inspection. */\nexport type ScriptedExecRunner = import('./exec.ts').ExecRunner & {\n  /** Every exec call made, in order. */\n  calls: { file: string; args: string[] }[];\n  /** Steps not yet consumed (assert 0 at test end for full-sequence checks). */\n  remaining(): number;\n};\n\n/**\n * The DI'd process runner for lifecycle tests (the injectable counterpart to\n * defaultExecRunner). Takes an ordered script of steps; each call consumes the\n * next step, optionally asserting the argv shape, and resolves/rejects in the\n * execFile-error shape defaultExecRunner produces.\n */\nexport function scriptedExecRunner(steps: ScriptedExecStep[]): ScriptedExecRunner {\n  const queue = [...steps];\n  const calls: { file: string; args: string[] }[] = [];\n  const runner = (async (file: string, args: string[]) => {\n    calls.push({ file, args: [...args] });\n    const step = queue.shift();\n    if (!step) throw new Error(`scriptedExecRunner: unexpected call ${file} ${args.join(' ')}`);\n    if (step.expectArgs && !step.expectArgs(file, args)) {\n      throw new Error(`scriptedExecRunner: argv mismatch for ${file} ${args.join(' ')}`);\n    }\n    if (step.code !== undefined && step.code !== 0) {\n      const err = new Error(`Command failed: ${file} ${args.join(' ')}\\n${step.stderr ?? ''}`) as Error & {\n        code: number;\n        stdout: string;\n        stderr: string;\n        killed: boolean;\n      };\n      err.code = step.code;\n      err.stdout = step.stdout ?? '';\n      err.stderr = step.stderr ?? '';\n      err.killed = step.killed ?? false;\n      throw err;\n    }\n    if (step.killed) {\n      const err = new Error(`Command killed: ${file}`) as Error & { killed: boolean; signal: string };\n      err.killed = true;\n      err.signal = 'SIGTERM';\n      throw err;\n    }\n    return { stdout: step.stdout ?? '', stderr: step.stderr ?? '' };\n  }) as ScriptedExecRunner;\n  runner.calls = calls;\n  runner.remaining = () => queue.length;\n  return runner;\n}\n"],"mappings":"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"}

package/package.json

@@ -1,15 +1,29 @@
 {
   "name": "@phone-use/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Typed mobile-device SDK — Device, backends, errors, actions",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
+  "homepage": "https://www.phoneuse.dev",
+  "bugs": {
+    "url": "https://github.com/Rajmeet/phone-use/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Rajmeet/phone-use.git",
     "directory": "packages/sdk"
   },
+  "keywords": [
+    "ios",
+    "simulator",
+    "mobile",
+    "device",
+    "automation",
+    "agent",
+    "ai",
+    "testing"
+  ],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"

package/src/actions.ts

@@ -17,7 +17,7 @@ import {
 import { SecretStore } from './secrets.ts';
 
 // ---------------------------------------------------------------------------
-// The observe→act seam (docs/19 §API shape; docs/20 item 4): observe() returns
+// The observe→act seam: observe() returns
 // portable Action descriptors carrying RE-RESOLVABLE element queries; act()
 // re-resolves against the live tree and executes with no re-inference. A
 // compiled skill is a stored Action[]. The resolution ladder (DeviceCore) is
@@ -63,13 +63,13 @@ export type ActionVerb =
   | 'waitForText';
 
 /**
- * The observe→act seam (docs/19 §API shape; docs/20 item 4): a portable action
+ * The observe→act seam: a portable action
  * descriptor carrying a re-resolvable {@link ElementQuery}. `observe()` returns
  * these; `act()` re-resolves against the live tree and executes with no
  * re-inference. A compiled skill is a stored `Action[]`.
  */
 export type Action = {
-  /** Versioned, documented UNSTABLE pre-1.0 (docs/20 open-question 3). */
+  /** Versioned, documented UNSTABLE pre-1.0. */
   formatVersion: 0;
   /** What to do. */
   verb: ActionVerb;
@@ -106,7 +106,7 @@ export type Action = {
     | undefined;
 };
 
-/** The stored-Action[] artifact (public TYPE, unstable FORMAT — see docs/20). */
+/** The stored-Action[] artifact (public TYPE, unstable FORMAT pre-1.0). */
 export type CompiledSkill = {
   formatVersion: 0;
   name: string;
@@ -311,8 +311,8 @@ type WaitOutcome =
   | { ok: false; result: ActionResult };
 
 /**
- * Resolve + auto-wait (docs/19: visible+hittable+enabled+settled on every
- * action, no caller sleep; docs/20 risk 2: must not double latency).
+ * Resolve + auto-wait (visible+hittable+enabled+settled on every
+ * action, no caller sleep — and it must not double latency).
  * Fast path: a fresh cache resolving to an actionable target executes with
  * ZERO extra snapshots. Slow path: poll in place (never scroll — scrolling is
  * the ladder's job, and polling must not dismiss transient menus) until the

package/src/backend.ts

@@ -11,7 +11,7 @@ import type {
 import { PhoneUseError, UnsupportedCapabilityError } from './errors.ts';
 
 /**
- * The backend contract (docs/19 §Backend contract): a STRUCTURAL interface —
+ * The backend contract: a STRUCTURAL interface —
  * any object with these methods is a backend — plus an optional
  * {@link BaseDeviceBackend} class with the plumbing done (Appium BaseDriver
  * ergonomics). Methods reject only with PhoneUseError subclasses; backends
@@ -139,10 +139,9 @@ export abstract class BaseDeviceBackend implements DeviceBackend {
 }
 
 // ---------------------------------------------------------------------------
-// Runtime backend registry (registerBackend + phone-backend-* convention,
-// docs/19). A deliberate module-level Map: this IS the registry — mirrored on
-// permissions.ts's documented pattern; the item-2 grep audit is scoped to
-// driver code.
+// Runtime backend registry (registerBackend + the phone-backend-* naming
+// convention). A deliberate module-level Map: this IS the registry — mirrored
+// on permissions.ts's documented pattern.
 // ---------------------------------------------------------------------------
 
 /** Builds a backend from an optional {@link DeviceConfig}. */

package/src/backends/agent-device.ts

@@ -19,9 +19,8 @@ import { toPhoneUseError } from '../errors.ts';
 // pinning is per-request in agent-device (AgentDeviceSelectionOptions), so a
 // backend holds a selection object and spreads it into every call. With no
 // config, selection is {} and the client is default-constructed — requests are
-// byte-identical to the pre-seam process-global path (booted-sim auto-detect),
-// which is the item-2 backward-compat guarantee (docs/20 risk: default-
-// selection drift).
+// byte-identical to the pre-seam process-global path (booted-sim auto-detect)
+// — the backward-compat guarantee against default-selection drift.
 //
 // Every method normalizes errors via toPhoneUseError — no agent-device type
 // or error ever escapes this file.

package/src/backends/device-runner.ts

@@ -0,0 +1,205 @@
+import { BaseDeviceBackend } from '../backend.ts';
+import type {
+  AlertAction,
+  BackendAlertResult,
+  Capability,
+  OpenAppResult,
+  PressTarget,
+  ScrollDirection,
+  Snapshot,
+} from '../device.ts';
+import { ActionFailedError, DeviceNotFoundError, TimeoutError } from '../errors.ts';
+
+/**
+ * A device-runner is addressed purely by URL, so it takes no DeviceConfig
+ * platform/udid selection — only where to reach the runner and how to auth.
+ */
+export type DeviceRunnerConfig = {
+  endpoint?: string | undefined;
+  token?: string | undefined;
+  timeoutMs?: number | undefined;
+};
+
+const RUNNER_CAPABILITIES: readonly Capability[] = [
+  'snapshot',
+  'screenshot',
+  'press',
+  'fill',
+  'type',
+  'scroll',
+  'pan',
+  'openApp',
+  'home',
+];
+
+/**
+ * Backend that speaks to an on-device runner: an XCTest-hosted JSON-RPC server
+ * running ON the iPhone itself, which holds the automation privileges iOS
+ * denies to ordinary apps.
+ *
+ * The endpoint is just a URL, so the same backend serves every topology:
+ *   - `http://127.0.0.1:45678`  — port-forwarded from a paired host
+ *   - `http://<phone-ip>:45678` — straight over the LAN / tailnet
+ *   - `https://relay.example/d/<id>` — the runner dials out to a cloud relay,
+ *     which is what lets an agent anywhere drive the phone with no inbound
+ *     ports and no Mac in the loop.
+ *
+ * The wire format matches the shape proven by rounak/PhoneAgent: newline-free
+ * JSON request/response over HTTP POST, one method per call.
+ */
+export class DeviceRunnerBackend extends BaseDeviceBackend {
+  readonly #endpoint: string;
+  readonly #token: string | undefined;
+  readonly #timeoutMs: number;
+
+  constructor(config?: DeviceRunnerConfig) {
+    // BaseDeviceBackend owns backendName/capabilities — set them via super()
+    // rather than redeclaring the fields.
+    super('device-runner', RUNNER_CAPABILITIES);
+    const endpoint = config?.endpoint ?? process.env.PHONE_USE_RUNNER_URL ?? 'http://127.0.0.1:45678';
+    this.#endpoint = endpoint.replace(/\/+$/, '');
+    this.#token = config?.token ?? process.env.PHONE_USE_RUNNER_TOKEN;
+    this.#timeoutMs = config?.timeoutMs ?? 30_000;
+  }
+
+  async #rpc<T>(method: string, params: Record<string, unknown> = {}): Promise<T> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.#timeoutMs);
+    let res: Response;
+    try {
+      res = await fetch(this.#endpoint, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          ...(this.#token ? { authorization: `Bearer ${this.#token}` } : {}),
+        },
+        body: JSON.stringify({ jsonrpc: '2.0', id: Date.now(), method, params }),
+        signal: controller.signal,
+      });
+    } catch (cause) {
+      if (controller.signal.aborted) {
+        throw new TimeoutError(`runner did not answer ${method} within ${this.#timeoutMs}ms`);
+      }
+      throw new DeviceNotFoundError(
+        `cannot reach the on-device runner at ${this.#endpoint} — is it activated on the phone?`,
+        { cause },
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+
+    if (!res.ok) {
+      throw new ActionFailedError(`runner returned HTTP ${res.status} for ${method}`);
+    }
+    const body = (await res.json()) as { result?: T; error?: { message?: string } };
+    if (body.error) {
+      throw new ActionFailedError(body.error.message ?? `runner rejected ${method}`);
+    }
+    return body.result as T;
+  }
+
+  override async snapshot(opts?: {
+    interactiveOnly?: boolean | undefined;
+    depth?: number | undefined;
+  }): Promise<Snapshot> {
+    // The runner speaks its own compact wire shape; map it onto the SDK's
+    // Snapshot contract so every consumer (CLI, MCP, agent, bench) is unaware
+    // it is talking to a phone rather than a simulator.
+    const wire = await this.#rpc<{
+      app?: string;
+      elements: Array<{
+        ref: string;
+        role?: string;
+        label?: string;
+        value?: string;
+        enabled?: boolean;
+        rect?: { x: number; y: number; w: number; h: number };
+      }>;
+    }>('get_tree', {
+      interactiveOnly: opts?.interactiveOnly ?? false,
+      depth: opts?.depth,
+    });
+    return {
+      appBundleId: wire.app,
+      appName: wire.app,
+      nodes: (wire.elements ?? []).map((e) => ({
+        ref: e.ref,
+        role: e.role,
+        type: e.role,
+        label: e.label,
+        value: e.value,
+        enabled: e.enabled,
+        rect: e.rect ? { x: e.rect.x, y: e.rect.y, width: e.rect.w, height: e.rect.h } : undefined,
+      })),
+    };
+  }
+
+  override async screenshot(opts: {
+    path: string;
+    overlayRefs?: boolean | undefined;
+  }): Promise<{ path: string }> {
+    const { base64 } = await this.#rpc<{ base64: string }>('get_screen_image', {
+      overlayRefs: opts.overlayRefs ?? false,
+    });
+    const { writeFile } = await import('node:fs/promises');
+    await writeFile(opts.path, Buffer.from(base64, 'base64'));
+    return { path: opts.path };
+  }
+
+  override async press(target: PressTarget): Promise<void> {
+    // PressTarget is {ref} | {x,y} — never a bare string, so narrow on the key.
+    if ('ref' in target) {
+      await this.#rpc('tap_element', { ref: target.ref });
+      return;
+    }
+    await this.#rpc('tap', { x: target.x, y: target.y });
+  }
+
+  override async fill(ref: string, text: string): Promise<void> {
+    await this.#rpc('enter_text', { ref, text, replace: true });
+  }
+
+  override async typeText(text: string): Promise<void> {
+    await this.#rpc('enter_text', { text, replace: false });
+  }
+
+  override async scroll(direction: ScrollDirection): Promise<void> {
+    await this.#rpc('scroll', { direction });
+  }
+
+  override async pan(x: number, y: number, dx: number, dy: number, durationMs = 300): Promise<void> {
+    await this.#rpc('swipe', { x, y, dx, dy, durationMs });
+  }
+
+  override async home(): Promise<void> {
+    await this.#rpc('home');
+  }
+
+  override async openApp(opts: {
+    app?: string | undefined;
+    url?: string | undefined;
+    relaunch?: boolean | undefined;
+  }): Promise<OpenAppResult> {
+    return this.#rpc<OpenAppResult>('open_app', {
+      app: opts.app,
+      url: opts.url,
+      relaunch: opts.relaunch ?? false,
+    });
+  }
+
+  override async systemAlert(action: AlertAction): Promise<BackendAlertResult> {
+    return this.#rpc<BackendAlertResult>('alert', { action });
+  }
+
+  override async closeSession(): Promise<void> {
+    // The runner outlives any single client; nothing to tear down.
+  }
+
+  /** Liveness probe used by `phone-use doctor` and the relay health check. */
+  async ping(): Promise<{ ok: boolean; ios?: string; device?: string }> {
+    return this.#rpc('get_context');
+  }
+}
+
+export const createDeviceRunnerBackend = (config?: DeviceRunnerConfig): DeviceRunnerBackend =>
+  new DeviceRunnerBackend(config);

package/src/backends/ios.ts

@@ -5,12 +5,12 @@ import { createDeviceHandle, type Device } from '../lifecycle.ts';
 import { createAgentDeviceBackend } from './agent-device.ts';
 
 // ---------------------------------------------------------------------------
-// The iOS engine (docs/19 §Lifecycle, engine-as-object): ios.launch() creates
+// The iOS engine (engine-as-object): ios.launch() creates
 // and boots a DEDICATED simulator via simctl — no more "whatever is booted" —
 // and returns a Device whose backend is pinned to that udid. ios.connect()
 // reattaches; its no-arg form is the sole survivor of the old booted-sim
 // auto-detect. Scripts never branch on locality: connect(endpoint) for cloud
-// devices is reserved API (docs/20 kill list — local-only this cycle).
+// devices is reserved API — local-only for now.
 //
 // Created sims are named `phone-use-<hex>` deliberately: if a process is
 // kill -9'd, the in-process reaper can't run, and the name prefix is how
@@ -40,7 +40,7 @@ type CommonIosOptions = {
    * open lazily and a probe requires the daemon to exist.
    */
   failFast?: boolean | undefined;
-  /** @internal test seam — DI'd process runner (docs/19 test strategy). */
+  /** @internal test seam — DI'd process runner. */
   exec?: ExecRunner | undefined;
 };
 
@@ -73,7 +73,7 @@ function simctlArgs(setPath: string | undefined, args: string[]): string[] {
 
 // Exit 149 = "operation not allowed in current state" (already booted /
 // already shut down). Code first, stderr regex as fallback — Apple rewords
-// messages; the numeric code is a Mac-verification item (docs/20 as-built).
+// messages; the numeric code is the stable signal.
 function isAlreadyInState(err: unknown): boolean {
   if (!isExecError(err)) return false;
   if (err.code === 149) return true;

package/src/config.ts

@@ -1,9 +1,8 @@
 // ---------------------------------------------------------------------------
 // Device configuration: a discriminated union, never a stringly-typed
-// capability blob (docs/19 §Backend contract, learning from Appium's leaks).
+// capability blob (learning from Appium's leaks).
 // Field names verified against agent-device 0.19.3's AgentDeviceSelectionOptions
-// and AgentDeviceClientConfig. Plain types — no zod in the SDK public API
-// (docs/20 risk 6).
+// and AgentDeviceClientConfig. Plain types — no zod in the SDK public API.
 // ---------------------------------------------------------------------------
 
 /** Fields shared by every platform's device config (session/daemon pinning). */
@@ -37,7 +36,7 @@ export type AndroidDeviceConfig = CommonDeviceConfig & {
 
 /**
  * Device configuration: a discriminated union on `platform`, never a
- * stringly-typed capability blob (docs/19 §Backend contract, learning from
- * Appium's leaks). Plain types — no zod in the SDK public API.
+ * stringly-typed capability blob (learning from Appium's leaks).
+ * Plain types — no zod in the SDK public API.
  */
 export type DeviceConfig = IosDeviceConfig | AndroidDeviceConfig;

package/src/device.ts

@@ -1,7 +1,7 @@
 // ---------------------------------------------------------------------------
 // Shared device types — the SDK's own vocabulary, structurally compatible with
-// agent-device's snapshot nodes but never importing its types (docs/20 item 2:
-// no backend type in the public API). Every optional is `| undefined` so
+// agent-device's snapshot nodes but never importing its types — no backend
+// type in the public API. Every optional is `| undefined` so
 // narrower backend types assign structurally under exactOptionalPropertyTypes.
 // ---------------------------------------------------------------------------
 
@@ -11,7 +11,7 @@ export type Rect = { x: number; y: number; width: number; height: number };
 /**
  * One accessibility-tree node as reported by a backend snapshot. The SDK's own
  * vocabulary — structurally compatible with agent-device's nodes but never
- * importing its types (docs/20 item 2: no backend type in the public API).
+ * importing its types (no backend type in the public API).
  */
 export type SnapshotNode = {
   ref?: string | undefined;

package/src/errors.ts

@@ -28,7 +28,7 @@ export type PhoneUseErrorDetails = Record<string, unknown> & {
 };
 
 /**
- * Root of the typed error tree (docs/19 §Artifacts, errors; docs/20 item 2).
+ * Root of the typed error tree.
  * Every backend method rejects only with PhoneUseError subclasses; agent-device
  * (or any transport) errors are normalized at the boundary by
  * {@link toPhoneUseError} so no backend type ever reaches the public API. Each
@@ -143,8 +143,8 @@ export function toPhoneUseError(
     const message = e.message || String(e.code ?? 'agent-device error');
     const details: PhoneUseErrorDetails = { ...(e.details ?? {}) };
     const opts = { details, cause: err };
-    // Timeout is a shape, not a code, in agent-device — heuristic on message.
-    // Flagged in docs/20: Mac verification is the arbiter for this mapping.
+    // Timeout is a shape, not a code, in agent-device — heuristic on message,
+    // verified against real agent-device errors on macOS.
     if (TIMEOUT_RE.test(message)) return new TimeoutError(message, opts);
     switch (e.code) {
       case 'DEVICE_NOT_FOUND':

package/src/exec.ts

@@ -13,7 +13,7 @@ export type ExecOptions = {
 export type ExecResult = { stdout: string; stderr: string };
 
 /**
- * The process-execution seam (docs/19: dependency-inject the spawn/exec runner
+ * The process-execution seam (dependency-inject the spawn/exec runner
  * so unit tests run without the real binaries). Runners are dumb: resolve on
  * exit 0, reject with the execFile error shape otherwise — error normalization
  * to PhoneUseError happens at the call site, once.

package/src/index.ts

@@ -1,13 +1,13 @@
 /**
  * @phone-use/sdk — the device runtime SDK: engine-as-object lifecycle
- * (ios.launch/connect → Device), Device backends, config, errors, capabilities
- * (docs/20-runtime-sdk-v1-plan.md items 2-3; action verbs land in item 4).
+ * (ios.launch/connect → Device), Device backends, config, errors, capabilities,
+ * and the action verb surface.
  *
  * The test double (FakeBackend) lives on the "@phone-use/sdk/testing" subpath,
  * deliberately not re-exported here.
  */
 /** The published package version (kept in sync with package.json by the release flow). */
-export const VERSION = '0.1.0';
+export const VERSION = '0.2.0';
 
 export {
   type Action,
@@ -31,6 +31,7 @@ export {
   registerBackend,
 } from './backend.ts';
 export { createAgentDeviceBackend } from './backends/agent-device.ts';
+export { createDeviceRunnerBackend, DeviceRunnerBackend } from './backends/device-runner.ts';
 export { type IosConnectOptions, type IosLaunchOptions, ios } from './backends/ios.ts';
 export type { AndroidDeviceConfig, CommonDeviceConfig, DeviceConfig, IosDeviceConfig } from './config.ts';
 export type {

package/src/lifecycle.ts

@@ -19,10 +19,10 @@ export type DevicePlatform = 'ios' | 'android';
 export type DeviceStatus = 'running' | 'closed';
 
 /**
- * The Device lifecycle handle (docs/20 item 3; docs/19 §Lifecycle): id, pinned
- * backend, close/dispose, idle lease + reaper — plus the action verb surface
- * (item 4) layered onto the same type. `ios.launch()` and `ios.connect()`
- * return it; the android engine (item 7b) will share `createDeviceHandle`.
+ * The Device lifecycle handle: id, pinned backend, close/dispose, idle lease +
+ * reaper — plus the action verb surface layered onto the same type.
+ * `ios.launch()` and `ios.connect()` return it; the future android engine will
+ * share `createDeviceHandle`.
  */
 export interface Device {
   /** udid (iOS) / serial (Android). */
@@ -53,7 +53,7 @@ export interface Device {
   /** `await using` support — delegates to {@link Device.close}. */
   [Symbol.asyncDispose](): Promise<void>;
 
-  // --- the action surface (docs/20 item 4): flat hot path -------------------
+  // --- the action surface: flat hot path ------------------------------------
   /** Look at the screen: elements + rendered text + portable Action[]. */
   observe(opts?: { signal?: AbortSignal | undefined }): Promise<ObserveResult>;
   /** Tap by label/id query. Auto-waits; never throws for normal outcomes. */

package/src/observe.ts

@@ -3,7 +3,7 @@ import type { Rect, SnapshotNode } from './device.ts';
 import { SessionNotFoundError } from './errors.ts';
 
 // ---------------------------------------------------------------------------
-// DeviceCore (docs/20 item 4): the one-brain observe/resolve/act core, moved
+// DeviceCore: the one-brain observe/resolve/act core, moved
 // verbatim from the harness's DeviceContext. Everything here is portable —
 // no runtime-specific globals and no image libraries — so it runs under Node. The
 // module level holds only types, pure functions, and read-only lookup tables;

package/src/secrets.ts

@@ -1,5 +1,5 @@
 // ---------------------------------------------------------------------------
-// %variable% secret substitution (docs/19 §API shape, Stagehand's pattern):
+// %variable% secret substitution (Stagehand's pattern):
 // the model/caller plans against NAMES; values are injected at the last moment
 // before backend.fill/typeText and never rendered into Actions, results,
 // observations, or traces. Redaction is best-effort belt-and-braces — after
@@ -12,7 +12,7 @@
 const MIN_SECRET_LENGTH = 4;
 
 /**
- * `%variable%` secret substitution (docs/19 §API shape, Stagehand's pattern):
+ * `%variable%` secret substitution (Stagehand's pattern):
  * the model/caller plans against NAMES; values are injected at the last moment
  * before backend.fill/typeText and never rendered into Actions, results,
  * observations, or traces. Redaction is best-effort belt-and-braces; the hard

package/src/testing.ts

@@ -18,8 +18,8 @@ export type FakeScreen = Snapshot;
 export type FakeCall = { method: string; args: unknown[] };
 
 /**
- * The device-free test double the VPS test tier stands on (docs/20 item 2
- * verification protocol). Scripts a sequence of snapshot "screens"; records
+ * The device-free test double — runs anywhere, no simulator needed.
+ * Scripts a sequence of snapshot "screens"; records
  * every call; lets tests simulate screen transitions per action. Zero deps,
  * Node-only. Public via the `@phone-use/sdk/testing` subpath so harness tests
  * and third-party backend authors share it.
@@ -197,8 +197,8 @@ export type ScriptedExecRunner = import('./exec.ts').ExecRunner & {
 };
 
 /**
- * The DI'd process runner for lifecycle tests (docs/19: dependency-inject the
- * spawn/exec runner). Takes an ordered script of steps; each call consumes the
+ * The DI'd process runner for lifecycle tests (the injectable counterpart to
+ * defaultExecRunner). Takes an ordered script of steps; each call consumes the
  * next step, optionally asserting the argv shape, and resolves/rejects in the
  * execFile-error shape defaultExecRunner produces.
  */