sootsim 0.1.169 → 0.1.170

package/dist-lib/profiles.cjs

@@ -1,4 +1,4 @@
-/*! sootsim v0.1.169 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! sootsim v0.1.170 | (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/dist-lib/render-mode.cjs

@@ -1,4 +1,4 @@
-/*! sootsim v0.1.169 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! sootsim v0.1.170 | (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 __defProp = Object.defineProperty;

package/dist-lib/scripts/dev-server-scanner.cjs

@@ -1,4 +1,4 @@
-/*! sootsim v0.1.169 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! sootsim v0.1.170 | (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;
@@ -33,6 +33,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var dev_server_scanner_exports = {};
 __export(dev_server_scanner_exports, {
   __applyManifestForTests: () => __applyManifestForTests,
+  __isSootSelfServerForTests: () => __isSootSelfServerForTests,
   __resetScannerCache: () => __resetScannerCache,
   __shouldReuseScannerCacheEntry: () => __shouldReuseScannerCacheEntry,
   discoverListeningPorts: () => discoverListeningPorts,
@@ -412,12 +413,11 @@ async function probePort(port, buildIconProxyUrl) {
   return null;
 }
 function isSootSelfServer(server) {
-  const projectName = server.projectName?.trim().toLowerCase();
-  if (projectName === "soot" || projectName === "sootsim") return true;
   const bundleId = server.bundleId?.trim().toLowerCase();
-  if (bundleId?.startsWith("dev.soot")) return true;
+  if (bundleId?.startsWith("dev.sootsim.")) return true;
   return false;
 }
+var __isSootSelfServerForTests = isSootSelfServer;
 var portCache = /* @__PURE__ */ new Map();
 var NEGATIVE_CACHE_TTL_MS = 3e4;
 var WEAK_RESULT_CACHE_TTL_MS = 1500;
@@ -507,6 +507,7 @@ async function scanDevServers(opts = {}) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   __applyManifestForTests,
+  __isSootSelfServerForTests,
   __resetScannerCache,
   __shouldReuseScannerCacheEntry,
   discoverListeningPorts,

package/dist-lib/sdk.cjs

@@ -1,4 +1,4 @@
-/*! sootsim v0.1.169 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! sootsim v0.1.170 | (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 __defProp = Object.defineProperty;

package/dist-lib/sdk.mjs

@@ -1,4 +1,4 @@
-/*! sootsim v0.1.169 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! sootsim v0.1.170 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 
 // cli/commands/inspect/core.ts
 function resolveMaxMsFlag(args, fallbackMs) {

package/dist-lib/skills.cjs

@@ -1,4 +1,4 @@
-/*! sootsim v0.1.169 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! sootsim v0.1.170 | (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;
@@ -3249,8 +3249,8 @@ var init_registry = __esm({
           {
             range: ">=3.1.0",
             coverage: 0.85,
-            note: "ExpoSpeechRecognition module and Web Speech wrapper backed by browser SpeechRecognition when available",
-            working: "ExpoSpeechRecognitionModule start/stop/abort/state, native event addListener/remove, granted permission helpers, recognition availability, speech services/default-service helpers, supported locales, iOS audio-session getters/setters, ExpoWebSpeechRecognition class, grammar/list classes, constants",
+            note: "native-seam only \u2014 upstream expo-speech-recognition JS (ExpoWebSpeechRecognition, useSpeechRecognitionEvent, constants, and direct module API) runs unchanged from the bundle; SootSim registers only the ExpoSpeechRecognition native module, backed by the host-service SpeechRecognition bridge when available",
+            working: "ExpoSpeechRecognition native module start/stop/abort/state, native event addListener/remove, granted permission helpers, recognition availability, speech services/default-service helpers, supported-locales shape, iOS audio-session getters/setters; upstream ExpoWebSpeechRecognition class, grammar/list classes, hook, and constants stay authoritative",
             missing: "native SFSpeechRecognizer and Android SpeechRecognizer engines, real microphone permission prompts, audioSource transcription, recording persistence, locale installation data, offline model downloads, volume metering"
           }
         ]
@@ -10350,10 +10350,8 @@ async function probePort(port, buildIconProxyUrl) {
   return null;
 }
 function isSootSelfServer(server) {
-  const projectName = server.projectName?.trim().toLowerCase();
-  if (projectName === "soot" || projectName === "sootsim") return true;
   const bundleId = server.bundleId?.trim().toLowerCase();
-  if (bundleId?.startsWith("dev.soot")) return true;
+  if (bundleId?.startsWith("dev.sootsim.")) return true;
   return false;
 }
 function isWeakCachedResult(result) {
@@ -10507,6 +10505,27 @@ function sootsimHomeDir() {
   if (override && override.length > 0) return import_node_path.default.resolve(override);
   return import_node_path.default.join((0, import_node_os.homedir)(), ".sootsim");
 }
+function isSootsimDevCheckout() {
+  if (process.env.SOOTSIM_FORCE_DAEMON_INSTALL === "1") return false;
+  const env = process.env.SOOTSIM_DEV;
+  if (env === "1" || env === "true") return true;
+  if (env === "0" || env === "false") return false;
+  const argv1 = process.argv[1];
+  if (!argv1) return false;
+  try {
+    const real = import_node_fs2.default.realpathSync(argv1);
+    return real.includes(`${import_node_path.default.sep}packages${import_node_path.default.sep}sootsim${import_node_path.default.sep}`);
+  } catch {
+    return false;
+  }
+}
+function isDevWorkstation() {
+  if (process.env.SOOTSIM_FORCE_DAEMON_INSTALL === "1") return false;
+  return process.env.IS_TAMAGUI_DEV === "1";
+}
+function shouldSkipPersistentDaemon() {
+  return isSootsimDevCheckout() || isDevWorkstation();
+}
 function runtimesDir() {
   return import_node_path.default.join(sootsimHomeDir(), "runtimes");
 }
@@ -10531,6 +10550,9 @@ function cacheDir() {
 function daemonLockfilePath() {
   return import_node_path.default.join(sootsimHomeDir(), DAEMON_LOCKFILE);
 }
+function devBridgeLockfilePath() {
+  return import_node_path.default.join(sootsimHomeDir(), DEV_BRIDGE_LOCKFILE);
+}
 function configFilePath() {
   return import_node_path.default.join(sootsimHomeDir(), CONFIG_FILE);
 }
@@ -10636,6 +10658,25 @@ function readDaemonLockfile() {
     return null;
   }
 }
+function readDevBridgeLockfile() {
+  try {
+    const fd = import_node_fs2.default.openSync(devBridgeLockfilePath(), "r");
+    try {
+      const buf = Buffer.alloc(DAEMON_LOCKFILE_MAX_BYTES);
+      const bytesRead = import_node_fs2.default.readSync(fd, buf, 0, DAEMON_LOCKFILE_MAX_BYTES, 0);
+      const raw = buf.subarray(0, bytesRead).toString("utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed && parsed.schema === 1 && parsed.source === "vite-dev" && typeof parsed.pid === "number" && typeof parsed.bridgePort === "number" && typeof parsed.runtimePort === "number" && typeof parsed.cwd === "string" && typeof parsed.startedAt === "number" && typeof parsed.heartbeatAt === "number") {
+        return parsed;
+      }
+      return null;
+    } finally {
+      import_node_fs2.default.closeSync(fd);
+    }
+  } catch {
+    return null;
+  }
+}
 function isDaemonLockfileFresh(lock, now = Date.now()) {
   if (!lock) return false;
   if (now - lock.heartbeatAt > DAEMON_HEARTBEAT_STALE_MS) return false;
@@ -10646,6 +10687,16 @@ function isDaemonLockfileFresh(lock, now = Date.now()) {
     return false;
   }
 }
+function isDevBridgeLockfileFresh(lock, now = Date.now()) {
+  if (!lock) return false;
+  if (now - lock.heartbeatAt > DAEMON_HEARTBEAT_STALE_MS) return false;
+  try {
+    process.kill(lock.pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function writeDaemonLockfile(data) {
   ensureSootsimHome();
   const tmp = `${daemonLockfilePath()}.tmp`;
@@ -10653,6 +10704,13 @@ function writeDaemonLockfile(data) {
 `, "utf8");
   import_node_fs2.default.renameSync(tmp, daemonLockfilePath());
 }
+function writeDevBridgeLockfile(data) {
+  ensureSootsimHome();
+  const tmp = `${devBridgeLockfilePath()}.tmp`;
+  import_node_fs2.default.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}
+`, "utf8");
+  import_node_fs2.default.renameSync(tmp, devBridgeLockfilePath());
+}
 function claimDaemonLockfile(data) {
   ensureSootsimHome();
   const existing = readDaemonLockfile();
@@ -10668,7 +10726,13 @@ function removeDaemonLockfile() {
   } catch {
   }
 }
-var import_node_fs2, import_node_os, import_node_path, SOOTSIM_HOME_ENV, ACTIVE_RUNTIME_FILE, DAEMON_LOCKFILE, CONFIG_FILE, DAEMON_HEARTBEAT_STALE_MS, DAEMON_LOCKFILE_MAX_BYTES;
+function removeDevBridgeLockfile() {
+  try {
+    import_node_fs2.default.unlinkSync(devBridgeLockfilePath());
+  } catch {
+  }
+}
+var import_node_fs2, import_node_os, import_node_path, SOOTSIM_HOME_ENV, ACTIVE_RUNTIME_FILE, DAEMON_LOCKFILE, DEV_BRIDGE_LOCKFILE, CONFIG_FILE, DAEMON_HEARTBEAT_STALE_MS, DAEMON_LOCKFILE_MAX_BYTES;
 var init_home_paths = __esm({
   "src/home-paths.ts"() {
     "use strict";
@@ -10678,6 +10742,7 @@ var init_home_paths = __esm({
     SOOTSIM_HOME_ENV = "SOOTSIM_HOME";
     ACTIVE_RUNTIME_FILE = "active";
     DAEMON_LOCKFILE = "daemon.json";
+    DEV_BRIDGE_LOCKFILE = "dev-bridge.json";
     CONFIG_FILE = "config.json";
     DAEMON_HEARTBEAT_STALE_MS = 3e4;
     DAEMON_LOCKFILE_MAX_BYTES = 16 * 1024;
@@ -12860,10 +12925,12 @@ var init_bridge_host = __esm({
       maxConcurrentAutomationSims;
       automationSimActiveGraceMs;
       shouldWriteLockfile;
+      shouldWriteDevLockfile;
       sootbeanOrigin = null;
       effectivePort = 0;
       startedAt = 0;
       heartbeatTimer = null;
+      devHeartbeatTimer = null;
       // ws-level heartbeat: sims that hang up uncleanly (page navigated, network
       // dropped, sim crashed) leave their server-side WebSocket sitting "open"
       // forever. ping every WS_HEARTBEAT_INTERVAL_MS; if the previous round's
@@ -12890,6 +12957,7 @@ var init_bridge_host = __esm({
         this.preferredPort = opts.port || DEFAULT_SOOTSIM_BRIDGE_PORT;
         this.port = this.preferredPort;
         this.shouldWriteLockfile = opts.writeLockfile === true;
+        this.shouldWriteDevLockfile = opts.writeDevLockfile === true;
         this.portFallbackCount = Math.max(1, opts.portFallbackCount ?? 10);
         this.openUrlHandler = opts.openUrl;
         this.agentHost = new AgentHost({ getExcludePorts: opts.agentScanExcludes });
@@ -13407,7 +13475,7 @@ var init_bridge_host = __esm({
           });
         });
       }
-      /** after a successful bind: start the cli idle sweep, write the daemon
+      /** after a successful bind: start the cli idle sweep, write the daemon/dev
        *  lockfile (if this host owns it), seed the agent host, kick off the
        *  heartbeat loop. idempotent across rebinds because close() tears down
        *  every timer and the lockfile. */
@@ -13449,6 +13517,23 @@ var init_bridge_host = __esm({
           this.heartbeatTimer.unref();
           this.startRuntimeUpdater();
         }
+        if (this.shouldWriteDevLockfile) {
+          try {
+            this.writeDevLockfileSnapshot();
+          } catch (err) {
+            process.stderr.write(
+              `ws bridge failed to write dev bridge lockfile: ${String(err)}
+`
+            );
+          }
+          this.devHeartbeatTimer = setInterval(() => {
+            try {
+              this.writeDevLockfileSnapshot();
+            } catch {
+            }
+          }, DAEMON_HEARTBEAT_INTERVAL_MS);
+          this.devHeartbeatTimer.unref();
+        }
         void this.agentHost.seedOnBoot();
       }
       bootstrapping = true;
@@ -13466,9 +13551,25 @@ var init_bridge_host = __esm({
           bootstrapping: this.bootstrapping
         };
       }
+      buildDevLockfileSnapshot() {
+        return {
+          schema: 1,
+          pid: process.pid,
+          platform: process.platform,
+          bridgePort: this.effectivePort,
+          runtimePort: this.effectivePort,
+          cwd: process.cwd(),
+          startedAt: this.startedAt,
+          heartbeatAt: Date.now(),
+          source: "vite-dev"
+        };
+      }
       writeLockfileSnapshot() {
         writeDaemonLockfile(this.buildLockfileSnapshot());
       }
+      writeDevLockfileSnapshot() {
+        writeDevBridgeLockfile(this.buildDevLockfileSnapshot());
+      }
       refreshActiveRuntime() {
         this.activeRuntimeVersion = readActiveRuntime();
         this.activeRuntimeDirPath = activeRuntimeDir();
@@ -13704,6 +13805,7 @@ var init_bridge_host = __esm({
               bridgePort: this.effectivePort,
               runtimePort: this.effectivePort,
               activeRuntime: this.activeRuntimeVersion,
+              bridgeSource: this.shouldWriteDevLockfile ? "vite-dev" : this.shouldWriteLockfile ? "daemon" : "embedded",
               startedAt: this.startedAt,
               uptimeMs: this.startedAt > 0 ? Date.now() - this.startedAt : 0
             })
@@ -14085,6 +14187,10 @@ var init_bridge_host = __esm({
           clearInterval(this.heartbeatTimer);
           this.heartbeatTimer = null;
         }
+        if (this.devHeartbeatTimer) {
+          clearInterval(this.devHeartbeatTimer);
+          this.devHeartbeatTimer = null;
+        }
         if (this.wsHeartbeatTimer) {
           clearInterval(this.wsHeartbeatTimer);
           this.wsHeartbeatTimer = null;
@@ -14099,6 +14205,12 @@ var init_bridge_host = __esm({
           } catch {
           }
         }
+        if (this.shouldWriteDevLockfile) {
+          try {
+            removeDevBridgeLockfile();
+          } catch {
+          }
+        }
         this.effectivePort = 0;
         this.startedAt = 0;
         this.agentHost.close();
@@ -14708,6 +14820,10 @@ __export(ws_bridge_exports, {
   resolveDefaultBridgePort: () => resolveDefaultBridgePort
 });
 function resolveDefaultBridgePort() {
+  if (shouldSkipPersistentDaemon()) {
+    const dev = readDevBridgeLockfile();
+    if (dev && isDevBridgeLockfileFresh(dev)) return dev.bridgePort;
+  }
   const lock = readDaemonLockfile();
   if (lock && isDaemonLockfileFresh(lock)) return lock.bridgePort;
   return DEFAULT_SOOTSIM_BRIDGE_PORT;

package/dist-lib/vite.cjs

@@ -1,4 +1,4 @@
-/*! sootsim v0.1.169 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! sootsim v0.1.170 | (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;
@@ -74,7 +74,7 @@ function readActiveRuntime() {
 var DAEMON_LOCKFILE_MAX_BYTES = 16 * 1024;
 
 // src/runtime-assets.ts
-var SOOTSIM_RUNTIME_MISSING_MESSAGE = "[sootsim] no engine runtime installed \u2014 run `sootsim setup-repo` in your project, or `sootsim runtime install`";
+var SOOTSIM_RUNTIME_MISSING_MESSAGE = "[sootsim] no engine runtime installed \u2014 run `sootsim setup`, or `sootsim runtime install`";
 var MIME_TYPES = {
   ".js": "application/javascript",
   ".mjs": "application/javascript",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sootsim",
-  "version": "0.1.169",
+  "version": "0.1.170",
   "description": "sootsim CLI + vite/metro plugins + skills registry. bridge client for driving the proprietary sootsim-engine over WebSocket.",
   "author": "Tamagui LLC",
   "license": "MIT",
@@ -132,6 +132,7 @@
     "dist-cli/",
     "dist-lib/",
     "src/",
+    "skills/",
     "scripts/dev-server-scanner.ts",
     "scripts/optional-demo-registry.ts",
     "detox/",

package/scripts/dev-server-scanner.ts

@@ -556,15 +556,14 @@ export interface ScanOptions {
 }
 
 function isSootSelfServer(server: DiscoveredServer): boolean {
-  const projectName = server.projectName?.trim().toLowerCase()
-  if (projectName === 'soot' || projectName === 'sootsim') return true
-
   const bundleId = server.bundleId?.trim().toLowerCase()
-  if (bundleId?.startsWith('dev.soot')) return true
+  if (bundleId?.startsWith('dev.sootsim.')) return true
 
   return false
 }
 
+export const __isSootSelfServerForTests = isSootSelfServer
+
 // per-(port, pid) probe cache. as long as the same process still owns the
 // port, its signature endpoints can't have changed, so we return the cached
 // result without issuing any HTTP. negative results (null) are cached too,

package/scripts/postinstall.cjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 // postinstall — best-effort runtime install after `npm i -g sootsim`.
 //
-// runs as a child of npm. failures here are non-fatal: any first invocation
-// of the CLI will retry the install via auto-bootstrap.
+// runs as a child of npm. failures here are non-fatal; setup/open/runtime
+// commands can install the runtime later.
 //
 // skipped when running as root via sudo: $HOME would be /root, but the user
 // who actually wants the runtime probably isn't root. their first sootsim

package/scripts/preuninstall.cjs

@@ -11,8 +11,8 @@
 // reliability: npm preuninstall hooks are best-effort — they don't fire when
 // the package wasn't installed by npm (yarn/bun/pnpm have their own lifecycle
 // rules), and they don't run as part of `npm cache verify` cleanup or manual
-// dir removal. that's why we also document `sootsim daemon uninstall` as the
-// manual fallback and show a hint pointing at it.
+// dir removal. that's why `sootsim daemon uninstall` is also documented as
+// the manual teardown path.
 //
 // strategy: spawn the bundled bin to run `daemon uninstall` (single source of
 // truth — the same logic the user invokes manually). if that fails for any
@@ -73,17 +73,15 @@ function rawCleanup() {
   const home = sootsimHomeDir()
   if (process.platform === 'darwin') {
     safeSpawn('launchctl', ['bootout', `gui/${getuid()}/dev.sootsim.daemon`])
-    safeSpawn('launchctl', ['bootout', `gui/${getuid()}/dev.sootsim.server`])
     safeRemove(path.join(os.homedir(), 'Library/LaunchAgents/dev.sootsim.daemon.plist'))
-    safeRemove(path.join(os.homedir(), 'Library/LaunchAgents/dev.sootsim.server.plist'))
     safeRemove(path.join(os.homedir(), 'Library/Logs/sootsim'), {
       recursive: true,
     })
   } else if (process.platform === 'linux') {
-    safeSpawn('systemctl', ['--user', 'disable', '--now', 'sootsim-server'])
+    safeSpawn('systemctl', ['--user', 'disable', '--now', 'sootsim-daemon'])
     safeSpawn('systemctl', ['--user', 'daemon-reload'])
-    safeSpawn('systemctl', ['--user', 'reset-failed', 'sootsim-server'])
-    safeRemove(path.join(os.homedir(), '.config/systemd/user/sootsim-server.service'))
+    safeSpawn('systemctl', ['--user', 'reset-failed', 'sootsim-daemon'])
+    safeRemove(path.join(os.homedir(), '.config/systemd/user/sootsim-daemon.service'))
     safeRemove(path.join(os.homedir(), '.local/state/sootsim'), { recursive: true })
   }
   // ~/.sootsim is the same on every platform; honor $SOOTSIM_HOME.

package/skills/soot.md

@@ -0,0 +1,178 @@
+---
+name: soot
+description: >-
+  index of all Soot and SootSim agent skills and CLI commands.
+  auto-generated from the CLI info registry — do not edit by hand.
+---
+
+# soot
+
+overview of all available skills and CLI commands in this repo.
+
+> this file is auto-generated by `bun scripts/generate-soot-skill.ts`.
+> to update, edit the source registries and re-run the generator.
+
+## sootsim CLI commands
+
+the `sootsim` CLI is the operational surface for booting shells, driving
+automation, inspecting the render tree, and managing sims.
+
+| command | description |
+| --- | --- |
+| `sootsim preview` | production-like preview build |
+| `sootsim test` | run tests against sootsim |
+| `sootsim flow` | run flows through the current sim or manage a draft from live inspect actions |
+| `sootsim maestro` | run existing Maestro YAML flows against sootsim |
+| `sootsim detox` | run existing Detox suites against sootsim on headless Chromium |
+| `sootsim record` | capture the live sim as webm/mp4/gif, or sample N png frames (--frames) |
+| `sootsim profile` | manage isolated storage profiles |
+| `sootsim storage-clear` | clear the current guest app storage and reload it |
+| `sootsim cpu-profile` | capture a JS CPU profile of the sim workers over the Chrome DevTools Protocol |
+| `sootsim react` | inspect React component render cost in the tenant worker |
+| `sootsim assert` | run any read verb and convert its output into an exit code |
+| `sootsim screenshot` | capture the canvas (full or cropped) as PNG |
+| `sootsim get` | read runtime state (tree, a11y, url, count, errors, …) |
+| `sootsim screenshots` | capture + compose app-store screenshot sets from a single plan |
+| `sootsim do` | drive the app (tap, type, scroll, swipe, key, reload, …) |
+| `sootsim screenshots-capture` | headlessly (re)capture editable App Store slides and upload them to your org |
+| `sootsim screenshot-mode` | toggle the screenshot-mode chrome overlay |
+| `sootsim wait` | block until the runtime reaches a known state |
+| `sootsim shell` | drive shell state and simulator chrome |
+| `sootsim slides` | compose App Store screenshot slides in the live sim |
+| `sootsim three-mode` | toggle the live browser 3d device stage |
+| `sootsim upload` | publish the current recorded bundle as a shareable /preview/<id> link |
+| `sootsim device` | inspect or change the live device preset for a sim |
+| `sootsim inspect` | query, describe, and drive the running sootsim instance |
+| `sootsim network` | inspect live network traffic from the running sootsim worker |
+| `sootsim logs` | inspect live console output from the running sootsim worker |
+| `sootsim debug` | drive __sootsimDebug: channels, snapshots, and inspectors |
+| `sootsim camera` | drive the sim camera — inject synthetic barcode scans |
+| `sootsim what-happened` | show recent semantic events: toasts, keyboards, screens, alerts, fetches, errors |
+| `sootsim diagnose` | composed read commands for "what just went wrong?" |
+| `sootsim timeline` | control the semantic event timeline (enable opt-in kinds, clear, dump) |
+| `sootsim open` | load a target into the current sim or open a new one |
+| `sootsim list` | list connected sims or available launch drivers |
+| `sootsim use` | select a connected sim |
+| `sootsim skill` | install and inspect bundled SootSim agent skills |
+| `sootsim claim` | take an exclusive lease on a sim |
+| `sootsim agent` | attached projects + local agent sessions (codex/claude) |
+| `sootsim close` | close a connected sim |
+| `sootsim setup` | set up this machine and, optionally, this repo |
+| `sootsim compat` | check package compatibility (alias: scan) |
+| `sootsim electron` | launch the desktop companion |
+| `sootsim daemon` | manage the sootsim bridge as a login agent |
+| `sootsim version` | show the CLI + engine runtime versions you are running |
+| `sootsim upgrade` | update the sootsim CLI and engine runtime to the latest |
+| `sootsim serve` | run the sootsim bridge in the foreground |
+| `sootsim runtime` | manage engine runtimes under ~/.sootsim/runtimes/ |
+| `sootsim install-desktop` | download and install the optional desktop GUI |
+| `sootsim login` | sign in so preview uploads are associated with your account |
+| `sootsim logout` | clear the local desktop auth state |
+| `sootsim whoami` | print the currently signed-in account |
+| `sootsim keys` | manage the api keys that authorize CI preview uploads |
+| `sootsim hints` | inspect and manage the CLI hint registry |
+
+### runtime verb groups
+
+every runtime verb is organized under one of these grouping prefixes.
+run `sootsim --help` to see the full list under each group.
+
+- `sootsim describe` — summarize the current UI
+- `sootsim find <...>` — unified finder (bare text, --testid, --role, --type, --pressable, --visible)
+- `sootsim get <noun>` — read runtime state (tree, a11y, url, count, errors, warnings, requests, globals, layout, node)
+- `sootsim do <action>` — drive the app (tap, tap-text, tap-id, type, type-into, key, dismiss, scroll, drag, swipe, pinch, reload, shell, sleep, settle, wait)
+- `sootsim debug <tool>` — instrumentation (state, js, eval, perf, sample-color, enable/disable channels, snapshots, diff, record, recent)
+
+### global flags
+
+- `-h, --help` — show help
+- `-V, --version` — show version
+- `-v, --verbose` — verbose output
+- `-p, --port <number>` — bridge or preview port, depending on command
+- `-d, --device <model>` — override the simulated device model
+- `-t, --theme <scheme>` — override light, dark, or auto color scheme
+- `--headless` — run browser automation without a visible window where supported
+
+## bundled SootSim agent skills
+
+skills for working with the SootSim native preview engine:
+
+| skill | description |
+| --- | --- |
+| `/sootsim-debug` | Debug rendering, performance, and accessibility issues in your React Native app under sootsim |
+| `/sootsim-setup` | Get sootsim connected to your React Native app — from `npm install sootsim` to a driveable sim |
+| `/sootsim-test` | Run automated tests against your React Native app under sootsim — native YAML flows, Maestro drop-in, or Detox drop-in |
+| `/sootsim-visual` | Pixel-level rendering comparison between sootsim and native iOS — fonts, gradients, shadows, image fidelity |
+
+## automatic settling
+
+every CLI command already waits at the right moment — **do not wrap
+commands in your own `sleep` or chain `do settle` "just to be safe"**.
+
+- **before read commands** (`describe`, `find`, `get`, `tree`, `node`,
+  `layout`, `screenshot`, `capture`, `a11y`, `sample-color`, `count`,
+  and every gesture — `tap`, `tap-id`, `tap-text`, `type-into`,
+  `touch`, `swipe`, `drag`, `scroll`, `pinch`, `long-press`,
+  `double-tap`, `gesture`) the CLI waits up to **1800 ms** for any
+  in-flight screen transition to actually start, so the tree you read is
+  never mid-flip.
+- **after write commands** (`tap`, `tap-text`, `tap-id`, `type`,
+  `type-into`, `key`, `key-sequence`, `keycode`, `drag`, `swipe`,
+  `long-press`, `touch`, `gesture`, `pinch`, `scroll`, `shell`)
+  the CLI polls the layout hash until it is stable for two consecutive
+  frames. budget: **1200 ms for agents** (`SOOTSIM_AGENT=1`, set by the
+  harness), 350 ms for humans.
+
+what this means:
+
+- `sootsim do tap-id login` then `sootsim find "Welcome"` Just Works™.
+- you only need `sootsim do settle <seconds>` or `sootsim wait idle
+  --max-ms <N>` when the CLI explicitly prints
+  `⚠ auto-wait timed out after Nms — next command may see mid-animation
+  state`, or when the transition you care about lasts longer than ~1.2 s
+  (full stack navigation, crossfades, video load).
+- opt-out: `--no-wait` on a single command, `SOOTSIM_NO_AUTO_WAIT=1`
+  for a whole lane.
+- if a read keeps racing its write, the fix is **never** a blind `sleep` —
+  prefer `wait selector`, `wait ready`, `wait idle`, or a longer
+  explicit `do settle`, and investigate whether the app's animation
+  completion signal is actually firing.
+
+## quick reference
+
+### dev workflow
+
+```sh
+bun dev                              # start everything
+sootsim dev -- pnpm dev              # wrap a bundler
+sootsim open 8081                    # load an app
+sootsim describe                     # inspect the UI tree
+```
+
+### debugging
+
+```sh
+sootsim get errors 5                 # recent console errors
+sootsim get requests 5               # recent failed requests
+sootsim debug snapshot before        # capture state
+sootsim debug diff before after      # compare snapshots
+sootsim debug state shell            # runtime state dump
+```
+
+### testing
+
+```sh
+sootsim test                         # run tests
+sootsim flow flows/login.yaml        # run a YAML flow
+sootsim flow start                   # start recording a flow
+```
+
+### inspection
+
+```sh
+sootsim describe                     # visible elements
+sootsim find "Sign in"               # find by text
+sootsim find --testid loginButton    # find by testID
+sootsim do tap-text "Submit"         # tap by text
+sootsim do type "hello"              # type text
+```