@avasapp/agent-bridge 0.5.0 → 0.6.0

package/dist/runtime/index.d.cts

@@ -1,5 +1,5 @@
-import { a as Transport, A as AgentBridgeOptions } from '../types-BmpykP1P.cjs';
-export { C as CallMessage, D as DeviceInfo, L as LogEntry, O as OptionsSchema, R as RUNTIME_MARKER, b as ResultMessage, S as Scenario, c as ScenarioContext, d as Scenarios, e as ToolDefinition, f as ToolFn, g as ToolInfo, T as Tools } from '../types-BmpykP1P.cjs';
+import { a as Transport, A as AgentBridgeOptions } from '../types-qlwdcGjt.cjs';
+export { C as CallMessage, D as DeviceInfo, L as LogEntry, O as OptionsSchema, R as RUNTIME_MARKER, b as ResultMessage, S as Scenario, c as ScenarioContext, d as Scenarios, e as ToolDefinition, f as ToolFn, g as ToolInfo, T as Tools } from '../types-qlwdcGjt.cjs';
 
 /**
  * Works in any React Native app served by Metro. The client evaluates one fixed

package/dist/store-common-j0cHHvBr.d.cts

@@ -0,0 +1,23 @@
+/**
+ * Keeps secrets out of what store.* prints. Either dotted paths per store
+ * (`{ auth: ['accessToken', 'user.phone'] }`), or a hook called for the store
+ * value and every nested value with its dotted path; what it returns is
+ * printed instead.
+ *
+ * Paths are store paths. A `store.call` result that is a piece of the store's
+ * state (same object, e.g. `() => get().user`) is matched by where it lives; a
+ * copy or derived value (`() => ({ ...get().user })`) is not, so its paths are
+ * matched relative to the result and store paths like `user.phone` won't apply.
+ * Use the hook, or don't return secrets from actions.
+ */
+type Redact = Record<string, string[]> | ((store: string, path: string, value: unknown) => unknown);
+/**
+ * Keeps secrets out of what an adapter prints, by the name of the slice or
+ * atom: dotted paths inside it (`{ auth: ['token', 'user.phone'] }`), or `true`
+ * for all of it (`{ authToken: true }`). Or a hook called for the whole value
+ * (path `''`) and every nested value with its dotted path; what it returns is
+ * printed instead.
+ */
+type NamedRedact = Record<string, string[] | true> | ((name: string, path: string, value: unknown) => unknown);
+
+export type { NamedRedact as N, Redact as R };

package/dist/{types-BmpykP1P.d.cts → types-qlwdcGjt.d.cts}

@@ -6,6 +6,10 @@ type CallMessage = {
     args?: unknown[];
     /** Device to run on. Expo's socket broadcasts, so every app sees every call. */
     to?: string;
+    /** A session's own: the journal tag it holds, so the reply carries the journal only when it is stale. */
+    journalAck?: string;
+    /** A session's own secret; the runtime keeps the first one it gets and ignores the journal calls of anyone else. */
+    journalKey?: string;
 };
 /** An error or warning the app logged, threw or left unhandled. */
 type LogEntry = {
@@ -39,6 +43,10 @@ type ResultMessage = ({
     loadId?: string;
     /** Areas (`store`, `query`, ...) whose `*.restore` has something to undo. */
     pending?: string[];
+    /** Goes up when something persistent changed that a restore could undo. */
+    journal?: number;
+    /** What each area could undo from storage; sent only to a session that proved it holds the key and a stale tag. */
+    journalData?: Record<string, unknown>;
 };
 type ToolInfo = {
     name: string;
@@ -82,6 +90,20 @@ type ToolDefinition = ToolFn | {
     pending?: (options?: {
         detail?: boolean;
     }) => unknown;
+    /**
+     * On a `*.restore` tool: what it could undo that lives in persistent
+     * storage (so it outlives a reload), as JSON, or undefined. A session
+     * keeps it, and hands it to `adopt` after the app reloads.
+     */
+    journal?: () => unknown;
+    /**
+     * Takes what `journal` returned before a reload and re-arms the undo for
+     * it in the new load, without changing the app. Returns an
+     * `AdoptResult`.
+     */
+    adopt?: (data: unknown) => unknown;
+    /** Goes up when `journal` may have changed. Not shared state: keep it in the adapter's own module. */
+    journalRev?: () => number;
 };
 /** Tools by name. Namespace them with a dot, e.g. `query.pin`. */
 type Tools = Record<string, ToolDefinition>;

package/entries/async-storage.cjs

@@ -0,0 +1,9 @@
+'use strict'
+
+// Metro inlines NODE_ENV and drops the dead branch, so a release bundle
+// never includes the bridge, the same way react/index.js works.
+if (process.env.NODE_ENV === 'production') {
+  module.exports = require('../dist/noop/async-storage.cjs')
+} else {
+  module.exports = require('../dist/adapters/async-storage.cjs')
+}

package/entries/device.cjs

@@ -0,0 +1,9 @@
+'use strict'
+
+// Metro inlines NODE_ENV and drops the dead branch, so a release bundle
+// never includes the bridge, the same way react/index.js works.
+if (process.env.NODE_ENV === 'production') {
+  module.exports = require('../dist/noop/device.cjs')
+} else {
+  module.exports = require('../dist/adapters/device.cjs')
+}

package/entries/jotai.cjs

@@ -0,0 +1,9 @@
+'use strict'
+
+// Metro inlines NODE_ENV and drops the dead branch, so a release bundle
+// never includes the bridge, the same way react/index.js works.
+if (process.env.NODE_ENV === 'production') {
+  module.exports = require('../dist/noop/jotai.cjs')
+} else {
+  module.exports = require('../dist/adapters/jotai.cjs')
+}

package/entries/react-navigation.cjs

@@ -0,0 +1,9 @@
+'use strict'
+
+// Metro inlines NODE_ENV and drops the dead branch, so a release bundle
+// never includes the bridge, the same way react/index.js works.
+if (process.env.NODE_ENV === 'production') {
+  module.exports = require('../dist/noop/react-navigation.cjs')
+} else {
+  module.exports = require('../dist/adapters/react-navigation.cjs')
+}

package/entries/redux.cjs

@@ -0,0 +1,9 @@
+'use strict'
+
+// Metro inlines NODE_ENV and drops the dead branch, so a release bundle
+// never includes the bridge, the same way react/index.js works.
+if (process.env.NODE_ENV === 'production') {
+  module.exports = require('../dist/noop/redux.cjs')
+} else {
+  module.exports = require('../dist/adapters/redux.cjs')
+}

package/entries/secure-store.cjs

@@ -0,0 +1,9 @@
+'use strict'
+
+// Metro inlines NODE_ENV and drops the dead branch, so a release bundle
+// never includes the bridge, the same way react/index.js works.
+if (process.env.NODE_ENV === 'production') {
+  module.exports = require('../dist/noop/secure-store.cjs')
+} else {
+  module.exports = require('../dist/adapters/secure-store.cjs')
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avasapp/agent-bridge",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Let coding agents drive a running React Native app directly: seed state, flip flags, navigate and check the screen in about a millisecond per call, with no taps.",
   "type": "module",
   "license": "MIT",
@@ -38,6 +38,14 @@
       "types": "./dist/adapters/zustand.d.cts",
       "default": "./entries/zustand.cjs"
     },
+    "./redux": {
+      "types": "./dist/adapters/redux.d.cts",
+      "default": "./entries/redux.cjs"
+    },
+    "./jotai": {
+      "types": "./dist/adapters/jotai.d.cts",
+      "default": "./entries/jotai.cjs"
+    },
     "./react-native-mmkv": {
       "types": "./dist/adapters/react-native-mmkv.d.cts",
       "default": "./entries/react-native-mmkv.cjs"
@@ -46,6 +54,10 @@
       "types": "./dist/adapters/expo-router.d.cts",
       "default": "./entries/expo-router.cjs"
     },
+    "./react-navigation": {
+      "types": "./dist/adapters/react-navigation.d.cts",
+      "default": "./entries/react-navigation.cjs"
+    },
     "./react-native-webview": {
       "types": "./dist/adapters/react-native-webview.d.cts",
       "default": "./entries/react-native-webview.cjs"
@@ -66,6 +78,18 @@
       "types": "./dist/adapters/socket-io.d.cts",
       "default": "./entries/socket.io.cjs"
     },
+    "./async-storage": {
+      "types": "./dist/adapters/async-storage.d.cts",
+      "default": "./entries/async-storage.cjs"
+    },
+    "./secure-store": {
+      "types": "./dist/adapters/secure-store.d.cts",
+      "default": "./entries/secure-store.cjs"
+    },
+    "./device": {
+      "types": "./dist/adapters/device.d.cts",
+      "default": "./entries/device.cjs"
+    },
     "./client": {
       "types": "./dist/client/index.d.ts",
       "import": "./dist/client/index.js",
@@ -92,7 +116,11 @@
     "cdp",
     "tanstack-query",
     "zustand",
+    "redux",
+    "jotai",
     "mmkv",
+    "async-storage",
+    "secure-store",
     "realtime",
     "ably",
     "socket.io",
@@ -135,12 +163,15 @@
   "devDependencies": {
     "@changesets/cli": "^3.0.3",
     "@expo/devtools": "^57.0.1",
+    "@reduxjs/toolkit": "^2.14.0",
     "@tanstack/query-core": "^5.90.0",
     "@types/bun": "^1.4.2",
     "@types/react": "^19.3.0",
     "@types/ws": "^8.18.1",
     "ably": "^2.29.0",
     "happy-dom": "^20.14.5",
+    "jotai": "^3.0.2",
+    "redux-persist": "^6.0.0",
     "socket.io-client": "^4.8.4",
     "tsup": "^8.5.1",
     "typescript": "~6.0.3",

package/skills/agent-bridge/SKILL.md

@@ -33,6 +33,11 @@ config on every call, so a project `.npmrc` with keys npm doesn't know prints
 `npm warn Unknown project config` into your output each time, and it adds
 roughly 200 ms more startup per call (machine-dependent).
 
+If the app's tools are already in your tool list as an MCP server
+(`agent-bridge mcp`; names like `screen_snapshot` for `screen.snapshot`), call
+those: each takes `args`, an array of the tool's arguments, and `full: true` for
+a result over 32 KB. If the list is empty or a call fails, call `agent_bridge_status`. A failed call keeps the session's own error (`may or may not have run`): check state before repeating a call that changes it. The rest of this skill applies the same way.
+
 ## Start a session
 
 ```sh
@@ -45,15 +50,25 @@ If Metro runs on another port, pass the same `--metro` (or set
 `Nothing is listening on …` error names the Metro it found instead and its apps;
 check it's yours before switching to it.
 
+Calls take `--timeout <ms>` (default 10000) for a slow call. To drive two apps
+at once, start named sessions (`session start --name ios`, `--name android`) and
+pass `--session <name>` on each call. A session is found from the nearest
+`package.json` above where you run: a command at a monorepo root also finds the
+one session started in an app folder under it (downward only; a nested checkout
+with its own `.git` doesn't count). With several app sessions under the root it
+connects directly, so pass `--session`.
+
 A session holds one connection for all your calls. It stops itself after 15
 minutes without calls and runs `bridge.restore` when it does.
 
-A JS reload (an error screen's Retry, or `app.reload`) throws away every pending
-restore. The session notices the app is a new runtime and reports
-`app reloaded; N pending restores lost: store, query` (the areas that
-had something to undo) as a warning on the next call (also on a failed one) and
-again in `session stop`. When you see it, redo your setup: nothing you changed
-before the reload will be undone.
+A JS reload (an error screen's Retry, or `app.reload`) throws away the app's
+undo state, except what lives in storage: string `mmkv.set`/`mmkv.delete` and
+persisted zustand stores are kept by the session and still undone by
+`bridge.restore`. The session reports what it kept, and
+`app reloaded; N pending restores lost: query, ...` (the areas that had
+something to undo) for the rest, as a warning on the next call (also on a
+failed one) and again in `session stop`. For the lost ones, redo your setup:
+they will not be undone.
 
 If a call fails with `app not connected; reconnecting` or `The app is gone`, the
 session lost the app (Metro or the app is down, or mid-reload). It retries on
@@ -61,6 +76,13 @@ its 5 s health check and on your next call: wait a few seconds and call again.
 `session stop` still works. A session never moves to another app: `<app> is
 not connected; connected: …` means its app is gone and something else is there.
 
+If a call fails with `the app reloaded during <tool>; it may or may not have run`
+(or `disconnected`, `the connection dropped`), the connection dropped mid-call
+and the session did not repeat it (only read-only tools are repeated). Check the screen or state before you call again.
+
+A `timeoutMs` in the options of `screen.waitFor` or `webview.waitFor` longer
+than the call timeout stretches it, so you don't need `--timeout` for that.
+
 If `tools` fails with "agent-bridge isn't running", the hook isn't mounted in
 this build. Say so; don't fall back to tapping silently.
 
@@ -99,15 +121,23 @@ real account instead. If you're asked to add one, read
 ## See and use the screen
 
 ```sh
-npx @avasapp/agent-bridge call screen.snapshot                       # buttons, inputs, text on the focused screen
+npx @avasapp/agent-bridge call screen.snapshot                       # one line per button, input, text on the focused screen (--json for rects)
 npx @avasapp/agent-bridge call screen.press '"add-plant"'            # by testID, label or text
 npx @avasapp/agent-bridge call screen.fill '["plant-name", "Fern"]'  # runs the input's handlers
 npx @avasapp/agent-bridge call screen.waitFor '"Name is required"'   # {"gone": true} waits for it to go
 npx @avasapp/agent-bridge call router.navigate /inbox
 ```
 
+Check `tools` for `router.*` (expo-router) or `nav.*` (React Navigation). `nav.*`
+takes route names (`nav.navigate Inbox`, `nav.popTo Home`), and paths only if the
+app passed `linking`; read the returned `warning`.
+
 `press` and `fill` return once the app has rendered the result, so the next
-check sees it. Arguments are a JSON array (or a single JSON value): the array is
+check sees it. `press` on plain text presses the nearest pressable ancestor.
+Unfocused tabs (native tabs included) and screens under others count as hidden.
+Screen tools need React Native's New Architecture (Fabric); where nothing can
+be measured they fail with a message saying so (`snapshot --all` and
+`findText` still return text, without rects). Arguments are a JSON array (or a single JSON value): the array is
 spread into the tool's arguments.
 
 ## Watch for errors
@@ -137,6 +167,7 @@ from the real state.
 | Read or set query data, store values, routes, modals; get argument shapes right | [references/state.md](references/state.md) |
 | Mock or inspect requests, or deal with strict network mode | [references/network.md](references/network.md) |
 | See or fake realtime messages (`realtime.*` in `tools`) | [references/realtime.md](references/realtime.md) |
+| Fake a deep link, background, offline, a push or the clock (`device.*` in `tools`) | [references/device.md](references/device.md) |
 | Handle a result over 32 KB or an argument over ~128 KB | [references/large-data.md](references/large-data.md) |
 | Run many calls at once, write a flow file, or measure timing | [references/flows.md](references/flows.md) |
 | Understand what restore undoes, or fix a value restore got wrong | [references/restore.md](references/restore.md) |

package/skills/agent-bridge/references/device.md

@@ -0,0 +1,21 @@
+# Device events (`device.*`)
+
+Only there if the app added `deviceTools`; check `bridge.tools`.
+
+```sh
+npx @avasapp/agent-bridge call device.openUrl '"myapp://orders/5"'   # deep link into the running app; returns the route when the app passes navigation
+npx @avasapp/agent-bridge call device.appState '"background"'        # then '"active"'
+npx @avasapp/agent-bridge call device.offline true                   # fetch, XHR and NetInfo; false goes back
+npx @avasapp/agent-bridge call device.notification '[{"title":"Hi","data":{"id":5}},{"tapped":true}]'
+npx @avasapp/agent-bridge call device.setTime '"2030-01-02T03:04:05Z"'   # only with time: true
+npx @avasapp/agent-bridge call device.restore
+```
+
+- `device.openUrl` is for a running app. A cold start reads its URL before the bridge can fake it: open that link with agent-device.
+- `device.offline` fails mocked requests too. Metro stays reachable.
+- Without `{tapped:true}` a notification calls the received listeners (app open); with it, the response listeners.
+- The clock moves `Date.now()` and `new Date()` only; timers do not move. After `device.setTime`, call `device.appState '"background"'` then `'"active"'` so query caches recheck staleness (`active` alone does nothing when the app is already active). JS-driven `Animated` animations and Reanimated worklets are not shifted safely.
+- `device.offline` shows in `net.log` as `(device offline)`. NetInfo is faked only for listeners, `useNetInfo` and `NetInfo.refresh`; `fetch('wifi')` and a real native network event are not.
+- `device.notification` returns `listeners`; 0 means nothing heard it.
+- `device.openUrl` also reaches `useLinkingURL()`, but `getLinkingURL()` still reads the native value.
+- `bridge.pending` lists what is set under `device`, and `bridge.restore` undoes it.

package/skills/agent-bridge/references/flows.md

@@ -35,11 +35,10 @@ result, and for timing checks. Name it `flows/<name>.flow.mjs` in the app: plain
 ```js
 export const scenario = 'signedIn'   // applied first, undone after, even on failure
 
-export default async ({ step }) => {
+export default async ({ step, expect }) => {
   await step('open form', 'screen.press', 'add-plant')
   await step('save empty', 'screen.press', 'save-plant')
-  await step('error shown', 'screen.waitFor', 'Name is required')
-  await step('undo', 'bridge.restore')
+  await expect.text('Name is required')   // also expect.gone, expect.route, expect.result
 }
 ```
 
@@ -56,6 +55,17 @@ when the flow fails. The flow gets what each scenario's `apply` returned as
 `scenarios.signedIn`. A failed restorer makes the run exit non-zero.
 `--scenario` replaces a declared one of the same name.
 
+Run several at once: `run flows/` (a directory's `*.flow.mjs`), several files, or a
+glob, in order on one connection, with a pass/fail line each and a summary; exit 1 if
+any failed. `--bail` stops at the first failure, `--grep <text>` filters by name or path
+(relative to here), `--reporter json|junit` is for CI: report on stdout with all
+other output on stderr, or `--out report.xml`. Globs only match `*.flow.mjs`. Every flow ends with
+`bridge.restore`, pass or fail (it is global: through a session it also undoes what
+you set up by hand first); `--keep` skips it to debug. A failed flow prints the
+screen elements and route. `expect.text(t)`, `expect.gone(t)`, `expect.route(path)`
+and `expect.result(tool, args, match)` (a RegExp matches a string) throw readable
+messages.
+
 `step` takes the same argument shapes as `call`; see [state.md](state.md).
 
 ## Timing

package/skills/agent-bridge/references/network.md

@@ -3,7 +3,8 @@
 ```sh
 npx @avasapp/agent-bridge call net.mock '["/inbox", {"status": 500}]'   # or {"offline": true}
 npx @avasapp/agent-bridge call net.log '[{"since": 1700000000000}]'     # entries carry startedAt (epoch ms)
-npx @avasapp/agent-bridge call net.entry 3                              # one request, bodies whole
+npx @avasapp/agent-bridge call net.entry 3                              # one request: bodies whole, headers (credential headers such as Authorization, Cookie, *-token, *-api-key cut unless {"full": true} second)
+npx @avasapp/agent-bridge call net.waitFor '[{"path": "/orders", "method": "POST"}, {"timeoutMs": 5000}]'  # wait for it to finish
 npx @avasapp/agent-bridge call net.mockFromLog '[3, {"user": {"name": "Moss"}}]'  # a real response, patched
 npx @avasapp/agent-bridge call net.mocks '[{"full": true}]'             # active mocks; bodies over ~2 KB are cut unless full
 ```
@@ -15,6 +16,23 @@ The newest mock is tried first, so a later broad mock shadows an earlier
 specific one: give the specific one `{"priority": 1}` as `net.mock`'s third
 argument, or read `shadows` in its result.
 
+## What a mock matches
+
+A string is a URL substring: `"/orders"` also answers `/orders/5/items`. For
+exact matches use the object form (every key given must match):
+
+```sh
+call net.mock '[{"path": "/orders/:id"}, {"json": {"id": 5}}]'                 # whole path, any host, query ignored; * is the rest
+call net.mock '[{"graphql": "GetUser"}, {"json": {"data": {}}}]'               # operationName in the POST body or ?operationName=
+call net.mock '[{"path": "/search", "body": {"filter": {"status": "open"}}}, {"json": []}]'  # JSON body contains this
+```
+
+`path` ignores case and the query, takes `:name` only as a whole segment (`/items:batchGet` is literal), and a trailing slash is optional; spaces are refused (write `%20`). A mock with only `body` or `graphql` looks at every request. `body` matches objects by key (extra keys are fine) and arrays by length and
+position; form and binary bodies never match. A batched GraphQL array body
+isn't matched by `graphql`; use `body`. `net.mockFromLog` returns a `warning` when a POST body wasn't kept and the mock may answer other operations. The reply's `matches` says it in words.
+`net.waitFor` takes the same match; pass `{"sinceId": <id from net.log>}` so an
+older request doesn't satisfy it.
+
 For a mock body too big for the command line, pass it as `@file`; see
 [large-data.md](large-data.md).
 

package/skills/agent-bridge/references/realtime.md

@@ -5,7 +5,7 @@ them instead of waiting for a backend to send one:
 
 ```sh
 npx @avasapp/agent-bridge call realtime.channels                         # what the app listens on
-npx @avasapp/agent-bridge call realtime.log '{"channel": "chat"}'        # recent messages, real and faked
+npx @avasapp/agent-bridge call realtime.log '{"channel": "chat"}'        # recent messages: real, faked, and `sent: true` ones the app sent (credential keys are [redacted] unless `{"full":true}`)
 npx @avasapp/agent-bridge call realtime.mute '"chat"'                    # stop real ones overwriting your state
 npx @avasapp/agent-bridge call realtime.emit '["chat", {"name": "message", "data": {"text": "hi"}}]'
 npx @avasapp/agent-bridge call realtime.connection '"disconnected"'      # null goes back to the real state

package/skills/agent-bridge/references/restore.md

@@ -7,14 +7,21 @@ npx @avasapp/agent-bridge session stop             # runs bridge.restore
 npx @avasapp/agent-bridge session stop --keep      # leaves the app as is; warns about anything still pending
 ```
 
-`bridge.restore` unpins queries, puts back store and MMKV values, removes
+`bridge.restore` unpins queries, puts back store, MMKV, AsyncStorage and SecureStore values, removes
 network mocks, unmutes realtime channels and ends a faked connection state,
 then undoes active scenarios (newest first), so the next run starts from the
 real state. With `session stop --keep`, a later restore will still apply what
 is pending.
 
-A JS reload throws away every pending restore; the session warns
-`app reloaded; N pending restores lost`. Redo your setup when you see it.
+A JS reload throws away the app's undo state. In a session, what lives in
+storage is kept: `mmkv.set`/`mmkv.delete` of string values and `store.set`/
+`store.call` on a persisted zustand store (one made with `persist`) are still
+undone by `bridge.restore` after the reload, and the next call says
+`app reloaded; kept N undos across the reload (...)`. A value the app changed
+after your write is left alone and named. Everything else (stores that are not
+persisted, redux, jotai, AsyncStorage and SecureStore changes, queries, mocks, `onRestore`) is lost: the session warns
+`app reloaded; N pending restores lost: ...`. Redo that setup when you see it. After a reload that also lost non-persisted changes, check `bridge.pending`: `kept N undos` does not list what was lost in the same area. `not kept across reload: store:key` means that key (a Set, Date, class instance, one `partialize` renames, or one `redact` hides) is not journaled, so the reload keeps the agent's value for it; `could not re-arm after the reload: ...` means a store or MMKV instance never became ready and its undo was dropped; `<tool> was cut off; ... that undo may be lost` means a write's reply was lost and may not be journaled.
+AsyncStorage and SecureStore values stay on disk across a reload with their old values gone, so run `bridge.restore` before `app.reload`. A key the app wrote after the agent did is left alone and returned under `skipped`.
 
 ## Mocked queries
 
@@ -38,6 +45,17 @@ with `store.set` snapshots the broken one.
   keeps the current value and drops the snapshot.
 - `store.set <store> {}` arms the snapshot before you drive the UI.
 
+`redux.*` and `jotai.*` work the same way, under their own names. `redux.set`
+snapshots each slice on its first change and restore puts back only those
+slices; `redux.dispatch` snapshots the whole state on its first call, so restore
+puts all of it back, including what the app changed in other slices after that.
+A slice or atom the app changed after the agent is left alone and returned in
+`{restored, skipped}`. `redux.commit` drops the snapshots. Jotai snapshots each
+atom on its first `jotai.set`; `jotai.commit <atom>` drops one. These snapshots
+live in memory, so **restore before `app.reload`**: with redux-persist or
+`atomWithStorage` the agent's values stay saved until then. With an async
+`atomWithStorage`, `jotai.get` the atom before the first set.
+
 ## WebViews
 
 `webview.press`, `fill` and `send` change the page and app, and restore does

package/skills/agent-bridge/references/screen.md

@@ -1,13 +1,19 @@
 # See and use the screen
 
 ```sh
-npx @avasapp/agent-bridge call screen.snapshot                          # buttons, inputs, text on the focused screen (`hidden` counts what was skipped; {"all":true} lists everything)
+npx @avasapp/agent-bridge call screen.snapshot                          # one line per element: `button #save "Save" disabled` (`hidden` counts what was skipped; {"all":true} lists everything)
+npx @avasapp/agent-bridge call screen.snapshot '{"kinds":["input","button"],"within":"checkout-form"}'   # only those kinds, only inside that target
+npx @avasapp/agent-bridge call screen.snapshot --json                  # JSON with rects and `role` (the text form already shows actions=, readonly, offscreen); `@x,y` on a line is `{"at":[x,y]}`, `index=N` is `{"index":N}`
 npx @avasapp/agent-bridge call screen.findText "Payment"                 # text or accessibility label; {"labels":false} for text only
 npx @avasapp/agent-bridge call screen.press '"add-plant"'               # by testID, label or text
 npx @avasapp/agent-bridge call screen.press '[{"at":[350,60]}]'          # icon-only button: by point; {"index":1} picks among matches; {"force":true} presses disabled
 npx @avasapp/agent-bridge call screen.press '["save-plant", {"scroll":true}]'   # scrolls an off-screen target into view first
 npx @avasapp/agent-bridge call screen.press '"Swipe to confirm"'        # no onPress: sends the "activate" accessibility action
 npx @avasapp/agent-bridge call screen.press '["Volume", {"action":"increment"}]'   # any action in the element's snapshot `actions`
+npx @avasapp/agent-bridge call screen.press '["Item 80", {"scroll":true}]'   # a row a FlatList has not rendered yet: pages the main list until it shows up (waitFor does not page)
+npx @avasapp/agent-bridge call screen.press '["Message", {"long":true}]'   # onPressIn, onLongPress, onPressOut; errors when there is no onLongPress
+npx @avasapp/agent-bridge call screen.press '"dark-mode"'                  # a Switch is toggled with onValueChange(!value)
+npx @avasapp/agent-bridge call screen.setValue '["volume", 7]'             # Switch true/false, Slider number, Picker or SegmentedControl item; reads the value back
 npx @avasapp/agent-bridge call screen.scroll '"Notes"'                   # bring a target to the middle of its ScrollView/FlatList; {"toEnd":true}, {"by":400}, [{"toEnd":true},{"within":"list"}]
 npx @avasapp/agent-bridge call screen.refresh                            # pull to refresh (the RefreshControl's onRefresh); then screen.waitFor the data
 npx @avasapp/agent-bridge call screen.fill '["plant-name", "Fern"]'     # runs the input's handlers
@@ -16,7 +22,7 @@ npx @avasapp/agent-bridge call screen.waitFor '["Section title", {"scroll":true}
 ```
 
 `press` and `fill` return once the app has rendered the result, so the next
-check sees it. `fill` skips the keyboard: autocorrect and native-only input
+check sees it. `fill` also takes `{"submit":true}` and `{"type":true}` (per-character, for debounced search); `""` clears. A press that hit an ancestor's handler says `via: "ancestor"`: check it did what you meant. `fill` skips the keyboard: autocorrect and native-only input
 behaviour need one real typing step from agent-device.
 
 A swipe-to-confirm or slider with no `onPress` shows as a button (or a view)

package/skills/agent-bridge/references/state.md

@@ -6,7 +6,7 @@
 npx @avasapp/agent-bridge call query.pin '[["features"], <data>]'       # stays through refetches
 npx @avasapp/agent-bridge call store.call '["settings", "setTheme", "dark"]'
 npx @avasapp/agent-bridge call router.navigate /inbox
-npx @avasapp/agent-bridge call router.current
+npx @avasapp/agent-bridge call router.current                            # React Navigation apps: nav.navigate Inbox, nav.current
 npx @avasapp/agent-bridge call router.dismiss                            # closes a route-based modal
 ```
 
@@ -31,6 +31,26 @@ npx @avasapp/agent-bridge call store.get '["app", {"keys": true}]'  # top-level
 `null` reply means the data is undefined. For a large query, narrow it with
 `pages` or `path`; see [large-data.md](large-data.md).
 
+## Redux and Jotai
+
+Same ideas under their own prefixes, so a Zustand `store.*` and these can coexist.
+
+```sh
+npx @avasapp/agent-bridge call redux.list
+npx @avasapp/agent-bridge call redux.get '["auth", "user.name"]'      # or [] for the whole state
+npx @avasapp/agent-bridge call redux.dispatch '[{"type":"cart/add","payload":"apple"}]'
+npx @avasapp/agent-bridge call redux.set '["auth", {"token": "abc"}]'  # merge into a slice
+npx @avasapp/agent-bridge call jotai.list                              # read-write or read-only
+npx @avasapp/agent-bridge call jotai.get '["user", "name"]'
+npx @avasapp/agent-bridge call jotai.set '["count", 5]'                # writable atoms only
+```
+
+`redux.set` and restore need the app to wrap its root reducer in
+`bridgeReducer()` (inside `persistReducer` with redux-persist); without it they
+fail and say so. `redux.set` merges into object slices only. `redux.dispatch`
+sends plain actions only. `jotai.set` refuses atoms whose value isn't the one
+sent (action atoms, `atomWithReducer`). Redacted slices, atoms and paths print as `"[redacted]"`.
+
 ## Argument shapes
 
 Arguments are a JSON array (or a single JSON value): the array is spread into