Contribution APIs

activate(context) receives capability-scoped registrars. Import the contribution types from @talerook/sdk; create a host with createExtensionHost from @talerook/engine.

Register and consume

Surface	Register in an extension	Consume in the host
Engine	context.engine.registerCommand(command)	host.execute(id, payload)
VTT layer	context.vtt.registerLayer(layer)	host.renderLayers(view)
VTT input tool	context.vtt.registerTool(tool)	host.pointer(id, input)
Rules system	context.systems.register(system)	host.system(id)
UI panel	context.ui.registerPanel(panel)	host.renderPanel(id, view)
Rich UI surface	context.ui.registerSurface(surface)	host.mountSurface(id, platform, target, options?)
Presentation	context.presentation.register(effect)	host.present(message)
Events	context.events.subscribe(type, listener)	host.emit(event)

Use host.contributions(kind) to enumerate commands, layers, tools, systems, panels, surfaces or presentation. host.subscribe(listener) reports host invalidation; keep its disposer in the adapter's own lifecycle.

Commands

A command contributes { id, title, execute(payload, context) }. Payloads and results are JsonValue. The execution context provides:

• signal: aborts with the owning extension's lifetime.
• dispatch({ type, payload }): invokes the host's durable-command adapter.
• present({ type, payload }): routes a local presentation message.

Validate your payload before acting. A namespaced command identifier selects local behavior; it is not authorization to perform a server action.

Layers and input

A layer contributes { id, order, render(view) }. It returns DrawPrimitive[]: circle, line, text or image. Images and resources explains opaque asset references, aspect fit and authenticated resource leases. Coordinates are world coordinates. The adapter owns camera transforms, painting and GPU/DOM resources. It must not expose canonical secret state to make rendering convenient.

A tool contributes { id, title, cursor, onPointer(input, context) }. Input has phase (down, move, up, cancel), a world-coordinate point, button, shiftKey and altKey. The tool context exposes execute(commandId, payload), invalidate() and signal.

import type { ToolContribution } from '@talerook/sdk';

const markerTool: ToolContribution = {
  id: 'example.marker/tool',
  title: 'Place marker',
  cursor: 'crosshair',
  async onPointer(input, context) {
    if (input.phase !== 'up' || input.button !== 0) return;
    await context.execute('example.marker/place', {
      x: input.point.x,
      y: input.point.y,
    });
  },
};

This tool expects a place command that validates and consumes x/y; the minimal quickstart intentionally places a fixed marker instead. Use one registration path for first-party and extension tools. Keep gesture previews local and send a deliberate durable command when the action completes.

UI panels

A panel contributes { id, title, render(view) } and returns a semantic PanelModel. Sections have a heading, optional text and optional actions. Actions contain id, label, commandId, payload and optional disabled.

The application renders accessible controls and routes an action to host.execute(action.commandId, action.payload). Panel models carry content and intent; they do not own the DOM or mutate a shared application store.

For a scene library, character sheet or encounter view, use a rich UI surface. It mounts into a typed platform adapter with its own resource lifetime and optional subject-scoped HTTP transport.

Presentation

A presentation contribution is { id, present(message, context) }. It observes { type, payload } and may return a cleanup function, synchronously or through a promise. The host owns that cleanup through unload. The context exposes signal and invalidate().

Presentation covers local playback and effects. A durable dice or rules outcome comes from authority; the effect displays the supplied outcome. Do not sample a second result to animate it.

Rules and events

A system provides pure validate, derive and resolveCheck methods plus id, title and schemaVersion. Rules systems explains source and entropy handling.

Events use { type, payload }; an extension subscribes to a specific event type. Events are local host observations, not an authenticated network protocol. Do not emit secrets into a host that serves a different audience.