superdoc 2.0.0-next.49 → 2.0.0-next.50

package/dist/style.layered.css

@@ -1368,28 +1368,28 @@ img[data-v-c95b2073] {
   background-color: #1355ff7f;
 }
 
-.comment-placeholder[data-v-a1bd2282] {
+.comment-placeholder[data-v-b5be33eb] {
   position: absolute;
   width: 300px;
   transition: top 0.3s ease;
 }
-.comment-placeholder.is-direct-decision-continuity-target[data-v-a1bd2282] .overflow-menu {
+.comment-placeholder.is-direct-decision-continuity-target[data-v-b5be33eb] .overflow-menu {
   opacity: 1;
   pointer-events: auto;
 }
-.floating-comment[data-v-a1bd2282] {
+.floating-comment[data-v-b5be33eb] {
   position: relative;
   display: block;
   min-width: 300px;
 }
-.sidebar-container[data-v-a1bd2282] {
+.sidebar-container[data-v-b5be33eb] {
   position: absolute;
   width: 300px;
   min-height: 300px;
   transition: transform 0.3s ease;
   will-change: transform;
 }
-.section-wrapper[data-v-a1bd2282] {
+.section-wrapper[data-v-b5be33eb] {
   position: relative;
   min-height: 100%;
   width: 300px;
@@ -1727,11 +1727,11 @@ img[data-v-c95b2073] {
   pointer-events: auto;
 }
 
-.superdoc[data-v-41f40a40] {
+.superdoc[data-v-2a7bfa95] {
   display: flex;
   position: relative;
 }
-.sd-visually-hidden[data-v-41f40a40] {
+.sd-visually-hidden[data-v-2a7bfa95] {
   position: absolute;
   width: 1px;
   height: 1px;
@@ -1742,30 +1742,30 @@ img[data-v-c95b2073] {
   white-space: nowrap;
   border: 0;
 }
-.right-sidebar[data-v-41f40a40] {
+.right-sidebar[data-v-2a7bfa95] {
   min-width: 320px;
   height: 100%;
 }
-.floating-comments[data-v-41f40a40] {
+.floating-comments[data-v-2a7bfa95] {
   min-width: 300px;
   width: 300px;
   height: 100%;
   overflow: visible;
 }
-.superdoc__layers[data-v-41f40a40] {
+.superdoc__layers[data-v-2a7bfa95] {
   height: 100%;
   position: relative;
   box-sizing: border-box;
 }
-.superdoc__document[data-v-41f40a40] {
+.superdoc__document[data-v-2a7bfa95] {
   width: 100%;
   position: relative;
 }
-.superdoc__sub-document[data-v-41f40a40] {
+.superdoc__sub-document[data-v-2a7bfa95] {
   width: 100%;
   position: relative;
 }
-.superdoc__selection-layer[data-v-41f40a40] {
+.superdoc__selection-layer[data-v-2a7bfa95] {
   position: absolute;
   min-width: 100%;
   min-height: 100%;
@@ -1776,13 +1776,13 @@ img[data-v-c95b2073] {
 /* SD-3497: PDF whiteboard overlay sits above the rendered PDF canvas but below
    the PDF comment anchors (z-index 6 in PdfCommentsLayer) so anchors stay
    clickable, and below the selection layer (z-index 10). */
-.superdoc__whiteboard-layer[data-v-41f40a40] {
+.superdoc__whiteboard-layer[data-v-2a7bfa95] {
   z-index: 4;
 }
-.superdoc__temp-selection[data-v-41f40a40] {
+.superdoc__temp-selection[data-v-2a7bfa95] {
   position: absolute;
 }
-.superdoc__right-sidebar[data-v-41f40a40] {
+.superdoc__right-sidebar[data-v-2a7bfa95] {
   width: 320px;
   min-width: 320px;
   padding: 0 10px;
@@ -1790,7 +1790,7 @@ img[data-v-c95b2073] {
   position: relative;
   z-index: 2;
 }
-.superdoc__compact-comment-popover[data-v-41f40a40] {
+.superdoc__compact-comment-popover[data-v-2a7bfa95] {
   position: absolute;
   top: 12px;
   right: 12px;
@@ -1799,14 +1799,14 @@ img[data-v-c95b2073] {
 }
 
 /* Tools styles */
-.tools[data-v-41f40a40] {
+.tools[data-v-2a7bfa95] {
   position: absolute;
   z-index: 3;
   display: flex;
   flex-direction: column;
   gap: var(--sd-ui-tools-gap, 6px);
 }
-.tools-item[data-v-41f40a40] {
+.tools-item[data-v-2a7bfa95] {
   display: flex;
   align-items: center;
   justify-content: center;
@@ -1817,10 +1817,10 @@ img[data-v-c95b2073] {
   cursor: pointer;
   position: relative;
 }
-.tools-item i[data-v-41f40a40] {
+.tools-item i[data-v-2a7bfa95] {
   cursor: pointer;
 }
-.superdoc__tools-icon[data-v-41f40a40] {
+.superdoc__tools-icon[data-v-2a7bfa95] {
   width: var(--sd-ui-tools-icon-size, 20px);
   height: var(--sd-ui-tools-icon-size, 20px);
   flex-shrink: 0;
@@ -1835,22 +1835,22 @@ img[data-v-c95b2073] {
 
 /* 834px is iPad screen size in portrait orientation */
 @media (max-width: 834px) {
-.superdoc .superdoc__layers[data-v-41f40a40] {
+.superdoc .superdoc__layers[data-v-2a7bfa95] {
     margin: 0;
     border: 0 !important;
     box-shadow: none;
 }
-.superdoc__sub-document[data-v-41f40a40] {
+.superdoc__sub-document[data-v-2a7bfa95] {
     max-width: 100%;
 }
-.superdoc__right-sidebar[data-v-41f40a40] {
+.superdoc__right-sidebar[data-v-2a7bfa95] {
     padding: 10px;
     position: relative;
 }
 }
 
 /* AI Writer styles */
-.ai-writer-container[data-v-41f40a40] {
+.ai-writer-container[data-v-2a7bfa95] {
   position: fixed;
   z-index: 1000;
   background: white;
@@ -1866,10 +1866,10 @@ img[data-v-c95b2073] {
   transform: translateY(-50%);
   z-index: 50;
 } */
-.ai-tool > svg[data-v-41f40a40] {
+.ai-tool > svg[data-v-2a7bfa95] {
   fill: transparent;
 }
-.ai-tool[data-v-41f40a40]::before {
+.ai-tool[data-v-2a7bfa95]::before {
   content: '';
   position: absolute;
   width: 20px;
@@ -1890,7 +1890,7 @@ img[data-v-c95b2073] {
   filter: brightness(1.2);
   transition: filter 0.2s ease;
 }
-.ai-tool[data-v-41f40a40]:hover::before {
+.ai-tool[data-v-2a7bfa95]:hover::before {
   filter: brightness(1.3);
 }
 

package/dist/superdoc/src/core/SuperDoc.d.ts

@@ -2,9 +2,12 @@ import { EventEmitter } from 'eventemitter3';
 import { HocuspocusProviderWebsocket } from '@hocuspocus/provider';
 import { createSuperdocVueApp } from './create-app.js';
 import { Whiteboard } from './whiteboard/Whiteboard.js';
+import { normalizeUiConfig } from './config/normalize-ui-config.js';
+import { normalizeInteractionConfig } from './config/normalize-interaction-config.js';
+import { normalizeSurfacesConfig } from './config/normalize-surfaces-config.js';
 import { EditorRuntimeFocusOptions } from './editor-runtime/types.js';
 import { BorrowedSuperDocUI } from '../public/ui/types.js';
-import { AwarenessUser, CanPerformPermissionParams, CollaborationProvider, Config, ContentControlActiveChangePayload, ContentControlClickPayload, DocumentMode, Editor, EditorUpdateEvent, ExportParams, FontsChangedPayload, FontsResolvedPayload, InternalConfig, ListDefinitionsPayload, NavigableAddress, DocumentRendererRuntime, SearchMatch, SuperDocAwarenessUpdatePayload, SuperDocCommentsUpdatePayload, SuperDocEditorPayload, SuperDocExceptionPayload, SuperDocFontsApi, SuperDocLockedPayload, SuperDocMeasurementUnit, SuperDocMeasurementUnitChangePayload, SuperDocReadyPayload, SuperDocState, SuperDocViewportChangePayload, SuperDocViewportMetrics, SuperDocZoomMode, SuperDocZoomPayload, SuperDocZoomState, SurfaceHandle, SurfaceRequest, UpgradeToCollaborationOptions, User } from './types/index.js';
+import { AwarenessUser, CanPerformPermissionParams, CollaborationProvider, Config, ContentControlActiveChangePayload, ContentControlClickPayload, DocumentMode, Editor, EditorUpdateEvent, ExportParams, FontsChangedPayload, FontsResolvedPayload, InternalConfig, ListDefinitionsPayload, NavigableAddress, DocumentRendererRuntime, SearchMatch, SuperDocAwarenessUpdatePayload, SuperDocCommentsUpdatePayload, SuperDocDocumentReplacedPayload, SuperDocEditorPayload, SuperDocExceptionPayload, SuperDocFontsApi, SuperDocLockedPayload, SuperDocMeasurementUnit, SuperDocMeasurementUnitChangePayload, SuperDocReadyPayload, SuperDocState, SuperDocViewportChangePayload, SuperDocViewportMetrics, SuperDocZoomMode, SuperDocZoomPayload, SuperDocZoomState, SurfaceHandle, SurfaceRequest, UpgradeToCollaborationOptions, User } from './types/index.js';
 import { WhiteboardData } from './whiteboard/Whiteboard.js';
 type ToolbarLike = {
     activeEditor?: unknown;
@@ -61,6 +64,21 @@ interface SuperDocEventMap {
      * neither a pre-ready read nor a clear would refresh without this.
      */
     'active-editor-change': [];
+    /**
+     * `replaceFile()` swapped the content under a stable editor identity.
+     *
+     * Deliberately distinct from `active-editor-change`: the editor object and its
+     * host both survive a replace, so anything bound to the HOST — geometry
+     * observers, for one — is still attached to the thing now rendering the
+     * replacement and must not be torn down. Only state describing the previous
+     * document's content is stale.
+     *
+     * Emitted only after the replacement is confirmed, and carrying the editor
+     * whose replacement completed: a replace is asynchronous, so the active editor
+     * can move while it is in flight, and a consumer must ignore an event naming an
+     * editor it is not bound to.
+     */
+    'document-replaced': [SuperDocDocumentReplacedPayload];
     'editor-update': [EditorUpdateEvent];
     'content-error': [SuperDocContentErrorPayload];
     'fonts-resolved': [FontsResolvedPayload];
@@ -92,6 +110,30 @@ interface SuperDocEventMap {
 export declare class SuperDoc extends EventEmitter<SuperDocEventMap> {
     #private;
     static allowedTypes: ("application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "application/pdf" | "text/html")[];
+    /**
+     * Which built-in surfaces this instance renders.
+     *
+     * Resolved from {@link Config.ui}, falling back to the historical defaults
+     * when it is omitted. Read-only: changing what SuperDoc renders after mount
+     * is a per-surface concern, not a config swap.
+     */
+    get uiConfig(): ReturnType<typeof normalizeUiConfig>;
+    /**
+     * What the user is permitted to do, as distinct from what SuperDoc draws.
+     *
+     * Resolved from {@link Config.interaction}. Stays meaningful when the
+     * application renders its own UI: `ui: false` removes the built-in comment
+     * dialog but not the policy that rejects a mutation.
+     */
+    get interactionConfig(): ReturnType<typeof normalizeInteractionConfig>;
+    /**
+     * Shared plumbing for dialogs and floating overlays, including ones the
+     * application opens itself through `openSurface()`.
+     *
+     * Resolved from {@link Config.surfaces}. Unaffected by `ui: false`, which
+     * turns off SuperDoc's own surfaces without disabling the mechanism.
+     */
+    get surfacesConfig(): ReturnType<typeof normalizeSurfacesConfig>;
     /**
      * Build-time SuperDoc version string. Initialized to `'0.0.0'` so the
      * field is structurally assigned before the constructor runs, then

package/dist/superdoc/src/core/config/merge-defined.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Merge config layers without letting an explicit `undefined` erase a value.
+ *
+ * Object spread treats a present-but-undefined key as a real assignment, so
+ * `{ ...legacy, ...next }` clobbers `legacy.closeOnEscape` whenever `next`
+ * carries `closeOnEscape: undefined`. That shape is common and unintentional:
+ * configs assembled from optional properties, spreads, or destructured
+ * arguments routinely carry keys whose value is undefined without the consumer
+ * meaning anything by it.
+ *
+ * Everywhere this migration merges a new spelling over a legacy one, the rule
+ * is the same as the single-value case: `undefined` means "unset, fall
+ * through", and only an explicit value overrides.
+ */
+/**
+ * Merge sources left to right, skipping keys whose value is `undefined`.
+ *
+ * Later sources win, as with spread. Non-object sources are ignored so callers
+ * can pass a possibly-absent block without guarding first.
+ *
+ * @param {...(Record<string, unknown> | undefined)} sources
+ * @returns {Record<string, unknown>}
+ */
+export function mergeDefined(...sources: (Record<string, unknown> | undefined)[]): Record<string, unknown>;
+/**
+ * Pick the first defined value, so `undefined` falls through but `null`,
+ * `false`, and `0` are honored as deliberate choices.
+ *
+ * `??` already does this for null and undefined together, which is wrong when
+ * `null` carries meaning — clearing an inherited resolver, for instance.
+ *
+ * @param {...unknown} values
+ * @returns {unknown}
+ */
+export function firstDefined(...values: unknown[]): unknown;

package/dist/superdoc/src/core/config/normalize-interaction-config.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Resolve the effective interaction policy.
+ *
+ * Reads `interaction.comments` first, then the legacy fields on
+ * `modules.comments`, so both spellings work while the migration lands.
+ *
+ * @param {Record<string, any>} [config] Raw consumer config.
+ * @returns {{ comments: { readOnly: boolean, allowResolve: boolean } }}
+ */
+export function normalizeInteractionConfig(config?: Record<string, any>): {
+    comments: {
+        readOnly: boolean;
+        allowResolve: boolean;
+    };
+};

package/dist/superdoc/src/core/config/normalize-surfaces-config.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Resolve the generic surface infrastructure config.
+ *
+ * Reads top-level `surfaces` first, then the legacy `modules.surfaces` block,
+ * so both spellings work while the migration lands. Built-in surface intents
+ * are deliberately not read here; they belong to the UI profile.
+ *
+ * The resolved shape mirrors the public `SurfacesConfig`, with every member
+ * present: the presets are merged objects rather than optional, and `resolver`
+ * is a function or `null` once a non-function value has been rejected.
+ *
+ * @param {Record<string, any>} [config] Raw consumer config.
+ * @returns {{
+ *   resolver: import('../types/index.js').SurfaceResolver | null,
+ *   dialog: NonNullable<import('../types/index.js').SurfacesConfig['dialog']>,
+ *   floating: NonNullable<import('../types/index.js').SurfacesConfig['floating']>,
+ * }}
+ */
+export function normalizeSurfacesConfig(config?: Record<string, any>): {
+    resolver: import('../types/index.js').SurfaceResolver | null;
+    dialog: NonNullable<import('../types/index.js').SurfacesConfig["dialog"]>;
+    floating: NonNullable<import('../types/index.js').SurfacesConfig["floating"]>;
+};

package/dist/superdoc/src/core/config/normalize-ui-config.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Collapse a consumer config into the effective built-in UI profile.
+ *
+ * @param {Record<string, any>} [config] Raw consumer config.
+ * @returns {{
+ *   enabled: boolean,
+ *   toolbar: { enabled: boolean, container: string | HTMLElement | null, options: Record<string, unknown> },
+ *   comments: { enabled: boolean, options: Record<string, unknown> },
+ *   contextMenu: { enabled: boolean, suppressed: boolean, options: Record<string, unknown> },
+ *   search: { enabled: boolean, options: Record<string, unknown> },
+ *   linkPopover: { enabled: boolean, suppressed: boolean, options: Record<string, unknown> },
+ *   ruler: { enabled: boolean, suppressed: boolean, container: string | HTMLElement | null },
+ *   contentControls: { enabled: boolean, options: Record<string, unknown> },
+ * }}
+ */
+export function normalizeUiConfig(config?: Record<string, any>): {
+    enabled: boolean;
+    toolbar: {
+        enabled: boolean;
+        container: string | HTMLElement | null;
+        options: Record<string, unknown>;
+    };
+    comments: {
+        enabled: boolean;
+        options: Record<string, unknown>;
+    };
+    contextMenu: {
+        enabled: boolean;
+        suppressed: boolean;
+        options: Record<string, unknown>;
+    };
+    search: {
+        enabled: boolean;
+        options: Record<string, unknown>;
+    };
+    linkPopover: {
+        enabled: boolean;
+        suppressed: boolean;
+        options: Record<string, unknown>;
+    };
+    ruler: {
+        enabled: boolean;
+        suppressed: boolean;
+        container: string | HTMLElement | null;
+    };
+    contentControls: {
+        enabled: boolean;
+        options: Record<string, unknown>;
+    };
+};
+/** Every built-in surface `ui: false` turns off. */
+export const BUILT_IN_SURFACES: readonly string[];
+/** Surfaces that render when the consumer says nothing at all. */
+export const HISTORICAL_DEFAULTS: Readonly<{
+    toolbar: true;
+    comments: true;
+    contextMenu: true;
+    search: false;
+    linkPopover: false;
+    ruler: false;
+    contentControls: true;
+}>;

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

@@ -995,8 +995,14 @@ export interface ExternalSurfaceRenderContext {
 }
 /** Module-level configuration for the surface system. */
 export interface SurfacesModuleConfig {
-    /** Global surface resolver. */
-    resolver?: SurfaceResolver;
+    /**
+     * Global surface resolver.
+     *
+     * `null` is the resolved "no resolver" value the normalizer produces after
+     * rejecting a non-function; SurfaceManager guards with `typeof === 'function'`
+     * either way.
+     */
+    resolver?: SurfaceResolver | null;
     /** Default dialog options. */
     dialog?: {
         /** Default escape behavior for dialogs (default: true). */
@@ -1961,6 +1967,32 @@ export interface SuperDocReadyPayload {
 export interface SuperDocEditorPayload {
     editor: Editor;
 }
+/**
+ * Payload emitted with `document-replaced`.
+ *
+ * `editor` is the editor whose replacement completed, not necessarily the one
+ * active when the event is received: a replace is asynchronous, so the active
+ * editor can move while it is in flight. A consumer must compare this against
+ * the editor it is bound to and ignore anything else.
+ *
+ * Typed `unknown` rather than `Editor`: the active editor can be a v2 facade
+ * that does not satisfy `Editor` (`getHTML` is required there and absent on the
+ * facade), so annotating it as `Editor` would promise methods that are not
+ * present. It is an identity token to compare, not an object to call.
+ */
+export interface SuperDocDocumentReplacedPayload {
+    editor: unknown;
+    /**
+     * The host that rendered the replaced document.
+     *
+     * Carried because `editor` alone cannot be matched in the V2 browser path: a
+     * successful replace emits its ready payload before `replaceFile()` resolves,
+     * so the shell has already installed a NEW facade by the time this event
+     * fires, and the captured facade is one the controller no longer holds. The
+     * host survives that swap, so it is the identity that still lines up.
+     */
+    host: unknown;
+}
 /**
  * Payload emitted with the `locked` event and passed to
  * `Config.onLocked`. `lockedBy` is non-optional because the runtime
@@ -2333,6 +2365,134 @@ export interface SuperDocZoomConfig {
     /** Bounds and padding for the `fit-width` policy. */
     fitWidth?: SuperDocFitWidthOptions;
 }
+/**
+ * Per-surface built-in UI configuration. Every field is optional; an omitted
+ * field keeps that surface's historical default rather than inheriting from
+ * its siblings, so a partial config only changes what it names.
+ *
+ * `false` disables a surface, `true` enables it with defaults, and an options
+ * object both enables and configures it.
+ *
+ * @see {@link Config.ui}
+ */
+export interface UIConfig {
+    /**
+     * Built-in toolbar. Enabled by default, but a toolbar only appears once
+     * `container` resolves to an element — enabling it without one creates the
+     * `superdoc.toolbar` handle and renders nothing.
+     */
+    toolbar?: boolean | {
+        /**
+         * Where to render the toolbar: an element, an id selector
+         * (`#toolbar`), a class selector (`.toolbar`), or a bare element id.
+         * Other CSS selector syntax resolves to nothing.
+         */
+        container?: string | HTMLElement;
+        /**
+         * Which groups render, or what goes in them. The shape decides which
+         * of the two it means, so both v1 spellings have somewhere to land.
+         *
+         * An array selects which groups render, e.g.
+         * `['left', 'center', 'right']`. This is where `Config.toolbarGroups`
+         * moves to. It is a membership list, not a sort order: the built-in
+         * toolbar lays groups out left, center, right, and renders center
+         * whether or not it is listed.
+         *
+         * An object is composition: a group id mapped to the item ids inside
+         * it, e.g. `{ right: ['bold'] }`. This is where
+         * `modules.toolbar.groups` moves to. Supplying both an ordering array
+         * here and a legacy composition map keeps the composition and applies
+         * the ordering as a filter.
+         */
+        groups?: string[] | Record<string, string[]>;
+        /** Toolbar item ids to hide from the default set. */
+        excludeItems?: string[];
+        /** Icon overrides, merged over the built-in set. */
+        icons?: Record<string, unknown>;
+        /** Text overrides, merged over the built-in set. */
+        texts?: Record<string, unknown>;
+        /** Size the toolbar to its container rather than the viewport. */
+        responsiveToContainer?: boolean;
+    };
+    /** Built-in comments UI. Enabled by default. */
+    comments?: boolean | Record<string, unknown>;
+    /** Built-in right-click and slash context menu. Enabled by default. */
+    contextMenu?: boolean | Record<string, unknown>;
+    /**
+     * Built-in find/replace surface. Disabled by default. Enabling it lets
+     * SuperDoc intercept Cmd+F / Ctrl+F; `editor.ui.search` stays available to
+     * custom UI either way.
+     */
+    search?: boolean | Record<string, unknown>;
+    /** Built-in popover shown when a link is selected. Disabled by default. */
+    linkPopover?: boolean | Record<string, unknown>;
+    /** Built-in ruler. Disabled by default. */
+    ruler?: boolean | {
+        /** Element or selector to render the ruler into. */
+        container?: string | HTMLElement;
+    };
+    /** Built-in chrome drawn around content controls. Enabled by default. */
+    contentControls?: boolean | Record<string, unknown>;
+}
+/**
+ * What the user is permitted to do, as distinct from what SuperDoc draws.
+ *
+ * Policy outlives presentation: `ui: false` removes the built-in comment
+ * dialog, but an application rendering its own still needs `readOnly`
+ * enforced. Keeping the two apart means a custom UI does not have to hold a
+ * `modules.comments` object alive purely to carry policy.
+ */
+export interface InteractionConfig {
+    /** Comment and tracked-change interaction policy. */
+    comments?: {
+        /** Reject every comment and tracked-change mutation (default: false). */
+        readOnly?: boolean;
+        /** Offer resolve/reopen actions when writable (default: true). */
+        allowResolve?: boolean;
+    };
+}
+/**
+ * Shared plumbing for dialogs and floating overlays, including surfaces the
+ * application opens itself through `superdoc.openSurface()`.
+ *
+ * Unaffected by `ui: false`: turning off SuperDoc's own surfaces does not
+ * disable the mechanism an application uses to render its own.
+ */
+export interface SurfacesConfig {
+    /**
+     * Resolver for intent-based surface requests.
+     *
+     * `null` explicitly clears a resolver inherited from the legacy
+     * `modules.surfaces.resolver`, which omitting the key does not do.
+     */
+    resolver?: SurfaceResolver | null;
+    /** Defaults applied to dialog surfaces. */
+    dialog?: {
+        /** Close on Escape (default: true). */
+        closeOnEscape?: boolean;
+        /** Close on backdrop click (default: true). */
+        closeOnBackdrop?: boolean;
+        /** Default max width. */
+        maxWidth?: string | number;
+    };
+    /** Defaults applied to floating surfaces. */
+    floating?: {
+        /** Placement preset (default: 'top-right'). */
+        placement?: SurfaceFloatingPlacement;
+        /** Default width. */
+        width?: string | number;
+        /** Default max width. */
+        maxWidth?: string | number;
+        /** Default max height. */
+        maxHeight?: string | number;
+        /** Close on Escape (default: true). */
+        closeOnEscape?: boolean;
+        /** Close on outside pointer down (default: false). */
+        closeOnOutsidePointerDown?: boolean;
+        /** Focus the surface on open (default: true). */
+        autoFocus?: boolean;
+    };
+}
 export interface Config {
     /** The ID of the SuperDoc. */
     superdocId?: string;
@@ -2380,6 +2540,53 @@ export interface Config {
     users?: User[];
     /** Colors to use for user awareness. */
     colors?: string[];
+    /**
+     * Which built-in interface SuperDoc renders.
+     *
+     * Omit it to keep SuperDoc's historical rendering: comments, the context
+     * menu, and content-control chrome are on; search, the link popover, and
+     * the ruler are opt-in; and the toolbar renders once it has somewhere to
+     * mount. That profile is not symmetrical, and omitting this field
+     * reproduces it exactly.
+     *
+     * Pass `false` when the application owns the interface. SuperDoc then
+     * renders no controls, chrome, dialogs, or popovers, while the document,
+     * the Document API, and `editor.ui` keep working — so a custom UI drives
+     * the same commands the built-in one would have.
+     *
+     * Pass an object to choose per surface. An omitted key keeps that
+     * surface's default rather than following its siblings, so
+     * `{ comments: false }` disables comments and changes nothing else.
+     *
+     * @example
+     * // Application owns the interface.
+     * new SuperDoc({ selector: '#editor', document: file, ui: false });
+     *
+     * @example
+     * // Built-in toolbar and search, no comments or context menu.
+     * new SuperDoc({
+     *   selector: '#editor',
+     *   document: file,
+     *   ui: {
+     *     toolbar: { container: '#toolbar' },
+     *     search: true,
+     *     comments: false,
+     *     contextMenu: false,
+     *   },
+     * });
+     */
+    ui?: false | UIConfig;
+    /**
+     * What the user is permitted to do. Independent of {@link Config.ui}: a
+     * `readOnly` policy still applies when the application renders its own
+     * comment UI.
+     */
+    interaction?: InteractionConfig;
+    /**
+     * Shared configuration for dialogs and floating overlays, including ones
+     * opened through `superdoc.openSurface()`. Stays active under `ui: false`.
+     */
+    surfaces?: SurfacesConfig;
     /** Modules to load. */
     modules?: Modules;
     /** Top-level override for permission checks. */