superdoc 2.0.0-next.44 → 2.0.0-next.46

package/dist/superdoc/src/core/types/index.d.ts

@@ -1,25 +1,13 @@
 import { Doc as YDoc } from 'yjs';
 import { HocuspocusProviderWebsocket } from '@hocuspocus/provider';
 import { Ref, ComputedRef } from 'vue';
-import { DocumentApi } from '../../../../document-api/src/index.js';
 import { DocumentFontOption, FontAssetUrlResolver, FontFamilyOption, FontLoadSummary, FontResolutionRecord } from '../../../../shared/font-system/src/index.js';
 import { SuperDoc as SuperDocClass } from '../SuperDoc.js';
 import { SuperDocActiveEditorExtensions, SuperDocExtension } from '../extensions/index.js';
+import { BrowserDocumentApi } from '../../public/browser-document-api.js';
 export type { DocumentFontOption, FontAssetUrlContext, FontAssetUrlResolver, FontFaceSlot, FontFamilyOption, FontLoadResult, FontLoadStatus, FontLoadSummary, FontResolutionReason, FontResolutionRecord, GlyphException, ResolvedFontEvidence, SubstitutePolicyAction, SubstituteVerdict, } from '../../../../shared/font-system/src/index.js';
 export type SuperDoc = SuperDocClass;
-type MaybePromise<T> = T | Promise<T>;
-type BrowserDocumentApiObject<T> = {
-    [K in keyof T]: BrowserDocumentApiValue<T[K]>;
-};
-type BrowserDocumentApiValue<T> = T extends (...args: infer Args) => infer Return ? ((...args: Args) => MaybePromise<Awaited<Return>>) & BrowserDocumentApiObject<T> : T extends object ? BrowserDocumentApiObject<T> : T;
-/**
- * Browser V2 active-editor Document API facade (`superdoc.activeEditor.doc`).
- * In the browser this surface is intentionally async-capable: callers must
- * tolerate promise-returning reads/writes, including the default
- * worker-backed runtime. SDK/headless callers should continue using the
- * synchronous `@superdoc/document-api` surface directly.
- */
-export type BrowserDocumentApi = BrowserDocumentApiObject<DocumentApi>;
+export type { BrowserDocumentApi } from '../../public/browser-document-api.js';
 export type V2AuthoringSelectionCollapse = 'start' | 'end' | null;
 export type V2AuthoringResult = {
     ok: true;
@@ -1639,17 +1627,31 @@ export interface Modules {
     /** Collaboration module configuration. */
     collaboration?: CollaborationConfig;
     /**
-     * Toolbar module configuration. Pass `true` to enable the toolbar with
-     * defaults (equivalent to an empty object). The `selector`, `groups`,
-     * `icons`, and `texts` fields fall back to the top-level `Config.toolbar`,
-     * `Config.toolbarGroups`, `Config.toolbarIcons`, and `Config.toolbarTexts`
-     * aliases respectively if not set here.
+     * Toolbar module configuration. Pass `true` to configure the toolbar with
+     * defaults (equivalent to an empty object).
+     *
+     * This field configures the toolbar's contents and behavior; it does not by
+     * itself provide a place to render it. A toolbar is only rendered once a
+     * mount target resolves, from either `selector` here or the top-level
+     * `Config.toolbar`. Without one, SuperDoc still creates the
+     * `superdoc.toolbar` handle (item lookup and command routing keep working)
+     * but renders no toolbar UI.
+     *
+     * Fallbacks to the top-level aliases are per field: `selector` falls back to
+     * `Config.toolbar`, `icons` to `Config.toolbarIcons`, and `texts` to
+     * `Config.toolbarTexts`. `Config.toolbarGroups` supplies the group ordering,
+     * not `groups`: the two are different settings. `groups` maps group ids to
+     * item ids (composition) and has no top-level alias, so omitting it uses the
+     * built-in composition. Supplying it also replaces the group ordering with
+     * its own keys.
      */
     toolbar?: boolean | ({
         /**
-         * CSS selector (id or class) for the DOM element to render the toolbar
-         * into. Must be a string selector, not an `HTMLElement` reference. Falls
-         * back to `Config.toolbar` if omitted.
+         * Selector for the DOM element to render the toolbar into: an id
+         * selector (`#toolbar`), a class selector (`.toolbar`), or a bare
+         * element id (`toolbar`). Must be a string, not an `HTMLElement`
+         * reference — pass an element through the top-level `Config.toolbar`.
+         * Falls back to `Config.toolbar` if omitted.
          */
         selector?: string;
         /** Toolbar item ids to hide from the default set. */
@@ -2348,7 +2350,18 @@ export interface Config {
     role?: 'editor' | 'viewer' | 'suggester';
     /**
      * The document to load. If a string, it will be treated as a URL. If a File
-     * or Blob, it will be used directly.
+     * or Blob, it will be used directly. For a v2 collaboration room, pass a
+     * structured document carrying `v2Collaboration`.
+     *
+     * Omitting this field and `documents` mounts a blank DOCX, so the Editor
+     * opens a real document rather than an empty surface. The blank document is
+     * a supported v2 source; it is seeded before mount and behaves like any
+     * other opened DOCX, including export.
+     *
+     * Setting the v1 `modules.collaboration` field also suppresses that seeding,
+     * but it is not a supported v2 path: the runtime fails closed with
+     * `collaboration-v1-config-unsupported` and mounts only enough state to
+     * report that error.
      */
     document?: object | string | globalThis.File | globalThis.Blob;
     /** Password for encrypted DOCX files. Forwarded during document load. */
@@ -2371,8 +2384,26 @@ export interface Config {
     modules?: Modules;
     /** Top-level override for permission checks. */
     permissionResolver?: (params: PermissionResolverParams) => boolean | undefined;
-    /** Optional DOM element to render the toolbar in. */
-    toolbar?: string;
+    /**
+     * Where to render the built-in toolbar. Either an `HTMLElement`, or a
+     * selector string in one of the supported forms: an id selector (`#toolbar`),
+     * a class selector (`.toolbar`), or a bare element id (`toolbar`). Other CSS
+     * selector syntax is not supported — an attribute or descendant selector such
+     * as `[data-toolbar]` resolves to nothing and leaves the toolbar unrendered.
+     *
+     * SuperDoc renders into the resolved element but does not manage its
+     * placement, and never includes it in the `contained` layout calculation.
+     * Where the application puts it therefore decides the space it needs: a
+     * sibling of a 400px `contained` Editor adds its own height alongside it,
+     * while a toolbar placed inside that host consumes part of the 400px and can
+     * overflow it.
+     *
+     * Omitting this field (and `modules.toolbar.selector`) renders no toolbar.
+     * `modules.toolbar: true` on its own does not render one either — it creates
+     * the `superdoc.toolbar` handle without a mount target. See
+     * {@link Modules.toolbar}.
+     */
+    toolbar?: string | HTMLElement;
     /** Toolbar groups to show. */
     toolbarGroups?: string[];
     /** Icons to show in the toolbar. */
@@ -2574,11 +2605,26 @@ export interface Config {
     /** Document view options (OOXML ST_View compatible). */
     viewOptions?: ViewOptions;
     /**
-     * Enable contained mode for fixed-height container embedding. When true,
-     * SuperDoc propagates height through its DOM tree and adds internal
-     * scrolling, so multi-page documents scroll within the consumer's
-     * fixed-height container. Default behavior (false) lets the document
-     * expand to its natural height.
+     * Enable contained mode for fixed-height container embedding.
+     *
+     * SuperDoc supports two layout modes, and the host element's height
+     * requirement differs between them:
+     *
+     * - Natural (default, `false`): the Editor grows to the document's full
+     *   height and the page scrolls. The host needs no height. Setting one does
+     *   not constrain the document or enable internal scrolling, because
+     *   SuperDoc leaves overflow visible in this mode, though application CSS
+     *   on the host can still clip what is drawn.
+     * - Contained (`true`): SuperDoc propagates `height: 100%` through its DOM
+     *   tree and scrolls the document internally, so multi-page documents stay
+     *   inside the host. This mode requires the host to have a definite height
+     *   (for example `height: 400px`); without one there is nothing for the
+     *   percentage heights to resolve against.
+     *
+     * A toolbar mounted through `Config.toolbar` or `modules.toolbar.selector` is
+     * never part of this calculation. Placed as a sibling of the host, its height
+     * adds to the host's: a 400px host with a 40px toolbar occupies 440px in
+     * total. Placed inside the host, it consumes part of the 400px instead.
      */
     contained?: boolean;
     /** Content Security Policy nonce for dynamically injected styles. */

package/dist/superdoc/src/internal/toolbar/built-in-toolbar.d.ts

@@ -177,14 +177,14 @@ export class BuiltInToolbar extends EventEmitter<string | symbol, any> {
     _detachFontsChanged: null;
     /** Active editor compatibility reference (set by `SuperDoc.setActiveEditor`). */
     activeEditor: any;
-    /** Live shared command controller (single command-state truth). */
-    ui: import('../../public/ui.js').SuperDocUI | null;
+    /** SuperDoc-owned command controller (single command-state truth). */
+    ui: any;
     /** Latest controller toolbar snapshot. */
-    snapshot: import('../../public/ui.js').ToolbarSnapshotSlice | null;
+    snapshot: any;
     /** Controller subscription unsubscribe handle. */
-    _unsubscribeController: (() => void) | null;
+    _unsubscribeController: any;
     /** Format-painter mode subscription unsubscribe handle. */
-    _detachFormatPainterModeChange: (() => void) | null;
+    _detachFormatPainterModeChange: any;
     /** Registered custom-button command unregister handles. */
     _customCommandRegs: Map<any, any>;
     /** Signature of the last-built font options, to skip redundant rebuilds. */

package/dist/superdoc/src/public/browser-document-api.d.ts

@@ -0,0 +1,53 @@
+import { DocumentApi } from '../../../document-api/src/index.js';
+type MaybePromise<T> = T | Promise<T>;
+type BrowserDocumentApiObject<T> = {
+    [K in keyof T]: BrowserDocumentApiValue<T[K]>;
+};
+type BrowserDocumentApiValue<T> = T extends (...args: infer Args) => infer Return ? ((...args: Args) => MaybePromise<Awaited<Return>>) & BrowserDocumentApiObject<T> : T extends object ? BrowserDocumentApiObject<T> : T;
+/**
+ * Browser V2 active-editor Document API facade (`superdoc.activeEditor.doc`).
+ * In the browser this surface is intentionally async-capable: callers must
+ * tolerate promise-returning reads/writes, including the default
+ * worker-backed runtime. SDK/headless callers should continue using the
+ * synchronous `@superdoc/document-api` surface directly.
+ */
+export type BrowserDocumentApi = BrowserDocumentApiObject<DocumentApi>;
+/**
+ * Every operation optional, at any depth.
+ *
+ * A callable member keeps its call signature *and* its properties, mirroring
+ * what {@link BrowserDocumentApiValue} does. Parts of the Document API are both:
+ * `capabilities` is callable and carries `get()`, so reconstructing only the call
+ * signature would make `doc.capabilities.get()` a type error on a value that
+ * supports it at runtime.
+ *
+ * Intersected rather than unioned with the property bag. A union would let a
+ * non-callable object stand in for a callable member, which also makes the
+ * member type unenforceable: `{ comments: { list: 42 } }` satisfies a
+ * props-only alternative and the type stops catching wrong operations at all.
+ */
+type DeepPartial<T> = T extends (...args: infer Args) => infer Return ? ((...args: Args) => Return) & {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/**
+ * What a *host* may supply as `activeEditor.doc`.
+ *
+ * A host is duck-typed: a custom adapter or a test stub is expected to carry
+ * only the operations it actually implements, and the controller resolves
+ * operations defensively at runtime rather than assuming any of them exist.
+ * Requiring the whole surface here would reject exactly the partial hosts the
+ * contract is documented to accept.
+ *
+ * `CustomCommandContext.doc` uses this same partial type, because that value is
+ * the host's own object passed straight through. It can promise no more than the
+ * host contract does. {@link BrowserDocumentApi}, the complete facade, is the
+ * type of `activeEditor.doc` on a real `Editor`.
+ *
+ * Partial, not permissive: the operations a host does declare are still
+ * checked, so a typo or a wrong member type fails instead of passing as
+ * `any`.
+ */
+export type PartialBrowserDocumentApi = DeepPartial<BrowserDocumentApi>;
+export {};

package/dist/superdoc/src/public/index.d.cts

@@ -5,6 +5,7 @@ import type { BlockNavigationAddress as __Cjs_BlockNavigationAddress } from './i
 import type { BlocksListResult as __Cjs_BlocksListResult } from './index.js' with { "resolution-mode": "import" };
 import type { BookmarkAddress as __Cjs_BookmarkAddress } from './index.js' with { "resolution-mode": "import" };
 import type { BookmarkInfo as __Cjs_BookmarkInfo } from './index.js' with { "resolution-mode": "import" };
+import type { BorrowedSuperDocUI as __Cjs_BorrowedSuperDocUI } from './index.js' with { "resolution-mode": "import" };
 import type { CanPerformPermissionParams as __Cjs_CanPerformPermissionParams } from './index.js' with { "resolution-mode": "import" };
 import type { CollaborationConfig as __Cjs_CollaborationConfig } from './index.js' with { "resolution-mode": "import" };
 import type { CommentAddress as __Cjs_CommentAddress } from './index.js' with { "resolution-mode": "import" };
@@ -133,6 +134,7 @@ import type { SuperDocStoryLocator as __Cjs_SuperDocStoryLocator } from './index
 import type { SuperDocTelemetryConfig as __Cjs_SuperDocTelemetryConfig } from './index.js' with { "resolution-mode": "import" };
 import type { SuperDocTextAddress as __Cjs_SuperDocTextAddress } from './index.js' with { "resolution-mode": "import" };
 import type { SuperDocTextTarget as __Cjs_SuperDocTextTarget } from './index.js' with { "resolution-mode": "import" };
+import type { SuperDocUI as __Cjs_SuperDocUI } from './index.js' with { "resolution-mode": "import" };
 import type { SuperDocViewportChangePayload as __Cjs_SuperDocViewportChangePayload } from './index.js' with { "resolution-mode": "import" };
 import type { SuperDocViewportMetrics as __Cjs_SuperDocViewportMetrics } from './index.js' with { "resolution-mode": "import" };
 import type { SuperDocVisibleRange as __Cjs_SuperDocVisibleRange } from './index.js' with { "resolution-mode": "import" };
@@ -175,6 +177,7 @@ export type { __Cjs_BlockNavigationAddress as BlockNavigationAddress };
 export type { __Cjs_BlocksListResult as BlocksListResult };
 export type { __Cjs_BookmarkAddress as BookmarkAddress };
 export type { __Cjs_BookmarkInfo as BookmarkInfo };
+export type { __Cjs_BorrowedSuperDocUI as BorrowedSuperDocUI };
 export declare const buildTheme: typeof import('./index.js', { with: { "resolution-mode": "import" } }).buildTheme;
 export type { __Cjs_CanPerformPermissionParams as CanPerformPermissionParams };
 export type { __Cjs_CollaborationConfig as CollaborationConfig };
@@ -312,6 +315,7 @@ export type { __Cjs_SuperDocStoryLocator as SuperDocStoryLocator };
 export type { __Cjs_SuperDocTelemetryConfig as SuperDocTelemetryConfig };
 export type { __Cjs_SuperDocTextAddress as SuperDocTextAddress };
 export type { __Cjs_SuperDocTextTarget as SuperDocTextTarget };
+export type { __Cjs_SuperDocUI as SuperDocUI };
 export type { __Cjs_SuperDocViewportChangePayload as SuperDocViewportChangePayload };
 export type { __Cjs_SuperDocViewportMetrics as SuperDocViewportMetrics };
 export type { __Cjs_SuperDocVisibleRange as SuperDocVisibleRange };

package/dist/superdoc/src/public/index.d.ts

@@ -81,6 +81,8 @@ export type { SuperDocMeasurementUnitChangePayload } from '../core/types/index.j
 export type { SuperDocReadyPayload } from '../core/types/index.js';
 export type { SuperDocState } from '../core/types/index.js';
 export type { SuperDocTelemetryConfig } from '../core/types/index.js';
+export type { BorrowedSuperDocUI } from './ui/types.js';
+export type { SuperDocUI } from './ui/types.js';
 export type { SuperDocViewportChangePayload } from '../core/types/index.js';
 export type { SuperDocViewportMetrics } from '../core/types/index.js';
 export type { SuperDocZoomConfig } from '../core/types/index.js';

package/dist/superdoc/src/public/ui/react.d.ts

@@ -1,5 +1,5 @@
 import { ReactNode } from 'react';
-import { CommandState, CommentsSlice, ContentControlsSlice, DocumentSlice, FontFamilyOption, FontSizeOption, SelectionSlice, Subscribable, SuperDocLike, SuperDocUI, ToolbarSnapshotSlice, TrackChangesSlice, ZoomSlice } from './types.js';
+import { BorrowedSuperDocUI, CommandState, CommentsSlice, ContentControlsSlice, DocumentSlice, FontFamilyOption, FontSizeOption, SelectionSlice, Subscribable, SuperDocLike, ToolbarSnapshotSlice, TrackChangesSlice, ZoomSlice } from './types.js';
 /** The raw SuperDoc instance (or host stub) handed to the provider. */
 export type SuperDocHost = SuperDocLike;
 /** Props accepted by {@link SuperDocUIProvider}. */
@@ -8,13 +8,24 @@ export interface SuperDocUIProviderProps {
     children?: ReactNode;
 }
 /**
- * Root provider. Owns the controller lifecycle: call {@link useSetSuperDoc}
- * from your editor-mount component's ready callback to bind a running SuperDoc
- * instance; the controller is created then and destroyed on unmount / rebind.
+ * Root provider. Call {@link useSetSuperDoc} from your editor-mount
+ * component's ready callback to bind a running SuperDoc instance; the hooks
+ * below then read that instance's own controller (`superdoc.ui`).
+ *
+ * The provider is a consumer, not an owner. SuperDoc creates the controller
+ * and destroys it in `superdoc.destroy()`, so unmounting or rebinding the
+ * provider leaves it running for the built-in toolbar and any other consumer
+ * of the same instance. Every React hook therefore observes the same command
+ * state the rest of the application sees.
  */
 export declare function SuperDocUIProvider(props: SuperDocUIProviderProps): import('react').ReactElement;
-/** Read the controller, or `null` until a SuperDoc instance is bound. */
-export declare function useSuperDocUI(): SuperDocUI | null;
+/**
+ * Read the controller, or `null` until a SuperDoc instance is bound.
+ *
+ * Borrowed: the bound instance owns teardown, so the returned type omits
+ * `destroy()`. A provider-built fallback controller is disposed by the provider.
+ */
+export declare function useSuperDocUI(): BorrowedSuperDocUI | null;
 /** Read the raw bound SuperDoc host, or `null` until one is bound. */
 export declare function useSuperDocHost(): SuperDocHost | null;
 /** Get the stable callback used to bind a running SuperDoc instance. */
@@ -46,7 +57,7 @@ export declare function toSliceSource<T>(source: SliceSource<T> | Subscribable<T
  * normalized via {@link toSliceSource}. `initial` is returned until the
  * controller is bound.
  */
-export declare function useSuperDocSlice<T>(pick: (ui: SuperDocUI) => SliceSource<T> | Subscribable<T>, initial: T): T;
+export declare function useSuperDocSlice<T>(pick: (ui: BorrowedSuperDocUI) => SliceSource<T> | Subscribable<T>, initial: T): T;
 /** Subscribe to the selection slice. */
 export declare function useSuperDocSelection(): SelectionSlice;
 /** Subscribe to the comments slice. */

package/dist/superdoc/src/public/ui/types.d.ts

@@ -1,4 +1,5 @@
 import { CommentsListQuery as DocumentApiCommentsListQuery, CommentsListResult, TrackChangesListResult, EntityAddress, TextAddress, TextTarget, ScrollIntoViewInput, ScrollIntoViewOutput, SelectionInfo, SelectionTarget, Receipt, ReceiptFailureCode, ContentControlInfo, StyleCatalogItem, StyleCatalogDiagnostic, StyleCatalogSourceStatus, StylesGetCatalogInput, StylesGetCatalogResult } from '../../../../document-api/src/index.js';
+import { PartialBrowserDocumentApi } from '../browser-document-api.js';
 import { SuperDocUIReason } from './reasons.js';
 /**
  * v2-native `superdoc/ui` controller types.
@@ -26,9 +27,10 @@ import { SuperDocUIReason } from './reasons.js';
  * (`scripts/ensure-types.cjs` `rewriteDocApiPaths`), so no bare private
  * specifier leaks into the emitted `.d.ts`.
  */
-export type { Receipt, SelectionInfo, SelectionTarget, SelectionPoint, TextTarget, TextAddress, ScrollIntoViewInput, ScrollIntoViewOutput, EntityAddress, CommentsListQuery as DocumentApiCommentsListQuery, CommentsListResult, TrackChangesListResult, ContentControlsListResult, ContentControlInfo, } from '../../../../document-api/src/index.js';
+export type { Receipt, SelectionInfo, SelectionTarget, SelectionPoint, TextTarget, TextAddress, ScrollIntoViewInput, ScrollIntoViewOutput, DocumentApi, EntityAddress, CommentsListQuery as DocumentApiCommentsListQuery, CommentsListResult, TrackChangesListResult, ContentControlsListResult, ContentControlInfo, } from '../../../../document-api/src/index.js';
 export type { StyleCatalogView, StyleCatalogItemType, StyleCatalogFilterType, StyleProvenance, StyleCatalogItemVisibility, StyleCatalogItemUsage, StyleCatalogItemPreview, StyleCatalogItem, StyleCatalogDefaults, StyleCatalogDiagnostic, StyleCatalogSourceStatus, StylesGetCatalogInput, StylesGetCatalogResult, } from '../../../../document-api/src/index.js';
 export type { ListPresetId } from '../../../../document-api/src/index.js';
+export type { BrowserDocumentApi, PartialBrowserDocumentApi } from '../browser-document-api.js';
 export type { SuperDocUIReason } from './reasons.js';
 /** Equality predicate used to suppress redundant slice notifications. */
 export type EqualityFn<T> = (a: T, b: T) => boolean;
@@ -414,14 +416,44 @@ export interface CustomCommandContext<TPayload = unknown> {
     editor: SuperDocEditorLike | null;
     superdoc: SuperDocLike;
     context?: ViewportContext;
-    /** The live UI controller (shared command-state truth). */
-    ui: SuperDocUI;
+    /**
+     * The live UI controller (shared command-state truth).
+     *
+     * Borrowed: a custom command runs against whichever controller invoked it,
+     * which for `superdoc.ui.commands.register(...)` is the instance-owned
+     * singleton the built-in toolbar also reads. Typing this as the owned form
+     * would let a command callback destroy it, which is the hole the borrowed
+     * handle exists to close.
+     *
+     * Borrowed unconditionally, including for a controller you built with
+     * `createSuperDocUI()`. That costs an owner nothing: you necessarily hold the
+     * owned reference already, since you called `.commands.register(...)` on it,
+     * so tear it down through that instead of through the context. Varying this
+     * by ownership would mean `SuperDocUI` and {@link BorrowedSuperDocUI} needing
+     * different `commands` handles, and the borrowed form is derived from the
+     * owned one precisely so the two cannot drift.
+     */
+    ui: BorrowedSuperDocUI;
     /** Run a catalog command id through the shared controller. */
     execute(id: string, payload?: unknown): CommandExecutionResult;
     /** Run a catalog command id and await its settled result. */
     executeAsync(id: string, payload?: unknown): Promise<CommandExecutionResult>;
-    /** Public browser Document API facade (read-only-guarded, async-capable), or `null` when unavailable. */
-    doc: Record<string, any> | null;
+    /**
+     * The host's browser Document API facade (read-only-guarded, async-capable),
+     * or `null` when unavailable.
+     *
+     * Partial for the same reason {@link SuperDocEditorLike.doc} is: this is the
+     * host's own object handed straight through, and a duck-typed host is only
+     * required to carry the operations it implements. Typing it as the complete
+     * facade would promise operations a custom adapter or stub never defines.
+     *
+     * Prefer {@link CustomCommandContext.execute}, `executeAsync`, and
+     * `insertText` where they cover the work: those route through the controller
+     * and fail closed with a reason or a receipt when an operation is missing.
+     * Reach for `doc` when you need an operation the controller does not route,
+     * and guard the call.
+     */
+    doc: PartialBrowserDocumentApi | null;
     /** Read-only selection snapshot at invocation time. */
     selection: SelectionSlice;
     /** Current document mode. */
@@ -1228,14 +1260,23 @@ export interface SearchHandle extends SnapshotSubscribable<SearchSlice> {
 export interface SuperDocEditorLike {
     /** Runtime evidence of the bundled v2 editor. */
     editorVersion?: number;
-    /** Public, read-only-guarded browser Document API facade (async-capable in browser). */
-    doc?: Record<string, any> | null;
+    /**
+     * Public, read-only-guarded browser Document API facade (async-capable in
+     * browser). Partial by design: this is what a host supplies, and a stub or
+     * custom adapter carries only the operations it implements.
+     *
+     * `CustomCommandContext.doc` is the same partial type, because the controller
+     * passes this object straight through and can promise no more than the host
+     * does. {@link BrowserDocumentApi}, the complete facade, is the type of
+     * `activeEditor.doc` on a real `Editor`.
+     */
+    doc?: PartialBrowserDocumentApi | null;
     /** Stable reason the Document API is unavailable. */
     documentApiUnavailableReason?: string | null;
     /** Editor-scoped event subscription. */
-    on?(event: string, handler: (...args: any[]) => void): unknown;
+    on?(event: string, handler: (...args: unknown[]) => void): unknown;
     /** Editor-scoped event unsubscription. */
-    off?(event: string, handler: (...args: any[]) => void): unknown;
+    off?(event: string, handler: (...args: unknown[]) => void): unknown;
     /** Export the active editor's document. */
     exportDocx?(...args: unknown[]): Promise<unknown>;
     /** Save the active editor's document. */
@@ -1251,10 +1292,19 @@ export interface SuperDocEditorLike {
 export interface SuperDocLike {
     /** The routed active editor, when one is mounted. */
     activeEditor?: SuperDocEditorLike | null;
+    /**
+     * The host-owned UI controller. A real `SuperDoc` instance always exposes
+     * one and owns its lifecycle; bare structural stubs may not, which is why
+     * this is optional. Consumers should read it rather than build their own.
+     *
+     * Borrowed, not owned: the host tears this down, so the type omits
+     * `destroy()` and a reader cannot call it.
+     */
+    ui?: BorrowedSuperDocUI;
     /** Lifecycle event subscription. */
-    on?(event: string, handler: (...args: any[]) => void): unknown;
+    on?(event: string, handler: (...args: unknown[]) => void): unknown;
     /** Lifecycle event unsubscription. */
-    off?(event: string, handler: (...args: any[]) => void): unknown;
+    off?(event: string, handler: (...args: unknown[]) => void): unknown;
     /** Set the document mode across the instance. */
     setDocumentMode?(mode: string): unknown;
     /** Export the active document. */
@@ -1351,6 +1401,25 @@ export interface SuperDocUI {
     readonly formatPainter: FormatPainterHandle;
     /** Create a disposable subscription scope. */
     createScope(): SuperDocUIScope;
-    /** Tear down all subscriptions and detach from the host. */
+    /**
+     * Tear down all subscriptions and detach from the host.
+     *
+     * Only the owner calls this. A controller obtained from `createSuperDocUI()`
+     * is owned by its caller. The one at `superdoc.ui` is owned by the instance
+     * and is typed {@link BorrowedSuperDocUI}, which does not carry this method.
+     */
     destroy(): void;
 }
+/**
+ * The controller as a *consumer* sees it: everything except `destroy()`.
+ *
+ * This is what `superdoc.ui` and the React hooks return. The instance owns that
+ * controller and tears it down in `superdoc.destroy()`, so a consumer calling
+ * `destroy()` would freeze command state for the built-in toolbar and every
+ * other reader of the same instance. Omitting the method makes that a compile
+ * error rather than a documented convention nobody reads.
+ *
+ * Derived from {@link SuperDocUI} rather than declared separately so the two
+ * cannot drift: every handle added there appears here automatically.
+ */
+export type BorrowedSuperDocUI = Omit<SuperDocUI, 'destroy'>;

package/dist/superdoc/src/public/ui-react.d.ts

@@ -1,9 +1,10 @@
 /**
  * SuperDoc public facade: `superdoc/ui/react` entry.
  *
- * v2-native React bindings for the `createSuperDocUI` controller: the
- * provider, the lifecycle bind hook, the generic slice hook, and the domain
- * hooks.
+ * v2-native React bindings for the SuperDoc-owned UI controller
+ * (`superdoc.ui`): the provider, the bind hook, the generic slice hook, and
+ * the domain hooks. This layer consumes the controller; SuperDoc creates and
+ * destroys it.
  *
  * v2 NOTE: this is NOT the v1 re-export. It routes through the local,
  * self-contained v2 React layer under `./ui/react.ts`, which is built on the

package/dist/superdoc/src/public/ui.d.cts

@@ -1,5 +1,7 @@
 // Generated by scripts/ensure-types.cjs. Do not edit by hand.
 import type { ActiveParagraphStyle as __Cjs_ActiveParagraphStyle } from './ui.js' with { "resolution-mode": "import" };
+import type { BorrowedSuperDocUI as __Cjs_BorrowedSuperDocUI } from './ui.js' with { "resolution-mode": "import" };
+import type { BrowserDocumentApi as __Cjs_BrowserDocumentApi } from './ui.js' with { "resolution-mode": "import" };
 import type { CommandExecutionResult as __Cjs_CommandExecutionResult } from './ui.js' with { "resolution-mode": "import" };
 import type { CommandHandle as __Cjs_CommandHandle } from './ui.js' with { "resolution-mode": "import" };
 import type { CommandsHandle as __Cjs_CommandsHandle } from './ui.js' with { "resolution-mode": "import" };
@@ -22,6 +24,7 @@ import type { CustomCommandHandle as __Cjs_CustomCommandHandle } from './ui.js'
 import type { CustomCommandHandleState as __Cjs_CustomCommandHandleState } from './ui.js' with { "resolution-mode": "import" };
 import type { CustomCommandRegistration as __Cjs_CustomCommandRegistration } from './ui.js' with { "resolution-mode": "import" };
 import type { CustomCommandRegistrationResult as __Cjs_CustomCommandRegistrationResult } from './ui.js' with { "resolution-mode": "import" };
+import type { DocumentApi as __Cjs_DocumentApi } from './ui.js' with { "resolution-mode": "import" };
 import type { DocumentHandle as __Cjs_DocumentHandle } from './ui.js' with { "resolution-mode": "import" };
 import type { DocumentSlice as __Cjs_DocumentSlice } from './ui.js' with { "resolution-mode": "import" };
 import type { EntityAddress as __Cjs_EntityAddress } from './ui.js' with { "resolution-mode": "import" };
@@ -31,6 +34,7 @@ import type { FontsHandle as __Cjs_FontsHandle } from './ui.js' with { "resoluti
 import type { FontSizeOption as __Cjs_FontSizeOption } from './ui.js' with { "resolution-mode": "import" };
 import type { FontsSlice as __Cjs_FontsSlice } from './ui.js' with { "resolution-mode": "import" };
 import type { MetadataHandle as __Cjs_MetadataHandle } from './ui.js' with { "resolution-mode": "import" };
+import type { PartialBrowserDocumentApi as __Cjs_PartialBrowserDocumentApi } from './ui.js' with { "resolution-mode": "import" };
 import type { Receipt as __Cjs_Receipt } from './ui.js' with { "resolution-mode": "import" };
 import type { ScrollIntoViewInput as __Cjs_ScrollIntoViewInput } from './ui.js' with { "resolution-mode": "import" };
 import type { ScrollIntoViewOutput as __Cjs_ScrollIntoViewOutput } from './ui.js' with { "resolution-mode": "import" };
@@ -90,6 +94,8 @@ import type { WorkflowScrollResult as __Cjs_WorkflowScrollResult } from './ui.js
 import type { ZoomHandle as __Cjs_ZoomHandle } from './ui.js' with { "resolution-mode": "import" };
 import type { ZoomSlice as __Cjs_ZoomSlice } from './ui.js' with { "resolution-mode": "import" };
 export type { __Cjs_ActiveParagraphStyle as ActiveParagraphStyle };
+export type { __Cjs_BorrowedSuperDocUI as BorrowedSuperDocUI };
+export type { __Cjs_BrowserDocumentApi as BrowserDocumentApi };
 export declare const BUILT_IN_COMMAND_IDS: typeof import('./ui.js', { with: { "resolution-mode": "import" } }).BUILT_IN_COMMAND_IDS;
 export type { __Cjs_CommandExecutionResult as CommandExecutionResult };
 export type { __Cjs_CommandHandle as CommandHandle };
@@ -114,6 +120,7 @@ export type { __Cjs_CustomCommandHandle as CustomCommandHandle };
 export type { __Cjs_CustomCommandHandleState as CustomCommandHandleState };
 export type { __Cjs_CustomCommandRegistration as CustomCommandRegistration };
 export type { __Cjs_CustomCommandRegistrationResult as CustomCommandRegistrationResult };
+export type { __Cjs_DocumentApi as DocumentApi };
 export type { __Cjs_DocumentHandle as DocumentHandle };
 export type { __Cjs_DocumentSlice as DocumentSlice };
 export type { __Cjs_EntityAddress as EntityAddress };
@@ -123,6 +130,7 @@ export type { __Cjs_FontsHandle as FontsHandle };
 export type { __Cjs_FontSizeOption as FontSizeOption };
 export type { __Cjs_FontsSlice as FontsSlice };
 export type { __Cjs_MetadataHandle as MetadataHandle };
+export type { __Cjs_PartialBrowserDocumentApi as PartialBrowserDocumentApi };
 export type { __Cjs_Receipt as Receipt };
 export type { __Cjs_ScrollIntoViewInput as ScrollIntoViewInput };
 export type { __Cjs_ScrollIntoViewOutput as ScrollIntoViewOutput };

package/dist/superdoc/src/public/ui.d.ts

@@ -26,4 +26,4 @@
 export { createSuperDocUI } from './ui/create-super-doc-ui.js';
 export { shallowEqual } from './ui/equality.js';
 export { BUILT_IN_COMMAND_IDS } from './ui/commands.js';
-export type { EqualityFn, SelectorFn, Subscribable, SuperDocUI, SuperDocUIOptions, SuperDocUIState, SuperDocUIScope, SuperDocLike, SuperDocEditorLike, CommandHandle, CommandState, CommandExecutionResult, WorkflowReceipt, WorkflowActionResult, WorkflowScrollResult, SelectionRestoreResult, SuperDocUIReason, CommandsHandle, ContextMenuItem, CustomCommandHandle, CustomCommandHandleState, CustomCommandRegistration, CustomCommandRegistrationResult, MetadataHandle, SelectionHandle, ToolbarHandle, CommentsHandle, TrackChangesHandle, ContentControlsHandle, ContentControlFocusResult, FontsHandle, ZoomHandle, DocumentHandle, ViewportHandle, StylesHandle, ActiveParagraphStyle, SliceStatus, SelectionSlice, SelectionCapture, CommentAnchorCapture, ToolbarSnapshotSlice, CommentsSlice, TrackChangesSlice, ContentControlsSlice, FontsSlice, ZoomSlice, DocumentSlice, StylesSlice, StyleCatalogView, StyleCatalogItemType, StyleCatalogFilterType, StyleProvenance, StyleCatalogItemVisibility, StyleCatalogItemUsage, StyleCatalogItemPreview, StyleCatalogItem, StyleCatalogDefaults, StyleCatalogDiagnostic, StyleCatalogSourceStatus, StylesGetCatalogInput, StylesGetCatalogResult, CommentInfo, CommentsListQuery, TrackChangeInfo, TrackChangePointHit, TrackChangesItem, FontFamilyOption, FontSizeOption, CommentAddress, TrackedChangeAddress, ContentControlViewportAddress, ViewportEntityAddress, ViewportEntityHit, ViewportContext, ViewportRect, ViewportGetRectInput, ViewportRectResult, Receipt, SelectionInfo, SelectionTarget, SelectionPoint, TextTarget, TextAddress, ScrollIntoViewInput, ScrollIntoViewOutput, EntityAddress, CommentsListResult, TrackChangesListResult, ContentControlsListResult, ContentControlInfo, } from './ui/types.js';
+export type { EqualityFn, SelectorFn, Subscribable, SuperDocUI, BorrowedSuperDocUI, SuperDocUIOptions, SuperDocUIState, SuperDocUIScope, SuperDocLike, SuperDocEditorLike, CommandHandle, CommandState, CommandExecutionResult, WorkflowReceipt, WorkflowActionResult, WorkflowScrollResult, SelectionRestoreResult, SuperDocUIReason, CommandsHandle, ContextMenuItem, CustomCommandHandle, CustomCommandHandleState, CustomCommandRegistration, CustomCommandRegistrationResult, MetadataHandle, SelectionHandle, ToolbarHandle, CommentsHandle, TrackChangesHandle, ContentControlsHandle, ContentControlFocusResult, FontsHandle, ZoomHandle, DocumentHandle, ViewportHandle, StylesHandle, ActiveParagraphStyle, SliceStatus, SelectionSlice, SelectionCapture, CommentAnchorCapture, ToolbarSnapshotSlice, CommentsSlice, TrackChangesSlice, ContentControlsSlice, FontsSlice, ZoomSlice, DocumentSlice, StylesSlice, StyleCatalogView, StyleCatalogItemType, StyleCatalogFilterType, StyleProvenance, StyleCatalogItemVisibility, StyleCatalogItemUsage, StyleCatalogItemPreview, StyleCatalogItem, StyleCatalogDefaults, StyleCatalogDiagnostic, StyleCatalogSourceStatus, StylesGetCatalogInput, StylesGetCatalogResult, CommentInfo, CommentsListQuery, TrackChangeInfo, TrackChangePointHit, TrackChangesItem, FontFamilyOption, FontSizeOption, CommentAddress, TrackedChangeAddress, ContentControlViewportAddress, ViewportEntityAddress, ViewportEntityHit, ViewportContext, ViewportRect, ViewportGetRectInput, ViewportRectResult, BrowserDocumentApi, PartialBrowserDocumentApi, DocumentApi, Receipt, SelectionInfo, SelectionTarget, SelectionPoint, TextTarget, TextAddress, ScrollIntoViewInput, ScrollIntoViewOutput, EntityAddress, CommentsListResult, TrackChangesListResult, ContentControlsListResult, ContentControlInfo, } from './ui/types.js';