Volux Docs

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:

ConcernFeedsRealm
objectKindsCapability rows per object kindBoth
contributesCapabilitiesPer-kind capability flag deltasBoth
actionsEvent-action executors + the offered-actions menuBoth
eventTypesThe implemented trigger setBoth
actionGateWhich actions are offered per event typeBoth
runtimeMountsObject-node and scene-view mountsBoth
layerStructureMaterial-layer structural dispatchBoth
layerKindsMaterial-layer UI tablesEditor
sceneSettingsScene-settings declarations (data-only)Both
commandsCommand descriptors into the catalogEditor
toolAddAdd-kind factories + toolbar tool idsEditor
toolMenusToolbar flyout groupsEditor
panelsObject3D panel sections per kindEditor
scenePanelsScene-panel section slotsEditor
actionConfigFormsEvent-action config formsEditor
treeIconsTree-row icons per kindEditor

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;
}
  • applied carries the slice that was handed to the realm appliers.
  • absent carries { 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-activation means 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

Last updated on

On this page