Command Bus
The typed command bus every surface uses to mutate documents — executeCommand, the descriptor catalog, and the read-only query side.
Every document mutation in Volux — from the panels and toolbar to the AI Builder — runs through one path: the command bus. A command is a named, schema-validated operation with an undo policy; a query is a named, schema-validated read. Extensions get both through window.voluxPlugin.getCommandBus(), which returns the same binding the editor itself uses.
interface VoluxCommandBus {
executeCommand: (id: string, payload?: unknown) => CommandResult | Promise<CommandResult>;
queryScene: (id: string, params?: unknown) => QueryResult;
}The binding is editor-realm only
The editor boot installs the bus binding; the public frontend and the preview never do. On those pages getCommandBus() answers null — registration still works there, but only the shared-realm concerns of a module apply, and no command can execute. Any extension that mutates documents is editor-realm by definition.
Running commands
executeCommand takes a command id and a payload (omitted for commands that take none) and answers a settled envelope — failures are values, never exceptions:
const bus = window.voluxPlugin.getCommandBus();
const result = bus.executeCommand('scene.add', { sceneSettings: {} });
if (result.ok) {
console.log('created scene', result.data.id);
} else {
console.error(result.error.code, result.error.message);
}Three error codes cover every failure:
Prop
Type
Handlers may be asynchronous: when a handler returns a promise, executeCommand returns a promise of the settled envelope — await it and you get the same { ok } shape either way.
Descriptors and undo
Every command in the catalog carries a descriptor: a title, a description, a payload schema (a JSON-Schema subset — objects are closed with additionalProperties: false), the realm it applies in, and an exposure level. Two fields govern undo:
undoable— whether the operation enters the undo history. Most authoring commands are undoable; read-style or purely transient operations are not.gestureGroup— how a command joins undo steps:'merge'coalesces into the current gesture (a drag's many ticks become one undo step),'batch'joins an explicit batch group. Interactive commands that fire rapidly during a gesture set this so a single Ctrl+Z reverts the whole gesture.
AI-exposed commands additionally accept an options.groupId in their payloads — the AI Builder tags every command of one turn with the same group id, so a single undo reverts the whole turn. The first module example shows a descriptor end to end.
Registering commands
Extensions contribute commands through a module's commands concern. Each entry is a catalog-ready record produced by defineCommand — the same factory Volux's own command families use:
import { defineCommand } from 'volux-commands/define-command';
import type { RegisteredCommandRecord } from 'volux-commands/define-command';
const reportCommand: RegisteredCommandRecord = defineCommand({
id: 'notes.report',
title: 'Notes Report',
description: 'Counts the scenes and objects of the open document.',
schema: { type: 'object', properties: {}, additionalProperties: false },
undoable: false,
realm: 'editor',
exposure: 'ui-only',
handler: (ctx, payload) => {
const canvas = ctx.getState().editorCanvas.present;
return { scenes: Object.keys(canvas.scenes).length, objects: Object.keys(canvas.objects3d).length };
}
});The handler receives an ops context — the sanctioned seam to the editor store (getState, dispatch, tree-sync and selection ports). It is the same context every built-in command runs against; going around it (dispatching raw store actions from panel code, say) bypasses undo and tree sync and has no guarantee of staying correct across releases.
Command ids are unique across the catalog — registering a duplicate throws. Late-registered commands land through the additive commands concern, so successive modules never collide with each other's ids, and the catalog's dup guard remains the single collision law. A descriptor may also declare an edition list of entitlement flags; a gated descriptor registers only when the boot's edition capabilities carry one of its flags — an unlicensed build never sees the id at all.
Queries
The read side mirrors the command side. queryScene(id, params?) is synchronous — queries answer from the store snapshot in hand — and the envelope requires data on success (a query always answers something):
const caps = bus.queryScene('capabilities.describe', {});
if (caps.ok) {
console.log(caps.data.capabilities.speaker);
}Query error codes are their own vocabulary: unknown-query (catalog miss only — never a data miss), invalid-params, and handler-error. The built-in catalog carries five queries:
| Query | Answers |
|---|---|
scene.tree | One scene's identity tree — the scene row, lean object rows, DOM-element rows. Call it first: every id a command takes is opaque, copied from here. |
object.get | One object at one band — the band-resolved record, raw breakpoint overrides, effective state id, and the composed per-type values. |
object.events | One record's event wiring — the owner's events with their actions in force, plus the offered actions per event type. The id resolves against objects first, then DOM elements. |
capabilities.describe | The complete per-kind capability matrix (see the Capabilities Reference). |
document.status | Editor-session status for tooling surfaces — dirty/save flags, active scene and band, selection, undo depths. |
The exposure note
Descriptors carry exposure: 'ai' | 'ui-only'. The value does not gate execution — both levels run through the same bus — it gates disclosure: exactly 46 command ids and 3 queries (scene.tree, object.get, capabilities.describe) are marked ai, and those are the only ids the AI Builder's tool catalog exposes to the model. Everything else is ui-only. When you register a command, pick honestly: a command the AI should drive gets exposure: 'ai'; a command only your own UI invokes stays ui-only.
Next
- Example: Your First Module — a working module whose command runs through this bus.
- registerModule & Module Anatomy — how the
commandsconcern rides activation and late registration. - Capabilities Reference — the matrix behind
capabilities.describe.
Capabilities Reference
The object-kind capability matrix — every flag, every kind's row, and how modules compose the rows they own.
Example: Your First Module
A complete, small feature module from registration to a working panel — every field mirrors the real API.
Last updated on