@zeke-02/docx-editor-core 0.1.0

package/dist/types-RchZmPFN.d.ts

@@ -0,0 +1,137 @@
+import { Schema, NodeSpec, MarkSpec } from 'prosemirror-model';
+import { Plugin, Command } from 'prosemirror-state';
+
+/**
+ * Extension Manager
+ *
+ * Two-phase initialization:
+ * 1. buildSchema() — collects NodeSpecs/MarkSpecs from extensions → new Schema
+ * 2. initializeRuntime() — calls onSchemaReady() on each extension, collects plugins/commands/keymaps
+ */
+
+declare class ExtensionManager {
+    private extensions;
+    private schema;
+    private plugins;
+    private commands;
+    constructor(extensions: AnyExtension[]);
+    /**
+     * Phase 1: Build schema from node/mark extensions
+     */
+    buildSchema(): void;
+    /**
+     * Phase 2: Initialize runtime (plugins, commands, keymaps)
+     * Must be called after buildSchema()
+     */
+    initializeRuntime(): void;
+    /**
+     * Get the built schema
+     */
+    getSchema(): Schema;
+    /**
+     * Get all plugins (raw + keymap merged)
+     */
+    getPlugins(): Plugin[];
+    /**
+     * Get the flat command registry
+     */
+    getCommands(): CommandMap;
+    /**
+     * Get a specific command by name
+     */
+    getCommand(name: string): ((...args: any[]) => Command) | undefined;
+    /**
+     * Lifecycle: destroy
+     */
+    destroy(): void;
+}
+
+/**
+ * Extension System Type Definitions
+ *
+ * Tiptap-style extension architecture for ProseMirror.
+ * Three extension types:
+ * - Extension: plugins, commands, keymaps (no schema)
+ * - NodeExtension: adds a node spec to the schema
+ * - MarkExtension: adds a mark spec to the schema
+ */
+
+type ExtensionPriority = number;
+declare const Priority: {
+    readonly Highest: 0;
+    readonly High: 50;
+    readonly Default: 100;
+    readonly Low: 150;
+    readonly Lowest: 200;
+};
+interface ExtensionContext {
+    schema: Schema;
+    /**
+     * The manager that owns this extension. Use this in runtime callbacks
+     * (e.g. `handleKeyDown`) that need to dispatch commands, instead of
+     * reaching back to the `singletonManager` export — the latter forms a
+     * circular import that breaks when the package is consumed as a built
+     * bundle.
+     */
+    manager: ExtensionManager;
+}
+type CommandMap = Record<string, (...args: any[]) => Command>;
+type KeyboardShortcutMap = Record<string, Command>;
+interface ExtensionRuntime {
+    commands?: CommandMap;
+    keyboardShortcuts?: KeyboardShortcutMap;
+    plugins?: Plugin[];
+}
+interface ExtensionConfig {
+    name: string;
+    priority: ExtensionPriority;
+    options: Record<string, unknown>;
+}
+interface NodeExtensionConfig extends ExtensionConfig {
+    schemaNodeName: string;
+    nodeSpec: NodeSpec;
+}
+interface MarkExtensionConfig extends ExtensionConfig {
+    schemaMarkName: string;
+    markSpec: MarkSpec;
+}
+interface Extension {
+    type: 'extension';
+    config: ExtensionConfig;
+    onSchemaReady(ctx: ExtensionContext): ExtensionRuntime;
+}
+interface NodeExtension {
+    type: 'node';
+    config: NodeExtensionConfig;
+    onSchemaReady(ctx: ExtensionContext): ExtensionRuntime;
+}
+interface MarkExtension {
+    type: 'mark';
+    config: MarkExtensionConfig;
+    onSchemaReady(ctx: ExtensionContext): ExtensionRuntime;
+}
+type AnyExtension = Extension | NodeExtension | MarkExtension;
+interface ExtensionDefinition<TOptions = Record<string, unknown>> {
+    name: string;
+    priority?: ExtensionPriority;
+    defaultOptions?: TOptions;
+    onSchemaReady(ctx: ExtensionContext, options: TOptions): ExtensionRuntime;
+}
+interface NodeExtensionDefinition<TOptions = Record<string, unknown>> {
+    name: string;
+    priority?: ExtensionPriority;
+    defaultOptions?: TOptions;
+    schemaNodeName: string;
+    nodeSpec: NodeSpec | ((options: TOptions) => NodeSpec);
+    onSchemaReady?(ctx: ExtensionContext, options: TOptions): ExtensionRuntime;
+}
+interface MarkExtensionDefinition<TOptions = Record<string, unknown>> {
+    name: string;
+    priority?: ExtensionPriority;
+    defaultOptions?: TOptions;
+    schemaMarkName: string;
+    markSpec: MarkSpec | ((options: TOptions) => MarkSpec);
+    onSchemaReady?(ctx: ExtensionContext, options: TOptions): ExtensionRuntime;
+}
+
+export { type AnyExtension as A, type CommandMap as C, type Extension as E, type KeyboardShortcutMap as K, type MarkExtensionDefinition as M, type NodeExtension as N, Priority as P, ExtensionManager as a, type ExtensionDefinition as b, type MarkExtension as c, type NodeExtensionDefinition as d, type ExtensionConfig as e, type ExtensionContext as f, type ExtensionPriority as g, type ExtensionRuntime as h, type MarkExtensionConfig as i, type NodeExtensionConfig as j };

package/dist/types-dYdjUZMo.d.mts

@@ -0,0 +1,311 @@
+import { Document } from './types/document.mjs';
+import { Position, Range, AgentCommand } from './types/agentApi.mjs';
+
+/**
+ * Core Plugin System Types
+ *
+ * Defines the interfaces for headless plugins that work in Node.js
+ * without React/DOM dependencies. These plugins extend DocumentAgent
+ * with additional commands and expose MCP tools for AI integration.
+ */
+
+/**
+ * Core plugin interface - headless, works in Node.js
+ *
+ * Plugins can:
+ * - Register command handlers that DocumentAgent dispatches to
+ * - Declare MCP tools that the MCP server exposes to AI clients
+ * - Have optional initialization logic
+ * - Declare dependencies on other plugins
+ */
+interface CorePlugin {
+    /** Unique plugin identifier */
+    id: string;
+    /** Human-readable plugin name */
+    name: string;
+    /** Plugin version (semver) */
+    version?: string;
+    /** Plugin description */
+    description?: string;
+    /**
+     * Command handlers this plugin provides.
+     * DocumentAgent dispatches commands to these handlers.
+     *
+     * @example
+     * ```ts
+     * commandHandlers: {
+     *   'insertTemplateVariable': (doc, cmd) => {
+     *     // Transform document
+     *     return modifiedDoc;
+     *   },
+     * }
+     * ```
+     */
+    commandHandlers?: Record<string, CommandHandler>;
+    /**
+     * MCP tools this plugin exposes.
+     * MCP server collects these from all plugins.
+     */
+    mcpTools?: McpToolDefinition[];
+    /**
+     * Optional setup when plugin is registered.
+     * Called once during plugin registration.
+     */
+    initialize?: () => void | Promise<void>;
+    /**
+     * Optional cleanup when plugin is unregistered.
+     */
+    destroy?: () => void | Promise<void>;
+    /**
+     * Dependencies on other plugins (by ID).
+     * The registry ensures dependencies are loaded first.
+     */
+    dependencies?: string[];
+}
+/**
+ * Command handler function type
+ *
+ * Receives a document and a command, returns a modified document.
+ * Must be pure/immutable - always return a new document.
+ */
+type CommandHandler = (doc: Document, command: PluginCommand) => Document;
+/**
+ * Extended command type for plugins
+ *
+ * Plugins can define custom command types beyond the built-in AgentCommand types.
+ */
+interface PluginCommand {
+    /** Command type identifier */
+    type: string;
+    /** Unique command ID (for undo tracking) */
+    id?: string;
+    /** Position for positional commands */
+    position?: Position;
+    /** Range for range-based commands */
+    range?: Range;
+    /** Additional command-specific data */
+    [key: string]: unknown;
+}
+/**
+ * Result of command execution
+ */
+interface CommandResult {
+    /** The modified document */
+    document: Document;
+    /** Whether the command succeeded */
+    success: boolean;
+    /** Error message if failed */
+    error?: string;
+    /** Metadata about the operation */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * MCP tool definition
+ *
+ * Describes a tool that can be called by AI clients through the MCP server.
+ */
+interface McpToolDefinition {
+    /** Tool name (used in MCP protocol) */
+    name: string;
+    /** Human-readable description for AI */
+    description: string;
+    /**
+     * JSON Schema for tool input validation.
+     * Can be a Zod schema or plain JSON Schema object.
+     */
+    inputSchema: JsonSchema | ZodSchemaLike;
+    /**
+     * Handler function for the tool.
+     * Receives validated input and returns a result.
+     */
+    handler: McpToolHandler;
+    /**
+     * Optional annotations for the tool
+     */
+    annotations?: McpToolAnnotations;
+}
+/**
+ * MCP tool handler function
+ */
+type McpToolHandler = (input: unknown, context: McpToolContext) => Promise<McpToolResult> | McpToolResult;
+/**
+ * Context passed to MCP tool handlers
+ */
+interface McpToolContext {
+    /** Current document (if loaded) */
+    document?: Document;
+    /** Document buffer (if loaded) */
+    documentBuffer?: ArrayBuffer;
+    /** Session state */
+    session: McpSession;
+    /** Logger for debugging */
+    log: (message: string, data?: unknown) => void;
+}
+/**
+ * MCP session state
+ *
+ * Maintains state across tool calls within a session.
+ */
+interface McpSession {
+    /** Session ID */
+    id: string;
+    /** Loaded documents by ID */
+    documents: Map<string, LoadedDocument>;
+    /** Custom session data */
+    data: Map<string, unknown>;
+}
+/**
+ * A loaded document in the session
+ */
+interface LoadedDocument {
+    /** Document ID */
+    id: string;
+    /** Parsed document */
+    document: Document;
+    /** Original buffer (for repacking) */
+    buffer?: ArrayBuffer;
+    /** Source filename or path */
+    source?: string;
+    /** Last modified timestamp */
+    lastModified: number;
+}
+/**
+ * MCP tool result
+ */
+interface McpToolResult {
+    /** Result content */
+    content: McpToolContent[];
+    /** Whether this is an error result */
+    isError?: boolean;
+}
+/**
+ * MCP tool content types
+ */
+type McpToolContent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    data: string;
+    mimeType: string;
+} | {
+    type: 'resource';
+    uri: string;
+    mimeType?: string;
+    text?: string;
+};
+/**
+ * MCP tool annotations
+ */
+interface McpToolAnnotations {
+    /** Tool category for organization */
+    category?: string;
+    /** Whether this tool modifies the document */
+    readOnly?: boolean;
+    /** Estimated cost/complexity */
+    complexity?: 'low' | 'medium' | 'high';
+    /** Example usage */
+    examples?: McpToolExample[];
+}
+/**
+ * MCP tool example
+ */
+interface McpToolExample {
+    /** Example description */
+    description: string;
+    /** Example input */
+    input: unknown;
+    /** Expected output description */
+    output?: string;
+}
+/**
+ * JSON Schema definition (subset)
+ */
+interface JsonSchema {
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    items?: JsonSchema;
+    required?: string[];
+    description?: string;
+    enum?: unknown[];
+    default?: unknown;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+    additionalProperties?: boolean | JsonSchema;
+    anyOf?: JsonSchema[];
+    oneOf?: JsonSchema[];
+    allOf?: JsonSchema[];
+    $ref?: string;
+}
+/**
+ * Zod-like schema interface for compatibility
+ */
+interface ZodSchemaLike {
+    _def?: unknown;
+    parse?: (data: unknown) => unknown;
+    safeParse?: (data: unknown) => {
+        success: boolean;
+        data?: unknown;
+        error?: unknown;
+    };
+}
+/**
+ * Check if a schema is Zod-like
+ */
+declare function isZodSchema(schema: unknown): schema is ZodSchemaLike;
+/**
+ * Plugin lifecycle events
+ */
+type PluginEvent = {
+    type: 'registered';
+    plugin: CorePlugin;
+} | {
+    type: 'unregistered';
+    pluginId: string;
+} | {
+    type: 'error';
+    pluginId: string;
+    error: Error;
+};
+/**
+ * Plugin event listener
+ */
+type PluginEventListener = (event: PluginEvent) => void;
+/**
+ * Extract command type from a union
+ */
+type ExtractCommand<T extends AgentCommand, Type extends string> = T extends {
+    type: Type;
+} ? T : never;
+/**
+ * Create a typed command handler
+ */
+type TypedCommandHandler<T extends PluginCommand> = (doc: Document, command: T) => Document;
+/**
+ * Plugin configuration options
+ */
+interface PluginOptions {
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Custom configuration */
+    config?: Record<string, unknown>;
+}
+/**
+ * Result of plugin registration
+ */
+interface PluginRegistrationResult {
+    /** Whether registration succeeded */
+    success: boolean;
+    /** Registered plugin (if successful) */
+    plugin?: CorePlugin;
+    /** Error message (if failed) */
+    error?: string;
+    /** Warning messages */
+    warnings?: string[];
+}
+
+export { type CommandHandler as C, type ExtractCommand as E, type JsonSchema as J, type LoadedDocument as L, type McpSession as M, type PluginCommand as P, type TypedCommandHandler as T, type ZodSchemaLike as Z, type CommandResult as a, type CorePlugin as b, type McpToolAnnotations as c, type McpToolContent as d, type McpToolContext as e, type McpToolDefinition as f, type McpToolHandler as g, type McpToolResult as h, type PluginEvent as i, type PluginEventListener as j, type PluginOptions as k, type PluginRegistrationResult as l, isZodSchema as m, type McpToolExample as n };

package/dist/utils/cardStyles.d.mts

@@ -0,0 +1,31 @@
+/**
+ * Sidebar card chrome — shared between React and Vue. Numeric
+ * pixel values rather than `'8px'` strings so both adapters'
+ * CSSProperties shapes accept them. Lifted from
+ * `packages/react/src/components/sidebar/cardStyles.ts` and the
+ * Vue mirror so there's one canonical table.
+ * @packageDocumentation
+ * @public
+ */
+/**
+ * Tiny shared CSSProperties shape so framework-agnostic style
+ * objects in core don't need to import from React or Vue. Both
+ * adapters' `CSSProperties` types are structurally compatible
+ * with this looser shape (string | number values, camelCased keys).
+ */
+type CSSProperties = Record<string, string | number | undefined>;
+
+/**
+ * Sidebar card chrome — shared between React and Vue. Numeric
+ * pixel values rather than `'8px'` strings so both adapters'
+ * CSSProperties shapes accept them. Lifted from
+ * `packages/react/src/components/sidebar/cardStyles.ts` and the
+ * Vue mirror so there's one canonical table.
+ * @packageDocumentation
+ * @public
+ */
+
+declare const CARD_STYLE_COLLAPSED: CSSProperties;
+declare const CARD_STYLE_EXPANDED: CSSProperties;
+
+export { CARD_STYLE_COLLAPSED, CARD_STYLE_EXPANDED };

package/dist/utils/cardStyles.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Sidebar card chrome — shared between React and Vue. Numeric
+ * pixel values rather than `'8px'` strings so both adapters'
+ * CSSProperties shapes accept them. Lifted from
+ * `packages/react/src/components/sidebar/cardStyles.ts` and the
+ * Vue mirror so there's one canonical table.
+ * @packageDocumentation
+ * @public
+ */
+/**
+ * Tiny shared CSSProperties shape so framework-agnostic style
+ * objects in core don't need to import from React or Vue. Both
+ * adapters' `CSSProperties` types are structurally compatible
+ * with this looser shape (string | number values, camelCased keys).
+ */
+type CSSProperties = Record<string, string | number | undefined>;
+
+/**
+ * Sidebar card chrome — shared between React and Vue. Numeric
+ * pixel values rather than `'8px'` strings so both adapters'
+ * CSSProperties shapes accept them. Lifted from
+ * `packages/react/src/components/sidebar/cardStyles.ts` and the
+ * Vue mirror so there's one canonical table.
+ * @packageDocumentation
+ * @public
+ */
+
+declare const CARD_STYLE_COLLAPSED: CSSProperties;
+declare const CARD_STYLE_EXPANDED: CSSProperties;
+
+export { CARD_STYLE_COLLAPSED, CARD_STYLE_EXPANDED };

package/dist/utils/cardStyles.js

@@ -0,0 +1 @@
+'use strict';require('../chunk-DC7S76ZX.js');var r={padding:"8px 10px",borderRadius:8,backgroundColor:"#f8fbff",cursor:"pointer",boxShadow:"0 1px 3px rgba(60,64,67,0.2), 0 2px 6px rgba(60,64,67,0.08)"},o={padding:"10px 12px",borderRadius:8,backgroundColor:"#fff",cursor:"pointer",boxShadow:"0 1px 3px rgba(60,64,67,0.3), 0 4px 8px 3px rgba(60,64,67,0.15)"};exports.CARD_STYLE_COLLAPSED=r;exports.CARD_STYLE_EXPANDED=o;

package/dist/utils/cardStyles.mjs

@@ -0,0 +1 @@
+import'../chunk-QYUPLKLP.mjs';var r={padding:"8px 10px",borderRadius:8,backgroundColor:"#f8fbff",cursor:"pointer",boxShadow:"0 1px 3px rgba(60,64,67,0.2), 0 2px 6px rgba(60,64,67,0.08)"},o={padding:"10px 12px",borderRadius:8,backgroundColor:"#fff",cursor:"pointer",boxShadow:"0 1px 3px rgba(60,64,67,0.3), 0 4px 8px 3px rgba(60,64,67,0.15)"};export{r as CARD_STYLE_COLLAPSED,o as CARD_STYLE_EXPANDED};

package/dist/utils/comments.d.mts

@@ -0,0 +1,121 @@
+/**
+ * Framework-agnostic comment + tracked-change helpers shared by the
+ * React and Vue adapters. The data shapes and string-formatting rules
+ * here are part of the visible UI (avatar colors, date strings) so
+ * keep this file as the single source of truth — both adapters import
+ * from here. CSS-property factories live in adapter-specific files
+ * (sidebar/cardUtils.ts in React, sidebar/sidebarUtils.ts in Vue).
+ * @packageDocumentation
+ * @public
+ */
+import { P as Paragraph } from '../content-5Mrz6w_b.mjs';
+import '../formatting-BH4hcZiq.mjs';
+import '../colors-C3vA7HUU.mjs';
+import '../docx/wrapTypes.mjs';
+
+/**
+ * Framework-agnostic comment + tracked-change helpers shared by the
+ * React and Vue adapters. The data shapes and string-formatting rules
+ * here are part of the visible UI (avatar colors, date strings) so
+ * keep this file as the single source of truth — both adapters import
+ * from here. CSS-property factories live in adapter-specific files
+ * (sidebar/cardUtils.ts in React, sidebar/sidebarUtils.ts in Vue).
+ * @packageDocumentation
+ * @public
+ */
+
+/** Extract plain text from a Comment's paragraph content. */
+declare function getCommentText(paragraphs?: Paragraph[]): string;
+declare function formatDate(dateStr?: string): string;
+declare function getInitials(name: string): string;
+declare function getAvatarColor(name: string): string;
+declare function truncateText(text: string, maxLength?: number): string;
+/**
+ * One tracked change surfaced by `extractTrackedChanges`. Each entry
+ * groups all sites of one revision into a single row that the sidebar
+ * renders as one card. Resolve via {@link acceptChangeById} /
+ * {@link rejectChangeById} for any type — the by-id resolver walks
+ * every site sharing the id so coalesced edits clear in one click.
+ *
+ * @public
+ */
+interface TrackedChangeEntry {
+    /**
+     * Revision shape. Inline shapes (`insertion`, `deletion`, `replacement`)
+     * wrap text runs; the rest are structural revisions on node attrs.
+     *
+     * - `insertion` — text was added (`<w:ins>`).
+     * - `deletion` — text was struck through but not removed (`<w:del>`).
+     * - `replacement` — a deletion + insertion by the same author at the
+     *   same position+time; sidebar shows one combined card. `deletedText`
+     *   and `insertionRevisionId` are set on this variant.
+     * - `paragraphMarkInsertion` / `paragraphMarkDeletion` — Enter /
+     *   Backspace produced a tracked paragraph break (`<w:pPr><w:rPr><w:ins/>` /
+     *   `<w:del/>`).
+     * - `paragraphPropertiesChanged` — formatting (alignment, spacing,
+     *   etc.) on the paragraph was changed (`<w:pPrChange>`).
+     * - `rowInserted` / `rowDeleted` / `rowPropertiesChanged` — table
+     *   row authored / removed / formatted (`<w:trPr><w:ins/>` / `<w:del/>`
+     *   / `<w:trPrChange>`).
+     * - `cellInserted` / `cellDeleted` / `cellMerged` /
+     *   `cellPropertiesChanged` — per-cell revisions
+     *   (`<w:cellIns>` / `<w:cellDel>` / `<w:cellMerge>` / `<w:tcPrChange>`).
+     * - `tablePropertiesChanged` — table-level formatting
+     *   (`<w:tblPrChange>`).
+     */
+    type: 'insertion' | 'deletion' | 'replacement' | 'paragraphMarkInsertion' | 'paragraphMarkDeletion' | 'paragraphPropertiesChanged' | 'rowInserted' | 'rowDeleted' | 'rowPropertiesChanged' | 'cellInserted' | 'cellDeleted' | 'cellMerged' | 'cellPropertiesChanged' | 'tableInserted' | 'tableDeleted' | 'tablePropertiesChanged';
+    /**
+     * Affected text. For inline types this is the run's text; for
+     * structural types it's the surrounding paragraph / cell content
+     * (truncated by the sidebar before display).
+     */
+    text: string;
+    /**
+     * Only set when `type === 'replacement'` — the text the user removed.
+     * The inserted text lives in {@link TrackedChangeEntry.text}.
+     */
+    deletedText?: string;
+    /** Author that minted the revision (`w:author`). */
+    author: string;
+    /** ISO timestamp the revision was minted (`w:date`). May be undefined for legacy imports. */
+    date?: string;
+    /**
+     * Document position where the revision starts. For inline types this
+     * is the start of the marked text run; for structural types it's the
+     * containing paragraph / row / cell / table node's start position.
+     * Used by the sidebar to anchor the card at the correct vertical
+     * offset.
+     */
+    from: number;
+    /**
+     * Document position where the revision ends. For inline coalesced
+     * runs that span multiple paragraphs, this is the END position of the
+     * LAST run in the group; the intervening structural positions are not
+     * preserved.
+     */
+    to: number;
+    /**
+     * The `w:id` of the revision. Pass to
+     * {@link acceptChangeById} / {@link rejectChangeById} to resolve every
+     * site sharing this id — including pPrIns paragraph attrs and
+     * subsequent typed runs in the same editing session.
+     */
+    revisionId: number;
+    /**
+     * Only set when `type === 'replacement'` — the insertion half carries
+     * a DIFFERENT `w:id` from the deletion (sharing would trip the OOXML
+     * move-pair serializer). Card Accept handlers dispatch BOTH ids to
+     * clear the deletion and the insertion + any coalesced paragraph-marks.
+     */
+    insertionRevisionId?: number;
+    /**
+     * Extra `w:id`s that map to the same logical revision as this card.
+     * Populated when the extractor coalesces a burst of distinct ids by
+     * (author, date) — e.g. a foreign document where the source editor
+     * minted a fresh id per atomic edit. Accept/reject handlers must
+     * resolve every id in this list in addition to {@link revisionId}.
+     */
+    coalescedRevisionIds?: number[];
+}
+
+export { type TrackedChangeEntry, formatDate, getAvatarColor, getCommentText, getInitials, truncateText };