@omniaibot/win-x64 1.1.0 → 1.1.6

package/bin/omnibot-windows-x64/omnibot/references/runtime-and-status.md

@@ -0,0 +1,111 @@
+# Runtime and Status
+
+Use this file before troubleshooting. Runtime checks establish whether the daemon, extension, browser, visibility mode, license, and packaged skills are healthy.
+
+## Startup Check
+
+Run this sequence before diagnosing browser failures:
+
+```bash
+omnibot doctor
+omnibot status
+omnibot tabs
+omnibot visibility status
+omnibot browser current
+omnibot license status
+```
+
+Interpretation:
+
+- `doctor` checks daemon and extension health.
+- `status` checks daemon status only (lighter than `doctor`).
+- `tabs` proves connected tabs are visible and provides tab ids.
+- `visibility status` shows whether automation is visible, background, dedicated-profile, or headless.
+- `browser current` shows current browser runtime ownership.
+- `license status` verifies license state.
+
+If the extension is not connected, open Chrome or Edge with the omnibot extension loaded and keep an HTTP/HTTPS page open.
+
+## Daemon Lifecycle
+
+Top-level shortcuts:
+
+```bash
+omnibot status   # Show daemon status
+omnibot start    # Start the daemon
+omnibot stop     # Stop the daemon
+omnibot run      # Run daemon in foreground
+```
+
+Full form (also supported):
+
+```bash
+omnibot daemon run
+omnibot daemon start
+omnibot daemon stop
+omnibot daemon status
+```
+
+## doctor
+
+```bash
+omnibot doctor
+```
+
+Use `doctor` first when commands fail, tabs are empty, screenshots fail, or the agent cannot reach the browser.
+
+## tabs
+
+```bash
+omnibot tabs
+```
+
+Use `tabs` to discover tab ids. Save the target tab id and use it on every page-state command:
+
+```bash
+OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>
+```
+
+## browser list/current
+
+```bash
+omnibot browser list
+omnibot browser current
+```
+
+Use browser status when multiple browser runtimes or agents may be active.
+
+## visibility status
+
+```bash
+omnibot visibility status
+```
+
+Use visibility status to confirm whether automation should share the user's visible browser state. Headless and dedicated-profile modes do not automatically inherit user login.
+
+## license status
+
+```bash
+omnibot license status
+```
+
+Use license status when runtime checks pass but features appear unavailable.
+
+## skills path
+
+```bash
+omnibot skills path
+```
+
+Use skills path to locate packaged skills for installation or inspection.
+
+## Skills Install
+
+```bash
+omnibot skills install --agent hermes --profile nuwa
+omnibot skills install --agent opencode
+omnibot skills install --agent claude
+omnibot skills install --agent codex
+```
+
+Install only when setting up or repairing an agent integration. It is not part of normal page operations.

package/bin/omnibot-windows-x64/omnibot/references/session-and-tabs.md

@@ -0,0 +1,164 @@
+# Sessions and Tabs
+
+Sessions and tabs are core reliability concepts, not advanced usage.
+
+## Session First
+
+`OMNIBOT_SESSION_TOKEN` is mandatory for every workflow.
+
+```bash
+OMNIBOT_SESSION_TOKEN=research omnibot tabs
+OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>
+```
+
+The same token keeps one workflow isolated. Different tokens prevent independent agents from sharing default state.
+
+## Tab Explicit
+
+`--tab-id <TAB_ID>` is mandatory for every page-state command.
+
+```bash
+OMNIBOT_SESSION_TOKEN=checkout omnibot get url --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot click --tab-id <TAB_ID> @e4
+OMNIBOT_SESSION_TOKEN=checkout omnibot get url --tab-id <TAB_ID>
+```
+
+Do not rely on default tab, active tab, current tab, or previous targeting state.
+
+## Explicit Targeting Model
+
+Page-state commands never infer a target tab. Always pass `--tab-id <TAB_ID>` for commands that read or mutate page state.
+
+Transport selection is internal. Omnibot may use any connected extension WebSocket to deliver extension-level commands, but that transport tab is never the page target.
+
+Do not use the first returned tab, `tabs[0]`, browser active tab, newest tab, or prior command state as a target.
+
+## Transport Is Not Target
+
+Omnibot can send extension commands through any connected extension WebSocket tab. That transport tab is not the page target. The target is only the tab id passed in the command, for example `--tab-id edge-client:123`.
+
+Safe sequence:
+
+```bash
+OMNIBOT_SESSION_TOKEN=research omnibot navigate https://example.com
+OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id edge-client:123
+OMNIBOT_SESSION_TOKEN=research omnibot click --tab-id edge-client:123 @e4
+OMNIBOT_SESSION_TOKEN=research omnibot wait --text "Saved" --tab-id edge-client:123
+```
+
+Unsafe sequence:
+
+```bash
+OMNIBOT_SESSION_TOKEN=research omnibot tabs
+OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i
+```
+
+The unsafe sequence has no target. Do not infer target from first tab, active tab, or prior operation.
+
+## Safe Browser Test Cleanup
+
+Browser integration tests must only close tabs they created:
+
+1. Record the list of existing tabs before creating fixtures.
+2. Create a unique fixture tab per case.
+3. Store the returned full tab id.
+4. Pass that id to every page-state command.
+5. Close only stored fixture ids in cleanup.
+6. Verify user tabs remain present after the test.
+
+## Why Both
+
+- Session = workflow isolation.
+- Tab ID = page targeting.
+
+Session alone does not prove which page receives a command. Tab ID alone does not isolate concurrent agents. Use both.
+
+## Ref Scope
+
+`@eN` refs are tab-scoped.
+
+Never reuse `@eN` across tabs. Never assume a ref remains valid after navigation, reload, major DOM changes, or a different snapshot.
+
+```bash
+OMNIBOT_SESSION_TOKEN=checkout omnibot snapshot -i --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=checkout omnibot click --tab-id <TAB_ID> @e4
+OMNIBOT_SESSION_TOKEN=checkout omnibot snapshot -i --tab-id <TAB_ID>
+```
+
+## Multi-Agent Pattern
+
+Agent A:
+
+```bash
+OMNIBOT_SESSION_TOKEN=research
+```
+
+Agent B:
+
+```bash
+OMNIBOT_SESSION_TOKEN=checkout
+```
+
+Agent C:
+
+```bash
+OMNIBOT_SESSION_TOKEN=debug
+```
+
+Each agent must:
+
+1. Set a stable token.
+2. Discover or create a tab.
+3. Save the tab id.
+4. Pass `--tab-id <TAB_ID>` on every page-state command.
+5. Run `snapshot` -> action -> verify, or `get/is` -> action -> `get/is`.
+
+Example:
+
+```bash
+OMNIBOT_SESSION_TOKEN=research omnibot tab new https://example.com --label research
+OMNIBOT_SESSION_TOKEN=research omnibot get url --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>
+```
+
+## No Implicit Targeting
+
+Omnibot does not provide a workflow-level current tab command. Every command that reads or changes page state must receive `--tab-id <TAB_ID>` in that command invocation.
+
+This prevents stale target state and cross-agent tab confusion.
+
+## browser claim/release
+
+Use `browser claim` and `browser release` in multi-browser or multi-runtime scenarios where an agent must explicitly own or release a browser tab.
+
+```bash
+OMNIBOT_SESSION_TOKEN=research omnibot browser list
+OMNIBOT_SESSION_TOKEN=research omnibot browser current
+OMNIBOT_SESSION_TOKEN=research omnibot browser claim 123
+OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id 123
+OMNIBOT_SESSION_TOKEN=research omnibot browser release 123
+```
+
+Claiming does not replace `--tab-id`. It only documents or coordinates ownership.
+
+## visibility
+
+Visibility controls where automation runs:
+
+- `visible`: controls the user's already-open real browser tabs and preserves visible session state.
+- `background`: avoids foregrounding tabs unless requested.
+- `dedicated-profile`: launches or uses a separate profile.
+- `headless`: uses a headless browser context.
+- `launch`: starts a dedicated-profile or headless browser with an explicit user data dir.
+
+Examples:
+
+```bash
+omnibot visibility status
+omnibot visibility set visible
+omnibot visibility set background
+omnibot visibility set headless --user-data-dir /tmp/omnibot-headless
+omnibot visibility launch headless --user-data-dir /tmp/omnibot-headless
+```
+
+Headless and dedicated-profile modes do not automatically share the user's current tabs or login state. Verify login state before assuming access.

package/bin/omnibot-windows-x64/omnibot/skills/omnibot/SKILL.md

@@ -12,7 +12,7 @@ metadata:
 
 Omnibot is Browser Infrastructure for AI Agents.
 
-It connects Hermes, Claude Code, Codex, OpenCode, MCP Agent Runtime, and other agent systems to a real Chromium browser through the local omnibot daemon and CLI.
+It connects Hermes, Claude Code, Codex, OpenCode, and other agent systems to a real Chromium browser through the local omnibot daemon and CLI.
 
 This skill is an execution specification for agents. It is not a human command manual.
 
@@ -44,7 +44,7 @@ Every page-state workflow must use both controls:
 
 They are not substitutes. Session controls which workflow owns state. Tab ID controls which page receives the command.
 
-Do not rely on `switch-tab`, default tab, active tab, current tab, or prior targeting state for multi-step workflows.
+Do not rely on default tab, active tab, current tab, or prior targeting state. Every page command requires explicit `--tab-id`.
 
 Use the same token inside one workflow. Use different tokens for independent workflows.
 
@@ -108,6 +108,19 @@ Start from the task, not the command name. Use operation patterns for read, clic
 
 Use fallback tiers only after standard patterns fail. Collect evidence separately from fallback execution. The command reference is only a lookup table; it must not decide behavior.
 
+## Read vs Snapshot Routing
+
+Choose by intent before choosing by command name:
+
+| Intent | Prefer | Why |
+| --- | --- | --- |
+| Summarize or extract page content, article text, search results, feeds, or long/lazy pages | `read` | Returns clean text/Markdown for agent reasoning. |
+| Quickly observe current visible UI structure before deciding what to do next | `snapshot -i` | Returns actionable refs and page structure for routing. |
+| Find buttons, links, inputs, or refs for a later action | `find` or `snapshot -i` | Produces actionable targets; `read` does not. |
+| Verify one concrete condition | `get`, `is`, or `wait` | Narrow evidence is more reliable than dumping a page. |
+
+Do not use `read` as the first step for click/fill workflows unless the user explicitly asked for page content first.
+
 ## Quick Routing
 
 | Need | Read |
@@ -168,6 +181,9 @@ Use screenshots, annotated screenshots, console logs, network logs, trace, recor
 
 - Missing `OMNIBOT_SESSION_TOKEN` or missing `--tab-id` on page-state commands.
 - Acting without verify or claiming success without evidence.
-- Using `execute-js` first, raw CSS before semantic find, `@eN` across tabs, `switch-tab` for workflow state, or shell sleep instead of `omnibot wait`.
+- Using `execute-js` first, raw CSS before semantic find, `@eN` across tabs, implicit tab targeting, or shell sleep instead of `omnibot wait`.
+- Using removed commands: `switch-tab`, `focus-tab`, `tab switch`. These are no longer available.
+- Using `tabs[0]` or the first tab as a target. The first tab is often a user tab or transport tab.
+- Closing user tabs discovered during cleanup. Only close tabs created by the current workflow.
 
 See `references/anti-patterns.md` before using shortcuts.

package/bin/omnibot-windows-x64/omnibot/skills/omnibot/references/anti-patterns.md

@@ -4,18 +4,23 @@
 | --- | --- | --- |
 | Missing `OMNIBOT_SESSION_TOKEN` | Workflows can share implicit state across agents. | `OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>` |
 | Missing `--tab-id` | The command may target the wrong page. | Pass `--tab-id <TAB_ID>` on every page-state command. |
-| `execute-js` first | JavaScript bypasses standard browser interaction and hides better evidence. | Try semantic find, snapshot refs, selectors, DOM, and mouse first. |
+| `execute-js` first | JavaScript bypasses standard browser interaction and hides better evidence. | Try semantic find, snapshot refs, selectors, DOM, and mouse first. For CSS-only dropdowns, use JavaScript only after the trigger clicked, options remain absent from `snapshot -i`, and higher tiers cannot complete open-then-select. |
 | Reusing `@eN` across tabs | Refs are tab-scoped and may point to a different element elsewhere. | Take a fresh `snapshot -i --tab-id <TAB_ID>` per tab. |
-| Relying on `switch-tab` | It creates implicit state and is unsafe for concurrent workflows. | Use explicit `--tab-id` on every command. |
+| Relying on implicit tab targeting | It is unavailable and unsafe for concurrent workflows. | Use explicit `--tab-id` on every page-state command. |
 | Using sleep instead of wait | Fixed sleeps are flaky and either too short or too slow. | Use `omnibot wait --text`, `--url`, selector state, load state, or `--fn`. |
 | Acting without verify | Command success is not task success. | Run `snapshot`, `get`, `is`, or `wait` after every action. |
 | Claiming success without evidence | The browser may not have changed as expected. | Cite verified URL, text, element state, screenshot, console, or network evidence. |
 | Raw CSS before semantic find | CSS is more brittle and less tied to user intent. | Start with `find role/text/label/placeholder/testid`. |
-| Screenshot when text extraction is enough | Screenshots cost more and are harder to parse. | Use `get text`, `scan --json`, or `full-scan --text-only`. |
+| Screenshot when text extraction is enough | Screenshots cost more and are harder to parse. | Use `read` for page content or `get text` for a selector. |
+| Using `read` before an action workflow | `read` returns text, not stable action targets. | Use `find`, `snapshot -i`, `get`, or `is` for click/fill/verify workflows. |
 | Headless expecting existing user login | Headless does not automatically share the user's visible browser session. | Use visible/background mode for existing login or explicitly log in headless. |
 | Mixing multiple workflows in one session token | Agents can overwrite each other's default state. | Use different tokens: `research`, `checkout`, `debug`. |
-| Using default tab state in concurrent agents | Active/current tab can change outside the workflow. | Discover or create a tab, save its id, and pass `--tab-id`. |
+| Using default tab state in concurrent agents | There is no default tab. Every page command requires explicit `--tab-id`. | Discover or create a tab, save its id, and pass `--tab-id`. |
 | Not checking doctor/tabs before troubleshooting | You may debug page logic when the runtime is disconnected. | Run `omnibot doctor` and `omnibot tabs` first. |
+| Using `tabs[0]` or the first tab | The first tab is often a user tab or the transport tab, not the workflow target. | Create or identify the intended tab and store its full id. |
+| Treating transport as target | Extension routing may use a different tab than the page being acted on. | Always pass `--tab-id <TAB_ID>` and verify with `get url --tab-id <TAB_ID>`. |
+| Closing discovered user tabs | Cleanup can destroy the user's real work. | Track only tool-created tabs and close only those ids. |
+| Leaving worker-token tabs untracked | Cross-token test tabs can remain open or auto-close later. | Add every worker-created tab id to cleanup tracking. |
 
 ## Red Flags
 
@@ -25,5 +30,8 @@
 - "The ref probably still points to the same element."
 - "A screenshot is enough even though I need text."
 - "Sleep should be fine."
+- "The trigger clicked, so another `find text` should eventually select the option."
+- "`snapshot -i` cannot see the option, so the element must not exist."
+- "This dropdown is custom, so I can start with JavaScript."
 
 All of these mean: stop, re-enter the standard pattern, and make state explicit.

package/bin/omnibot-windows-x64/omnibot/skills/omnibot/references/command-reference.md

@@ -15,6 +15,47 @@ omnibot doctor
 Preferred pattern: See `runtime-and-status.md#startup-check`.
 Fallback relation: Not a fallback command.
 
+### status
+
+Purpose: Show daemon status only (lighter than `doctor`).
+
+```bash
+omnibot status
+```
+
+Preferred pattern: See `runtime-and-status.md#daemon-lifecycle`.
+Fallback relation: Not a fallback command.
+
+### start
+
+Purpose: Start the daemon in the background.
+
+```bash
+omnibot start
+```
+
+Equivalent to: `omnibot daemon start`
+
+### stop
+
+Purpose: Stop the running daemon.
+
+```bash
+omnibot stop
+```
+
+Equivalent to: `omnibot daemon stop`
+
+### run
+
+Purpose: Run the daemon in the foreground.
+
+```bash
+omnibot run
+```
+
+Equivalent to: `omnibot daemon run`
+
 ### tabs
 
 Purpose: List connected browser tabs and discover tab ids.
@@ -39,28 +80,19 @@ Fallback relation: Not a fallback command.
 
 ## Reading
 
-### scan
+### read
 
-Purpose: Read current rendered viewport, optionally as JSON.
+Purpose: Read clean rendered page text/Markdown from an existing tab or a temporary URL tab.
 
 ```bash
-OMNIBOT_SESSION_TOKEN=research omnibot scan --json --tab-id <TAB_ID>
-OMNIBOT_SESSION_TOKEN=research omnibot scan --text-only --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot read --screens 5 --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot read --screens 5 --timeout 120 --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot read --screens 3 https://example.com/article
+OMNIBOT_SESSION_TOKEN=research omnibot read --json --screens 5 --tab-id <TAB_ID>
 ```
 
 Preferred pattern: See `operation-patterns.md#read` and `operation-patterns.md#extraction`.
-Fallback relation: Before `full-scan`, `dom visible`, or `execute-js`.
-
-### full-scan
-
-Purpose: Scroll and read more page content, including lazy-loaded content.
-
-```bash
-OMNIBOT_SESSION_TOKEN=research omnibot full-scan --duration 5 --text-only --tab-id <TAB_ID>
-```
-
-Preferred pattern: See `operation-patterns.md#read` and `operation-patterns.md#extraction`.
-Fallback relation: Use after targeted `get`, `is`, or `scan` are insufficient.
+Fallback relation: Prefer for page content. Use `snapshot -i` when the next step is action planning, and `get`/`is`/`wait` for narrow state verification.
 
 ### snapshot -i
 
@@ -198,7 +230,7 @@ OMNIBOT_SESSION_TOKEN=form omnibot select @e5 "US" --tab-id <TAB_ID>
 ```
 
 Preferred pattern: See `operation-patterns.md#select--check`.
-Fallback relation: Prefer refs/selectors before JavaScript value changes.
+Fallback relation: Prefer refs/selectors before JavaScript value changes. For CSS-only dropdowns whose options are absent from `snapshot -i`, see `fallback-operations.md#css-only-dropdown-javascript-fallback`.
 
 ### check / uncheck
 
@@ -307,7 +339,7 @@ OMNIBOT_SESSION_TOKEN=repair omnibot execute-js --file /tmp/repair.js --tab-id <
 ```
 
 Preferred pattern: See `fallback-operations.md#javascript-fallback`.
-Fallback relation: After semantic, refs, selector, DOM, and mouse are insufficient.
+Fallback relation: After semantic, refs, selector, DOM, and mouse are insufficient. Valid examples include CSS-only dropdowns where the trigger exists but option refs are absent from `snapshot -i`.
 
 ### cdp
 
@@ -360,27 +392,21 @@ Purpose: Manage browser tabs.
 ```bash
 OMNIBOT_SESSION_TOKEN=research omnibot tab list
 OMNIBOT_SESSION_TOKEN=research omnibot tab new https://docs.example.com --label docs
-OMNIBOT_SESSION_TOKEN=research omnibot tab switch docs
 OMNIBOT_SESSION_TOKEN=research omnibot tab close docs
 ```
 
 Preferred pattern: See `session-and-tabs.md#tab-explicit`.
-Fallback relation: `tab switch` is casual only; do not use it as workflow state.
+Removed: `tab switch` and `tab focus` are no longer available. Use explicit `--tab-id` on every page-state command.
 
-### window / frame / switch-tab / focus-tab
+### window / frame
 
-Purpose: Manage windows, frames, and visible browser focus.
+Purpose: Manage windows and frames.
 
 ```bash
 OMNIBOT_SESSION_TOKEN=research omnibot window new
 OMNIBOT_SESSION_TOKEN=research omnibot frame main
-OMNIBOT_SESSION_TOKEN=research omnibot switch-tab 123
-OMNIBOT_SESSION_TOKEN=research omnibot focus-tab 123
 ```
 
-Preferred pattern: See `session-and-tabs.md#switch-tab` and `session-and-tabs.md#focus-tab`.
-Fallback relation: `focus-tab` is for user-visible UI, not targeting reliability.
-
 ## Waiting & Batch
 
 ### wait
@@ -406,7 +432,7 @@ Fallback relation: Prefer over shell sleep.
 Purpose: Send short command arrays as JSON or from a file.
 
 ```bash
-OMNIBOT_SESSION_TOKEN=research omnibot batch '[{"cmd":"scan"},{"cmd":"snapshot","interactive":true}]' --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=research omnibot batch '[{"cmd":"snapshot","interactive":true}]' --tab-id <TAB_ID>
 OMNIBOT_SESSION_TOKEN=research omnibot batch --file /tmp/omnibot-batch.json --tab-id <TAB_ID>
 ```
 

package/bin/omnibot-windows-x64/omnibot/skills/omnibot/references/debugging-and-evidence.md

@@ -89,7 +89,7 @@ CDP inspection is not a first-choice operation path. If CDP changes state, it be
 Before reporting a browser issue, collect the smallest evidence set that explains it:
 
 - Runtime: `doctor`, `tabs`, `visibility status`.
-- Page state: `get`, `is`, `scan`, or `snapshot`.
+- Page state: `get`, `is`, `snapshot`, or `wait`.
 - Visual proof: `screenshot --annotate` only if visual state matters.
 - Browser diagnostics: `console errors` and `network summary`.
 - Reproduction artifact: `trace` or `record` when the flow is unstable.

package/bin/omnibot-windows-x64/omnibot/skills/omnibot/references/fallback-operations.md

@@ -106,7 +106,8 @@ Use `execute-js` only when:
 - CSS selector operation fails.
 - DOM fallback fails.
 - A complex frontend event must be triggered.
-- Runtime state cannot be read through `scan`, `full-scan`, `get`, or `is`.
+- A CSS-only dropdown or hover menu requires an atomic open-then-select sequence, and `snapshot -i` confirms the option nodes are absent from the accessibility tree.
+- Runtime state cannot be read through `read`, `snapshot`, `get`, or `is`.
 
 Read-only JavaScript fallback:
 
@@ -129,6 +130,64 @@ OMNIBOT_SESSION_TOKEN=repair omnibot execute-js "document.querySelector('button[
 OMNIBOT_SESSION_TOKEN=repair omnibot wait --url "/dashboard" --tab-id <TAB_ID>
 ```
 
+### CSS-only dropdown JavaScript fallback
+
+Use this only after the trigger is known and higher tiers failed: semantic `find` clicked the trigger or found the text, `snapshot -i` could not expose option refs, selector/DOM/mouse could not complete the two-step interaction, and verification showed the selection did not change.
+
+Example for a visible trigger like `按留言时间排序` and a target option text:
+
+```bash
+OMNIBOT_SESSION_TOKEN=repair omnibot execute-js --file /tmp/omnibot-css-dropdown.js --tab-id <TAB_ID>
+OMNIBOT_SESSION_TOKEN=repair omnibot snapshot -i --tab-id <TAB_ID>
+```
+
+`/tmp/omnibot-css-dropdown.js`:
+
+```js
+const triggerText = '按留言时间排序';
+const optionText = '目标选项文本';
+
+const visibleElements = [...document.querySelectorAll('button, [role="button"], [aria-haspopup], div, span, li')]
+  .filter((el) => {
+    const style = getComputedStyle(el);
+    const box = el.getBoundingClientRect();
+    return style.display !== 'none' && style.visibility !== 'hidden' && box.width > 0 && box.height > 0;
+  });
+
+const byExactText = (text) => visibleElements.find((el) => el.textContent?.trim() === text);
+const trigger = byExactText(triggerText);
+if (!trigger) {
+  return { ok: false, reason: 'trigger-not-found', triggerText, optionText };
+}
+
+trigger.click();
+await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+
+const option = [...document.querySelectorAll('div, span, li, button, [role="option"], [role="menuitem"]')]
+  .filter((el) => {
+    const style = getComputedStyle(el);
+    const box = el.getBoundingClientRect();
+    return style.display !== 'none' && style.visibility !== 'hidden' && box.width > 0 && box.height > 0;
+  })
+  .find((el) => el.textContent?.trim() === optionText);
+
+if (!option) {
+  return { ok: false, reason: 'option-not-found-after-trigger-click', triggerText, optionText };
+}
+
+option.click();
+await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+
+return {
+  ok: true,
+  triggerText,
+  optionText,
+  selectedText: trigger.textContent?.trim(),
+};
+```
+
+Verify with the user-visible result, not just `{ ok: true }`: selected label, sorted result order, result count, URL/query state, or another page-specific condition.
+
 Prefer `--file` for longer scripts:
 
 ```bash