@kedataindo/docflow-core 0.0.83 → 0.0.84

package/dist/index.d.cts

@@ -1,15 +1,15 @@
 import { AnyExtension, Editor, Extension } from '@tiptap/core';
-import { a as CollaborationSetup } from './Collaboration-CGv9OZlB.cjs';
-export { A as AwarenessState, C as CollaborationOptions, c as collaborationExtensions, b as createCollaboration } from './Collaboration-CGv9OZlB.cjs';
-import { I as ImageUploadHandler, C as CitationPort, A as AIStreamFn, a as AIDraftFn } from './index-BTF6gajh.cjs';
-export { b as AIAction, c as AIActionRequest, d as AICompleteRequest, e as AIConfig, f as AIContextLocation, g as AIDraftCitation, h as AIDraftEvent, i as AIProvider, j as AIProviderFactory, k as AiChatRequestContext, l as Auth, m as CONTEXT_CHAR_CAP, n as CslDate, o as CslItemData, p as CslName, H as HttpKeyStorageUrls, q as ImageUploadResult, K as KeyStorage, L as LOCAL_STORAGE_KEY, O as OpenAICompatibleConfig, S as StreamEvent, r as buildAIPrompt, s as httpKeyStorage, t as localStorageKeyStorage, u as memoryKeyStorage, v as openaiCompatibleProvider, w as toAIStreamFn, x as trimContextAfter, y as trimContextBefore } from './index-BTF6gajh.cjs';
+import { Awareness } from 'y-protocols/awareness';
+import { IndexeddbPersistence } from 'y-indexeddb';
+import { WebrtcProvider } from 'y-webrtc';
+import { WebsocketProvider } from 'y-websocket';
+import * as Y from 'yjs';
+import { I as ImageUploadHandler, C as CitationPort, A as AIStreamFn, a as AIDraftFn } from './index-BsIFJXPk.cjs';
+export { b as AIAction, c as AIActionRequest, d as AICompleteRequest, e as AIConfig, f as AIDraftCitation, g as AIDraftEvent, h as AIProvider, i as AIProviderFactory, j as Auth, k as CONTEXT_CHAR_CAP, l as CslDate, m as CslItemData, n as CslName, H as HttpKeyStorageUrls, o as ImageUploadResult, K as KeyStorage, L as LOCAL_STORAGE_KEY, O as OpenAICompatibleConfig, S as StreamEvent, p as buildAIPrompt, q as httpKeyStorage, r as localStorageKeyStorage, s as memoryKeyStorage, t as openaiCompatibleProvider, u as toAIStreamFn, v as trimContextAfter, w as trimContextBefore } from './index-BsIFJXPk.cjs';
+import { PaginationPlusOptions } from 'tiptap-pagination-plus';
+export { PAGE_SIZES, PageSize, PaginationPlus, PaginationPlusOptions } from 'tiptap-pagination-plus';
 import { PluginKey } from '@tiptap/pm/state';
 import { Node } from '@tiptap/pm/model';
-import 'y-protocols/awareness';
-import 'y-indexeddb';
-import 'y-webrtc';
-import 'y-websocket';
-import 'yjs';
 
 interface ToolbarItem {
     id: string;
@@ -18,16 +18,6 @@ interface ToolbarItem {
     label?: string;
     action: string;
     args?: unknown[];
-    /**
-     * Group this item into the toolbar's compact groups instead of rendering it
-     * as a flat button. Currently only `'insert'` (the "+" / Sisipkan dropdown)
-     * is supported; built-in insert actions (link, image, table, footnote, page
-     * break, …) are grouped automatically, so plugins only need this flag for
-     * their OWN actions.
-     *
-     * Defaults to `undefined` → flat toolbar button (previous behaviour).
-     */
-    menu?: 'insert';
 }
 interface SlashCommand {
     name: string;
@@ -50,67 +40,86 @@ declare function collectExtensions(plugins: DocsEditorPlugin[]): AnyExtension[];
 declare function resolveAction(editor: Editor, action: string, ...args: unknown[]): boolean;
 declare function createActionMap(editor: Editor, plugins: DocsEditorPlugin[]): Record<string, (...args: unknown[]) => boolean>;
 
-interface PageSize {
-    pageHeight: number;
-    pageWidth: number;
-    marginTop: number;
-    marginBottom: number;
-    marginLeft: number;
-    marginRight: number;
+interface AwarenessState {
+    clientId: number;
+    user: {
+        name: string;
+        color: string;
+    };
+    cursor?: {
+        from: number;
+        to: number;
+    } | null;
+    /**
+     * Phase 9 PR2 — *present* flag. False when the local user has navigated
+     * away from the editor route (the Yjs provider is still alive but the
+     * host has gated cursor emission off, per the §6 *\"TOC sidebar orphan
+     * wiring\"* / REST-heartbeat scope notes). Peers see this instantly
+     * via the awareness `change` event — far faster than the 15s REST
+     * heartbeat fallback. Defaults to true when the user is in the editor.
+     */
+    present: boolean;
 }
-
-interface PaginationPlusOptions {
-    enabled?: boolean;
-    pageBreakBackground?: string;
-    pageHeight?: number;
-    pageWidth?: number;
-    marginTop?: number;
-    marginBottom?: number;
-    marginLeft?: number;
-    marginRight?: number;
-    pageGap?: number;
-    contentMarginTop?: number;
-    contentMarginBottom?: number;
-    footerRight?: string;
-    footerLeft?: string;
-    headerRight?: string;
-    headerLeft?: string;
-    customHeader?: Record<number, any>;
-    customFooter?: Record<number, any>;
-    pageGapBorderSize?: number;
-    pageGapBorderColor?: string;
-    onHeaderClick?: (info: {
-        event: MouseEvent;
-        pageNumber: number;
-    }) => void;
-    onFooterClick?: (info: {
-        event: MouseEvent;
-        pageNumber: number;
-    }) => void;
+interface CollaborationOptions {
+    room: string;
+    provider?: 'webrtc' | 'websocket';
+    websocketUrl?: string;
+    signaling?: string[];
+    user: {
+        name: string;
+        color: string;
+    };
+    onAwarenessChange?: (states: AwarenessState[]) => void;
+    initialStorageState?: Uint8Array;
+    /**
+     * Phase 9 PR2 — when false, the local user is treated as
+     * out-of-editor: their cursor field is nulled and `present` is false.
+     * Default is true (in editor). Toggle at runtime via
+     * `setLocalCursorEnabled()` returned from `createCollaboration`.
+     */
+    emitCursor?: boolean;
+    /**
+     * Phase 9 OF1 — when true, mirror the room's Y.Doc into IndexedDB
+     * (`docflow-<room>`) via y-indexeddb so edits survive offline and reload.
+     * Reconcile-on-reconnect is plain Yjs merge — no conflict resolution
+     * needed. The IndexedDB mirror is NEVER a seed source: the server (or the
+     * legacy-JSON seed path) still owns initial state; the mirror only
+     * contributes local offline edits via the normal Yjs update exchange.
+     */
+    offline?: boolean;
 }
-declare const PAGE_SIZES: Record<string, PageSize>;
-declare const PaginationPlus: Extension<PaginationPlusOptions, any>;
-declare module '@tiptap/core' {
-    interface Commands<ReturnType> {
-        paginationPlus: {
-            updatePageBreakBackground: (color: string) => ReturnType;
-            updatePageSize: (size: PageSize) => ReturnType;
-            updatePageWidth: (width: number) => ReturnType;
-            updatePageHeight: (height: number) => ReturnType;
-            updatePageGap: (gap: number) => ReturnType;
-            updateMargins: (margins: {
-                top: number;
-                bottom: number;
-                left: number;
-                right: number;
-            }) => ReturnType;
-            enablePagination: () => ReturnType;
-            disablePagination: () => ReturnType;
-            updateHeaderContent: (left?: string, right?: string) => ReturnType;
-            updateFooterContent: (left?: string, right?: string) => ReturnType;
-        };
-    }
+interface CollaborationSetup {
+    ydoc: Y.Doc;
+    provider: WebrtcProvider | WebsocketProvider | null;
+    awareness: Awareness;
+    /**
+     * Phase 9 OF1 — y-indexeddb persistence instance, present only when
+     * `options.offline` is true. Exposed so hosts/tests can `await
+     * persistence.whenSynced` before asserting the mirror contents. Do not
+     * use it as a seed source.
+     */
+    persistence?: IndexeddbPersistence;
+    /**
+     * Issue #117 — resolves after BOTH the offline mirror (if `offline`) AND
+     * the provider's first sync (if `websocket`) have completed. Hosts MUST
+     * `await setup.whenReady` before binding the editor, otherwise the
+     * TipTap view can render against the IndexedDB cache before the
+     * authoritative server state arrives, briefly showing — and on a
+     * disconnected peer potentially re-broadcasting — nodes the server has
+     * since deleted. Resolves immediately when neither side applies.
+     */
+    whenReady: Promise<void>;
+    destroy: () => void;
+    /**
+     * Phase 9 PR2 — toggle the local cursor emission + present flag.
+     * Pass `false` when the editor route unmounts, `true` when it remounts.
+     * Triggers an awareness `change` event so peers see the leave/rejoin
+     * instantly (no REST-heartbeat lag).
+     */
+    setLocalCursorEnabled: (enabled: boolean) => void;
 }
+declare function createCollaboration(options: CollaborationOptions): CollaborationSetup;
+declare function collaborationExtensions(options: CollaborationOptions | CollaborationSetup): AnyExtension[];
 
 /**
  * Lightweight client-side performance monitor (debug overlay).
@@ -207,31 +216,12 @@ interface EditorOptions {
     plugins?: DocsEditorPlugin[];
     editable?: boolean;
     onUpdate?: (json: object) => void;
-    /**
-     * Prebuilt collaboration setup from `await createCollaboration(...)`.
-     *
-     * A `CollaborationSetup` — never raw `CollaborationOptions` (issue
-     * fe-aktifai#230): building a provider is async (lazy-imports of
-     * y-webrtc/y-websocket), so `createEditor` cannot construct one itself.
-     * When set, history is disabled and the Yjs document is authoritative
-     * (local `content` is not seeded).
-     *
-     * **Ownership (host-owned):** the host that built the setup owns its
-     * lifecycle. `editor.destroy()` tears down the TipTap view only — it does
-     * **not** call `setup.destroy()`. This is deliberate: hosts routinely
-     * remount the editor against the same room (Vue `:key` bumps, tab
-     * switches, external document refreshes), and destroying the shared
-     * `Y.Doc`/provider/awareness on every remount silently kills sync and
-     * remote cursors until a full page reload. Destroy the setup yourself when
-     * the room is no longer needed (unmount, room change, `createCollaboration`
-     * resolving after disposal).
-     */
-    collaboration?: CollaborationSetup;
+    collaboration?: CollaborationOptions | CollaborationSetup;
     getPageMap?: () => Map<number, {
         page: number;
         blockIndex: number;
     }>;
-    paginationOptions?: PaginationPlusOptions;
+    paginationOptions?: Partial<PaginationPlusOptions>;
     /** Host-injected image upload port (see docs/LIBRARY_CONTRACT.md). */
     onImageUpload?: ImageUploadHandler;
     /** Host-injected citation port (Phase 6 — reference library + CSL styles). */
@@ -343,4 +333,66 @@ declare function replaceCurrent(editor: Editor, replacement: string): boolean;
 /** Replace every match in one transaction (applied back-to-front). */
 declare function replaceAll(editor: Editor, replacement: string): number;
 
-export { AIDraftFn, AIStreamFn, BlockAttributesExtension, CitationPort, type ClipboardSource, CollaborationSetup, type DocsEditor, type DocsEditorPlugin, EditorContextExtension, type EditorContextOptions, type EditorOptions, FontSizeExtension, ImageUploadHandler, type MonitorMetric, PAGE_SIZES, type PageSize, PaginationPlus, type PaginationPlusOptions, PerformanceMonitor, type PerformanceMonitorOptions, SearchAndReplaceExtension, type SearchMatch, type SearchState, type SlashCommand, type ToolbarItem, clearSearch, collectExtensions, createActionMap, createEditor, createPerformanceMonitor, definePlugin, detectClipboardSource, findMatches, getSearchState, normalizeClipboardHTML, replaceAll, replaceCurrent, resolveAction, sanitizePastedHTML, searchAndReplaceKey, searchNext, searchPrev, setSearchQuery };
+interface SubdocState {
+    id: string;
+    doc: Y.Doc;
+    provider: WebsocketProvider | null;
+    active: boolean;
+}
+interface SubdocumentProviderOptions {
+    /** WebSocket URL for the collaboration server. */
+    websocketUrl: string;
+    /** Room prefix — subdocuments use `${roomPrefix}/${id}` as room name. */
+    roomPrefix: string;
+    /** User info for awareness. */
+    user: {
+        name: string;
+        color: string;
+    };
+    /** Number of subdocuments to keep active (buffer around visible viewport). */
+    maxActive?: number;
+    /** Called when subdocument state changes (active/deactivated). */
+    onStateChange?: (states: SubdocState[]) => void;
+}
+/**
+ * Manages multiple Y.Doc subdocuments under a parent document.
+ *
+ * Use case: large documents (100+ pages) split into per-section subdocuments.
+ * Only active (visible) subdocuments are connected to the network via
+ * WebSocketProvider; inactive ones keep local state but stop syncing.
+ *
+ * Usage:
+ *   const provider = new SubdocumentProvider({ websocketUrl, roomPrefix, user })
+ *   provider.createSubdoc('section-1')
+ *   provider.activate('section-1')     // starts syncing
+ *   provider.deactivate('section-1')   // stops syncing
+ *   const frag = provider.getFragment('section-1') // Y.XmlFragment for editor
+ */
+declare class SubdocumentProvider {
+    readonly parentDoc: Y.Doc;
+    readonly subdocs: Y.Map<Y.Doc>;
+    readonly awareness: Awareness;
+    private readonly options;
+    private readonly states;
+    private readonly activeQueue;
+    private readonly parentProvider;
+    constructor(options: SubdocumentProviderOptions);
+    /** Create a new subdocument. Does NOT activate it. */
+    createSubdoc(id: string, initialState?: Uint8Array): Y.Doc;
+    /** Activate a subdocument — connects it to the network for live sync. */
+    activate(id: string): void;
+    /** Deactivate a subdocument — disconnects it from the network. */
+    deactivate(id: string): void;
+    /** Get the Y.XmlFragment for a subdocument. */
+    getFragment(id: string): Y.XmlFragment | null;
+    /** Check if a subdocument is currently active (syncing). */
+    isActive(id: string): boolean;
+    /** Get all subdocument states. */
+    getAllStates(): SubdocState[];
+    /** Get IDs of all active subdocuments. */
+    getActiveIds(): string[];
+    /** Destroy all subdocuments and providers. */
+    destroy(): void;
+}
+
+export { AIDraftFn, AIStreamFn, type AwarenessState, BlockAttributesExtension, CitationPort, type ClipboardSource, type CollaborationOptions, type CollaborationSetup, type DocsEditor, type DocsEditorPlugin, EditorContextExtension, type EditorContextOptions, type EditorOptions, FontSizeExtension, ImageUploadHandler, type MonitorMetric, PerformanceMonitor, type PerformanceMonitorOptions, SearchAndReplaceExtension, type SearchMatch, type SearchState, type SlashCommand, type SubdocState, SubdocumentProvider, type SubdocumentProviderOptions, type ToolbarItem, clearSearch, collaborationExtensions, collectExtensions, createActionMap, createCollaboration, createEditor, createPerformanceMonitor, definePlugin, detectClipboardSource, findMatches, getSearchState, normalizeClipboardHTML, replaceAll, replaceCurrent, resolveAction, sanitizePastedHTML, searchAndReplaceKey, searchNext, searchPrev, setSearchQuery };

package/dist/index.d.ts

@@ -1,15 +1,15 @@
 import { AnyExtension, Editor, Extension } from '@tiptap/core';
-import { a as CollaborationSetup } from './Collaboration-CGv9OZlB.js';
-export { A as AwarenessState, C as CollaborationOptions, c as collaborationExtensions, b as createCollaboration } from './Collaboration-CGv9OZlB.js';
-import { I as ImageUploadHandler, C as CitationPort, A as AIStreamFn, a as AIDraftFn } from './index-BTF6gajh.js';
-export { b as AIAction, c as AIActionRequest, d as AICompleteRequest, e as AIConfig, f as AIContextLocation, g as AIDraftCitation, h as AIDraftEvent, i as AIProvider, j as AIProviderFactory, k as AiChatRequestContext, l as Auth, m as CONTEXT_CHAR_CAP, n as CslDate, o as CslItemData, p as CslName, H as HttpKeyStorageUrls, q as ImageUploadResult, K as KeyStorage, L as LOCAL_STORAGE_KEY, O as OpenAICompatibleConfig, S as StreamEvent, r as buildAIPrompt, s as httpKeyStorage, t as localStorageKeyStorage, u as memoryKeyStorage, v as openaiCompatibleProvider, w as toAIStreamFn, x as trimContextAfter, y as trimContextBefore } from './index-BTF6gajh.js';
+import { Awareness } from 'y-protocols/awareness';
+import { IndexeddbPersistence } from 'y-indexeddb';
+import { WebrtcProvider } from 'y-webrtc';
+import { WebsocketProvider } from 'y-websocket';
+import * as Y from 'yjs';
+import { I as ImageUploadHandler, C as CitationPort, A as AIStreamFn, a as AIDraftFn } from './index-BsIFJXPk.js';
+export { b as AIAction, c as AIActionRequest, d as AICompleteRequest, e as AIConfig, f as AIDraftCitation, g as AIDraftEvent, h as AIProvider, i as AIProviderFactory, j as Auth, k as CONTEXT_CHAR_CAP, l as CslDate, m as CslItemData, n as CslName, H as HttpKeyStorageUrls, o as ImageUploadResult, K as KeyStorage, L as LOCAL_STORAGE_KEY, O as OpenAICompatibleConfig, S as StreamEvent, p as buildAIPrompt, q as httpKeyStorage, r as localStorageKeyStorage, s as memoryKeyStorage, t as openaiCompatibleProvider, u as toAIStreamFn, v as trimContextAfter, w as trimContextBefore } from './index-BsIFJXPk.js';
+import { PaginationPlusOptions } from 'tiptap-pagination-plus';
+export { PAGE_SIZES, PageSize, PaginationPlus, PaginationPlusOptions } from 'tiptap-pagination-plus';
 import { PluginKey } from '@tiptap/pm/state';
 import { Node } from '@tiptap/pm/model';
-import 'y-protocols/awareness';
-import 'y-indexeddb';
-import 'y-webrtc';
-import 'y-websocket';
-import 'yjs';
 
 interface ToolbarItem {
     id: string;
@@ -18,16 +18,6 @@ interface ToolbarItem {
     label?: string;
     action: string;
     args?: unknown[];
-    /**
-     * Group this item into the toolbar's compact groups instead of rendering it
-     * as a flat button. Currently only `'insert'` (the "+" / Sisipkan dropdown)
-     * is supported; built-in insert actions (link, image, table, footnote, page
-     * break, …) are grouped automatically, so plugins only need this flag for
-     * their OWN actions.
-     *
-     * Defaults to `undefined` → flat toolbar button (previous behaviour).
-     */
-    menu?: 'insert';
 }
 interface SlashCommand {
     name: string;
@@ -50,67 +40,86 @@ declare function collectExtensions(plugins: DocsEditorPlugin[]): AnyExtension[];
 declare function resolveAction(editor: Editor, action: string, ...args: unknown[]): boolean;
 declare function createActionMap(editor: Editor, plugins: DocsEditorPlugin[]): Record<string, (...args: unknown[]) => boolean>;
 
-interface PageSize {
-    pageHeight: number;
-    pageWidth: number;
-    marginTop: number;
-    marginBottom: number;
-    marginLeft: number;
-    marginRight: number;
+interface AwarenessState {
+    clientId: number;
+    user: {
+        name: string;
+        color: string;
+    };
+    cursor?: {
+        from: number;
+        to: number;
+    } | null;
+    /**
+     * Phase 9 PR2 — *present* flag. False when the local user has navigated
+     * away from the editor route (the Yjs provider is still alive but the
+     * host has gated cursor emission off, per the §6 *\"TOC sidebar orphan
+     * wiring\"* / REST-heartbeat scope notes). Peers see this instantly
+     * via the awareness `change` event — far faster than the 15s REST
+     * heartbeat fallback. Defaults to true when the user is in the editor.
+     */
+    present: boolean;
 }
-
-interface PaginationPlusOptions {
-    enabled?: boolean;
-    pageBreakBackground?: string;
-    pageHeight?: number;
-    pageWidth?: number;
-    marginTop?: number;
-    marginBottom?: number;
-    marginLeft?: number;
-    marginRight?: number;
-    pageGap?: number;
-    contentMarginTop?: number;
-    contentMarginBottom?: number;
-    footerRight?: string;
-    footerLeft?: string;
-    headerRight?: string;
-    headerLeft?: string;
-    customHeader?: Record<number, any>;
-    customFooter?: Record<number, any>;
-    pageGapBorderSize?: number;
-    pageGapBorderColor?: string;
-    onHeaderClick?: (info: {
-        event: MouseEvent;
-        pageNumber: number;
-    }) => void;
-    onFooterClick?: (info: {
-        event: MouseEvent;
-        pageNumber: number;
-    }) => void;
+interface CollaborationOptions {
+    room: string;
+    provider?: 'webrtc' | 'websocket';
+    websocketUrl?: string;
+    signaling?: string[];
+    user: {
+        name: string;
+        color: string;
+    };
+    onAwarenessChange?: (states: AwarenessState[]) => void;
+    initialStorageState?: Uint8Array;
+    /**
+     * Phase 9 PR2 — when false, the local user is treated as
+     * out-of-editor: their cursor field is nulled and `present` is false.
+     * Default is true (in editor). Toggle at runtime via
+     * `setLocalCursorEnabled()` returned from `createCollaboration`.
+     */
+    emitCursor?: boolean;
+    /**
+     * Phase 9 OF1 — when true, mirror the room's Y.Doc into IndexedDB
+     * (`docflow-<room>`) via y-indexeddb so edits survive offline and reload.
+     * Reconcile-on-reconnect is plain Yjs merge — no conflict resolution
+     * needed. The IndexedDB mirror is NEVER a seed source: the server (or the
+     * legacy-JSON seed path) still owns initial state; the mirror only
+     * contributes local offline edits via the normal Yjs update exchange.
+     */
+    offline?: boolean;
 }
-declare const PAGE_SIZES: Record<string, PageSize>;
-declare const PaginationPlus: Extension<PaginationPlusOptions, any>;
-declare module '@tiptap/core' {
-    interface Commands<ReturnType> {
-        paginationPlus: {
-            updatePageBreakBackground: (color: string) => ReturnType;
-            updatePageSize: (size: PageSize) => ReturnType;
-            updatePageWidth: (width: number) => ReturnType;
-            updatePageHeight: (height: number) => ReturnType;
-            updatePageGap: (gap: number) => ReturnType;
-            updateMargins: (margins: {
-                top: number;
-                bottom: number;
-                left: number;
-                right: number;
-            }) => ReturnType;
-            enablePagination: () => ReturnType;
-            disablePagination: () => ReturnType;
-            updateHeaderContent: (left?: string, right?: string) => ReturnType;
-            updateFooterContent: (left?: string, right?: string) => ReturnType;
-        };
-    }
+interface CollaborationSetup {
+    ydoc: Y.Doc;
+    provider: WebrtcProvider | WebsocketProvider | null;
+    awareness: Awareness;
+    /**
+     * Phase 9 OF1 — y-indexeddb persistence instance, present only when
+     * `options.offline` is true. Exposed so hosts/tests can `await
+     * persistence.whenSynced` before asserting the mirror contents. Do not
+     * use it as a seed source.
+     */
+    persistence?: IndexeddbPersistence;
+    /**
+     * Issue #117 — resolves after BOTH the offline mirror (if `offline`) AND
+     * the provider's first sync (if `websocket`) have completed. Hosts MUST
+     * `await setup.whenReady` before binding the editor, otherwise the
+     * TipTap view can render against the IndexedDB cache before the
+     * authoritative server state arrives, briefly showing — and on a
+     * disconnected peer potentially re-broadcasting — nodes the server has
+     * since deleted. Resolves immediately when neither side applies.
+     */
+    whenReady: Promise<void>;
+    destroy: () => void;
+    /**
+     * Phase 9 PR2 — toggle the local cursor emission + present flag.
+     * Pass `false` when the editor route unmounts, `true` when it remounts.
+     * Triggers an awareness `change` event so peers see the leave/rejoin
+     * instantly (no REST-heartbeat lag).
+     */
+    setLocalCursorEnabled: (enabled: boolean) => void;
 }
+declare function createCollaboration(options: CollaborationOptions): CollaborationSetup;
+declare function collaborationExtensions(options: CollaborationOptions | CollaborationSetup): AnyExtension[];
 
 /**
  * Lightweight client-side performance monitor (debug overlay).
@@ -207,31 +216,12 @@ interface EditorOptions {
     plugins?: DocsEditorPlugin[];
     editable?: boolean;
     onUpdate?: (json: object) => void;
-    /**
-     * Prebuilt collaboration setup from `await createCollaboration(...)`.
-     *
-     * A `CollaborationSetup` — never raw `CollaborationOptions` (issue
-     * fe-aktifai#230): building a provider is async (lazy-imports of
-     * y-webrtc/y-websocket), so `createEditor` cannot construct one itself.
-     * When set, history is disabled and the Yjs document is authoritative
-     * (local `content` is not seeded).
-     *
-     * **Ownership (host-owned):** the host that built the setup owns its
-     * lifecycle. `editor.destroy()` tears down the TipTap view only — it does
-     * **not** call `setup.destroy()`. This is deliberate: hosts routinely
-     * remount the editor against the same room (Vue `:key` bumps, tab
-     * switches, external document refreshes), and destroying the shared
-     * `Y.Doc`/provider/awareness on every remount silently kills sync and
-     * remote cursors until a full page reload. Destroy the setup yourself when
-     * the room is no longer needed (unmount, room change, `createCollaboration`
-     * resolving after disposal).
-     */
-    collaboration?: CollaborationSetup;
+    collaboration?: CollaborationOptions | CollaborationSetup;
     getPageMap?: () => Map<number, {
         page: number;
         blockIndex: number;
     }>;
-    paginationOptions?: PaginationPlusOptions;
+    paginationOptions?: Partial<PaginationPlusOptions>;
     /** Host-injected image upload port (see docs/LIBRARY_CONTRACT.md). */
     onImageUpload?: ImageUploadHandler;
     /** Host-injected citation port (Phase 6 — reference library + CSL styles). */
@@ -343,4 +333,66 @@ declare function replaceCurrent(editor: Editor, replacement: string): boolean;
 /** Replace every match in one transaction (applied back-to-front). */
 declare function replaceAll(editor: Editor, replacement: string): number;
 
-export { AIDraftFn, AIStreamFn, BlockAttributesExtension, CitationPort, type ClipboardSource, CollaborationSetup, type DocsEditor, type DocsEditorPlugin, EditorContextExtension, type EditorContextOptions, type EditorOptions, FontSizeExtension, ImageUploadHandler, type MonitorMetric, PAGE_SIZES, type PageSize, PaginationPlus, type PaginationPlusOptions, PerformanceMonitor, type PerformanceMonitorOptions, SearchAndReplaceExtension, type SearchMatch, type SearchState, type SlashCommand, type ToolbarItem, clearSearch, collectExtensions, createActionMap, createEditor, createPerformanceMonitor, definePlugin, detectClipboardSource, findMatches, getSearchState, normalizeClipboardHTML, replaceAll, replaceCurrent, resolveAction, sanitizePastedHTML, searchAndReplaceKey, searchNext, searchPrev, setSearchQuery };
+interface SubdocState {
+    id: string;
+    doc: Y.Doc;
+    provider: WebsocketProvider | null;
+    active: boolean;
+}
+interface SubdocumentProviderOptions {
+    /** WebSocket URL for the collaboration server. */
+    websocketUrl: string;
+    /** Room prefix — subdocuments use `${roomPrefix}/${id}` as room name. */
+    roomPrefix: string;
+    /** User info for awareness. */
+    user: {
+        name: string;
+        color: string;
+    };
+    /** Number of subdocuments to keep active (buffer around visible viewport). */
+    maxActive?: number;
+    /** Called when subdocument state changes (active/deactivated). */
+    onStateChange?: (states: SubdocState[]) => void;
+}
+/**
+ * Manages multiple Y.Doc subdocuments under a parent document.
+ *
+ * Use case: large documents (100+ pages) split into per-section subdocuments.
+ * Only active (visible) subdocuments are connected to the network via
+ * WebSocketProvider; inactive ones keep local state but stop syncing.
+ *
+ * Usage:
+ *   const provider = new SubdocumentProvider({ websocketUrl, roomPrefix, user })
+ *   provider.createSubdoc('section-1')
+ *   provider.activate('section-1')     // starts syncing
+ *   provider.deactivate('section-1')   // stops syncing
+ *   const frag = provider.getFragment('section-1') // Y.XmlFragment for editor
+ */
+declare class SubdocumentProvider {
+    readonly parentDoc: Y.Doc;
+    readonly subdocs: Y.Map<Y.Doc>;
+    readonly awareness: Awareness;
+    private readonly options;
+    private readonly states;
+    private readonly activeQueue;
+    private readonly parentProvider;
+    constructor(options: SubdocumentProviderOptions);
+    /** Create a new subdocument. Does NOT activate it. */
+    createSubdoc(id: string, initialState?: Uint8Array): Y.Doc;
+    /** Activate a subdocument — connects it to the network for live sync. */
+    activate(id: string): void;
+    /** Deactivate a subdocument — disconnects it from the network. */
+    deactivate(id: string): void;
+    /** Get the Y.XmlFragment for a subdocument. */
+    getFragment(id: string): Y.XmlFragment | null;
+    /** Check if a subdocument is currently active (syncing). */
+    isActive(id: string): boolean;
+    /** Get all subdocument states. */
+    getAllStates(): SubdocState[];
+    /** Get IDs of all active subdocuments. */
+    getActiveIds(): string[];
+    /** Destroy all subdocuments and providers. */
+    destroy(): void;
+}
+
+export { AIDraftFn, AIStreamFn, type AwarenessState, BlockAttributesExtension, CitationPort, type ClipboardSource, type CollaborationOptions, type CollaborationSetup, type DocsEditor, type DocsEditorPlugin, EditorContextExtension, type EditorContextOptions, type EditorOptions, FontSizeExtension, ImageUploadHandler, type MonitorMetric, PerformanceMonitor, type PerformanceMonitorOptions, SearchAndReplaceExtension, type SearchMatch, type SearchState, type SlashCommand, type SubdocState, SubdocumentProvider, type SubdocumentProviderOptions, type ToolbarItem, clearSearch, collaborationExtensions, collectExtensions, createActionMap, createCollaboration, createEditor, createPerformanceMonitor, definePlugin, detectClipboardSource, findMatches, getSearchState, normalizeClipboardHTML, replaceAll, replaceCurrent, resolveAction, sanitizePastedHTML, searchAndReplaceKey, searchNext, searchPrev, setSearchQuery };