Docs Operation reference preview operations
preview operations#
16 operations. Generated from assets/operations.json; all areas.
On this page (16)
preview.sessions#
Preview sessions
Find running Qt preview sessions owned by this OS user.
Annotations: read-only, idempotent, open world.
Takes no arguments.
tomaccoctl call preview.sessions
preview.state#
Preview status
Read current device, viewport, page, loading status and rendering engine.
Annotations: read-only, idempotent, open world.
| Argument | Type | Required | Default | Details |
|---|---|---|---|---|
session | string | matching [A-Za-z0-9_-]{1,40}; Running preview session name; defaults to main |
tomaccoctl call preview.state
preview.navigate#
Open URL
Navigate the running preview to an HTTP(S) URL or tomacco://demo.
Annotations: writes, idempotent, open world.
| Argument | Type | Required | Default | Details |
|---|---|---|---|---|
url | string | yes | ||
session | string | matching [A-Za-z0-9_-]{1,40}; Running preview session name; defaults to main |
tomaccoctl call preview.navigate '{"url":"<url>"}'
preview.configure#
Configure preview
Set profile, orientation, fold state, insets, guides, zoom, the page's color scheme and reduced-motion preference, and network throttling, without reloading the page.
Annotations: writes, idempotent, open world.
| Argument | Type | Required | Default | Details |
|---|---|---|---|---|
device | string | |||
orientation | string | one of portrait, landscape | ||
unfolded | boolean | |||
safe_area | boolean | |||
guides | boolean | |||
status_bar | boolean | |||
chrome_theme | string | one of auto, light, dark | ||
zoom | number | 0 to 3 | ||
color_scheme | string | one of system, light, dark; prefers-color-scheme the page sees; system follows the desktop | ||
reduced_motion | string | one of system, reduce, no-preference; prefers-reduced-motion the page sees; system follows the desktop | ||
network | object | Throttle the page's requests or take it offline, through Chromium's DevTools network emulation. A preset sets every field; fields given with it override the preset. All zero and offline false turns throttling off. | ||
network.preset | string | one of none, fast-3g, slow-3g, offline; Chromium DevTools' presets: fast-3g 562.5 ms, 1440/675 kbit/s; slow-3g 2000 ms, 400/400 kbit/s | ||
network.offline | boolean | |||
network.latency_ms | number | 0 to 60000; Added round-trip latency in milliseconds | ||
network.download_kbps | number | 0 to 10000000; Download limit in kbit/s; 0 is unlimited | ||
network.upload_kbps | number | 0 to 10000000; Upload limit in kbit/s; 0 is unlimited | ||
session | string | matching [A-Za-z0-9_-]{1,40}; Running preview session name; defaults to main | ||
ios_guest | object | The virtual iOS guest display shown by the desktop for a running interactive guest job. | ||
ios_guest.detached | boolean | Show the guest display as its own phone-shaped window, or dock it back into the dialog. A request to detach made while no interactive guest is running is kept for up to 10 minutes and applied when the guest starts; until then the returned state reports workspace.ios_research.guest.detach_pending as true. | ||
native | object | |||
native.platform | string | one of android, ios | ||
native.apple_target | string | one of device, simulator | ||
native.setup | boolean | |||
native.device | string | non-empty, up to 200 characters; Select a native device by serial/UDID and attach its existing runtime session. | ||
native.connect | boolean | With device: if no runtime session exists yet, the app waits for the device and starts one with its own settings (sound, iPhone runner, Mac). Its window shows the device frame and a startup screen until the stream is live; other sessions are not attached meanwhile. An existing session is shown as it is and never reconfigured. | ||
native.frame | boolean | Show the matching native device frame. Never changes the guest hardware or screen geometry. | ||
native.detached | boolean | Show the live device as its own frameless, device-shaped window instead of inside the workspace. The same display item moves; no second stream is opened. | ||
native.pending_avd | string | up to 200 characters; Name of an Android virtual device that is starting. The device view shows its frame and a startup screen and attaches the real stream once Android has booted. An empty string clears it. | ||
native.profile_id | string | up to 200 characters; Device profile for the startup frame of pending_avd or connect. | ||
native.solo | boolean | With detached and a device window that is shown or on its way: hide the main window so the device window is the whole app. Closing that window stops its runtime session and ends the app; the device itself keeps running. With unsaved source edits, or once two minutes pass without any device window, the main window returns instead. desktop.open without device_only also brings it back. |
tomaccoctl call preview.configure
preview.evaluate#
Run JavaScript
Evaluate JavaScript in the web page, returning a JSON-compatible result.
Annotations: writes, not idempotent, open world.
| Argument | Type | Required | Default | Details |
|---|---|---|---|---|
script | string | yes | ||
session | string | matching [A-Za-z0-9_-]{1,40}; Running preview session name; defaults to main |
tomaccoctl call preview.evaluate '{"script":"<script>"}'
preview.capture#
Capture preview
Capture the device or display as a PNG artifact.
Annotations: writes, not idempotent, open world.
| Argument | Type | Required | Default | Details |
|---|---|---|---|---|
path | string | yes | non-empty; Absolute local filesystem path | |
frame | boolean | |||
scale | number | 1 to 3 | ||
session | string | matching [A-Za-z0-9_-]{1,40}; Running preview session name; defaults to main | ||
window | boolean | false | Capture the full desktop window including workspace panels |
tomaccoctl call preview.capture '{"path":"<path>"}'
preview.inspect#
Inspect DOM
Read page title, text, links, inputs and actionable DOM elements.
Annotations: read-only, idempotent, open world.
| Argument | Type | Required | Default | Details |
|---|---|---|---|---|
session | string | matching [A-Za-z0-9_-]{1,40}; Running preview session name; defaults to main |
tomaccoctl call preview.inspect
preview.console#
Browser console
Read the last 200 browser console messages.
Annotations: read-only, idempotent, open world.
| Argument | Type | Required | Default | Details |
|---|---|---|---|---|
session | string | matching [A-Za-z0-9_-]{1,40}; Running preview session name; defaults to main |
tomaccoctl call preview.console
preview.errors#
Page errors
Report the current page load's errors as structured results: console errors, uncaught exceptions, unhandled promise rejections and failed requests (network errors and HTTP status 400 and above from fetch, XMLHttpRequest, elements, style sheets, fonts and the document), with clean true when there are none. reload:true reloads first and waits for the page, so the report covers exactly one load.
Annotations: writes, idempotent, open world.
| Argument | Type | Required | Default | Details |
|---|---|---|---|---|
reload | boolean | false | Reload the page and wait until it is ready before reporting | |
timeout | integer | 30 | 1 to 60; Seconds to wait for the reloaded page | |
wait_for | string | "" | JavaScript expression that becomes true when application content is ready, after a reload | |
session | string | matching [A-Za-z0-9_-]{1,40}; Running preview session name; defaults to main |
tomaccoctl call preview.errors
preview.click#
Click element
Click a CSS selector in the preview page.
Annotations: writes, not idempotent, open world.
| Argument | Type | Required | Default | Details |
|---|---|---|---|---|
selector | string | yes | ||
session | string | matching [A-Za-z0-9_-]{1,40}; Running preview session name; defaults to main |
tomaccoctl call preview.click '{"selector":"<selector>"}'
preview.fill#
Fill in form
Fill an input/textarea and emit input/change events.
Annotations: writes, not idempotent, open world.
| Argument | Type | Required | Default | Details |
|---|---|---|---|---|
selector | string | yes | ||
text | string | yes | ||
session | string | matching [A-Za-z0-9_-]{1,40}; Running preview session name; defaults to main |
tomaccoctl call preview.fill '{"selector":"<selector>","text":"<text>"}'
preview.reload#
Reload page
Reload the active page.
Annotations: writes, not idempotent, open world.
| Argument | Type | Required | Default | Details |
|---|---|---|---|---|
session | string | matching [A-Za-z0-9_-]{1,40}; Running preview session name; defaults to main |
tomaccoctl call preview.reload
preview.catalog_reload#
Reload catalog
Refresh the desktop catalogue after import/remove.
Annotations: writes, idempotent, open world.
| Argument | Type | Required | Default | Details |
|---|---|---|---|---|
session | string | matching [A-Za-z0-9_-]{1,40}; Running preview session name; defaults to main |
tomaccoctl call preview.catalog_reload
preview.audit#
Check layout
Check overflow of the page and its elements, text under the camera cutout or system bars, accessible names, input labels and target sizes (24 px, and 44 pt on iOS or 48 dp on Android), with a unique selector per finding; returns evidence, not a compliance certification.
Annotations: read-only, idempotent, open world.
| Argument | Type | Required | Default | Details |
|---|---|---|---|---|
session | string | "main" | matching [A-Za-z0-9_-]{1,40}; Running preview session name; defaults to main |
tomaccoctl call preview.audit
preview.ready#
Wait for rendering
Wait for document/fonts and Flutter's first frame, optionally a JavaScript readiness predicate.
Annotations: read-only, idempotent, open world.
| Argument | Type | Required | Default | Details |
|---|---|---|---|---|
session | string | "main" | matching [A-Za-z0-9_-]{1,40}; Running preview session name; defaults to main | |
timeout | integer | 30 | 1 to 60 | |
wait_for | string | "" | JavaScript expression that becomes true when application content is ready |
tomaccoctl call preview.ready
preview.matrix#
Capture device matrix
Capture and audit a page across multiple profiles and orientations, saving PNGs, a labelled contact sheet of all captures and a JSON report.
Annotations: writes, not idempotent, open world.
| Argument | Type | Required | Default | Details |
|---|---|---|---|---|
device_ids | array of string | yes | 1 to 30 items | |
directory | string | yes | non-empty; Absolute local filesystem path | |
url | string | "" | ||
orientations | array of string | items one of portrait, landscape; 1 to 2 items | ||
session | string | "main" | matching [A-Za-z0-9_-]{1,40}; Running preview session name; defaults to main | |
wait_for | string | "" | ||
folded_views | boolean | true | ||
contact_sheet | boolean | true | Also write contact-sheet.png: every capture side by side at one scale, labelled with model and orientation |
tomaccoctl call preview.matrix '{"device_ids":["<device_id>"],"directory":"<directory>"}'