registerModule & Module Anatomy
The anatomy of a feature module — the module record, the two-tree split, dependency and entitlement gating, and late registration semantics.
A feature module is a plain data record: an id, the modules it depends on, optional entitlement flags, and a bag of capability contributions. window.voluxPlugin.registerModule(module) hands that record to the extension registry, which decides whether — and in what order — the module activates. Nothing in a module runs at registration time: a module is a declaration, and activation is what turns the declaration into live registrations.
The module record
Every module conforms to one shape:
Prop
Type
A minimal, fully valid module:
window.voluxPlugin.registerModule({
id: 'pro.notes',
dependsOn: ['core-builtin'],
capabilities: {}
});dependsOn: ['core-builtin'] is the convention for extension modules: it orders the feed base-then-pilot and keeps the module activatable wherever core-builtin is registered.
How activation works
At boot, the registry activates every registered module with Kahn's algorithm — a topological sort over dependsOn, with the ready queue seeded in registration order, so among independent modules the earlier-registered one activates first. Three things keep a module out, each disclosed with its direct blocker:
Prop
Type
The first activation freezes the kernel: later calls return the same memoized result, and the frozen feed is never re-run. Everything a module contributes lands through the activation feed — the ordered aggregate of every activated module's capabilities, which realm-specific appliers turn into live registrations (executors, capability rows, runtime mounts, panel slots, catalog commands).
The two-tree split
Volux's own pilots each live as two trees, and extensions that need both a runtime and an editor presence follow the same split:
- The portable half —
features/<id>/in Volux's own source. Realms-agnostic data: object-kind rows, event-action executors, runtime mounts, capability flag deltas, scene-settings declarations. It registers in both activations (editor and frontend), so its runtime mounts render on the public page too. - The editor half —
editor/feature-ui/<id>/in Volux's source. Everything editor-realm: command descriptors, toolbar tool entries, panel sections, action config forms, tree icons. It registers only from the editor's bus activation, and the frontend never loads it.
The speaker pilot is the canonical example. Its portable half:
import { OBJECT3D_CAPABILITIES } from 'volux-core/document/capabilities';
import { registerModule } from 'volux-registry';
import { SceneAudioProvider } from 'volux-shared/runtime/speaker/scene-audio-listener';
import { SpeakerNode } from 'volux-shared/runtime/speaker/speaker-node';
import { speakerControlAction } from './speaker-control';
import type { FeatureModule } from 'volux-registry';
export const SPEAKER_MODULE: FeatureModule = {
id: 'speaker',
dependsOn: ['core-builtin'],
capabilities: {
objectKinds: [{ kind: 'speaker', capabilities: OBJECT3D_CAPABILITIES.speaker }],
actions: [{ type: 'speakerControl', executor: speakerControlAction }],
runtimeMounts: [
{ kind: 'object-node', objectType: 'speaker', component: SpeakerNode },
{ kind: 'scene-view', position: 'wrapper', realm: 'both', component: SceneAudioProvider }
]
}
};And its editor half — note the id and the dependency on both the portable module and the editor base:
export const SPEAKER_EDITOR_MODULE: FeatureModule = {
id: 'speaker-editor',
dependsOn: ['speaker', 'editor-builtin'],
capabilities: {
commands: SPEAKER_SETTINGS_COMMANDS,
toolAdd: [{ kind: 'speaker', toolId: 'speaker', factory: createDefaultSpeaker }],
toolMenus: speakerToolMenus,
panels: [{ objectType: 'speaker', components: [SpeakerSection, SpeakerSpatialSection] }],
actionConfigForms: [{ actionType: 'speakerControl', component: SpeakerControlConfigForm }],
treeIcons: [{ objectType: 'speaker', iconName: 'speaker' }]
}
};An extension registering after boot through the public seam does not need to split trees at all — a single module registered late simply contributes whichever concerns it declares, and the realms apply what applies (shared concerns everywhere; editor and command concerns only where the bus binding is installed).
The concerns
Each key of capabilities is a concern the appliers know how to land:
| Concern | Feeds | Realm |
|---|---|---|
objectKinds | Capability rows per object kind | Both |
contributesCapabilities | Per-kind capability flag deltas | Both |
actions | Event-action executors + the offered-actions menu | Both |
eventTypes | The implemented trigger set | Both |
actionGate | Which actions are offered per event type | Both |
runtimeMounts | Object-node and scene-view mounts | Both |
layerStructure | Material-layer structural dispatch | Both |
layerKinds | Material-layer UI tables | Editor |
sceneSettings | Scene-settings declarations (data-only) | Both |
commands | Command descriptors into the catalog | Editor |
toolAdd | Add-kind factories + toolbar tool ids | Editor |
toolMenus | Toolbar flyout groups | Editor |
panels | Object3D panel sections per kind | Editor |
scenePanels | Scene-panel section slots | Editor |
actionConfigForms | Event-action config forms | Editor |
treeIcons | Tree-row icons per kind | Editor |
The concerns split into two composition families, and the difference matters for late registration:
- Replace-composed —
objectKinds,actions,eventTypes,actionGate,toolMenus,layerKinds,layerStructure. Their appliers register the composed aggregate as one whole entry, so a late module's slice is kernel-enriched to the full world (every applied module so far plus the new one). This is why a commands-only late module cannot accidentally wipe the boot's layer tables: the kernel composes the slice, not the caller. - Additive —
commands,runtimeMounts,toolAdd,panels,scenePanels,actionConfigForms,treeIcons,sceneSettings. These register per entry and pass through slice-only, so successive late modules never re-register each other's entries.
Late registration
Registering through window.voluxPlugin after the boot activation has run triggers a scoped re-apply — the kernel classifies the module with the same absence semantics as the boot, and on success appends its feed slice deterministically after the boot feed. The return value is the disclosure surface, with three possible statuses:
const outcome = window.voluxPlugin.registerModule(myModule);
switch (outcome.status) {
case 'applied':
// outcome.slice — the feed slice that was applied
break;
case 'absent':
// outcome.absent — { id, reason, blocker }
console.warn(`${outcome.absent.id} not applied: ${outcome.absent.reason} (${outcome.absent.blocker})`);
break;
case 'pre-activation':
// The boot activation has not run yet; the module rides it.
break;
}appliedcarries theslicethat was handed to the realm appliers.absentcarries{ id, reason, blocker }— the same three reasons as the boot (missing-dependency,missing-entitlement,cycle), with the entitlement check run against the first activation's entitlement set.pre-activationmeans the boot activation has not run yet; the module simply rides it.
Dependents are not cascaded: a late re-apply is scoped to the new module alone. And registration is side-effect-free on the modules themselves — Volux's own modules never self-register on import; a boot entry calls each module's register function exactly once.
Malformed records throw named errors
The public seam validates the record shape before anything else: id must be a non-empty string, dependsOn an array, capabilities a non-null object. A malformed record throws a named error saying exactly which field is wrong — fix the record, do not wrap the call in a try/catch and move on.
Next
- Capabilities Reference — what the
objectKindsrows and flag deltas compose into. - Command Bus — authoring the
commandsconcern's descriptors. - Example: Your First Module — the anatomy above, assembled into a working module.
Overview: voluxPlugin API
The versioned public API seam for extending the Volux editor — what window.voluxPlugin exposes and when to reach for it.
Capabilities Reference
The object-kind capability matrix — every flag, every kind's row, and how modules compose the rows they own.
Last updated on