Volux Docs

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:

QueryAnswers
scene.treeOne 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.getOne object at one band — the band-resolved record, raw breakpoint overrides, effective state id, and the composed per-type values.
object.eventsOne 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.describeThe complete per-kind capability matrix (see the Capabilities Reference).
document.statusEditor-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

Last updated on

On this page