@avasapp/agent-bridge 0.4.2 → 0.6.0

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

@@ -1,22 +1,36 @@
 # See and use the screen
 
 ```sh
-npx agent-bridge call screen.snapshot                          # buttons, inputs, text on the focused screen (`hidden` counts what was skipped; {"all":true} lists everything)
-npx agent-bridge call screen.findText "Payment"                 # text or accessibility label; {"labels":false} for text only
-npx agent-bridge call screen.press '"add-plant"'               # by testID, label or text
-npx agent-bridge call screen.press '[{"at":[350,60]}]'          # icon-only button: by point; {"index":1} picks among matches; {"force":true} presses disabled
-npx agent-bridge call screen.press '["save-plant", {"scroll":true}]'   # scrolls an off-screen target into view first
-npx 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 agent-bridge call screen.refresh                            # pull to refresh (the RefreshControl's onRefresh); then screen.waitFor the data
-npx agent-bridge call screen.fill '["plant-name", "Fern"]'     # runs the input's handlers
-npx agent-bridge call screen.waitFor '"Name is required"'      # {"gone": true} waits for it to go
-npx agent-bridge call screen.waitFor '["Section title", {"scroll":true}]'   # also below the fold: scrolls it into view (not with gone)
+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
+npx @avasapp/agent-bridge call screen.waitFor '"Name is required"'      # {"gone": true} waits for it to go
+npx @avasapp/agent-bridge call screen.waitFor '["Section title", {"scroll":true}]'   # also below the fold: scrolls it into view (not with gone)
 ```
 
 `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)
+with `actions` in the snapshot. `press` calls its `onAccessibilityAction` with
+`activate`, as a screen reader's double tap does, and the reply says
+`via: "accessibilityAction:activate"`. A gesture control with no `actions`
+needs a real swipe from agent-device.
+
 A WebView shows in the snapshot as one element (`webview "checkout"`);
 `screen.*` can't reach inside it. See [webview.md](webview.md).
 

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

@@ -3,11 +3,11 @@
 ## Set state
 
 ```sh
-npx agent-bridge call query.pin '[["features"], <data>]'       # stays through refetches
-npx agent-bridge call store.call '["settings", "setTheme", "dark"]'
-npx agent-bridge call router.navigate /inbox
-npx agent-bridge call router.current
-npx agent-bridge call router.dismiss                            # closes a route-based modal
+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                            # React Navigation apps: nav.navigate Inbox, nav.current
+npx @avasapp/agent-bridge call router.dismiss                            # closes a route-based modal
 ```
 
 `router.back` only pops the navigator: an in-app modal or sheet the app renders
@@ -19,18 +19,38 @@ own tool (e.g. `modal.close`) if it has one; check `tools` first.
 Read the current value first and change only what you need:
 
 ```sh
-npx agent-bridge call query.get '["todos", 1]'             # a flat key or '[["todos", 1]]'
-npx agent-bridge call query.list '["todos"]'               # key prefix; shows isStale, isInvalidated, fetchStatus
-npx agent-bridge call query.refetch '["todos"]'            # {matched, refetched, data}; errors when nothing matches
-npx agent-bridge call store.get '["app", "auth.isLoggedIn"]'   # or ["app","auth","isLoggedIn"]
-npx agent-bridge call store.get '["app", {"pick": ["auth.isLoggedIn", "settings.fontScale"]}]'
-npx agent-bridge call store.get '["app", {"keys": true}]'  # top-level keys and types, no values
+npx @avasapp/agent-bridge call query.get '["todos", 1]'             # a flat key or '[["todos", 1]]'
+npx @avasapp/agent-bridge call query.list '["todos"]'               # key prefix; shows isStale, isInvalidated, fetchStatus
+npx @avasapp/agent-bridge call query.refetch '["todos"]'            # {matched, refetched, data}; errors when nothing matches
+npx @avasapp/agent-bridge call store.get '["app", "auth.isLoggedIn"]'   # or ["app","auth","isLoggedIn"]
+npx @avasapp/agent-bridge call store.get '["app", {"pick": ["auth.isLoggedIn", "settings.fontScale"]}]'
+npx @avasapp/agent-bridge call store.get '["app", {"keys": true}]'  # top-level keys and types, no values
 ```
 
 `query.get` errors on a key that is not cached (with similar keys), so a
 `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

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

@@ -5,15 +5,15 @@
 `tools`), use the same verbs on the page:
 
 ```sh
-npx agent-bridge call webview.list                              # name, url, loaded, allowed
-npx agent-bridge call webview.snapshot '"checkout"'             # buttons, links, inputs, text in the page
-npx agent-bridge call webview.press '["Pay now", {"webview": "checkout"}]'
-npx agent-bridge call webview.fill '["Email", "ada@example.com"]'   # {"submit":true} presses Enter
-npx agent-bridge call webview.waitFor '["Payment complete", {"timeoutMs": 8000}]'   # {"gone":true}
-npx agent-bridge call webview.messages '"checkout"'             # page <-> app, last 100, bodies cut at 2 KB
-npx agent-bridge call webview.message 17                        # one in full
-npx agent-bridge call webview.send '["checkout", {"type": "auth", "ok": true}]'      # as if the app sent it
-npx agent-bridge call webview.receive '["checkout", {"type": "done"}]'               # runs the app's onMessage
+npx @avasapp/agent-bridge call webview.list                              # name, url, loaded, allowed
+npx @avasapp/agent-bridge call webview.snapshot '"checkout"'             # buttons, links, inputs, text in the page
+npx @avasapp/agent-bridge call webview.press '["Pay now", {"webview": "checkout"}]'
+npx @avasapp/agent-bridge call webview.fill '["Email", "ada@example.com"]'   # {"submit":true} presses Enter
+npx @avasapp/agent-bridge call webview.waitFor '["Payment complete", {"timeoutMs": 8000}]'   # {"gone":true}
+npx @avasapp/agent-bridge call webview.messages '"checkout"'             # page <-> app, last 100, bodies cut at 2 KB
+npx @avasapp/agent-bridge call webview.message 17                        # one in full
+npx @avasapp/agent-bridge call webview.send '["checkout", {"type": "auth", "ok": true}]'      # as if the app sent it
+npx @avasapp/agent-bridge call webview.receive '["checkout", {"type": "done"}]'               # runs the app's onMessage
 ```
 
 Targets match in `screen.*` order: `data-testid` (also `data-test-id`,

package/skills/agent-bridge/references/writing-scenarios.md

@@ -56,8 +56,8 @@ useAgentBridge({ tools, scenarios })
   is back in its real state. If `apply` throws, the callbacks it had registered
   run straight away.
 - Tools: `scenario.list`, `scenario.apply [name, options?]` (applying an active
-  one again undoes it first) and `scenario.restore`. `npx agent-bridge scenarios`
-  lists them.
+  one again undoes it first) and `scenario.restore`.
+  `npx @avasapp/agent-bridge scenarios` lists them.
 - Flows declare scenarios with `export const scenario` or
   `export const scenarios`; see [flows.md](flows.md).
 
@@ -93,5 +93,5 @@ In a release build it's always open. `realtime.connection` isn't enough on its
 own: it hides the state from the app, but the client still connects.
 
 The agent-bridge repo's example app has a complete local `signedIn` in
-`example/src/dev/scenarios.ts`, and `example/flows/checks/signed-in.mjs`
+`example/src/dev/scenarios.ts`, and `example/flows/checks/signed-in.flow.mjs`
 declares it.