mosaic-browser

name	mosaic-browser
description	End-user browser automation with mosaic. Use when you need to open sites, interact with pages, wait for state changes, and extract data from mosaic browser surfaces.

Browser Automation with mosaic

Use this skill for browser tasks inside mosaic webviews.

Core Workflow

1. Open or target a browser surface.
2. Verify navigation with get url before waiting or snapshotting.
3. Snapshot (--interactive) to get fresh element refs.
4. Act with refs (click, fill, type, select, press).
5. Wait for state changes.
6. Re-snapshot after DOM/navigation changes.

mosaic --json browser open https://example.com
# use returned surface ref, for example: surface:7

mosaic browser surface:7 get url
mosaic browser surface:7 wait --load-state complete --timeout-ms 15000
mosaic browser surface:7 snapshot --interactive
mosaic browser surface:7 fill e1 "hello"
mosaic --json browser surface:7 click e2 --snapshot-after
mosaic browser surface:7 snapshot --interactive

Surface Targeting

# identify current context
mosaic identify --json

# open routed to a specific topology target
mosaic browser open https://example.com --workspace workspace:2 --window window:1 --json

Notes:

• CLI output defaults to short refs (surface:N, pane:N, workspace:N, window:N).
• UUIDs are still accepted on input; only request UUID output when needed (--id-format uuids|both).
• Keep using one surface:N per task unless you intentionally switch.

Wait Support

mosaic supports wait patterns similar to agent-browser:

mosaic browser <surface> wait --selector "#ready" --timeout-ms 10000
mosaic browser <surface> wait --text "Success" --timeout-ms 10000
mosaic browser <surface> wait --url-contains "/dashboard" --timeout-ms 10000
mosaic browser <surface> wait --load-state complete --timeout-ms 15000
mosaic browser <surface> wait --function "document.readyState === 'complete'" --timeout-ms 10000

Common Flows

Form Submit

mosaic --json browser open https://example.com/signup
mosaic browser surface:7 get url
mosaic browser surface:7 wait --load-state complete --timeout-ms 15000
mosaic browser surface:7 snapshot --interactive
mosaic browser surface:7 fill e1 "Jane Doe"
mosaic browser surface:7 fill e2 "[e-mail]"
mosaic --json browser surface:7 click e3 --snapshot-after
mosaic browser surface:7 wait --url-contains "/welcome" --timeout-ms 15000
mosaic browser surface:7 snapshot --interactive

Clear an Input

mosaic browser surface:7 fill e11 "" --snapshot-after --json
mosaic browser surface:7 get value e11 --json

Stable Agent Loop (Recommended)

# navigate -> verify -> wait -> snapshot -> action -> snapshot
mosaic browser surface:7 get url
mosaic browser surface:7 wait --load-state complete --timeout-ms 15000
mosaic browser surface:7 snapshot --interactive
mosaic --json browser surface:7 click e5 --snapshot-after
mosaic browser surface:7 snapshot --interactive

If get url is empty or about:blank, navigate first instead of waiting on load state.

Deep-Dive References

Reference	When to Use
references/commands.md	Full browser command mapping and quick syntax
references/snapshot-refs.md	Ref lifecycle and stale-ref troubleshooting
references/authentication.md	Login/OAuth/2FA patterns and state save/load
references/authentication.md#saving-authentication-state	Save authenticated state right after login
references/session-management.md	Multi-surface isolation and state persistence patterns
references/video-recording.md	Current recording status and practical alternatives
references/proxy-support.md	Proxy behavior in WKWebView and workarounds

Ready-to-Use Templates

Template	Description
templates/form-automation.sh	Snapshot/ref form fill loop
templates/authenticated-session.sh	Login once, save/load state
templates/capture-workflow.sh	Navigate + capture snapshots/screenshots

Limits (WKWebView)

These commands currently return not_supported because they rely on Chrome/CDP-only APIs not exposed by WKWebView:

• viewport emulation
• offline emulation
• trace/screencast recording
• network route interception/mocking
• low-level raw input injection

Use supported high-level commands (click, fill, press, scroll, wait, snapshot) instead.

Troubleshooting

js_error on snapshot --interactive or eval

Some complex pages can reject or break the JavaScript used for rich snapshots and ad-hoc evaluation.

Recovery steps:

mosaic browser surface:7 get url
mosaic browser surface:7 get text body
mosaic browser surface:7 get html body

• Use get url first so you know whether the page actually navigated.
• Fall back to get text body or get html body when snapshot --interactive or eval returns js_error.
• If the page is still failing, navigate to a simpler intermediate page, then retry the task from there.