@goliapkg/smix 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { App, } from './App.js';
+export { literal, patternFromJson, patternToJson, regex, type Pattern, } from './Pattern.js';
+export { encodeSelectorJson, Selector, selectorFromJsonValue, selectorToJsonValue, type AnchorBox, type IndexModifiers, type Modifiers, type SelectorData, type SelectorKind, } from './Selector.js';
+export { ExpectationFailure, FAILURE_CODES, type FailureCode, } from './ExpectationFailure.js';
+export { Locator, SmixNotImplementedError, } from './Locator.js';
+export { appPath, bundleId, Smix, type AppTarget, } from './Smix.js';
+export { MockSimRuntime, type KeyName, type LaunchFreshCall, type SmixSimRuntime, type SwipeDirection, } from './SimRuntime.js';
+export { MockLabelsResolver, MockSelectorResolver, type LabelsResolver, type SelectorResolver, } from './SelectorResolver.js';
+export { HttpSimRuntime, type HttpFetch, } from './HttpRunner.js';
+export { findById, flatten, rectCenter, type A11yNode, type A11yRole, type Rect, } from './A11yNode.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,GAAG,GACJ,MAAM,UAAU,CAAA;AAEjB,OAAO,EACL,OAAO,EACP,eAAe,EACf,aAAa,EACb,KAAK,EACL,KAAK,OAAO,GACb,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,kBAAkB,EAClB,QAAQ,EACR,qBAAqB,EACrB,mBAAmB,EACnB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,YAAY,GAClB,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,KAAK,WAAW,GACjB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EACL,OAAO,EACP,uBAAuB,GACxB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,OAAO,EACP,QAAQ,EACR,IAAI,EACJ,KAAK,SAAS,GACf,MAAM,WAAW,CAAA;AAElB,OAAO,EACL,cAAc,EACd,KAAK,OAAO,EACZ,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAA;AAExB,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,gBAAgB,GACtB,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EACL,cAAc,EACd,KAAK,SAAS,GACf,MAAM,iBAAiB,CAAA;AAExB,OAAO,EACL,QAAQ,EACR,OAAO,EACP,UAAU,EACV,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,IAAI,GACV,MAAM,eAAe,CAAA"}

package/dist/index.js

@@ -0,0 +1,16 @@
+// v7.5 c1 — @smix/rn public API exports.
+//
+// Mirror Kotlin SDK + Swift SDK surface. Per iron rule §9 #13:
+// this package only ships to test harnesses (vitest / jest / Detox-like
+// runners) — never bundled into a production RN app.
+export { App, } from './App.js';
+export { literal, patternFromJson, patternToJson, regex, } from './Pattern.js';
+export { encodeSelectorJson, Selector, selectorFromJsonValue, selectorToJsonValue, } from './Selector.js';
+export { ExpectationFailure, FAILURE_CODES, } from './ExpectationFailure.js';
+export { Locator, SmixNotImplementedError, } from './Locator.js';
+export { appPath, bundleId, Smix, } from './Smix.js';
+export { MockSimRuntime, } from './SimRuntime.js';
+export { MockLabelsResolver, MockSelectorResolver, } from './SelectorResolver.js';
+export { HttpSimRuntime, } from './HttpRunner.js';
+export { findById, flatten, rectCenter, } from './A11yNode.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,+DAA+D;AAC/D,wEAAwE;AACxE,qDAAqD;AAErD,OAAO,EACL,GAAG,GACJ,MAAM,UAAU,CAAA;AAEjB,OAAO,EACL,OAAO,EACP,eAAe,EACf,aAAa,EACb,KAAK,GAEN,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,kBAAkB,EAClB,QAAQ,EACR,qBAAqB,EACrB,mBAAmB,GAMpB,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,kBAAkB,EAClB,aAAa,GAEd,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EACL,OAAO,EACP,uBAAuB,GACxB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,OAAO,EACP,QAAQ,EACR,IAAI,GAEL,MAAM,WAAW,CAAA;AAElB,OAAO,EACL,cAAc,GAKf,MAAM,iBAAiB,CAAA;AAExB,OAAO,EACL,kBAAkB,EAClB,oBAAoB,GAGrB,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EACL,cAAc,GAEf,MAAM,iBAAiB,CAAA;AAExB,OAAO,EACL,QAAQ,EACR,OAAO,EACP,UAAU,GAIX,MAAM,eAAe,CAAA"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@goliapkg/smix",
+  "version": "0.1.0",
+  "description": "Playwright-shape iOS Simulator / Android emulator UI automation SDK for React Native + Expo + Detox-compatible TypeScript test runners.",
+  "type": "module",
+  "license": "Apache-2.0 OR MIT",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "homepage": "https://github.com/goliajp/smix",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/goliajp/smix.git",
+    "directory": "npm/smix-rn"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/A11yNode.ts

@@ -0,0 +1,62 @@
+// v7.5 c1 — A11yNode + Rect mirror Rust smix-screen A11yNode +
+// Swift v7.2 + Kotlin v7.4 A11yNode. CamelCase wire keys match
+// Rust `#[serde(rename_all = "camelCase")]`.
+
+export interface Rect {
+  x: number
+  y: number
+  w: number
+  h: number
+}
+
+export function rectCenter(r: Rect): { x: number; y: number } {
+  return { x: r.x + r.w / 2, y: r.y + r.h / 2 }
+}
+
+export type A11yRole =
+  | 'button' | 'link' | 'textField' | 'secureTextField' | 'searchField'
+  | 'switch' | 'toggle' | 'checkBox' | 'radio' | 'image' | 'staticText'
+  | 'tab' | 'tabBar' | 'navigationBar' | 'cell' | 'alert' | 'dialog'
+  | 'slider' | 'progressBar' | 'picker' | 'menu' | 'menuItem'
+  | 'scrollView' | 'segmentedControl' | 'table' | 'collectionView'
+  | 'webView' | 'keyboard'
+
+export interface A11yNode {
+  rawType: string
+  role?: A11yRole | undefined
+  identifier?: string | undefined
+  label?: string | undefined
+  title?: string | undefined
+  placeholderValue?: string | undefined
+  value?: string | undefined
+  text?: string | undefined
+  bounds: Rect
+  enabled?: boolean | undefined
+  selected?: boolean | undefined
+  hasFocus?: boolean | undefined
+  visible?: boolean | undefined
+  children?: A11yNode[] | undefined
+}
+
+/**
+ * Recursively find the first node whose [identifier] matches [id].
+ */
+export function findById(node: A11yNode, id: string): A11yNode | null {
+  if (node.identifier === id) return node
+  for (const child of node.children ?? []) {
+    const hit = findById(child, id)
+    if (hit !== null) return hit
+  }
+  return null
+}
+
+/**
+ * DFS pre-order flatten — self + all descendants in a single list.
+ */
+export function flatten(node: A11yNode): A11yNode[] {
+  const out: A11yNode[] = [node]
+  for (const child of node.children ?? []) {
+    out.push(...flatten(child))
+  }
+  return out
+}

package/src/App.ts

@@ -0,0 +1,153 @@
+// v7.5 c3 — App class full wire mirrors Kotlin v7.4 c5 / Swift v7.2.
+
+import { type A11yNode, findById, flatten } from './A11yNode.js'
+import { ExpectationFailure } from './ExpectationFailure.js'
+import { Locator, SmixNotImplementedError } from './Locator.js'
+import {
+  encodeSelectorJson,
+  type Selector,
+} from './Selector.js'
+import {
+  type KeyName,
+  type SmixSimRuntime,
+  type SwipeDirection,
+} from './SimRuntime.js'
+import type { LabelsResolver, SelectorResolver } from './SelectorResolver.js'
+
+/**
+ * A handle to a running app on the simulator / emulator.
+ */
+export class App {
+  constructor(
+    public readonly bundleId: string,
+    public readonly runtime: SmixSimRuntime,
+    public readonly resolver: SelectorResolver,
+    /**
+     * v7.6 c1 — wraps Rust `resolve_selector_labels` (each match's
+     * `.label`). Used by Locator.toHaveCount + toHaveLabel. Defaults
+     * to a stub that throws — tests + production should pass a real
+     * impl (HttpSimRuntime.labelsResolver or MockLabelsResolver.resolve).
+     */
+    public readonly labelsResolver: LabelsResolver = async () => {
+      throw new Error('labelsResolver not configured; pass one to Smix.launchApp or App constructor')
+    },
+  ) {}
+
+  // ---- act methods --------------------------------------------------
+
+  async tap(selector: Selector, _opts: { timeoutMs?: number } = {}): Promise<void> {
+    const tree = await this.runtime.snapshotTree()
+    const selectorJson = encodeSelectorJson(selector)
+    const treeJson = JSON.stringify(tree)
+
+    let matches: readonly string[]
+    try {
+      matches = await this.resolver(treeJson, selectorJson)
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e)
+      throw new ExpectationFailure({
+        code: 'unknown',
+        message: `FFI resolveSelector raised: ${msg}`,
+        selectorJson,
+      })
+    }
+
+    const firstId = matches[0]
+    const node = firstId !== undefined ? findById(tree, firstId) : null
+    if (node === null) {
+      throw new ExpectationFailure({
+        code: 'notFound',
+        message: 'no candidates after spatial + index filters',
+        selectorJson,
+        visibleElements: flatten(tree).slice(0, 20),
+        suggestions: [
+          'check `accessibilityIdentifier` is set on the target view',
+          'consider relaxing to text(...) if the label is more stable than the id',
+        ],
+      })
+    }
+
+    await this.runtime.synthesizeTap(
+      node.bounds.x + node.bounds.w / 2,
+      node.bounds.y + node.bounds.h / 2,
+    )
+  }
+
+  /**
+   * Resolve [selector], tap to focus, then type [text]. Mirror
+   * Kotlin App.fill from v7.4 c3.
+   */
+  async fill(selector: Selector, text: string): Promise<void> {
+    await this.tap(selector)
+    await this.runtime.sendString(text)
+  }
+
+  async pressKey(key: KeyName): Promise<void> {
+    await this.runtime.pressKey(key)
+  }
+
+  async swipe(direction: SwipeDirection): Promise<void> {
+    await this.runtime.swipe(direction)
+  }
+
+  async screenshot(): Promise<Uint8Array> {
+    return this.runtime.screenshot()
+  }
+
+  /**
+   * Tap at a normalized coordinate (0..1) — escape hatch per §9 #3.
+   * Out-of-range values throw ExpectationFailure code=wrongState.
+   */
+  async tapAtCoord(nx: number, ny: number): Promise<void> {
+    if (nx < 0 || nx > 1 || ny < 0 || ny > 1) {
+      throw new ExpectationFailure({
+        code: 'wrongState',
+        message: `tapAtCoord arguments out of [0,1] range: nx=${nx}, ny=${ny}`,
+        suggestions: ['use normalized 0..1 — for raw points, divide by viewport size'],
+      })
+    }
+    await this.runtime.synthesizeTapAtNormalized(nx, ny)
+  }
+
+  async terminate(): Promise<void> {
+    await this.runtime.terminate(this.bundleId)
+  }
+
+  async relaunch(): Promise<void> {
+    await this.runtime.terminate(this.bundleId)
+    await this.runtime.launch(this.bundleId)
+  }
+
+  async launchFresh(opts: {
+    clearState?: boolean
+    clearKeychain?: boolean
+    appPath?: string
+  } = {}): Promise<void> {
+    await this.runtime.launchFresh({
+      bundleId: this.bundleId,
+      clearState: opts.clearState ?? false,
+      clearKeychain: opts.clearKeychain ?? false,
+      appPath: opts.appPath,
+    })
+  }
+
+  // ---- sense methods ------------------------------------------------
+
+  find(selector: Selector): Locator {
+    return new Locator(this, selector)
+  }
+
+  async tree(): Promise<A11yNode> {
+    return this.runtime.snapshotTree()
+  }
+
+  async systemPopups(): Promise<A11yNode[]> {
+    return this.runtime.systemPopups()
+  }
+
+  async openUrl(url: string): Promise<void> {
+    await this.runtime.openUrl(url)
+  }
+}
+
+export { SmixNotImplementedError }

package/src/ExpectationFailure.ts

@@ -0,0 +1,67 @@
+// v7.5 c1 — ExpectationFailure + FailureCode mirror Swift v7.2 c4 +
+// Kotlin v7.4 c1 + Rust smix-error.
+//
+// AI-readable JSON contract: toJson() emits sorted-keys, ISO-8601
+// timestamp single-line JSON matching Swift errorDescription contract
+// (per design.md §9 #11).
+
+import type { A11yNode } from './A11yNode.js'
+
+export type FailureCode =
+  | 'notFound'
+  | 'ambiguous'
+  | 'notInteractable'
+  | 'timeout'
+  | 'wrongState'
+  | 'unknown'
+
+export const FAILURE_CODES: readonly FailureCode[] = [
+  'notFound', 'ambiguous', 'notInteractable',
+  'timeout', 'wrongState', 'unknown',
+] as const
+
+/**
+ * Structured failure thrown by SDK resolver paths (App.tap, Locator
+ * assertions) when matching fails. Wire format matches Swift +
+ * Kotlin + Rust 1:1.
+ */
+export class ExpectationFailure extends Error {
+  readonly code: FailureCode
+  readonly selectorJson: string | null
+  readonly visibleElements: readonly A11yNode[]
+  readonly suggestions: readonly string[]
+  readonly timestamp: number
+
+  constructor(opts: {
+    code: FailureCode
+    message: string
+    selectorJson?: string | undefined
+    visibleElements?: readonly A11yNode[] | undefined
+    suggestions?: readonly string[] | undefined
+    timestamp?: number | undefined
+  }) {
+    super(opts.message)
+    this.name = 'ExpectationFailure'
+    this.code = opts.code
+    this.selectorJson = opts.selectorJson ?? null
+    this.visibleElements = opts.visibleElements ?? []
+    this.suggestions = opts.suggestions ?? []
+    this.timestamp = opts.timestamp ?? Date.now()
+  }
+
+  /**
+   * AI-readable JSON dump — what Claude Code sees when the test fails.
+   * Sorted keys, single line. Mirror Swift errorDescription / Kotlin
+   * errorJson() byte-shape.
+   */
+  toJson(): string {
+    return JSON.stringify({
+      code: this.code,
+      message: this.message,
+      selector: this.selectorJson,
+      suggestions: this.suggestions,
+      timestamp: this.timestamp,
+      visibleElements: this.visibleElements,
+    })
+  }
+}

package/src/HttpRunner.ts

@@ -0,0 +1,185 @@
+// v7.5 c3 — HTTP-based SmixSimRuntime + SelectorResolver implementations.
+//
+// Per R-7.5-B HTTP-runtime decision: TS SDK communicates with smix-runner
+// via fetch JSON-RPC-ish API (one POST per call). Default endpoint
+// matches existing smix-runner-client conventions; consumers override
+// via base URL constructor param.
+//
+// Wire contract (mirrors smix-runner-client v3+):
+//   POST /sim/launch         { bundleId }                                  → 200
+//   POST /sim/terminate      { bundleId }                                  → 200
+//   POST /sim/launch-fresh   { bundleId, clearState, clearKeychain, appPath? } → 200
+//   POST /sim/launch-from-path { appPath }                                 → 200
+//   POST /sim/screenshot     {}                                            → 200 { png: base64 }
+//   POST /sim/system-popups  {}                                            → 200 { nodes: A11yNode[] }
+//   POST /sim/open-url       { url }                                       → 200
+//   POST /a11y/snapshot      {}                                            → 200 { tree: A11yNode }
+//   POST /input/tap          { x, y }                                      → 200
+//   POST /input/tap-normalized { nx, ny }                                  → 200
+//   POST /input/swipe        { direction }                                 → 200
+//   POST /input/send-string  { text }                                      → 200
+//   POST /input/press-key    { key }                                       → 200
+//   POST /select/resolve     { treeJson, selectorJson }                    → 200 { ids: string[] }
+//
+// v7.7 c1 contract additions (server impl deferred):
+//   POST /select/resolve-count   { treeJson, selectorJson }                → 200 { count: u32 }
+//   POST /select/resolve-labels  { treeJson, selectorJson }                → 200 { labels: string[] }
+//
+// The exact endpoint shapes are negotiated with smix-runner-server in
+// follow-up Swift work; for v7.5-v7.7 c1 we wire the TS-side fetch +
+// decode and a MockHttpRunnerClient stub that lets vitest exercise the
+// runtime without booting a real server.
+
+import { type A11yNode } from './A11yNode.js'
+import type {
+  KeyName,
+  LaunchFreshCall,
+  SmixSimRuntime,
+  SwipeDirection,
+} from './SimRuntime.js'
+import type { LabelsResolver, SelectorResolver } from './SelectorResolver.js'
+
+/**
+ * Minimal HTTP client surface — overridable for testing. fetch-compatible
+ * signature so consumers can pass globalThis.fetch directly.
+ */
+export type HttpFetch = (
+  input: string,
+  init: { method: 'POST'; headers: Record<string, string>; body: string },
+) => Promise<{ ok: boolean; status: number; json(): Promise<unknown>; text(): Promise<string> }>
+
+/**
+ * SmixSimRuntime + SelectorResolver wrapper around the smix-runner HTTP
+ * server. Used in production RN/Expo test targets via fetch.
+ */
+export class HttpSimRuntime implements SmixSimRuntime {
+  readonly resolver: SelectorResolver
+  /**
+   * v7.7 c1 — labels resolver wrapping Rust `resolve_selector_labels`
+   * via smix-runner-server `/select/resolve-labels` endpoint. Used by
+   * `Locator.toHaveCount` (count = labels.length) + Locator.toHaveLabel.
+   * Pass directly to App constructor or Smix.launchApp.
+   */
+  readonly labelsResolver: LabelsResolver
+
+  constructor(
+    public readonly baseUrl: string,
+    public readonly fetchImpl: HttpFetch = globalThis.fetch as unknown as HttpFetch,
+  ) {
+    this.resolver = async (treeJson, selectorJson) => {
+      const r = await this.post('/select/resolve', { treeJson, selectorJson })
+      return (r as { ids: readonly string[] }).ids
+    }
+    this.labelsResolver = async (treeJson, selectorJson) => {
+      const r = await this.post('/select/resolve-labels', { treeJson, selectorJson })
+      return (r as { labels: readonly string[] }).labels
+    }
+  }
+
+  /**
+   * v7.7 c1 — direct match-count via dedicated FFI fn (avoid allocating
+   * the full ids list when callers only need count). Mirrors Rust
+   * `resolve_selector_count`. Locator.toHaveCount can prefer this over
+   * `labelsResolver` if it needs only count, not the labels themselves.
+   */
+  async resolveCount(treeJson: string, selectorJson: string): Promise<number> {
+    const r = await this.post('/select/resolve-count', { treeJson, selectorJson })
+    return (r as { count: number }).count
+  }
+
+  async launch(bundleId: string): Promise<void> {
+    await this.post('/sim/launch', { bundleId })
+  }
+
+  async terminate(bundleId: string): Promise<void> {
+    await this.post('/sim/terminate', { bundleId })
+  }
+
+  async snapshotTree(): Promise<A11yNode> {
+    const r = await this.post('/a11y/snapshot', {})
+    return (r as { tree: A11yNode }).tree
+  }
+
+  async synthesizeTap(x: number, y: number): Promise<void> {
+    await this.post('/input/tap', { x, y })
+  }
+
+  async sendString(text: string): Promise<void> {
+    await this.post('/input/send-string', { text })
+  }
+
+  async pressKey(key: KeyName): Promise<void> {
+    await this.post('/input/press-key', { key })
+  }
+
+  async swipe(direction: SwipeDirection): Promise<void> {
+    await this.post('/input/swipe', { direction })
+  }
+
+  async screenshot(): Promise<Uint8Array> {
+    const r = await this.post('/sim/screenshot', {}) as { png: string }
+    return base64ToBytes(r.png)
+  }
+
+  async systemPopups(): Promise<A11yNode[]> {
+    const r = await this.post('/sim/system-popups', {}) as { nodes: A11yNode[] }
+    return r.nodes
+  }
+
+  async openUrl(url: string): Promise<void> {
+    await this.post('/sim/open-url', { url })
+  }
+
+  async launchFresh(opts: {
+    bundleId: string
+    clearState: boolean
+    clearKeychain: boolean
+    appPath?: string | undefined
+  }): Promise<void> {
+    const payload: LaunchFreshCall = {
+      bundleId: opts.bundleId,
+      clearState: opts.clearState,
+      clearKeychain: opts.clearKeychain,
+      appPath: opts.appPath,
+    }
+    await this.post('/sim/launch-fresh', payload)
+  }
+
+  async launchFromPath(appPath: string): Promise<void> {
+    await this.post('/sim/launch-from-path', { appPath })
+  }
+
+  async synthesizeTapAtNormalized(nx: number, ny: number): Promise<void> {
+    await this.post('/input/tap-normalized', { nx, ny })
+  }
+
+  private async post(path: string, body: unknown): Promise<unknown> {
+    const url = `${this.baseUrl}${path}`
+    const resp = await this.fetchImpl(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    })
+    if (!resp.ok) {
+      const text = await resp.text()
+      throw new Error(`smix-runner ${path} → HTTP ${resp.status}: ${text}`)
+    }
+    // 200 with no body returns undefined; tolerate empty response
+    try {
+      return await resp.json()
+    } catch {
+      return undefined
+    }
+  }
+}
+
+function base64ToBytes(b64: string): Uint8Array {
+  if (typeof globalThis.atob === 'function') {
+    const bin = globalThis.atob(b64)
+    const out = new Uint8Array(bin.length)
+    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
+    return out
+  }
+  // Node fallback
+  return Uint8Array.from(Buffer.from(b64, 'base64'))
+}