Update an existing plugin — PexarBolt Docs

Legacy Plugin CoverageThe production contract remains SDK/device 1.0.0 and JSON projection format 1. widgets are additive; existing installed flat projections do not need conversion. Capability negotiation prevents newer controls from being sent to older firmware.Examples Reviewed

Source

Coverage and migration

Firmware examples/music-lyrics

Media metadata/control, lyric parsing and timed lines already have a production counterpart in apps/desktop/examples/music-lyrics. Its ordinary text, image, progress and hit nodes remain supported. The trusted Node/MediaRemote server becomes the permission-scoped media broker; copying the old manifest/server directly is invalid.

Client examples/video-player

Migrated to native JSON buttons and system icons/fonts. Image stream supports tap-to-enter fullscreen and tap-anywhere-to-exit; adaptive playback still requests at most 50 fps. Old hit/knob event contexts remain accepted alongside widget contexts.

Firmware examples/agent-studio

Rows, columns, absolute stacks, text, images, icons, buttons and progress map to current projection nodes. Badge/value/divider/spacer/tile visuals can be composed from text/rect/container/button with explicit geometry. Its repeated rich cards require fixed child nodes or conversion to a plain option list; current lists are not arbitrary item templates.

Firmware examples/plugin-host

Catalog and lifecycle are host responsibilities, now supplied by the client plugin manager, runtime and transport. The development HTTP/SSE server is not an installable production plugin.

Remaining Differences

Legacy gauge and sparkline are not public JSON nodes. They can now be drawn with host Canvas and ctx.frames, alongside normal JSON controls; this retains the image-stream limits and host dependency.

Legacy CSS grids/flex growth and item-relative expressions must be resolved into explicit row/column/absolute sizes and host-published paths. Production firmware runs no browser, CSS or JS.

Legacy Agent Studio includes simulated telemetry/release workflows and direct macOS keyboard, mouse, text injection and application focusing. These are not exposed by the current broker. New controls do not provide those host APIs.

Consumer HID keys are available through the actual Dock with hid.consumer; the legacy absolute Core Audio volume read/write API is different. Do not invent an absolute volume or a host acknowledgement.

Consumer playback has a production broker. UI migration must not replay external writes.

Music Lyrics and Video Player can use the current package form. Custom chart visuals are possible through host-rendered frames. Agent Studio is retired because plugins no longer have access to built-in Agent sessions or approval requests.Removed Agent Runtime APIsctx.agent.query(), ctx.agent.detail() and ctx.agent.approve() are removed. The agent.read and agent.approve permissions are no longer accepted in manifests or event declarations. Packages depending on these operations must remove the integration and permissions before they can be checked, imported or submitted. Removing only the permissions does not migrate host code. Live and preview brokers reject the retired operations, including calls made through raw SDK IPC or stale grants.The App-owned Agent UI and Plugin Studio's AI authoring/MCP tools remain separate from the plugin runtime contract. Plugins cannot query built-in Agent sessions or resolve their approval requests.Authoring And ValidationUse the current contract and apps/desktop/examples/control-gallery for both control batches, system resources and image animation/fullscreen. The gallery is a local authoring/verification example, not an automatically installed user plugin. Its camera names are fixture selections; it does not claim camera streaming support.The bundled sdk-showcase extends this into a working capability gallery, including host Canvas, raw BGRA/JPEG and decoded GIF frames. See plugin media for its API and source boundaries.New interactions should use widgets; existing hits continue to send their old context. Widgets send {id,value,context}. Update event schemas and handlers together, and retain null support on shared knob events. Prefer the built-in named fonts/icons; keep real cover/photo/video artwork as assets.The dated control, SDL and physical-device results for this migration are recorded in hardware verification.Local page navigationProjection.pages adds four-direction Dock-local navigation in Host-connected and independent native installations. Tag primitives, hits or root widgets with page; use initialPage for entry and optional read-only pageChange for Host notifications. Requires firmware advertising pages.swipe.v1; legacy projections remain valid. See local page navigation for the declaration, lifecycle, gesture priorities and examples.