rnxsim 0.1.514 → 0.1.516

package/dist-lib/index.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.516 | (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;
@@ -78,29 +78,60 @@ function isLoopbackHost(hostname) {
 // src/cloud-contract.ts
 var RNX_CLOUD_MAX_ARTIFACT_BYTES = 20 * 1024 * 1024;
 var RNX_CLOUD_DESIGN_MAX_STORAGE_BYTES = 1024 * 1024;
-var RNX_CLOUD_COMMAND_TYPES = Object.freeze([
-  "state",
-  "query",
-  "resolve",
-  "perform",
-  "waitFor",
-  "reset",
-  "screenshot",
-  "capture",
-  "captureRegions",
-  "settle",
-  "setAppearance",
-  "openUrl",
-  "tree",
-  "tap",
-  "longPress",
-  "memory",
-  "diagnostics"
-]);
+var RNX_CLOUD_COMMAND_SCOPES = {
+  state: "read",
+  tree: "read",
+  query: "read",
+  resolve: "read",
+  screenshot: "read",
+  capture: "read",
+  captureRegions: "read",
+  memory: "read",
+  diagnostics: "read",
+  storageSnapshot: "read",
+  perform: "drive",
+  waitFor: "drive",
+  tap: "drive",
+  longPress: "drive",
+  settle: "drive",
+  openUrl: "drive",
+  setAppearance: "drive",
+  keyboard: "drive",
+  focus: "drive",
+  flowStatus: "drive",
+  reset: "reset",
+  camera: "media",
+  // string evaluation and arbitrary bridge calls are maestro's boundary: the
+  // customer sdk never carries this scope, and the service grants it only to
+  // the account api key caller. close rides along, since ending the page ends
+  // the sim and belongs to the sim's owner rather than any driver.
+  evaluate: "debug",
+  call: "debug",
+  close: "debug"
+};
+function scopeTableKeys() {
+  return Object.keys(RNX_CLOUD_COMMAND_SCOPES).filter(
+    (key) => Object.prototype.hasOwnProperty.call(RNX_CLOUD_COMMAND_SCOPES, key)
+  );
+}
+var RNX_CLOUD_COMMAND_TYPES = Object.freeze(scopeTableKeys());
 var RNX_CLOUD_COMMAND_TYPE_SET = new Set(RNX_CLOUD_COMMAND_TYPES);
 function isRnxCloudCommandType(value) {
   return RNX_CLOUD_COMMAND_TYPE_SET.has(value);
 }
+function rnxCloudCommandScope(type) {
+  return RNX_CLOUD_COMMAND_SCOPES[type];
+}
+var RNX_CLOUD_TOKEN_SCOPES = Object.freeze([
+  "read",
+  "drive",
+  "reset",
+  "media"
+]);
+var RNX_CLOUD_ALL_COMMAND_SCOPES = Object.freeze(["read", "drive", "reset", "media", "debug"]);
+function rnxCloudScopesAllowCommand(scopes, type) {
+  return scopes.includes(RNX_CLOUD_COMMAND_SCOPES[type]);
+}
 
 // src/metro-production-bundle.ts
 var RNXSIM_METRO_MODULE_PATHS_PREFIX = "globalThis.__sootsimModulePaths=";
@@ -444,10 +475,17 @@ function cloudCommand(command) {
   for (const [key, value] of Object.entries(command)) {
     if (key !== "id" && key !== "simId") clean[key] = value;
   }
-  if (isRnxCloudCommandType(command.type)) return clean;
-  throw new Error(
-    `a remote simulator does not support bridge command type ${command.type}`
-  );
+  if (!isRnxCloudCommandType(command.type)) {
+    throw new Error(
+      `a remote simulator does not support bridge command type ${command.type}`
+    );
+  }
+  if (!rnxCloudScopesAllowCommand(RNX_CLOUD_TOKEN_SCOPES, command.type)) {
+    throw new Error(
+      `a remote simulator command ${command.type} requires the ${rnxCloudCommandScope(command.type)} scope`
+    );
+  }
+  return clean;
 }
 var CloudBridge = class {
   constructor(session) {

package/dist-lib/jump-to-source-babel.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.516 | (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/jump-to-source-native.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.516 | (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/menu.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.516 | (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/menu.mjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.516 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 
 // src/public-brand.ts
 var name = "rnx";

package/dist-lib/metro-fingerprint-registry.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.516 | (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/metro-fingerprint-registry.mjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.516 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 
 // src/metro-fingerprint-registry.ts
 var RNX_METRO_FINGERPRINT_SCHEMA_VERSION = 2;

package/dist-lib/metro-production-bundle.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.516 | (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/metro-production-bundle.mjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.516 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 
 // src/metro-production-bundle.ts
 var RNXSIM_METRO_MODULE_PATHS_PREFIX = "globalThis.__sootsimModulePaths=";

package/dist-lib/metro.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.516 | (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/profiles.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.516 | (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/public-brand.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.516 | (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/react-native-host-modules.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.516 | (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/react-native-host-modules.mjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.516 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 
 // src/react-native-host-modules.ts
 var REACT_NATIVE_PASSTHROUGH_SPECIFIERS = [

package/dist-lib/render-mode.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.516 | (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 @@
-/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.516 | (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/sdk.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.516 | (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 @@
-/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.516 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);

package/dist-lib/skills.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.516 | (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;
@@ -27513,35 +27513,66 @@ var init_metro_fingerprint = __esm({
 });
 
 // src/cloud-contract.ts
+function scopeTableKeys() {
+  return Object.keys(RNX_CLOUD_COMMAND_SCOPES).filter(
+    (key) => Object.prototype.hasOwnProperty.call(RNX_CLOUD_COMMAND_SCOPES, key)
+  );
+}
 function isRnxCloudCommandType(value) {
   return RNX_CLOUD_COMMAND_TYPE_SET.has(value);
 }
-var RNX_CLOUD_MAX_ARTIFACT_BYTES, RNX_CLOUD_DESIGN_MAX_STORAGE_BYTES, RNX_CLOUD_COMMAND_TYPES, RNX_CLOUD_COMMAND_TYPE_SET;
+function rnxCloudCommandScope(type) {
+  return RNX_CLOUD_COMMAND_SCOPES[type];
+}
+function rnxCloudScopesAllowCommand(scopes, type) {
+  return scopes.includes(RNX_CLOUD_COMMAND_SCOPES[type]);
+}
+var RNX_CLOUD_MAX_ARTIFACT_BYTES, RNX_CLOUD_DESIGN_MAX_STORAGE_BYTES, RNX_CLOUD_COMMAND_SCOPES, RNX_CLOUD_COMMAND_TYPES, RNX_CLOUD_COMMAND_TYPE_SET, RNX_CLOUD_TOKEN_SCOPES, RNX_CLOUD_ALL_COMMAND_SCOPES;
 var init_cloud_contract = __esm({
   "src/cloud-contract.ts"() {
     "use strict";
     RNX_CLOUD_MAX_ARTIFACT_BYTES = 20 * 1024 * 1024;
     RNX_CLOUD_DESIGN_MAX_STORAGE_BYTES = 1024 * 1024;
-    RNX_CLOUD_COMMAND_TYPES = Object.freeze([
-      "state",
-      "query",
-      "resolve",
-      "perform",
-      "waitFor",
+    RNX_CLOUD_COMMAND_SCOPES = {
+      state: "read",
+      tree: "read",
+      query: "read",
+      resolve: "read",
+      screenshot: "read",
+      capture: "read",
+      captureRegions: "read",
+      memory: "read",
+      diagnostics: "read",
+      storageSnapshot: "read",
+      perform: "drive",
+      waitFor: "drive",
+      tap: "drive",
+      longPress: "drive",
+      settle: "drive",
+      openUrl: "drive",
+      setAppearance: "drive",
+      keyboard: "drive",
+      focus: "drive",
+      flowStatus: "drive",
+      reset: "reset",
+      camera: "media",
+      // string evaluation and arbitrary bridge calls are maestro's boundary: the
+      // customer sdk never carries this scope, and the service grants it only to
+      // the account api key caller. close rides along, since ending the page ends
+      // the sim and belongs to the sim's owner rather than any driver.
+      evaluate: "debug",
+      call: "debug",
+      close: "debug"
+    };
+    RNX_CLOUD_COMMAND_TYPES = Object.freeze(scopeTableKeys());
+    RNX_CLOUD_COMMAND_TYPE_SET = new Set(RNX_CLOUD_COMMAND_TYPES);
+    RNX_CLOUD_TOKEN_SCOPES = Object.freeze([
+      "read",
+      "drive",
       "reset",
-      "screenshot",
-      "capture",
-      "captureRegions",
-      "settle",
-      "setAppearance",
-      "openUrl",
-      "tree",
-      "tap",
-      "longPress",
-      "memory",
-      "diagnostics"
+      "media"
     ]);
-    RNX_CLOUD_COMMAND_TYPE_SET = new Set(RNX_CLOUD_COMMAND_TYPES);
+    RNX_CLOUD_ALL_COMMAND_SCOPES = Object.freeze(["read", "drive", "reset", "media", "debug"]);
   }
 });
 
@@ -28270,10 +28301,17 @@ function cloudCommand(command) {
   for (const [key, value] of Object.entries(command)) {
     if (key !== "id" && key !== "simId") clean[key] = value;
   }
-  if (isRnxCloudCommandType(command.type)) return clean;
-  throw new Error(
-    `a remote simulator does not support bridge command type ${command.type}`
-  );
+  if (!isRnxCloudCommandType(command.type)) {
+    throw new Error(
+      `a remote simulator does not support bridge command type ${command.type}`
+    );
+  }
+  if (!rnxCloudScopesAllowCommand(RNX_CLOUD_TOKEN_SCOPES, command.type)) {
+    throw new Error(
+      `a remote simulator command ${command.type} requires the ${rnxCloudCommandScope(command.type)} scope`
+    );
+  }
+  return clean;
 }
 function createCloudBridgeForParsed(parsed) {
   const session = resolveCloudSessionForParsed(parsed);

package/dist-lib/swift.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.516 | (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/vite.cjs

@@ -1,4 +1,4 @@
-/*! rnx v0.1.514 | (c) 2026 Tamagui LLC | Proprietary — see LICENSE */
+/*! rnx v0.1.516 | (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.514",
+  "version": "0.1.516",
   "description": "Vite and Metro plugins, testing drivers, and SDK exports for rnx.",
   "author": "Tamagui LLC",
   "license": "SEE LICENSE IN LICENSE",
@@ -92,6 +92,7 @@
     "./bridge-contract-input": {
       "types": "./src/bridge-contract-input.ts",
       "source": "./src/bridge-contract-input.ts",
+      "bun": "./src/bridge-contract-input.ts",
       "import": "./dist-lib/bridge-contract-input.mjs",
       "default": "./dist-lib/bridge-contract-input.cjs"
     },

package/src/bridge-contract-input.ts

@@ -198,6 +198,46 @@ export function parsePerformStep(value: unknown, index: number): SimPerformStep
       return { type, key: stringValue(step.key, `${path}.key`) }
     case 'dismissKeyboard':
       return { type }
+    case 'setElementValue': {
+      const submit = optionalBoolean(step, 'submit', path)
+      return {
+        type,
+        id: stringValue(step.id, `${path}.id`),
+        text: stringValue(step.text, `${path}.text`),
+        ...(submit === undefined ? {} : { submit }),
+      }
+    }
+    case 'toggleKeyboard':
+      return { type }
+    case 'openUrl': {
+      const url = stringValue(step.url, `${path}.url`)
+      if (url.length === 0) validationFailure(`${path}.url`, 'must be non-empty')
+      return { type, url }
+    }
+    case 'keyDown':
+    case 'keyUp':
+      return { type, key: stringValue(step.key, `${path}.key`) }
+    case 'setOrientation': {
+      const orientation = stringValue(step.orientation, `${path}.orientation`)
+      if (orientation !== 'portrait' && orientation !== 'landscape') {
+        validationFailure(`${path}.orientation`, 'must be portrait or landscape')
+      }
+      return { type, orientation }
+    }
+    case 'deviceInfo':
+      return { type }
+    case 'buttonDown':
+    case 'buttonUp': {
+      const button =
+        step.button === undefined ? undefined : stringValue(step.button, `${path}.button`)
+      return { type, ...(button === undefined ? {} : { button }) }
+    }
+    case 'incrementElement':
+    case 'decrementElement':
+      return { type, id: stringValue(step.id, `${path}.id`) }
+    case 'discoverStoreKitConfig':
+    case 'clearStoreKitConfig':
+      return { type }
     case 'wait':
       return { type, ms: numberValue(step.ms, `${path}.ms`) }
     case 'waitFor': {
@@ -233,6 +273,40 @@ export function parsePerformStep(value: unknown, index: number): SimPerformStep
   }
 }
 
+// an unclosed touchDown leaves a pointer stuck down, and the batch abort path
+// would cancel it after the caller was told the batch failed. every batch is
+// self-contained (pointers never survive it), so a touchDown without its
+// touchUp or touchCancel in the same batch is rejected before anything runs.
+export function findUnbalancedTouchDown(
+  steps: readonly SimPerformStep[],
+): { index: number; pointerId: number } | null {
+  const open = new Map<number, number>()
+  const pointerIdOf = (step: SimPerformStep): number | null => {
+    if (
+      step.type !== 'touchDown' &&
+      step.type !== 'touchMove' &&
+      step.type !== 'touchUp' &&
+      step.type !== 'touchCancel'
+    ) {
+      return null
+    }
+    const pointerId = step.pointerId ?? 999
+    return Number.isSafeInteger(pointerId) ? pointerId : null
+  }
+  for (const [index, step] of steps.entries()) {
+    if (step.type === 'touchDown') {
+      const pointerId = pointerIdOf(step) ?? 999
+      if (!open.has(pointerId)) open.set(pointerId, index)
+    } else if (step.type === 'touchUp' || step.type === 'touchCancel') {
+      const pointerId = pointerIdOf(step)
+      if (pointerId !== null) open.delete(pointerId)
+    }
+  }
+  const next = open.entries().next()
+  if (next.done) return null
+  return { index: next.value[1], pointerId: next.value[0] }
+}
+
 export function parseStateOptions(value: unknown): SimStateOptions {
   const input = recordValue(value, 'state')
   const route = optionalBoolean(input, 'route', 'state')

package/src/bridge-contract.ts

@@ -163,6 +163,24 @@ export type PerformStep =
       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
@@ -179,6 +197,91 @@ export interface PerformOptions {
   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']