rnxsim 0.1.381 → 0.1.382

package/dist-lib/vite.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.381 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.382 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 let __sootsim_import_meta_url = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; } catch {}
 "use strict";
 var __create = Object.create;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rnxsim",
-  "version": "0.1.381",
+  "version": "0.1.382",
   "description": "Vite and Metro plugins, testing drivers, and SDK exports for rnx.",
   "author": "Tamagui LLC",
   "license": "SEE LICENSE IN LICENSE",
@@ -41,6 +41,7 @@
     "./metro-production-bundle": {
       "types": "./src/metro-production-bundle.ts",
       "source": "./src/metro-production-bundle.ts",
+      "bun": "./src/metro-production-bundle.ts",
       "import": "./dist-lib/metro-production-bundle.mjs",
       "default": "./dist-lib/metro-production-bundle.cjs"
     },
@@ -115,6 +116,20 @@
       "import": "./dist-lib/bridge-contract.mjs",
       "default": "./dist-lib/bridge-contract.cjs"
     },
+    "./cloud-contract": {
+      "types": "./src/cloud-contract.ts",
+      "source": "./src/cloud-contract.ts",
+      "bun": "./src/cloud-contract.ts",
+      "import": "./dist-lib/cloud-contract.mjs",
+      "default": "./dist-lib/cloud-contract.cjs"
+    },
+    "./capture-contract": {
+      "types": "./src/capture-contract.ts",
+      "source": "./src/capture-contract.ts",
+      "bun": "./src/capture-contract.ts",
+      "import": "./dist-lib/capture-contract.mjs",
+      "default": "./dist-lib/capture-contract.cjs"
+    },
     "./bridge-constants": {
       "source": "./src/bridge-constants.ts",
       "default": "./dist-lib/bridge-constants.cjs"
@@ -214,12 +229,13 @@
     }
   },
   "devDependencies": {
-    "@contrast/harness": "workspace:*",
     "@contrast/runtime-delivery": "workspace:*",
     "@sootsim/compat": "workspace:*",
-    "@sootsim/globals": "workspace:*",
-    "@sootsim/skills": "workspace:*",
+    "@rnx/box": "workspace:*",
+    "@rnx/globals": "workspace:*",
+    "@rnx/skills": "workspace:*",
     "@types/ws": "^8.5.13",
+    "rnx-cloud-box": "workspace:*",
     "sootsim-engine": "workspace:*",
     "typescript": "^5.7.0",
     "vite": "^8.2.2",

package/scripts/dev-server-scanner.ts

@@ -34,7 +34,7 @@ import {
   readAppSettingsBundle,
 } from '../src/settings-bundle.ts'
 import { loadOptionalDemoApps, optionalDemoAppsSync } from './optional-demo-registry.ts'
-import type { AppSettingsSpecifier } from '@sootsim/globals'
+import type { AppSettingsSpecifier } from '@rnx/globals'
 
 // how long past a command's own budget we wait before deciding its exit event is
 // never coming. generous, because this only fires when the child is already
@@ -787,7 +787,7 @@ export async function probePort(
   buildIconProxyUrl?: (externalUrl: string) => string,
   listeningProcess?: ListeningProcess,
 ): Promise<DiscoveredServer | null> {
-  // callers such as `sootsim open <port>` probe one port directly instead of
+  // callers such as `rnx open <port>` probe one port directly instead of
   // going through scanDevServers. wait for the optional in-repo registry here
   // too, or a cold CLI process can build the known app's bundle url before its
   // runtime config is available.
@@ -1074,7 +1074,7 @@ export function __shouldReuseScannerCacheEntry(
   return true
 }
 
-// exported for tests / `sootsim debug` — forces the next scan to re-probe.
+// exported for tests / `rnx debug` — forces the next scan to re-probe.
 export function __resetScannerCache() {
   portCache.clear()
   knownNonPatched.clear()

package/skills/contrast/SKILL.md

@@ -42,7 +42,7 @@ automation, inspecting the render tree, and managing sims.
 | `rnx debug` | drive __sootsimDebug: channels, snapshots, and inspectors |
 | `rnx what-happened` | show recent semantic events: toasts, keyboards, screens, alerts, fetches, errors |
 | `rnx timeline` | control the semantic event timeline (enable opt-in kinds, clear, dump) |
-| `rnx box` | start a local box and enter its shell |
+| `rnx box` | start a local Box or create a cloud Box |
 | `rnx ios` | start an iOS simulator |
 | `rnx android` | start an Android simulator |
 | `rnx open` | load a target into the current sim or open a new one |

package/skills/rnx-perf/SKILL.md

@@ -24,7 +24,7 @@ indict, remeasure — and every wasted week came from skipping a step.
    draw call, paint boundary and raster-tier decision is in the compositor's
    render profile, not the shell's.** `perf shell stop` prints both, labelled
    by worker — read the compositor block for anything inside an app. for
-   months it printed only the shell's, and a uniswap token-list fling
+   months it printed only the shell's, and a dense token-list fling
    therefore reported `raster tier: 0 promotions / 0 blits` while the
    compositor was blitting ~14 rows a frame; the giveaway was `node visits: 7`
    next to `app:one 1014 paints`. if a render-profile block describes a
@@ -32,26 +32,25 @@ indict, remeasure — and every wasted week came from skipping a step.
    are reading the wrong worker.
    browser matters just as much: playwright's bundled headless chromium has
    NO GPU — CanvasKit falls back to software rendering and every number lies
-   high. launch GPU-backed Chrome via `launchReapedChrome` from
-   `scripts/lib/reap-browser`, never a bare `chromium.launch()`. never
-   `channel: 'chrome'` — that is the user's own browser, and automation
-   launching it hijacks their Dock events.
+   high. launch a dedicated GPU-backed Chrome executable with a disposable
+   profile and an owning process supervisor that terminates its exact process
+   tree. never automate the user's own browser profile.
 2. **machinery silently not engaging is the default failure mode.** the
    raster tier compiled, gated, and did *nothing* for months — zero
    promotions on its textbook case — until per-gate rejection counters
    existed. the frame-demand gate was blind to commit storms. the vsync
    pump flapped 100 msgs/s at rest. never assume a tier works because it's
    wired; read its counter during the exact workload.
-3. **check free memory and sampled CPU before blaming code.** an OOM or busy
-   machine mimics every perf and infra failure. read `vm_stat`, then take at
-   least two `top -l 2` samples and use the busiest sample for admission.
-   attribute browser processes with `ps -eo pid,ppid,args` before treating
-   one as abandoned or stopping an exact pid. load average is not an
-   admission signal on macOS.
-4. **never trade animation fidelity for CPU.** the home clock sweeps
-   sub-second like real iOS; discrete ticks have been proposed and rejected
-   repeatedly. attack per-frame cost (layers, caching, damage), never
-   cadence or fidelity.
+3. **check reclaimable memory and sampled CPU before blaming code.** an OOM or
+   busy machine mimics every perf and infra failure. on macOS, read
+   `memory_pressure -Q` and take multiple `iostat -c 3` CPU samples; on Linux,
+   read `MemAvailable` from `/proc/meminfo` and sample CPU idle over time. keep
+   the busiest sample. raw macOS `freemem()` and load average are not admission
+   signals. attribute browser processes with `ps -eo pid,ppid,args` before
+   treating one as abandoned or stopping an exact pid.
+4. **never trade animation fidelity for CPU.** perpetual sub-frame animation
+   must keep its authored cadence. attack per-frame cost (layers, caching,
+   damage), never cadence or fidelity.
 
 ## measuring
 
@@ -63,14 +62,12 @@ paths add work to the simulator or browser and can change the cadence being
 measured. Record the visible window with the operating system's native screen
 capture instead.
 
-On macOS, use the window-object recorder in `~/screen` so the simulator does
-not copy or encode its own frames:
-
-```sh
-bun ~/screen/src/cli.ts list-windows --owner "Google Chrome for Testing" --json
-bun ~/screen/src/cli.ts run --window-id <id> --duration <seconds> \
-  --out <artifact.mov> -- <operating-system input command>
-```
+Use an operating-system-owned window recorder. Target the exact browser window
+rather than the display when the platform supports it, start recording before
+normal user input, preserve the movie, and record the operating system and
+recorder version. Confirm that the recorder process, not the browser or
+simulator, owns capture and encoding. If native window capture is unavailable,
+report the proof as blocked instead of substituting an in-page capture path.
 
 The visual run contains only normal user input. Do not query the performance,
 debug, or test bridge while it records. Treat that video as visual evidence of
@@ -82,15 +79,10 @@ Open the sim with `?debug=framestamp` to make that video machine-readable.
 Every surface paint then draws its `Date.now()` low 20 bits as a 23-cell
 barcode — `home` and `app:*` at 45% of the surface height, `shell-overlay` on
 its own row at 55% so overlay paints (keyboard, native UI) are attributable
-separately — and the decoder reports, per presented frame, which paint it
-shows and how late that paint presented:
-
-```sh
-# sim opened with ?debug=framestamp
-bun ~/screen/src/cli.ts run --window-id <id> --duration <seconds> \
-  --out <artifact.mov> -- <operating-system input command>
-bun scripts/debug/decode-framestamp.ts <artifact.mov>
-```
+separately. Decode the documented 23-cell barcode with a compatible framestamp
+decoder to report, per presented frame, which paint it shows and how late that
+paint presented. If no decoder is available, keep the recording as qualitative
+evidence and make no numeric presentation-latency claim from it.
 
 This is the only way to separate a frame the compositor never produced from one
 it produced and the browser never presented.
@@ -153,13 +145,13 @@ the report and how to read it:
   workload.
   **before widening any skip bucket, read the `also fail a later gate`
   line under it.** the counters name only the FIRST failed gate, so a big
-  bucket can be entirely blocked a second time and unwidenable: on a uniswap
+  bucket can be entirely blocked a second time and unwidenable: on one dense
   token-list fling all 8298 `animated` skips also carried a style transform
   or a non-cacheable chunk, and narrowing the animated gate moved 6007 to
   `transform` and 2350 to `cacheable` while promoting nothing. a bucket is
   worth attacking when its also-blocked share is small.
-  and blits firing is not the same as the tier paying for itself: on the
-  uniswap token list the tier blits every visible row and costs 70MB of GPU
+  and blits firing is not the same as the tier paying for itself: on that same
+  token list the tier blits every visible row and costs 70MB of GPU
   cache for no frame-time change, while the retained row boundaries under it
   cost 2.4ms a frame. the discriminator is per-row draw density, so check
   `draw calls` in the same block before concluding a cache is earning its
@@ -198,11 +190,34 @@ not the installed Safari engine.
 
 every receipt must carry the exact page and frame URLs, browser user agent,
 harness-source identity, capture time, engine build identity and generation,
-runtime bundle receipt, system memory, runtime errors, and any partial failure.
+runtime bundle receipt, sampled host capacity at run start, runtime errors, and
+any partial failure. use the shared host-capacity sampler; do not record raw
+`freemem()` or decide from macOS load average.
 partial artifacts remain inadmissible until every requested run number for that
 scenario exists with one harness, engine, seed, and viewport identity. browser
-comparisons use the same css viewport and backing scale; finite but different
-device pixel ratios are not comparable.
+comparisons use the same root/target viewport tuple and backing scale. for a
+wrapper or embedded surface, first prove the target has nonzero presented
+geometry; a finite host viewport that responsively hides the target measures a
+different surface. direct and embedded modes may intentionally have different
+tuples, but browsers within one mode may not. finite but different device pixel
+ratios are not comparable. if setup reloads only the child frame, replay the
+parent's presentation control and wait for the new child to acknowledge it. a
+selected parent toggle can outlive its child and is not proof of the child's
+mode.
+the profile intentionally blocks Graphite cache cleanup, so its cache snapshot
+is not a terminal memory verdict. require a capture-local post-profile
+compositor snapshot with before, after, and delta cleanup counters. an
+over-limit profiled Context needs fresh submitted-work attempt and
+successful-completion deltas; an over-limit profiled Recorder also needs a
+fresh cleanup in that capture. classify Context and Recorder independently as
+within-limit, locked-over-limit, or purgeable-over-limit; never compare their
+aggregate, and never admit purgeable overage. a cache with zero purgeable bytes
+can still hold a returned-resource queue: settled maintenance releases completed
+Recorder resources, then budget enforcement evicts
+least-recently-used overage before the next paint or resource insertion can
+inherit the synchronous work. perpetual renderer
+animation is not finite interaction demand; finite motion, readbacks, and
+profiling must still block cleanup.
 the host-clock `displayFrames`/`timerFrames` and shell-link
 `displayPumps`/`timerPumps` counters prove whether the visible-rAF fallback
 engaged. preserve failed receipts instead of retrying them out of the data set.
@@ -255,9 +270,9 @@ invalidates the profile.
 
 ### the cadence block: frames that never happened
 
-work-per-painted-frame cannot see a frame that was never delivered — host
-rAF starved, shell worker descheduled, or the compositor's shared-frame wait
-resumed late. the report shows low avg and zero jank while the user sees stutter.
+work-per-painted-frame cannot see a frame that was never delivered because a
+worker was descheduled or its resilient clock fell back late. the report shows
+low avg and zero jank while the user sees stutter.
 the `cadence` section of `perf shell stop` measures the delivery side and
 attributes a missing frame to its hop:
 
@@ -271,13 +286,14 @@ attributes a missing frame to its hop:
 - `idle breaks` — gaps >250ms, excluded from all three: demand-gated
   quiesce is legitimate, not starvation.
 
-the compositor `compositorHostFrameClock` separates display/timer ticks published into
-its shared latest-frame cell from ticks consumed during the acknowledged worker
-profile window. published timer ticks prove the renderer fallback won; sparse consumed ticks
-with low production time identifies worker scheduling starvation. many consumed
-ticks with sparse paints can be legitimate dirty-gating; correlate the frame
-series before treating it as a regression. shell-owned captures expose the
-corresponding `note.frameLink.sharedFrameClock` counters.
+the compositor `compositorHostFrameClock` keeps its historical name and reports
+display/timer ticks consumed by the compositor worker's resilient clock during
+the acknowledged profile window. `published` is null because renderer-main no
+longer publishes compositor frames. sparse consumed ticks with low production
+time identifies worker scheduling starvation. many consumed ticks with sparse
+paints can be legitimate dirty-gating; correlate the frame series before
+treating it as a regression. shell cadence comes from its worker frame and paint
+series.
 
 compare baseline vs contended captures of the same scripted window; also
 compare **painted-frame counts**, the crudest and most robust signal.
@@ -339,9 +355,9 @@ which tier *should* absorb your cost and prove whether it does.
 | layer compositor (`paint-boundary.ts`) | animating a child never re-records ancestors | replays >> records |
 | idle boundary pre-record | the first drag replays instead of recording; cold records happen while the surface is quiet | `pre-recorded: N boundaries at idle` in the report, and the first interaction's record cost near its warm cost |
 | damage rects (`damage-rect.ts`) | repaint clips to changed region (opaque-backdrop gated) | worst-frame render bounded during small updates |
-| raster tier | stable rows become GPU textures; scroll skips recording | compositor block: promotions > 0 once warm, blits ≈ one per visible row (uniswap token list: ~13.7/frame) |
+| raster tier | stable rows become GPU textures; scroll skips recording | compositor block: promotions > 0 once warm, blits ≈ one per visible row on a dense feed |
 | flood guard, pointer coalescing, vsync hysteresis | message-storm and pump-thrash protection | msgs/s sane during gestures and at rest |
-| resilient renderer-main frame clock | visible rAF holes do not stall pointer coalescing or worker vsync | compositor `published` / `consumed` display and timer frames; shell `displayPumps` / `timerPumps` |
+| worker-owned resilient frame clocks | renderer-main stalls do not stop shell or compositor motion | compositor consumed display/timer frames plus shell worker frame and paint cadence |
 
 there is no whole-screen scroll blit. one existed for a few hours in June
 2026 and was reverted (`6706f3a014`): it shifted a surface RECTANGLE, so a
@@ -374,5 +390,5 @@ tier fire on feeds came entirely from rejection counters.
 done means: a named hot path + the counter or split that indicts it + the
 same capture re-run showing the number moved + no new errors (`get errors`)
 + nothing torn down left running (close sims you opened, kill load loops).
-for engine changes, run the rnx gate (`bun run test:sootsim:gate`) and
-screenshot-stable surfaces you touched.
+for engine changes, run the affected integration tests exposed by the installed
+rnx version and capture stable screenshots of surfaces you touched.

package/src/app-url.ts

@@ -24,9 +24,8 @@ export function isAppDeepLinkTarget(target: string): boolean {
 export async function openAppUrl(bridge: InspectBridge, target: string): Promise<string> {
   const normalized = normalizeAppUrlTarget(target)
   const result: unknown = await bridge.send({
-    type: 'call',
-    path: 'SootSim.bridges.test.openDeepLink',
-    args: [normalized],
+    type: 'openUrl',
+    url: normalized,
   })
   if (
     result !== null &&

package/src/bridge-contract-input.ts

@@ -208,8 +208,10 @@ export function parseStateOptions(value: unknown): SimStateOptions {
   const input = recordValue(value, 'state')
   const route = optionalBoolean(input, 'route', 'state')
   const errors = optionalBoolean(input, 'errors', 'state')
+  const logs = optionalBoolean(input, 'logs', 'state')
   const depth = optionalNumber(input, 'depth', 'state')
   const errorLimit = optionalNumber(input, 'errorLimit', 'state')
+  const logLimit = optionalNumber(input, 'logLimit', 'state')
   const layers =
     input.layers === undefined ? undefined : stringValue(input.layers, 'state.layers')
   if (
@@ -225,9 +227,11 @@ export function parseStateOptions(value: unknown): SimStateOptions {
     tree: optionalBoolean(input, 'tree', 'state') ?? true,
     ...(route === undefined ? {} : { route }),
     ...(errors === undefined ? {} : { errors }),
+    ...(logs === undefined ? {} : { logs }),
     ...(depth === undefined ? {} : { depth }),
     ...(layers === undefined ? {} : { layers }),
     ...(errorLimit === undefined ? {} : { errorLimit }),
+    ...(logLimit === undefined ? {} : { logLimit }),
   }
 }
 
@@ -277,15 +281,22 @@ export function parseSemanticQuery(value: unknown): SimSemanticQuery {
   return validationFailure('query.kind', 'must be tree, find, or count')
 }
 
-export function parseSemanticResolveSelector(value: unknown): SimSemanticResolveSelector {
-  const selector = recordValue(value, 'selector')
+function semanticResolveSelector(
+  value: unknown,
+  path: string,
+): SimSemanticResolveSelector {
+  const selector = recordValue(value, path)
   if (selector.testID !== undefined) {
-    return { testID: stringValue(selector.testID, 'selector.testID') }
+    return { testID: stringValue(selector.testID, `${path}.testID`) }
   }
   if (selector.text !== undefined) {
-    return { text: stringValue(selector.text, 'selector.text') }
+    return { text: stringValue(selector.text, `${path}.text`) }
   }
-  return validationFailure('selector', 'must select testID or text')
+  return validationFailure(path, 'must select testID or text')
+}
+
+export function parseSemanticResolveSelector(value: unknown): SimSemanticResolveSelector {
+  return semanticResolveSelector(value, 'selector')
 }
 
 export function parseSemanticWaitOptions(value: unknown): SemanticWaitOptions {
@@ -308,7 +319,7 @@ export function parseSemanticWaitOptions(value: unknown): SemanticWaitOptions {
   return {
     condition: {
       type,
-      testID: stringValue(condition.testID, 'waitFor.condition.testID'),
+      selector: semanticResolveSelector(condition.selector, 'waitFor.condition.selector'),
     },
     ...(timeoutMs === undefined ? {} : { timeoutMs }),
   }

package/src/bridge-contract.ts

@@ -11,12 +11,16 @@
 import type {
   SootSimAgentActionDetail,
   SootSimExternalAppLifecycleOptions,
-} from '@sootsim/globals'
+} from '@rnx/globals'
 
 export type BridgeCommandType =
   | 'evaluate'
   | 'call'
   | 'screenshot'
+  | 'capture'
+  | 'captureRegions'
+  | 'setAppearance'
+  | 'openUrl'
   | 'tap'
   | 'longPress'
   | 'keyboard'
@@ -48,6 +52,11 @@ export interface WsCommand {
   target?: SootSimAgentActionDetail['target']
   action?: string
   text?: string
+  appearance?: 'light' | 'dark'
+  url?: string
+  includeVisual?: boolean
+  includeFonts?: 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
@@ -174,8 +183,8 @@ export interface PerformResult {
 
 export type SemanticWaitCondition =
   | { type: 'ready' }
-  | { type: 'present'; testID: string }
-  | { type: 'absent'; testID: string }
+  | { type: 'present'; selector: SimSemanticResolveSelector }
+  | { type: 'absent'; selector: SimSemanticResolveSelector }
 
 export interface SemanticWaitOptions {
   condition: SemanticWaitCondition
@@ -239,11 +248,22 @@ export interface SimStateOptions {
   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 {
@@ -251,7 +271,8 @@ export interface SimStateResult {
   screenshot?: unknown
   tree?: SimSemanticNode[]
   route?: { url?: string; screen?: string | null; stack?: string[] } | null
-  recentErrors?: Array<{ level: string; text: string; at?: number }>
+  recentErrors?: SimStateLogEntry[]
+  recentLogs?: SimStateLogEntry[]
   keyboard?: { visible: boolean; mode?: string | null }
   capturedAt: number
 }