Action Vocabulary

The qontinui runner and the wrapper SDK communicate via action names — short camelCase identifiers like getControlSnapshot, executeElementAction, find. The runner sends an action name with a payload; your wrapper's HandlerRegistry dispatches to the handler keyed by that string. A typo on either side fails silently with NO_HANDLER at runtime.

This page is the canonical reference for the vocabulary. If you're new to wrappers, read Authoring a Wrapper first.

Where the vocabulary is defined

Two files are the source of truth — one per side of the protocol:

Side	File	Role
Wrapper SDK	ui-bridge/packages/ui-bridge/src/server/relay-handlers.ts	Defines every action handler available to apps. Each relayCommand('<name>', payload) / queueCommand<T>('<name>', payload) site is a registered action.
Runner	qontinui-runner/src-tauri/src/mcp/sdk_client.rs	Dispatches actions over WebSocket via dispatch_app_request(state, "<name>", ...). Each call is a runner-side use of the action.

The cross-language validator below diffs the two sets and fails CI if the runner dispatches an action the wrapper SDK has no handler for.

Action → HTTP route table

The table below is auto-generated from sdk_client.rs by walking every /// METHOD /path — description\nasync fn handle_X(...) block and pairing it with the first dispatch_app_request(&state, "<action>", ...) site inside that handler's body. Regenerate with:

cd qontinui-runner
npm run validate:ws-actions -- --emit-doc docs-site/docs/wrappers/action-vocabulary.md

CI runs the equivalent --check-doc mode (via npm run check) and fails if the table is stale.

138 routes; regenerate via npm run validate:ws-actions -- --emit-doc docs-site/docs/wrappers/action-vocabulary.md.

Action	HTTP route	Handler
activateState	POST /ui-bridge/sdk/state/:id/activate — Activate a state	handle_activate_state
activateStateGroup	POST /ui-bridge/sdk/state-group/:id/activate — Activate a state group	handle_activate_state_group
aiAssert	POST /ui-bridge/sdk/ai/assert — AI-powered assertions	handle_ai_assert
aiAssertBatch	POST /ui-bridge/sdk/ai/assert/batch — Batch AI assertions	handle_ai_assert_batch
aiExecute	POST /ui-bridge/sdk/ai/execute — AI-powered action execution	handle_ai_execute
aiFind	POST /ui-bridge/sdk/ai/find — AI-powered element finding	handle_ai_find
aiSearch	POST /ui-bridge/sdk/ai/search — AI-powered element search	handle_ai_search
aiSemanticSearch	POST /ui-bridge/sdk/ai/semantic-search — Semantic search	handle_ai_semantic_search
analyzeMedia	POST /ui-bridge/sdk/ai/media/analyze — AI analysis of single media element	handle_media_analyze
analyzeMediaBatch	POST /ui-bridge/sdk/ai/media/analyze/batch — AI analysis of multiple media elements	handle_media_analyze_batch
analyzeMediaPage	POST /ui-bridge/sdk/ai/media/analyze/page — AI analysis of all visible media on page	handle_media_analyze_page
analyzePageData	GET /ui-bridge/sdk/ai/analyze/data — Extract page data	handle_ai_analyze_data
analyzePageRegions	GET /ui-bridge/sdk/ai/analyze/regions — Segment page regions	handle_ai_analyze_regions
analyzeStructuredChanges	POST /ui-bridge/sdk/ai/structured-changes — Analyze structured changes	handle_ct_structured_changes
analyzeStructuredData	GET /ui-bridge/sdk/ai/analyze/structured-data — Extract tables/lists	handle_ai_analyze_structured_data
attemptRecovery	POST /ui-bridge/sdk/ai/recovery/attempt — Attempt error recovery	handle_recovery_attempt
canExecuteTransition	GET /ui-bridge/sdk/transition/:id/can-execute — Check if transition can execute	handle_can_execute_transition
captureMediaSnapshot	POST /ui-bridge/sdk/ai/media/snapshot — Capture media snapshot	handle_media_snapshot
captureSnapshot	POST /ui-bridge/sdk/render-log/snapshot — Capture render log snapshot	handle_render_log_snapshot
categorizeLastDiff	GET /ui-bridge/sdk/ai/categorize-last-diff — Categorize the last diff	handle_ct_categorize_last_diff
clearConsoleErrors	POST /ui-bridge/sdk/console-errors/clear — Clear console errors in SDK app	handle_clear_console_errors
clearPerformanceEntries	POST /ui-bridge/sdk/performance-entries/clear — Clear performance entries	handle_clear_performance_entries
clearRenderLog	DELETE /ui-bridge/sdk/render-log — Clear render log	handle_clear_render_log
clearStyleGuide	DELETE /ui-bridge/sdk/design/style-guide — Clear loaded style guide	handle_design_clear_style_guide
clickBySelector	POST /ui-bridge/sdk/page/click-by-selector — Click an element by CSS selector	handle_click_by_selector
clickByText	POST /ui-bridge/sdk/page/click-by-text — Click an element by visible text	handle_click_by_text
compareMediaSnapshots	POST /ui-bridge/sdk/ai/media/compare — Compare two media snapshots	handle_media_compare
controlBatch	POST /ui-bridge/sdk/control/batch — Execute a batched control request	handle_control_batch
crossAppCompare	POST /ui-bridge/sdk/ai/analyze/cross-app-compare — Compare two snapshots	handle_ai_analyze_cross_app_compare
deactivateState	POST /ui-bridge/sdk/state/:id/deactivate — Deactivate a state	handle_deactivate_state
deactivateStateGroup	POST /ui-bridge/sdk/state-group/:id/deactivate — Deactivate a state group	handle_deactivate_state_group
deleteAnnotation	DELETE /ui-bridge/sdk/annotations/:id — Delete an annotation	handle_annotation_delete
deleteBookmark	DELETE /ui-bridge/sdk/ai/bookmark/:name — Delete a bookmark	handle_ct_delete_bookmark
deleteIntent	DELETE /ui-bridge/sdk/control/intent/:name — Delete a registered intent	handle_delete_intent
diffBaseline	POST /ui-bridge/sdk/design/evaluate/diff — Diff quality baseline	handle_diff_baseline
diffForms	POST /ui-bridge/sdk/forms/diff — Diff two form snapshots	handle_diff_forms
diffFromBookmark	GET /ui-bridge/sdk/ai/bookmark/:name/diff — Diff from a bookmark	handle_ct_diff_from_bookmark
disableChangeBuffer	POST /ui-bridge/sdk/ai/change-buffer/disable — Disable change buffer	handle_ct_disable_change_buffer
drainChangeBuffer	POST /ui-bridge/sdk/ai/change-buffer/drain — Drain change buffer	handle_ct_drain_change_buffer
enableChangeBuffer	POST /ui-bridge/sdk/ai/change-buffer/enable — Enable change buffer	handle_ct_enable_change_buffer
evaluateQuality	POST /ui-bridge/sdk/design/evaluate — Evaluate quality	handle_evaluate_quality
executeBatchAction	POST /ui-bridge/sdk/control/batch-action — Execute a batch of element actions	handle_execute_batch_action
executeComponentAction	POST /ui-bridge/sdk/component/:id/action/:actionId — Execute component action	handle_component_action
executeElementAction	POST /ui-bridge/sdk/element/:id/action — Execute an action on an element	handle_element_action
executeIntent	POST /ui-bridge/sdk/ai/intents/execute — Execute an intent	handle_execute_intent
executeIntentFromQuery	POST /ui-bridge/sdk/ai/intents/execute-from-query — Execute intent from natural language	handle_execute_intent_from_query
executeRedo	POST /ui-bridge/sdk/redo — Execute redo	handle_redo
executeTransition	POST /ui-bridge/sdk/transition/:id/execute — Execute a transition	handle_execute_transition
executeUndo	POST /ui-bridge/sdk/undo — Execute undo	handle_undo
executeWithDiff	POST /ui-bridge/sdk/ai/execute-with-diff — Execute action and return diff	handle_ct_execute_with_diff
exportAnnotations	GET /ui-bridge/sdk/annotations/export — Export annotations	handle_annotations_export
fillForm	POST /ui-bridge/sdk/fill — Smart form fill	handle_fill_form
find	POST /ui-bridge/sdk/discover — Find/discover elements	handle_discover
findByText	POST /ui-bridge/sdk/page/find-by-text — Find elements by visible text	handle_find_by_text
findIntent	POST /ui-bridge/sdk/ai/intents/find — Find matching intents	handle_find_intent
findMedia	POST /ui-bridge/sdk/ai/media/find — Find media elements with filters	handle_media_find
findPath	POST /ui-bridge/sdk/states/find-path — Find path between states	handle_find_path
getActionHistory	GET /ui-bridge/sdk/debug/action-history — Get action history	handle_action_history
getActiveStates	GET /ui-bridge/sdk/states/active — Get active states	handle_active_states
getAnnotation	GET /ui-bridge/sdk/annotations/:id — Get a specific annotation	handle_annotation_get
getAnnotationCoverage	GET /ui-bridge/sdk/annotations/coverage — Get annotation coverage	handle_annotations_coverage
getAnnotations	GET /ui-bridge/sdk/annotations — Get all annotations	handle_annotations
getBookmark	GET /ui-bridge/sdk/ai/bookmark/:name — Get a specific bookmark	handle_ct_get_bookmark
getChangeBufferSize	GET /ui-bridge/sdk/ai/change-buffer/size — Get change buffer size	handle_ct_get_change_buffer_size
getComponentState	GET /ui-bridge/sdk/component/:id/state — Get component state	handle_component_state
getConsoleErrors	GET /ui-bridge/sdk/console-errors — Get console errors from SDK app	handle_console_errors
getControlSnapshot	GET /ui-bridge/sdk/component/:id — Get a single component	handle_component
getControlSnapshot	GET /ui-bridge/sdk/components — List components	handle_components
getControlSnapshot	GET /ui-bridge/sdk/states/snapshot — Get state snapshot	handle_state_snapshot
getControlSnapshot	GET /ui-bridge/sdk/workflows — List workflows	handle_workflows
getDesignSnapshot	POST /ui-bridge/sdk/design/snapshot — Design data for all/filtered elements	handle_design_snapshot
getDiagnostics	GET /ui-bridge/sdk/diagnostics — SDK diagnostic information	handle_diagnostics
getElement	GET /ui-bridge/sdk/element/:id — Get a single element	handle_element
getElementHistory	GET /ui-bridge/sdk/control/element/:id/history — Get element history	handle_element_history
getElementImages	GET /ui-bridge/sdk/control/element/:id/images — Get images associated with an element	handle_element_images
getElementReactState	GET /ui-bridge/sdk/element/:id/state — Get element state	handle_element_state
getElementState	GET /ui-bridge/sdk/control/element/:id/state-generic — Get generic element state	handle_element_state_generic
getElementStateStyles	POST /ui-bridge/sdk/design/element/:id/state-styles — Styles across interaction states	handle_design_element_state_styles
getElementStyles	GET /ui-bridge/sdk/design/element/:id/styles — Extended computed styles for one element	handle_design_element_styles
getElementTree	GET /ui-bridge/sdk/debug/element-tree — Get element tree	handle_element_tree
getErrorReport	GET /ui-bridge/sdk/error-report — Get error report	handle_error_report
getErrorSessions	GET /ui-bridge/sdk/console/error-sessions — List all error session summaries	handle_console_error_sessions_list
getErrorSnapshots	GET /ui-bridge/sdk/error-snapshots — Get error snapshots	handle_error_snapshots
getForms	GET /ui-bridge/sdk/forms — Form state awareness	handle_forms
getIdleSignalStatus	GET /ui-bridge/sdk/idle-status/:signal — Get single signal idle status from SDK app	handle_idle_status_signal
getIdleStatus	GET /ui-bridge/sdk/idle-status — Get idle status from SDK app	handle_idle_status
getNetworkRequest	GET /ui-bridge/sdk/network-request/:id — Get specific request by ID	handle_network_request
getNetworkRequestsInFlight	GET /ui-bridge/sdk/network-requests/in-flight — Currently in-flight requests	handle_network_requests_in_flight
getPageSummary	GET /ui-bridge/sdk/ai/summary — Page summary	handle_ai_summary
getPerformanceEntries	GET /ui-bridge/sdk/performance-entries — Get performance entries	handle_performance_entries
getQualityContexts	GET /ui-bridge/sdk/design/evaluate/contexts — Get quality evaluation contexts	handle_quality_contexts
getRenderLog	GET /ui-bridge/sdk/render-log — Get render log entries	handle_render_log
getResponsiveSnapshots	POST /ui-bridge/sdk/design/responsive — Snapshots at multiple viewports	handle_design_responsive
getRoutes	GET /ui-bridge/sdk/page/routes — List available routes	handle_page_routes
getScopedDiff	POST /ui-bridge/sdk/ai/scoped-diff — Get scoped diff	handle_ct_scoped_diff
getSemanticDiff	GET /ui-bridge/sdk/ai/diff — Get semantic diff	handle_ai_diff
getSemanticSnapshot	GET /ui-bridge/sdk/ai/snapshot — Semantic AI snapshot	handle_ai_snapshot
getState	GET /ui-bridge/sdk/state/:id — Get a specific state	handle_get_state
getStateGroups	GET /ui-bridge/sdk/state-groups — Get all state groups	handle_state_groups
getStates	GET /ui-bridge/sdk/states — Get all states	handle_states
getStyleGuide	GET /ui-bridge/sdk/design/style-guide — Get loaded style guide	handle_design_get_style_guide
getTransitions	GET /ui-bridge/sdk/transitions — Get all transitions	handle_transitions
getUndoState	GET /ui-bridge/sdk/undo-state — Get undo/redo state	handle_undo_state
getWorkflowStatus	GET /ui-bridge/sdk/workflow/:runId/status — Get workflow run status	handle_workflow_status
highlightElement	POST /ui-bridge/sdk/debug/highlight/:id — Highlight an element	handle_debug_highlight
importAnnotations	POST /ui-bridge/sdk/annotations/import — Import annotations	handle_annotations_import
listBookmarks	GET /ui-bridge/sdk/ai/bookmarks — List all bookmarks	handle_ct_list_bookmarks
listIntents	GET /ui-bridge/sdk/ai/intents — List all intents	handle_list_intents
loadStyleGuide	POST /ui-bridge/sdk/design/style-guide/load — Load a style guide	handle_design_load_style_guide
mediaAuditAccessibility	POST /ui-bridge/sdk/ai/media/audit/accessibility — Alt text audit	handle_media_audit_accessibility
mediaAuditPerformance	POST /ui-bridge/sdk/ai/media/audit/performance — Performance audit	handle_media_audit_performance
navigateByAdapter	POST /ui-bridge/sdk/page/navigate-to — Navigate using the navigation adapter	handle_navigate_by_adapter
navigateTo	POST /ui-bridge/sdk/states/navigate — Navigate to a state	handle_navigate_to
pageGoBack	POST /ui-bridge/sdk/page/back — Go back in history	handle_page_go_back
pageGoForward	POST /ui-bridge/sdk/page/forward — Go forward in history	handle_page_go_forward
pageNavigate	POST /ui-bridge/sdk/page/navigate — Navigate to a URL	handle_page_navigate
pageRefresh	POST /ui-bridge/sdk/page/refresh — Refresh the page	handle_page_refresh
pageScroll	POST /ui-bridge/sdk/control/page/scroll — Scroll the page or a target element	handle_page_scroll
readValue	POST /ui-bridge/sdk/page/read-value — Read a form element's value	handle_read_value
registerIntent	POST /ui-bridge/sdk/ai/intents/register — Register an intent	handle_register_intent
runDesignAudit	POST /ui-bridge/sdk/design/audit — Run style audit against style guide	handle_design_audit
runWorkflow	POST /ui-bridge/sdk/workflow/:id/run — Run a workflow	handle_workflow_run
saveBaseline	POST /ui-bridge/sdk/design/evaluate/baseline — Save quality baseline	handle_save_baseline
saveBookmark	POST /ui-bridge/sdk/ai/bookmarks — Save a bookmark	handle_ct_save_bookmark
setAnnotation	PUT /ui-bridge/sdk/annotations/:id — Set/update an annotation	handle_annotation_set
setViewportConstraints	POST /ui-bridge/sdk/control/viewport — Set viewport constraints for the active window	handle_set_viewport_constraints
snapshotForms	POST /ui-bridge/sdk/forms/snapshot — Capture form state snapshot	handle_snapshot_forms
summarizeDiff	POST /ui-bridge/sdk/ai/summarize-diff — Summarize a diff with budget	handle_ct_summarize_diff
typeInto	POST /ui-bridge/sdk/page/type-into — Type text into an input field	handle_type_into
waitForChange	POST /ui-bridge/sdk/ai/wait-for-change — Wait for a change matching predicate	handle_ct_wait_for_change
waitForElement	POST /ui-bridge/sdk/control/wait-for-element — Wait for an element matching a query	handle_wait_for_element_sdk
waitForElementByCondition	POST /ui-bridge/sdk/control/wait-for-element-by-condition — Wait until an element satisfies a condition	handle_wait_for_element_by_condition
waitForElementRegistered	POST /ui-bridge/sdk/control/wait-for-element-registered — Wait for an element to register	handle_wait_for_element_registered
waitForIdle	POST /ui-bridge/sdk/wait-for-idle — Block until SDK app is idle	handle_wait_for_idle
waitForNetworkRequest	POST /ui-bridge/sdk/network-requests/wait — Wait for a specific request matching criteria	handle_wait_for_network_request
waitForRouteChange	POST /ui-bridge/sdk/control/wait-for-route-change — Wait for a router route change	handle_wait_for_route_change
waitForSignalIdle	POST /ui-bridge/sdk/wait-for-idle/:signal — Block until specific signal is idle in SDK app	handle_wait_for_signal
waitForTargets	POST /ui-bridge/sdk/wait-for-targets — Wait for specific targets in SDK app	handle_wait_for_targets

Multiple rows for the same action mean the runner exposes multiple HTTP routes that share a handler — typically a /snapshot-flavored route that synthesizes a sub-view from getControlSnapshot.

Aliases that no longer exist

These names appeared in older docs / scaffolder templates. They forward to canonical names in current relay-handlers.ts (with @deprecated JSDoc), so existing callers keep working but the canonical name is what goes over the wire:

Deprecated	Canonical	Removed since
discover	find	21ef25e (ui-bridge)
clipboardRead	getClipboard	21ef25e (ui-bridge)
clipboardWrite	setClipboard	21ef25e (ui-bridge)

Wrapper-only actions (no runner caller)

Some actions exist on the wrapper-SDK side but the runner doesn't proxy them. They're intentional non-proxies, not gaps:

Action	Why no runner route
pageEvaluate	Runner uses IPC (ui_bridge_request_sync) instead — see handle_page_evaluate
query	Runner uses IPC — see handle_query_selector
getStateSnapshot	Runner synthesizes from getControlSnapshot — see handle_state_snapshot
getSpecs	Runner calls it via sdk_request directly from handle_discover_and_cache, not through the dispatch helper

If you add a new action to relay-handlers.ts and want it reachable via HTTP, add a matching dispatch_app_request site in sdk_client.rs — see Adding a new action below.

Validating action names

The runner ships a cross-language validator that diffs the two action sets:

cd qontinui-runner
npm run validate:ws-actions

# verbose mode lists wrapper-only orphans
npm run validate:ws-actions -- --verbose

# regenerate the table above (writes to the path you pass)
npm run validate:ws-actions -- --emit-doc docs-site/docs/wrappers/action-vocabulary.md

# CI-style check that the committed table is in sync
npm run validate:ws-actions -- --check-doc docs-site/docs/wrappers/action-vocabulary.md

Sample default output:

runner sites=146, wrapper actions=150, missing=0, orphans=4
ok: every runner action has a matching wrapper handler

missing=0 means every action the runner dispatches has a matching handler in relay-handlers.ts. If missing > 0, the validator exits non-zero and lists the offenders — a wrapper running this version of the runner would silently fail with NO_HANDLER for those routes.

The validator is wired into npm run check for the runner, so CI fails on action-name drift before the change ships.

Adding a new action

End-to-end checklist for adding action <X>:

1. Wrapper SDK side (ui-bridge/packages/ui-bridge/src/server/relay-handlers.ts): add a handler method that calls relayCommand('<X>', payload) (or relayWithFallback if you have a server-side fallback).
2. Browser-side wrapper (or your wrapper's transport.register('<X>', fn)): register the handler that actually does the work.
3. Runner (qontinui-runner/src-tauri/src/mcp/sdk_client.rs):
   • Add a handler function handle_<x> with /// METHOD /path — description doc comment, and have its body call dispatch_app_request(&state, "<X>", payload, METHOD, "/control/<path>", body).
   • Add .route("/ui-bridge/sdk/control/<path>", post(handle_<x>)) (or get/delete) in the route registration block.
4. Regenerate the doc table: npm run validate:ws-actions -- --emit-doc docs-site/docs/wrappers/action-vocabulary.md. Commit the diff alongside the source change.
5. Validate: npm run validate:ws-actions — should still report missing=0, with runner sites increased by 1.
6. Test: extend the wrapper-live-example smoke or add a curl-based assertion.

The runner's dispatch_app_request helper handles WS routing and HTTP fallback in one call — every retrofitted route follows the same pattern.

Related

• Authoring a Wrapper — when to pick which transport, register-frame contract, smoke test pattern.
• relay-handlers.ts — wrapper SDK handler vocabulary.
• sdk_client.rs — runner dispatch sites and HTTP routes.
• validate-ws-actions.mjs — drift validator + doc generator.