peachsim 0.1.527

package/src/bridge-contract.ts

@@ -0,0 +1,558 @@
+// the wire contract for the sootsim ws bridge. the engine implements it in
+// sootsim-engine/src/mcp/ws-bridge.ts; the rnxsim cli client, the SimClient
+// sdk, and the flow runner speak it. it is the single owner of these shapes,
+// and neither side redeclares them.
+//
+// it lives in rnxsim rather than the engine because rnxsim is published and
+// sootsim-engine is `private: true`. the engine already depends on rnxsim
+// (see its `rnxsim` dependency and its `rnxsim/bridge-constants` import), so
+// this is the direction that ships.
+
+import type {
+  SootSimAgentActionDetail,
+  SootSimCaptureFilter,
+  SootSimExternalAppLifecycleOptions,
+  SootSimStorageResetStrategy,
+} from '@rnx/globals'
+
+export type BridgeCommandType =
+  | 'evaluate'
+  | 'call'
+  | 'screenshot'
+  | 'capture'
+  | 'captureRegions'
+  | 'settle'
+  | 'setAppearance'
+  | 'openUrl'
+  | 'memory'
+  | 'tap'
+  | 'longPress'
+  | 'keyboard'
+  | 'tree'
+  | 'focus'
+  | 'close'
+  | 'flowStatus'
+  | 'perform'
+  | 'waitFor'
+  | 'state'
+  | 'query'
+  | 'resolve'
+  | 'reset'
+  | 'camera'
+  | 'diagnostics'
+  | 'storageSnapshot'
+
+export interface WsCommand {
+  id: string | number
+  type: BridgeCommandType
+  // local daemon routing; cloud transport strips it before execution.
+  simId?: string
+  // flowStatus — live flow-runner progress payload (see flow-run-store)
+  status?: Record<string, unknown>
+  code?: string
+  path?: string
+  args?: unknown[]
+  x?: number
+  y?: number
+  durationMs?: number
+  maxFrames?: number
+  target?: SootSimAgentActionDetail['target']
+  action?: string
+  text?: string
+  appearance?: 'light' | 'dark'
+  url?: string
+  includeVisual?: boolean
+  includeFonts?: boolean
+  includeRasterAtlas?: boolean
+  regions?: import('./capture-contract').RnxCaptureRegionRequest[]
+  depth?: number
+  // screenshot — which canvas layers to composite. omit for full (today's
+  // default: everything including iOS chrome). 'tenant' excludes the shell
+  // overlay for a clean app capture.
+  layers?: 'full' | 'tenant' | 'shell'
+  // screenshot — engine-side layer isolation (hide subtrees / solo one
+  // subtree on transparency). see SootSimCaptureOptions.captureFilter.
+  captureFilter?: SootSimCaptureFilter
+  // screenshot — optional crop rect in logical sootsim coords. the capture
+  // module scales x/y/w/h by device pixel ratio before cropping.
+  crop?: { x: number; y: number; w: number; h: number }
+  // perform — ordered batch executed inside the page, no round trips
+  steps?: PerformStep[]
+  performOptions?: PerformOptions
+  // waitFor — one engine-side polling loop and one transport round trip
+  waitForOptions?: SemanticWaitOptions
+  // state — compound screenshot + tree + route + errors
+  stateOptions?: SimStateOptions
+  // query / resolve — structured visible-tree reads and selector geometry
+  query?: SimSemanticQuery
+  selector?: SimSemanticResolveSelector
+  // reset — two-tier app state wipe
+  resetOptions?: ResetOptions
+  // camera — fixture injection into the host camera pipeline
+  camera?: CameraCommand
+  // diagnostics — read-only engine debug state: channel recording, the sheet /
+  // portal / boundary finders, and the recent event ring.
+  diagnostics?: DiagnosticsOptions
+  // storageSnapshot — the running app's own storage and route, as
+  // `StorageSnapshot` from the engine's preview/storage-snapshot module. the
+  // default result is share-safe; `includeCredentials` carries the signed-in
+  // session and belongs only to a send to the owner's own box.
+  storageSnapshotOptions?: { includeCredentials?: boolean }
+}
+
+// ---------------------------------------------------------------------------
+// perform — batched input
+// ---------------------------------------------------------------------------
+
+// every step maps onto a primitive that already exists on
+// SootSim.bridges.interact / .keyboard / .test. the batch runs entirely inside
+// the page so gesture timing is real wall-clock timing, not ws round-trips.
+//
+// deliberately absent: text-based tap resolution. matching by visible text is
+// fuzzy, needs ranking and failure diagnostics, and lives once in the cli's
+// tapByText. the sdk resolves text to coordinates before it builds a batch.
+// testID lookup is exact, so tapId resolves in-engine.
+export type PerformStep =
+  // raw pointer steps — full control over gesture physics
+  | { type: 'touchDown'; x: number; y: number; pointerId?: number }
+  | { type: 'touchMove'; x: number; y: number; pointerId?: number }
+  | { type: 'touchUp'; x: number; y: number; pointerId?: number }
+  | { type: 'touchCancel'; pointerId?: number }
+  // semantic steps
+  | { type: 'tap'; x: number; y: number; target?: SootSimAgentActionDetail['target'] }
+  | { type: 'tapId'; id: string }
+  | { type: 'doubleTap'; x: number; y: number; gapMs?: number }
+  | {
+      type: 'longPress'
+      x: number
+      y: number
+      durationMs?: number
+      target?: SootSimAgentActionDetail['target']
+    }
+  | {
+      type: 'drag'
+      fromX: number
+      fromY: number
+      toX: number
+      toY: number
+      steps?: number
+      stepMs?: number
+    }
+  | {
+      type: 'pinch'
+      fromX1: number
+      fromY1: number
+      fromX2: number
+      fromY2: number
+      toX1: number
+      toY1: number
+      toX2: number
+      toY2: number
+      steps?: number
+      stepMs?: number
+    }
+  | { type: 'scroll'; id: string; x?: number; y?: number; animated?: boolean }
+  | { type: 'type'; text: string }
+  | { type: 'key'; key: string }
+  | { type: 'dismissKeyboard' }
+  | { type: 'wait'; ms: number }
+  | {
+      type: 'waitFor'
+      testID?: string
+      id?: string
+      condition?: 'present' | 'mounted' | 'absent'
+      timeoutMs?: number
+    }
+  // limrun parity steps. each maps onto an engine primitive and reports
+  // per step; the refused ones below parse but never run.
+  | { type: 'setElementValue'; id: string; text: string; submit?: boolean }
+  | { type: 'toggleKeyboard' }
+  | { type: 'openUrl'; url: string }
+  | { type: 'keyDown'; key: string }
+  | { type: 'keyUp'; key: string }
+  | { type: 'setOrientation'; orientation: 'portrait' | 'landscape' }
+  | { type: 'deviceInfo' }
+  // refused with a named reason, never emulated: no hardware-button model,
+  // no storekit simulation, no stepper primitive, and key/orientation state
+  // the engine does not hold.
+  | { type: 'buttonDown'; button?: string }
+  | { type: 'buttonUp'; button?: string }
+  | { type: 'incrementElement'; id: string }
+  | { type: 'decrementElement'; id: string }
+  | { type: 'discoverStoreKitConfig' }
+  | { type: 'clearStoreKitConfig' }
+
+export interface PerformOptions {
+  // stop the batch at the first failing step. default true — a gesture whose
+  // touchDown missed should not keep dragging.
+  stopOnError?: boolean
+  // ceiling on batch PROGRESS, checked between steps: once it passes, the
+  // batch starts no further steps and reports which one it reached. a step
+  // already running is always awaited to completion, never abandoned, because
+  // a gesture that keeps dispatching pointer events after the caller has been
+  // told the batch failed is worse than a late reply. every step is bounded on
+  // its own (drag and pinch by steps * stepMs, wait by ms, waitFor by its own
+  // timeout), and a wedged worker is caught by the CLI client's per-command
+  // timeout one layer up. default 30000.
+  timeoutMs?: number
+}
+
+// observed device identity for the `deviceInfo` step: the live device spec
+// in both runtimes, so every field is measured, never a default.
+export interface PerformDeviceInfo {
+  platform: string
+  model?: string
+  width: number
+  height: number
+  scale: number
+}
+
+// steps that parse but never run. one owner for the refusal vocabulary so
+// the browser page and the cpu runtime refuse with the same named reason and
+// neither plane emulates what the engine cannot do.
+export const REFUSED_PERFORM_STEP_TYPES = [
+  'keyDown',
+  'keyUp',
+  'setOrientation',
+  'buttonDown',
+  'buttonUp',
+  'incrementElement',
+  'decrementElement',
+  'discoverStoreKitConfig',
+  'clearStoreKitConfig',
+] as const
+
+export type RefusedPerformStepType = (typeof REFUSED_PERFORM_STEP_TYPES)[number]
+
+export function refusedPerformStepReason(type: RefusedPerformStepType): string {
+  switch (type) {
+    case 'keyDown':
+    case 'keyUp':
+      return `${type} is not supported: keys dispatch atomically; use the key step`
+    case 'setOrientation':
+      return 'setOrientation is not supported: the simulator viewport is fixed at boot'
+    case 'buttonDown':
+    case 'buttonUp':
+      return `${type} is not supported: the simulator has no hardware buttons`
+    case 'incrementElement':
+    case 'decrementElement':
+      return `${type} is not supported: steppers have no engine primitive; drive them with tapId`
+    case 'discoverStoreKitConfig':
+    case 'clearStoreKitConfig':
+      return `${type} is not supported: storekit has no simulator model`
+  }
+}
+
+// returns the refusal for a refused step, null when the step is runnable.
+// every variant is listed so adding a step forces its classification here;
+// the executors mirror the refused cases in their own switches.
+export function performStepRefusal(type: PerformStep['type']): string | null {
+  switch (type) {
+    case 'keyDown':
+    case 'keyUp':
+    case 'setOrientation':
+    case 'buttonDown':
+    case 'buttonUp':
+    case 'incrementElement':
+    case 'decrementElement':
+    case 'discoverStoreKitConfig':
+    case 'clearStoreKitConfig':
+      return refusedPerformStepReason(type)
+    case 'touchDown':
+    case 'touchMove':
+    case 'touchUp':
+    case 'touchCancel':
+    case 'tap':
+    case 'tapId':
+    case 'doubleTap':
+    case 'longPress':
+    case 'drag':
+    case 'pinch':
+    case 'scroll':
+    case 'type':
+    case 'key':
+    case 'dismissKeyboard':
+    case 'setElementValue':
+    case 'toggleKeyboard':
+    case 'openUrl':
+    case 'deviceInfo':
+    case 'wait':
+    case 'waitFor':
+      return null
+  }
+}
+
+export interface PerformStepResult {
+  index: number
+  type: PerformStep['type']
+  ok: boolean
+  // step-specific payload: tap hit info, waitFor match, resolved coordinates
+  value?: unknown
+  error?: string
+  // wall-clock ms this step took inside the page
+  durationMs: number
+}
+
+export interface PerformResult {
+  ok: boolean
+  steps: PerformStepResult[]
+  // number of steps that ran. less than steps.length when the batch aborted.
+  completed: number
+  durationMs: number
+  error?: string
+}
+
+// ---------------------------------------------------------------------------
+// waitFor — engine-side semantic condition polling
+// ---------------------------------------------------------------------------
+
+// `present` is what a person can see: the node must survive the occlusion pass,
+// so a button behind a sheet does not count. `mounted` asks only whether the
+// node exists and is laid out, which is the right question for a marker the app
+// renders as proof of something (a build id, a launch phase) rather than as
+// something to look at — those are 1x1 and painted under the whole app, so they
+// are permanently occluded and `present` can never match one.
+export type SemanticWaitCondition =
+  | { type: 'ready' }
+  | { type: 'present'; selector: SimSemanticResolveSelector }
+  | { type: 'mounted'; selector: SimSemanticResolveSelector }
+  | { type: 'absent'; selector: SimSemanticResolveSelector }
+
+export interface SemanticWaitOptions {
+  condition: SemanticWaitCondition
+  timeoutMs?: number
+}
+
+export interface SemanticReadyProbe {
+  flag: unknown
+  at: number
+  nodes: number
+  targets: number
+  liveFrameActive: boolean
+  liveFrameChannels: number
+  liveFramePublishes: number
+  errors: number
+  loadingText: string
+  externalReady: boolean | null
+  externalStatus: string
+  externalError: string
+  suppressedEntryError: string
+}
+
+// react native's own Pressable/Touchable delayLongPress default, and the
+// ceiling any transport accepts for a press-and-hold. a driver that holds
+// longer than this is describing a drag, not a long press.
+export const SIM_LONG_PRESS_DEFAULT_MS = 500
+export const SIM_LONG_PRESS_MAX_MS = 5_000
+
+export const SEMANTIC_READY_CONTENT_NODE_FLOOR = 100
+export const SEMANTIC_READY_NODE_STABLE_MS = 750
+export const SEMANTIC_READY_POLL_MS = 150
+
+export const PUBLIC_NO_NETWORK_MARKER = 'public RNX Cloud simulators have no network'
+export const HEADLESS_TENANT_FETCH_HUNG_MARKER = 'headless tenant fetch hung'
+
+export function readyProbeHasContent(
+  probe: Pick<SemanticReadyProbe, 'nodes' | 'targets'> &
+    Partial<Pick<SemanticReadyProbe, 'liveFrameActive'>>,
+): boolean {
+  return (
+    probe.liveFrameActive ||
+    probe.targets > 0 ||
+    probe.nodes >= SEMANTIC_READY_CONTENT_NODE_FLOOR
+  )
+}
+
+export function readyProbeHasTargetContent(
+  probe: Pick<SemanticReadyProbe, 'targets'> &
+    Partial<Pick<SemanticReadyProbe, 'liveFrameActive'>>,
+): boolean {
+  return probe.liveFrameActive || probe.targets > 0
+}
+
+export interface SemanticWaitResult {
+  matched: boolean
+  elapsedMs: number
+  polls: number
+  probe?: SemanticReadyProbe
+  node?: SimSemanticNode
+  error?: string
+}
+
+// ---------------------------------------------------------------------------
+// state — one round-trip situational awareness
+// ---------------------------------------------------------------------------
+
+export interface DiagnosticsOptions {
+  // debug channels to record from this point on. omitted leaves recording as
+  // it is; an empty list stops recording.
+  channels?: readonly string[]
+  find?: 'sheets' | 'portals' | 'boundaries'
+  recentChannel?: string
+  recentLimit?: number
+}
+
+export interface DiagnosticsResult {
+  channels: string[]
+  runtime: unknown
+  found: unknown[] | null
+  events: unknown[]
+}
+
+export interface SimStateOptions {
+  // omit a section an agent does not need this turn
+  screenshot?: boolean
+  tree?: boolean
+  route?: boolean
+  errors?: boolean
+  // include the bounded guest console tail. omitted by the ordinary state
+  // command so one-shot state remains compact; `rnx logs` requests it.
+  logs?: boolean
+  // tree depth, matching the standalone `tree` command. default 5.
+  depth?: number
+  layers?: WsCommand['layers']
+  // cap on recentErrors entries. default 20.
+  errorLimit?: number
+  // cap on recentLogs entries. default and maximum 100.
+  logLimit?: number
+}
+
+export interface SimStateLogEntry {
+  level: string
+  text: string
+  at?: number
+}
+
+export interface SimStateResult {
+  // png data uri, same encoding the `screenshot` command returns
+  screenshot?: unknown
+  tree?: SimSemanticNode[]
+  route?: { url?: string; screen?: string | null; stack?: string[] } | null
+  recentErrors?: SimStateLogEntry[]
+  recentLogs?: SimStateLogEntry[]
+  keyboard?: { visible: boolean; mode?: string | null }
+  capturedAt: number
+}
+
+// ---------------------------------------------------------------------------
+// semantic tree — pruned visible structure shared by local and cloud runtimes
+// ---------------------------------------------------------------------------
+
+export interface SimSemanticGeometry {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export interface SimSemanticNode {
+  nodeId: number
+  type: string
+  testID?: string
+  text?: string
+  role?: string
+  label?: string
+  pressable?: true
+  geometry: SimSemanticGeometry
+  children?: SimSemanticNode[]
+}
+
+export type SimSemanticSelector =
+  | { testID: string }
+  | { text: string }
+  | { role: string }
+  | { type: string }
+  | { pressable: true }
+  | { visible: true }
+
+export type SimSemanticQuery =
+  | { kind: 'tree'; depth?: number }
+  | { kind: 'find'; selector: SimSemanticSelector }
+  | { kind: 'count' }
+
+export interface SimSemanticQueryResult {
+  nodes: SimSemanticNode[]
+  total: number
+}
+
+export type SimSemanticResolveSelector = { testID: string } | { text: string }
+
+export interface SimSemanticResolveResult {
+  match: SimSemanticNode
+  target: SimSemanticNode
+  point: { x: number; y: number }
+}
+
+// ---------------------------------------------------------------------------
+// reset — two-tier app state wipe
+// ---------------------------------------------------------------------------
+
+// 'data' clears what a user could clear from inside the app: async storage,
+// MMKV, sqlite, cache dirs. 'full' also clears what only a fresh install would:
+// simulated keychain, user defaults, granted permissions.
+//
+// reset replaces the tenant worker before clearing storage, so background app
+// work cannot refill a store between its clear and verification.
+export type ResetStrategy = SootSimStorageResetStrategy
+
+export interface ResetOptions extends Pick<
+  SootSimExternalAppLifecycleOptions,
+  'initialUrl' | 'launchArguments'
+> {
+  strategy?: ResetStrategy
+  // relaunch the app after wiping. default true.
+  relaunch?: boolean
+  // boot the wiped simulator on a live copy of another simulator's storage
+  // instead of empty stores: the cheap clean-but-not-cold seam. the id names
+  // a simulator on the same account; runtimes that cannot reach another
+  // simulator's storage refuse it by name rather than wiping without forking.
+  from?: string
+}
+
+export interface ResetResult {
+  ok: boolean
+  strategy: ResetStrategy
+  // stores verified empty after the wipe, read back rather than assumed
+  cleared: string[]
+  // stores this strategy deliberately did NOT clear, each with the reason.
+  // a named gap is not a failure, so this leaves `ok` true and stays out of
+  // `error`; a caller that cares can branch on it.
+  skipped?: Array<{ store: string; reason: string }>
+  relaunched: boolean
+  // true when reset had to restart the tenant worker instead of doing an
+  // in-worker cold remount. a restart is correct but slow, so a caller running
+  // reset between tests needs to see which path it got.
+  workerReloaded?: boolean
+  error?: string
+}
+
+// ---------------------------------------------------------------------------
+// camera — fixture injection
+// ---------------------------------------------------------------------------
+
+// the host thread owns the camera pipeline (hidden <video> -> <canvas> ->
+// ImageBitmap -> worker). injection replaces the source of that <video>, so
+// every downstream consumer — expo-camera's live frame texture and the
+// BarcodeDetector scan loop — sees the fixture with no seam of its own.
+export interface CameraPlayOptions {
+  // url the host can fetch. the cli serves the local file from the daemon.
+  url: string
+  loop?: boolean
+  // playback rate, for making a slow fixture scan faster in ci
+  rate?: number
+}
+
+export type CameraCommand =
+  | ({ action: 'play' } & CameraPlayOptions)
+  | { action: 'stop' }
+  | { action: 'status' }
+
+export interface CameraResult {
+  ok: boolean
+  // 'live' = real getUserMedia, 'fixture' = injected video, 'idle' = no session
+  source: 'live' | 'fixture' | 'idle'
+  url?: string
+  loop?: boolean
+  rate?: number
+  error?: string
+}

package/src/browser-cache.ts

@@ -0,0 +1,16 @@
+export const DISPOSABLE_BROWSER_CACHE_DIR_NAMES = [
+  'Cache',
+  'Code Cache',
+  'DawnCache',
+  'DawnGraphiteCache',
+  'DawnWebGPUCache',
+  'GPUCache',
+  'GrShaderCache',
+  'ShaderCache',
+] as const
+
+const disposableBrowserCacheDirs = new Set<string>(DISPOSABLE_BROWSER_CACHE_DIR_NAMES)
+
+export function isDisposableBrowserCacheDir(name: string): boolean {
+  return disposableBrowserCacheDirs.has(name)
+}