feat(superdoc/ui): custom toolbar command registration (SD-2802) (#3004)

* feat(superdoc/ui): custom toolbar command registration (SD-2802)

ui.commands was a closed registry — 38 hardcoded ids, no extension
hook. Every TipTap / CKEditor / TinyMCE consumer with custom toolbar
buttons (AI rewrite, insert mention, internal workflow actions, slash
commands) had to fork the registry or work around it. The drop-in
replacement story isn't real until consumers can wire their own
buttons through the same surface as built-ins.

Add ui.commands.register(...) returning a typed registration object:

  const ai = ui.commands.register<{ prompt: string }>({
    id: 'company.aiRewrite',
    execute: async ({ payload, superdoc }) => { ... return true; },
    getState: ({ state }) => ({ active: false, disabled: !ready }),
  });

  ai.handle.execute({ prompt: 'fix tone' });   // typed
  ai.invalidate();                              // re-run getState
  ai.unregister();                              // idempotent

Custom commands appear in ui.toolbar.snapshot.commands alongside
built-ins. Every entry now carries source: 'built-in' | 'custom' so
consumers can render one uniform toolbar without branching on the id.

Built-in collisions are refused by default with a console warning;
override: true on the registration replaces the built-in deliberately.
Custom-vs-custom replacement warns and replaces. getState errors fall
back to a static disabled-false state and log once per unique error
message. Async execute is supported and normalized to boolean.

invalidate() exists because custom command state often depends on
external app state (permissions, AI quota, upload progress) that
SuperDoc has no way to observe via editor events. Consumers wire it
to whatever signal their app uses; the controller microtask-coalesces
the resulting snapshot rebuild.

The captured registration handle is the realistic typed path —
indexing ui.commands['company.aiRewrite'] degrades to unknown without
module augmentation. Don't promise type safety we can't deliver.

Backed by 14 new unit tests in custom-commands.test.ts. Existing 81
ui tests continue to pass. tsc -b clean.

* fix(superdoc/ui): four correctness fixes from PR #3004 review (SD-2802)

All four were verified by failing tests/typecheck before fixing:

1. Default TPayload to `void` instead of `unknown`. Without this,
   `register({ id, execute: () => true })` returned a handle whose
   zero-arg `handle.execute()` was a type error — consumers had to
   write `register<void>({...})` for every payload-less button.

2. Type `snapshot.commands` as `{ [id: string]: ... | undefined }`.
   The prior `Record<string, ...>` claimed every string lookup
   returned a state, but at runtime unregistered ids return undefined.
   Consumers writing `snapshot.commands[id].disabled` would crash.

3. Preserve `null` returned from `getState`. The old
   `derived?.value ?? STATIC_CUSTOM_STATE.value` collapsed null to
   undefined, so a custom command using null to mean "no current
   value" (matching built-ins like link / text-color) couldn't.

4. Stop observers firing after unregister. The Subscribable lives on
   the controller's selector substrate and outlives the registration;
   without an explicit early-return the next snapshot rebuild emitted
   the static fallback `{ disabled: false }` to active observers,
   leaving stale buttons enabled. The observe wrapper now detaches
   its inner subscription on the first post-unregister emit.

Adds four regression tests; total 18 in custom-commands.test.ts (up
from 14). All 99 ui tests pass, tsc -b clean.

* fix(superdoc/ui): identity-guard register lifecycle + active observer disposal (SD-2802)

PR #3004 second review pass.

Bot P1: A's stale `unregister()` would delete B's replacement.

  // before: identity-blind
  unregister() { entries.delete(id); ... }

  // after: identity-checked
  unregister() {
    if (entries.get(id) !== ownEntry) return; // stale call from prior owner
    entries.delete(id);
    ...
  }

Same guard on `invalidate()`. Verified by failing test before fix.

Bot P2: existing observers attached to a registration are now actively
disposed during `unregister()` and during register-time replacement.
The lazy `!entries.has(id)` short-circuit in the observer wrapper is
kept as a safety net — but no longer the only mechanism. A new
`observerDisposers: Map<string, Set<() => void>>` tracks each active
observer's teardown so the registry can call them all on demand.

Three new regression tests:
- A.unregister after B replaced does not remove B
- A.invalidate after B replaced does not re-emit on B's observer
- Replacement actively disposes prior-registration observers

Total 21 tests in custom-commands.test.ts (up from 18). All 102 ui
tests pass, tsc -b clean.

Author: caio-pizzol

packages/super-editor/src/ui/create-super-doc-ui.ts

@@ -16,6 +16,7 @@ import type {
 } from '@superdoc/document-api';
 import { shallowEqual } from './equality.js';
 import { scrollRangeIntoView } from './scroll-into-view.js';
+import { createCustomCommandsRegistry } from './custom-commands.js';
 import type {
   CommandHandle,
   CommandsHandle,
@@ -34,6 +35,8 @@ import type {
   Subscribable,
   ToolbarCommandHandleState,
   ToolbarHandle,
+  ToolbarSnapshotSlice,
+  UIToolbarCommandState,
   ViewportGetRectInput,
   ViewportHandle,
   ViewportRect,
@@ -231,6 +234,12 @@ export function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI {
     }
   });
 
+  // Custom-commands registry — built lazily so its hooks (scheduleNotify,
+  // buildSubscribable, isBuiltIn) can reference the substrate primitives
+  // declared further down. The actual registry instance is created after
+  // `select` is in scope.
+  const BUILT_IN_COMMAND_ID_SET: Set<string> = new Set(ALL_TOOLBAR_COMMAND_IDS);
+
   // Comments slice cache. `editor.doc.comments.list()` is O(N) and
   // re-running it on every `computeState()` would tax the hot path —
   // instead we cache the list result and refresh on `commentsUpdate` /
@@ -471,11 +480,31 @@ export function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI {
       selectionMemo = { key: selectionKey, slice: selectionSlice };
     }
 
-    return {
+    // Built-in commands are tagged with `source: 'built-in'` so consumers
+    // can render one uniform toolbar without branching on the id.
+    // Custom commands (registered via `ui.commands.register`) are merged
+    // in below, after the rest of the state is built — their `getState`
+    // callback receives the same `SuperDocUIState` we return here so the
+    // deriver can read selection, document mode, etc. without dipping
+    // back into the controller.
+    const builtInCommands: Record<string, UIToolbarCommandState> = {};
+    if (toolbarSnapshot.commands) {
+      for (const [id, cmdState] of Object.entries(toolbarSnapshot.commands)) {
+        if (!cmdState) continue;
+        builtInCommands[id] = {
+          active: cmdState.active,
+          disabled: cmdState.disabled,
+          value: cmdState.value,
+          source: 'built-in',
+        };
+      }
+    }
+
+    const partial: SuperDocUIState = {
       ready,
       documentMode,
       selection: selectionSlice,
-      toolbar: toolbarSnapshot,
+      toolbar: { context: toolbarSnapshot.context, commands: builtInCommands } as ToolbarSnapshotSlice,
       comments: {
         total: commentsListCache.total,
         items: commentsListCache.items,
@@ -491,6 +520,16 @@ export function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI {
       },
       review: reviewSlice,
     };
+
+    const customCommandStates = customCommandsRegistry.computeStates(partial);
+    const mergedCommands: Record<string, UIToolbarCommandState> = customCommandStates
+      ? { ...builtInCommands, ...customCommandStates }
+      : builtInCommands;
+
+    return {
+      ...partial,
+      toolbar: { context: toolbarSnapshot.context, commands: mergedCommands } as ToolbarSnapshotSlice,
+    };
   };
 
   // Wire SuperDoc-instance events. The wrapper-side bus (editorCreate /
@@ -667,7 +706,11 @@ export function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI {
   // built-in SuperToolbar.vue (and external standalone-controller
   // consumers) can swap to ui.toolbar without API churn.
   const toolbar: ToolbarHandle = {
-    getSnapshot: () => toolbarController.getSnapshot(),
+    // Pull from `state.toolbar` (post-merge with custom commands and
+    // tagged with `source`) rather than the bare headless-toolbar
+    // snapshot — the public `ToolbarSnapshotSlice` shape is the merged
+    // one, not the underlying built-ins-only shape.
+    getSnapshot: () => computeState().toolbar,
     subscribe(listener) {
       // Drives off the same selector substrate so subscribers receive
       // the same coalesced burst pattern as ui.select consumers.
@@ -736,9 +779,36 @@ export function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI {
     };
   };
 
+  // Custom commands registry. Wires the substrate primitives (selectors
+  // for state observation, scheduleNotify for re-emit) to the registry
+  // so registered commands ride the same dedupe/coalesce posture as
+  // built-ins. Built-in collisions are refused without `override: true`.
+  const customCommandsRegistry = createCustomCommandsRegistry({
+    superdoc,
+    isBuiltIn: (id) => BUILT_IN_COMMAND_ID_SET.has(id),
+    scheduleNotify,
+    buildSubscribable: (id) => select((state) => state.toolbar.commands?.[id], shallowEqual),
+  });
+  teardown.push(() => {
+    customCommandsRegistry.destroy();
+  });
+
   const commands = new Proxy({} as CommandsHandle, {
     get(_, prop) {
       if (typeof prop !== 'string') return undefined;
+      // `register` is the one non-id key on the Proxy. Delegates to the
+      // custom-commands registry; everything else flows through the
+      // per-id handle cache below.
+      if (prop === 'register') {
+        return customCommandsRegistry.register.bind(customCommandsRegistry);
+      }
+      // Custom-registered ids surface a typed handle from the registry.
+      // Built-in ids fall through to the existing per-id cache so they
+      // keep the same observe/execute shape they had before SD-2802.
+      if (customCommandsRegistry.has(prop)) {
+        const customHandle = customCommandsRegistry.getHandle(prop);
+        if (customHandle) return customHandle;
+      }
       let handle = commandHandleCache.get(prop);
       if (handle) return handle;
       handle = buildCommandHandle(prop as PublicToolbarItemId);