@kedataindo/docflow-core 0.0.2 → 0.0.3

package/dist/index.d.cts

@@ -1,10 +1,13 @@
 import { AnyExtension, Editor, Extension } from '@tiptap/core';
 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 { 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';
 
 interface ToolbarItem {
     id: string;
@@ -45,6 +48,15 @@ interface AwarenessState {
         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 CollaborationOptions {
     room: string;
@@ -57,16 +69,215 @@ interface CollaborationOptions {
     };
     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;
 }
 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;
     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[];
 
+/**
+ * Injectable ports — the narrow interfaces through which the library reaches
+ * host-provided backend capabilities (storage, persistence, …). The library
+ * declares them; the host app implements them. See docs/LIBRARY_CONTRACT.md.
+ */
+interface ImageUploadResult {
+    /** Resolved URL/href the host stored the file at. */
+    src: string;
+    alt?: string;
+    title?: string;
+}
+/**
+ * Host-supplied image upload handler. Called with the file picked by the user;
+ * resolves to the stored location to insert into the document. Reject to abort
+ * the insert (the failure is logged, nothing is inserted).
+ */
+type ImageUploadHandler = (file: File) => Promise<ImageUploadResult>;
+/** CSL-JSON name (see https://citeproc-js.readthedocs.io/csl-json/). */
+interface CslName {
+    family?: string;
+    given?: string;
+    literal?: string;
+}
+/** CSL-JSON date. */
+interface CslDate {
+    'date-parts'?: number[][];
+    raw?: string;
+    literal?: string;
+}
+/**
+ * A CSL-JSON item — the structured source metadata citeproc-js consumes.
+ * Nodes store only `{ sourceId, locator }`; all rendered text is derived from
+ * this data by the citation engine (never persisted in the document).
+ */
+interface CslItemData {
+    id: string;
+    type: string;
+    title?: string;
+    author?: CslName[];
+    editor?: CslName[];
+    issued?: CslDate;
+    'container-title'?: string;
+    publisher?: string;
+    'publisher-place'?: string;
+    page?: string;
+    volume?: string;
+    issue?: string;
+    DOI?: string;
+    URL?: string;
+    ISBN?: string;
+    abstract?: string;
+    [k: string]: unknown;
+}
+/**
+ * Host-supplied citation port. The library never fetches sources itself — the
+ * host owns the reference library and injects CSL-JSON through this port,
+ * mirroring the `onImageUpload` injection pattern.
+ */
+interface CitationPort {
+    /** CSL-JSON provider — a snapshot array or a getter for live data. */
+    sources: CslItemData[] | (() => CslItemData[]);
+    /** Active CSL style id (e.g. 'chicago-notes-bibliography'). */
+    style?: string;
+    /**
+     * Called when the user inserts a citation: the host opens its source
+     * picker and resolves with the chosen source id (null = cancelled).
+     */
+    onSourceRequest?: () => Promise<string | null>;
+    /**
+     * Called when the set of cited source ids changes, so the host can update
+     * its embedded per-document source snapshot.
+     */
+    onSourcesChange?: (ids: string[]) => void;
+    /**
+     * Optional importer (Phase 6C-2): resolve a DOI/URL into a new persisted
+     * source via the host's backend (CrossRef lookup). Returns the created
+     * (or deduplicated) source, null on failure.
+     */
+    onImportDoi?: (doi: string) => Promise<CslItemData | null>;
+    /**
+     * Optional importer (Phase 6C-3): parse + persist a BibTeX/RIS document
+     * via the host's backend. Returns the imported sources and how many
+     * entries failed.
+     */
+    onImportBibliography?: (payload: {
+        format: 'bibtex' | 'ris';
+        text: string;
+    }) => Promise<{
+        imported: CslItemData[];
+        failed: number;
+    }>;
+}
+
+/**
+ * Shared AI action types (Phase 7).
+ *
+ * The library (aiPlugin) is provider-agnostic: it never names a URL or holds a
+ * key. The app implements `AIStreamFn` (apps/web/src/ai/aiStream.ts) and injects
+ * it; the server owns provider selection via env config.
+ */
+type AIAction = 'rewrite' | 'summarize' | 'grammar' | 'tone' | 'translate' | 'expand' | 'shorten' | 'generate' | 'chat' | 'draft';
+interface AIActionRequest {
+    action: AIAction;
+    /** Selected text (7B). */
+    selection?: string;
+    /** Bounded surrounding text — never the whole document. */
+    context?: {
+        before: string;
+        after: string;
+    };
+    /** User instruction (/ai prompt, chat message, tone target, target language). */
+    prompt?: string;
+    /** For doc-aware chat / RAG scoping. */
+    documentId?: string;
+    options?: Record<string, unknown>;
+}
+/**
+ * The app implements this and injects it; the library never knows the URL.
+ * Yields streamed text chunks in order; stops at end of stream, throws on error.
+ */
+type AIStreamFn = (req: AIActionRequest, signal: AbortSignal) => AsyncIterable<string>;
+/** One entry in the citation table carried by the SSE `done` event (§3.4). */
+interface AIDraftCitation {
+    /** 1-based index matching a `[n]` marker in the streamed text. */
+    ref: number;
+    /** `Source._id` string — the library maps markers through this table. */
+    sourceId: string;
+    /** "first author family + year" tag, e.g. "Doe (2024)". */
+    label: string;
+}
+/**
+ * Events yielded by `aiDraft` (§3.5). The `done` event carries the citation
+ * table; the `error` event does NOT (the bug-hunter carry-forward — the client
+ * treats BOTH `done` and `error` as terminal; Insert is enabled only on `done`).
+ */
+type AIDraftEvent = {
+    type: 'delta';
+    text: string;
+} | {
+    type: 'done';
+    citations: AIDraftCitation[];
+} | {
+    type: 'error';
+    message: string;
+};
+/**
+ * The app implements this and injects it; the library never knows the URL.
+ * Mirrors `AIStreamFn` but yields richer `AIDraftEvent`s (carries the citation
+ * table on the terminal `done` event). Injected exactly like `aiStream`.
+ */
+type AIDraftFn = (req: {
+    prompt: string;
+    context?: {
+        before: string;
+        after: string;
+    };
+    k?: number;
+}, signal: AbortSignal) => AsyncIterable<AIDraftEvent>;
+
+/**
+ * Sanitize pasted HTML content (e.g. from Google Docs) to prevent crashes
+ * during ProseMirror parsing. Strips non-content tags like <meta>, <style>,
+ * and HTML comments that are common in rich clipboard data but not valid
+ * in the ProseMirror schema.
+ *
+ * Also converts Google Docs-specific markup into standard TipTap-compatible
+ * HTML so that text color and background-color survive the paste.
+ */
+declare function sanitizePastedHTML(html: string): string;
 interface EditorOptions {
     target?: HTMLElement;
     content?: object | string;
@@ -79,6 +290,14 @@ interface EditorOptions {
         blockIndex: number;
     }>;
     paginationOptions?: PaginationPlusOptions;
+    /** Host-injected image upload port (see docs/LIBRARY_CONTRACT.md). */
+    onImageUpload?: ImageUploadHandler;
+    /** Host-injected citation port (Phase 6 — reference library + CSL styles). */
+    citation?: CitationPort;
+    /** Host-injected AI transport (Phase 7 — editor → server → LLM). */
+    aiStream?: AIStreamFn;
+    /** Host-injected cited-draft transport (Phase 7E — editor → server → RAG LLM). */
+    aiDraft?: AIDraftFn;
 }
 interface DocsEditor {
     editor: Editor;
@@ -119,4 +338,121 @@ declare module '@tiptap/core' {
  */
 declare const FontSizeExtension: Extension<any, any>;
 
-export { type AwarenessState, BlockAttributesExtension, type CollaborationOptions, type CollaborationSetup, type DocsEditor, type DocsEditorPlugin, type EditorOptions, FontSizeExtension, type SlashCommand, type ToolbarItem, collaborationExtensions, collectExtensions, createActionMap, createCollaboration, createEditor, definePlugin, resolveAction };
+interface EditorContextOptions {
+    onImageUpload?: ImageUploadHandler;
+    citation?: CitationPort;
+    aiStream?: AIStreamFn;
+    aiDraft?: AIDraftFn;
+}
+/**
+ * Internal carrier for host-injected ports. Always registered (like TextStyle)
+ * so plugin commands can reach the ports through the editor instance:
+ *
+ *   editor.storage.editorContext.onImageUpload
+ *   editor.storage.editorContext.citation
+ *   editor.storage.editorContext.aiStream
+ *   editor.storage.editorContext.aiDraft
+ *
+ * Plugins must never import backend concerns — they read injected ports from
+ * this storage instead. See docs/LIBRARY_CONTRACT.md.
+ */
+declare const EditorContextExtension: Extension<EditorContextOptions, any>;
+
+/**
+ * Find & Replace — core editing infrastructure (always registered, like
+ * TextStyle). Plain-string, case-insensitive search with ProseMirror
+ * decorations for match highlighting. No regex (deliberate — see the
+ * edit-menu plan §5.6).
+ */
+interface SearchMatch {
+    from: number;
+    to: number;
+}
+interface SearchState {
+    query: string;
+    matches: SearchMatch[];
+    activeIndex: number;
+}
+declare const searchAndReplaceKey: PluginKey<SearchState>;
+/**
+ * Case-insensitive plain-string search across all text nodes.
+ * Matches are **non-overlapping** (the scan advances by the needle length) so
+ * replace-all can apply them in one transaction without position drift.
+ */
+declare function findMatches(doc: Node, query: string): SearchMatch[];
+declare const SearchAndReplaceExtension: Extension<any, any>;
+declare function getSearchState(editor: Editor): SearchState;
+declare function setSearchQuery(editor: Editor, query: string): void;
+declare function clearSearch(editor: Editor): void;
+/** Move to the next match (wraps). Returns the newly active match, if any. */
+declare function searchNext(editor: Editor): SearchMatch | null;
+/** Move to the previous match (wraps). Returns the newly active match, if any. */
+declare function searchPrev(editor: Editor): SearchMatch | null;
+/** Replace the active match. The doc change recomputes matches automatically. */
+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;
+
+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 { type AIAction, type AIActionRequest, type AIDraftCitation, type AIDraftEvent, type AIDraftFn, type AIStreamFn, type AwarenessState, BlockAttributesExtension, type CitationPort, type CollaborationOptions, type CollaborationSetup, type CslDate, type CslItemData, type CslName, type DocsEditor, type DocsEditorPlugin, EditorContextExtension, type EditorContextOptions, type EditorOptions, FontSizeExtension, type ImageUploadHandler, type ImageUploadResult, SearchAndReplaceExtension, type SearchMatch, type SearchState, type SlashCommand, type SubdocState, SubdocumentProvider, type SubdocumentProviderOptions, type ToolbarItem, clearSearch, collaborationExtensions, collectExtensions, createActionMap, createCollaboration, createEditor, definePlugin, findMatches, getSearchState, replaceAll, replaceCurrent, resolveAction, sanitizePastedHTML, searchAndReplaceKey, searchNext, searchPrev, setSearchQuery };