@rtif-sdk/engine 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cory Robinson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# @rtif-sdk/engine
+
+Editor engine for RTIF (Rich Text Input Format). Manages document state, dispatches operations through a plugin lifecycle, and provides undo/redo history.
+
+## Install
+
+```bash
+npm install @rtif-sdk/engine
+```
+
+## Usage
+
+### Create an engine
+
+```typescript
+import { createEngine } from '@rtif-sdk/engine';
+import type { Document } from '@rtif-sdk/core';
+
+const doc: Document = {
+  version: 1,
+  blocks: [{ id: 'b1', type: 'text', spans: [{ text: '' }] }],
+};
+
+const engine = createEngine(doc);
+```
+
+### Dispatch operations
+
+```typescript
+engine.dispatch({ type: 'insert_text', offset: 0, text: 'Hello' });
+
+console.log(engine.state.doc.blocks[0].spans[0].text); // 'Hello'
+```
+
+### Undo / Redo
+
+```typescript
+engine.undo(); // reverts to empty document
+engine.redo(); // re-applies 'Hello'
+```
+
+### Subscribe to changes
+
+```typescript
+const unsubscribe = engine.onChange((state) => {
+  console.log('Document changed:', state.doc);
+});
+```
+
+### Plugins
+
+```typescript
+import type { Plugin } from '@rtif-sdk/engine';
+
+const myPlugin: Plugin = {
+  id: 'my-plugin',
+  init(engine) {
+    engine.registerCommand('greet', (eng) => {
+      eng.dispatch({ type: 'insert_text', offset: 0, text: 'Hi! ' });
+    });
+  },
+};
+
+engine.use(myPlugin);
+engine.exec('greet');
+```
+
+## Plugin Lifecycle
+
+1. `beforeApply` hooks — inspect, modify, or cancel operations
+2. `apply()` — core applies operations to the document
+3. `afterApply` hooks — observe changes, trigger side effects
+4. `onChange` listeners — UI re-renders
+
+Plugin errors are caught and isolated — a failing plugin never breaks the editor.
+
+## License
+
+MIT

package/dist/commands.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Type-safe command name constants for built-in engine commands.
+ *
+ * Use these constants instead of raw strings when calling `engine.exec()`
+ * to get IDE autocomplete and catch typos at write-time.
+ *
+ * @example
+ * ```ts
+ * import { EngineCommands } from '@rtif-sdk/engine';
+ * engine.exec(EngineCommands.UNDO);
+ * engine.exec(EngineCommands.REDO);
+ * ```
+ *
+ * @module
+ */
+/**
+ * Command name constants for built-in engine commands (undo/redo).
+ *
+ * @example
+ * ```ts
+ * engine.exec(EngineCommands.UNDO);
+ * engine.exec(EngineCommands.REDO);
+ * ```
+ */
+export declare const EngineCommands: {
+    readonly UNDO: "undo";
+    readonly REDO: "redo";
+};
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;;;CAGjB,CAAC"}

package/dist/commands.js

@@ -0,0 +1,29 @@
+/**
+ * Type-safe command name constants for built-in engine commands.
+ *
+ * Use these constants instead of raw strings when calling `engine.exec()`
+ * to get IDE autocomplete and catch typos at write-time.
+ *
+ * @example
+ * ```ts
+ * import { EngineCommands } from '@rtif-sdk/engine';
+ * engine.exec(EngineCommands.UNDO);
+ * engine.exec(EngineCommands.REDO);
+ * ```
+ *
+ * @module
+ */
+/**
+ * Command name constants for built-in engine commands (undo/redo).
+ *
+ * @example
+ * ```ts
+ * engine.exec(EngineCommands.UNDO);
+ * engine.exec(EngineCommands.REDO);
+ * ```
+ */
+export const EngineCommands = {
+    UNDO: 'undo',
+    REDO: 'redo',
+};
+//# sourceMappingURL=commands.js.map

package/dist/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;CACJ,CAAC"}

package/dist/engine.d.ts

@@ -0,0 +1,137 @@
+/**
+ * EditorEngine — the state machine that drives all document mutations.
+ * See docs/spec/plugin-contract.md for specification.
+ */
+import type { Document, Block, Selection, Operation, RangeMarksResult } from '@rtif-sdk/core';
+import type { Plugin } from './plugin-host.js';
+import type { ShortcutBinding } from './registries.js';
+import type { PluginError } from './errors.js';
+/** Runtime editor state */
+export interface EditorState {
+    readonly doc: Document;
+    readonly selection: Selection;
+    /** Plugins can store state here, keyed by plugin ID */
+    readonly pluginState: Record<string, unknown>;
+}
+/** The engine interface — the only way to produce new states */
+export interface IEditorEngine {
+    /** Current state (readonly from outside) */
+    readonly state: EditorState;
+    /** Dispatch an operation or a batch of operations */
+    dispatch(ops: Operation | Operation[]): void;
+    /** Dispatch a high-level command by name */
+    exec(command: string, payload?: unknown): void;
+    /**
+     * Check whether a command can execute in the current state.
+     * Returns true if the command exists and its canExecute returns true (or is not defined).
+     * Returns false if the command is not registered.
+     *
+     * @param command - The command name
+     * @param payload - Optional payload passed to canExecute
+     * @returns Whether the command can execute
+     */
+    canExecute(command: string, payload?: unknown): boolean;
+    /**
+     * Check whether a command's effect is currently active.
+     * Returns false if the command is not registered or has no isActive handler.
+     *
+     * @param command - The command name
+     * @param payload - Optional payload passed to isActive
+     * @returns Whether the command is active
+     */
+    isActive(command: string, payload?: unknown): boolean;
+    /** Undo the last operation group */
+    undo(): void;
+    /** Redo the last undone operation group */
+    redo(): void;
+    /** Register a plugin */
+    use(plugin: Plugin): void;
+    /** Subscribe to state changes */
+    onChange(listener: (state: EditorState) => void): () => void;
+    /**
+     * Subscribe to selection-only changes (cursor moves that don't modify the document).
+     * Fires when setSelection() is called with a different selection.
+     * Does NOT fire during dispatch/undo/redo (those fire onChange instead).
+     *
+     * @param listener - Function called with the new state after selection change
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```ts
+     * const unsub = engine.onSelectionChange((state) => {
+     *   updateToolbar(state.selection);
+     * });
+     * ```
+     */
+    onSelectionChange(listener: (state: EditorState) => void): () => void;
+    /** Subscribe to plugin error events */
+    onError(listener: (error: PluginError) => void): () => void;
+    /**
+     * Update the engine's selection state without dispatching any operations.
+     *
+     * Used by platform implementations to sync cursor/selection changes that
+     * originate from user interaction (clicks, arrow keys, touch handles)
+     * back into the engine state, so that subsequent operations use the
+     * correct selection.
+     *
+     * Does NOT fire onChange listeners (the document did not change).
+     *
+     * @param selection - The new selection to store
+     *
+     * @example
+     * ```ts
+     * // After reading a DOM selectionchange event
+     * engine.setSelection({ anchor: { offset: 5 }, focus: { offset: 5 } });
+     * ```
+     */
+    setSelection(selection: Selection): void;
+    /**
+     * Destroy the engine, calling destroy() on all plugins and cleaning up.
+     * After calling destroy(), no further operations can be dispatched.
+     */
+    destroy(): void;
+    /** Get the formatting marks at a specific document offset */
+    getMarksAtOffset(offset: number): Record<string, unknown>;
+    /** Get the common and mixed marks across a text range */
+    getMarksInRange(offset: number, count: number): RangeMarksResult;
+    /** Get the block containing a specific document offset */
+    getBlockAtOffset(offset: number): Block;
+    /** Get all registered keyboard shortcuts */
+    getShortcuts(): ReadonlyArray<ShortcutBinding>;
+    /**
+     * Set a pending mark that will be applied to the next inserted text.
+     * Pending marks are ephemeral — not part of EditorState, not serialized, not in undo history.
+     *
+     * @param mark - The mark key (e.g., 'bold')
+     * @param value - The mark value (e.g., true)
+     */
+    setPendingMark(mark: string, value: unknown): void;
+    /**
+     * Toggle a pending mark. If the mark is set, remove it. If not, set it to `value` (default: true).
+     *
+     * @param mark - The mark key
+     * @param value - The value to set if toggling on (default: true)
+     */
+    togglePendingMark(mark: string, value?: unknown): void;
+    /** Get a shallow copy of the current pending marks */
+    getPendingMarks(): Readonly<Record<string, unknown>>;
+    /** Clear all pending marks */
+    clearPendingMarks(): void;
+}
+/**
+ * Create a new EditorEngine with the given initial document.
+ *
+ * @param doc - The initial document
+ * @returns A new engine instance
+ *
+ * @example
+ * ```ts
+ * const engine = createEngine({
+ *   version: 1,
+ *   blocks: [{ id: 'b1', type: 'text', spans: [{ text: '' }] }],
+ * });
+ * engine.dispatch({ type: 'insert_text', offset: 0, text: 'hello' });
+ * ```
+ */
+export declare function createEngine(doc: Document): IEditorEngine;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}