Subscriptions

Subscriptions push events to your driver. They travel through the same envelope as commands — a subscription is a command whose response returns a subscriptionId:

type ProtocolSubscription<T, REQ> = ProtocolCommand<
    T,
    REQ,
    { subscriptionId: string }
>;

Subscribing

Issue the subscription:* command in activate; the response carries the id you use to unsubscribe:

const res = await issueCommand({
    type: "subscription:camera:moved-debounced",
    driverId,
    requestId: nextRequestId(),
});
const subscriptionId = res.res.value.subscriptionId;

From then on, matching events arrive in onEvent:

type ProtocolSubscriptionEvent<T, BODY> = {
    type: T;
    subscriptionId: string;
} & (BODY extends undefined ? {} : { body: BODY });

Dispatch on event.type, read event.body, and unsubscribe with command:subscription:remove. Each subscription topic below lists its request (the subscription:* req) and the body of the event it delivers. Subscribing is a command, so it is gated by the same permissions: each section names the permission its topics need, and subscribing without it fails with an unauthorized error.

Typing a subscription

Same Extract pattern as commands — SubscriptionCommand for the subscribe request, DriverSubscriptionEvent for the event it delivers:

import type {
    SubscriptionCommand,
    DriverSubscriptionEvent,
} from "@drawdy/driver-protocol";

type PointerReq = Extract<
    SubscriptionCommand,
    { type: "subscription:scene:pointer" }
>;
type PointerEvent = Extract<
    DriverSubscriptionEvent,
    { type: "subscription:scene:pointer" }
>;

PointerReq carries req (here { elementIds? }); PointerEvent carries body.

Scene events

The subscriptions in this section require the scene permission.

"subscription:scene:elements-added"
req:  { properties: SubscribeableKey[] }
body: {
    drawdyElements: readonly SubscribedDrawdyElement[];
    properties: SubscribeableKey[];
}

"subscription:scene:elements-removed"
req:  { properties: SubscribeableKey[] }
body: {
    drawdyElements: readonly SubscribedDrawdyElement[];
    properties: SubscribeableKey[];
}

"subscription:scene:elements-updated"
req:  { properties: SubscribeableKey[] }
body: {
    drawdyElements: readonly SubscribedDrawdyElement[];
    properties: SubscribeableKey[];
}

"subscription:scene:elements-replaced"
req:  { properties: SubscribeableKey[] }
body: {
    drawdyElements: readonly SubscribedDrawdyElement[];
    replaced: readonly SubscribedDrawdyElement[];
    properties: SubscribeableKey[];
}

"subscription:scene:activity"
req:  { rect: { x: number; y: number; width: number; height: number } }
body: {
    drawdyElementIds: string[];
    rect: { x: number; y: number; width: number; height: number };
}

"subscription:scene:pointer"
req:  { elementIds?: string[] }
body:
    | {
          type: "up" | "down";
          drawdyElementIds: string[];
          pressure: number;
          cursor: {
              domSpace: { x: number; y: number };
              canvasSpace: { x: number; y: number };
          };
      }
    | {
          type: "enter" | "out";
          drawdyElementIds: string[];
          cursor: {
              domSpace: { x: number; y: number };
              canvasSpace: { x: number; y: number };
          };
      }
    | { type: "cancel" }

"subscription:scene:pointer-position"
body: {
    position: {
        domSpace: { x: number; y: number };
        canvasSpace: { x: number; y: number };
    };
}

"subscription:scene:click"
req:  { elementIds?: string[] }
body: {
    drawdyElementIds: string[];
    cursor: {
        domSpace: { x: number; y: number };
        canvasSpace: { x: number; y: number };
    };
}

"subscription:scene:text-edit"
body:
    | {
          type: "update";
          rect: { x: number; y: number; width: number; height: number };
          font: number;
          lineHeight: number;
          text: string;
      }
    | { type: "commit" | "cancel" }

"subscription:scene:drawdy-element-selection"
body: { drawdyElementIds: string[] }

"subscription:scene:drawdy-elements-dragged"
body:
    | { type: "dragStart" | "dragging"; drawdyElementIds: string[] }
    | { type: "dragEnd" }

The properties you pass when subscribing to element events select which fields populate each returned SubscribedDrawdyElement. elements-replaced reports both the new elements (drawdyElements) and the ones they replaced (replaced). scene:activity fires whenever there is activity inside the rect you registered. scene:pointer reports pointer activity over scene elements — type says which: down/up are presses (they carry pressure), and enter/out fire once as the pointer moves onto or off an element (hover — no pressure). Both report every element under the cursor (drawdyElementIds) and the position in both domSpace (screen/client pixels) and canvasSpace (world coordinates). cancel fires when the gesture is aborted and carries nothing. Pass req.elementIds to hear only about down/up/enter/out that land on those elements (the body is narrowed to the matching ids); omit it to hear about any element. enter/out are suppressed while drawing. Pointer events over empty canvas don’t fire, but cancel always reaches every subscriber. Like dom:pointer, this topic is about hit-testing: every event tells you which elements the pointer interacted with. It never reports plain movement. scene:pointer-position is the topic for the cursor itself. It fires on every pointer move over the canvas, with or without an element underneath, and carries only the position in both domSpace and canvasSpace. Use it when you need to follow the cursor (a crosshair, a snapping guide, a brush preview) rather than react to elements. It is scene-only, has no element filter, and arrives at pointer frequency, so keep the handler light or throttle it yourself. scene:click fires on a completed click — a pointer press and release that land on the same scene element(s) — reporting the elements clicked (drawdyElementIds) and the cursor position. Like scene:pointer, pass req.elementIds to hear only about clicks on those elements (the body is narrowed to the matching ids); omit it to hear about any element. It’s the scene-level counterpart to subscription:dom:element-clicked — use it for clicks on canvas elements (including component/widget elements), which live in the scene rather than the host DOM. Both scene:pointer and scene:click also report preview elements created with hitTestable: true, which is how an extension gets hover and click on ephemeral on-canvas controls without committing anything to the scene. scene:drag reports the select tool moving elements on the canvas: one dragStart when a press on a selected element begins a move (it carries the ids being moved), a dragging per pointer move while held, and one dragEnd on release or cancel. Note that dragStart fires on the press itself, before any movement, so a plain click on an element produces a dragStart/dragEnd pair. Use it to hide transient on-canvas UI (handles, quick-add dots) while things move and rebuild it from fresh geometry on dragEnd. It’s the scene-level counterpart to subscription:dom:drag. scene:drawdy-element-selection fires whenever the canvas selection changes, delivering the full set of currently selected ids (drawdyElementIds is empty when the selection is cleared) — not a delta. Read the current selection at any time with command:scene:get-current-selected-drawdy-elements.

Tool events

The subscriptions in this section require the scene permission.

"subscription:tool:laser"
body: {
    type: "laser-state-update";
    lasers: LaserStroke[];
}

type LaserStroke = [number, number][];

tool:laser mirrors the laser pointer’s on-canvas trail. lasers is the complete set of strokes currently visible — each a list of [x, y] canvas-space points in draw order — not a delta. It fires when a stroke is finished (pointer up) and carries every stroke of the session, including earlier ones that are still fading, then fires once more with an empty lasers when the whole trail has faded out or the tool is cancelled. Nothing is sent while the pointer is still down; pair it with subscription:scene:pointer-position if you need the live cursor.

Collaboration events

The subscription in this section requires the collaboration permission. CollaborationUserPresence is described in Commands.

"subscription:collaboration:presence-changed"
body: { users: CollaborationUserPresence[] }

Each event carries the full list of users on the board, in the same form as command:collaboration:get-all-users-in-board, so the driver can replace its copy instead of applying a change. It fires when someone joins or leaves, when anyone’s cursor moves (including the user running the driver), and when anyone’s name, color, avatar or host status changes. It does not fire on subscribe; call get-all-users-in-board for the starting list.

Camera events

No permission is required for the subscriptions in this section.

"subscription:camera:moved-rapid";
body: {
    x: number;
    y: number;
    zoom: number;
}

("subscription:camera:moved-debounced");
body: {
    x: number;
    y: number;
    zoom: number;
}

moved-rapid fires continuously during movement; moved-debounced fires once movement settles.

DOM events

The subscriptions in this section require the dom permission.

"subscription:dom:element-clicked";
req: {
    domElementId: string;
}
body: {
    domElementId: string;
    clientX: number;
    clientY: number;
}

("subscription:dom:pointer");
req: {
    domElementId: string;
}
body:
    | {
          type: "enter" | "out";
          domElementId: string;
          clientX: number;
          clientY: number;
      }
    | { type: "cancel"; domElementId: string }

("subscription:dom:theme-changed");
body: {
    styling: ModuleStyling;
}

("subscription:dom:fullscreen-changed");
body: {
    fullscreen: boolean;
}

("subscription:dom:screen-resized");
body: {
    width: number;
    height: number;
}

("subscription:dom:drag");
req: {
    domElementId: string;
}
body: {
    type: "dragStart" | "dragging" | "dragEnd";
    domElementId: string;
    position: {
        canvasSpace: {
            x: number;
            y: number;
        }
        domSpace: {
            x: number;
            y: number;
        }
    }
}

element-clicked fires when the named element is clicked — scoped to req.domElementId, reporting the pointer position in client pixels. dom:pointer is the DOM counterpart of scene:pointer and, like it, is about hit-testing the element you name rather than tracking the cursor (for that, see scene:pointer-position). It is scoped to req.domElementId: enter/out fire once as the pointer moves onto or off the element (each carries the pointer position in client pixels), and cancel fires when the pointer interaction is aborted. enter/out fire on element changes, not on every move within the element. theme-changed delivers the updated ModuleStyling whenever the user switches theme. drag is scoped to the element you name in req.domElementId: it fires only for gestures that start on that element (the drag is tracked document-wide and its start element latched for the whole gesture, so events keep coming even after the pointer leaves — e.g. while you drag a floating element around). One dragStart on pointer-down, a dragging per move while held, one dragEnd on pointer-up. It is synthesized from raw pointer events rather than the browser’s native drag, so it fires reliably. Each event’s domElementId echoes the element the gesture started on. position carries both coordinate spaces: domSpace (screen/client pixels, for command:dom:move-floating-element) and canvasSpace (world coordinates, ready to use). Grab a floating element by giving its create-floating-element schema pointerEvents: "auto" so it receives the pointer-down.

Webview events

The subscriptions in this section require the dom permission.

"subscription:webview:message";
req: {
    webviewDomId: string;
}
body: {
    webviewDomId: string;
    message: unknown;
}

Input events

The subscriptions in this section require the dom permission.

"subscription:context-menu:clicked";
req: {
    menuId: string;
}
body: {
    menuId: string;
}

("subscription:keyboard:control-keys");
body: {
    key: ControlKey;
    shift: boolean;
    ctrl: boolean;
    meta: boolean;
    alt: boolean;
}

type ControlKey =
    | "tab"
    | "enter"
    | "shift"
    | "escape"
    | "space"
    | "backspace"
    | "delete"
    | "arrow-up"
    | "arrow-down"
    | "arrow-left"
    | "arrow-right";

Guide

Protocol reference

Subscribing

Typing a subscription

Scene events

Tool events

Collaboration events

Camera events

DOM events

Webview events

Input events

​Subscribing

​Typing a subscription

​Scene events

​Tool events

​Collaboration events

​Camera events

​DOM events

​Webview events

​Input events

Subscribing

Typing a subscription

Scene events

Tool events

Collaboration events

Camera events

DOM events

Webview events

Input events