Peter Steinberger
ae55a4090c
* refactor(canvas): retire legacy host and commands * refactor(apple): narrow shared Canvas contracts * refactor(macos): keep Canvas as widget presenter * refactor(ios): remove Canvas client * refactor(android): remove Canvas client * refactor(linux): remove Canvas client * fix(ci): isolate native locale artifacts * fix(linux): regenerate companion lockfile * fix(canvas): refresh native tool display metadata * test(canvas): align coverage with presenter surface * test(canvas): remove obsolete asset root seam * test(canvas): stabilize retirement CI coverage * refactor(swift): remove orphaned resource wrapper * test(ios): remove retired canvas layout assertion * fix(macos): reserve retired canvas command namespace * refactor(macos): isolate canvas command policy * fix(canvas): select only eligible macOS panels * fix(canvas): keep panel selection plugin-owned
3.4 KiB
summary, read_when, title, doc-schema-version
| summary | read_when | title | doc-schema-version | |||
|---|---|---|---|---|---|---|
| Present hosted widgets in the macOS panel |
|
Widget panel | 1 |
The macOS app includes a native panel for presenting hosted widget documents. The Canvas plugin owns this presentation path; it is not a standalone visual workspace or an A2UI push target.
The recommended agent path is show_widget with
presentation.target: "node_panel". OpenClaw stores the widget as a hosted
document, selects a connected macOS node, opens the panel, and navigates it to
that document. If no eligible Mac is connected or presentation fails, the
widget still appears inline in chat and the tool result explains how to retry.
Widgets in the native panel are render-only. Host-integrated widget actions remain available in Control UI chat and session dashboard surfaces, not in the panel.
Panel behavior
- The panel is borderless, resizable, and anchored near the menu bar or mouse cursor.
- Presenting a widget does not switch apps or take keyboard focus.
- Only one widget panel is visible at a time.
- The app remembers the panel's size and position per session.
Canvas can be disabled from Settings -> Allow Canvas. When it is disabled,
panel commands return CANVAS_DISABLED.
Agent path
Ask the agent to use show_widget and target the node panel. The tool exposes
node_panel only while a widget presenter plugin is active.
{
"title": "Build status",
"widget_code": "<main><h1>Build passed</h1></main>",
"presentation": { "target": "node_panel" }
}
The result identifies the selected Mac when presentation succeeds. OpenClaw
currently selects only a connected macOS node that declares canvas.present.
Node commands
The paired-node command surface contains three commands:
openclaw nodes canvas present --node <id>
openclaw nodes canvas navigate --node <id> "/__openclaw__/canvas/documents/<document-id>/index.html"
openclaw nodes canvas hide --node <id>
canvas.presentshows the panel. It also accepts the existing optional target and placement arguments.canvas.navigateloads a hosted widget-document path or an app-local Canvas URL.canvas.hidehides the panel without changing its current document.
Hosted paths under /__openclaw__/canvas/ are resolved through the node
session's current scoped pluginSurfaceUrls.canvas URL. The app refreshes that
short-lived capability before navigation; callers should pass the document
path, not construct or copy a capability URL.
The app-local scheme remains available for app-owned content:
openclaw-canvas://<session>/<path>
Files addressed by that scheme must remain inside the session's Canvas root in Application Support. Directory traversal is blocked.
A2UI belongs on session dashboards
A2UI widgets render on session dashboards, where they share
the same pinning, layout, approval, and interaction model as other dashboard
widgets. Their renderer bundles continue to load from the Gateway's
/__openclaw__/a2ui/ asset route.
The macOS panel does not accept A2UI push/reset commands and does not automatically navigate to an A2UI page.