@owomark/core 0.1.0

package/README.md

@@ -0,0 +1,212 @@
+# @owomark/core
+
+Framework-agnostic Markdown editor engine. Provides document model, incremental rendering, input handling, commands, and selection management for a single-layer `contenteditable` editing experience.
+
+Official package: `@owomark/core`. The flat name `owomark-core` is reserved only as a compatibility redirect and should not be used for new installs.
+
+## Install
+
+```bash
+npm install @owomark/core
+```
+
+## Quick Start
+
+### Pure Logic Core (no DOM)
+
+```ts
+import { createOwoMarkCore } from '@owomark/core';
+
+const core = createOwoMarkCore({ initialMarkdown: '# Hello' });
+
+// Intent-driven input API
+const result = core.applyBeforeInput(
+  { inputType: 'insertText', data: 'X' },
+  { anchor: 7, focus: 7 },
+);
+// result.action: 'handled' | 'allow-native' | 'composition-sync'
+
+console.log(core.getMarkdown()); // '# HelloX'
+core.destroy();
+```
+
+### With DOM (use @owomark/view)
+
+```ts
+import { createOwoMarkCore } from '@owomark/core';
+import { createOwoMarkView } from '@owomark/view';
+
+const core = createOwoMarkCore({ initialMarkdown: '# Hello\n\nStart typing...' });
+const view = createOwoMarkView(core, document.getElementById('editor')!);
+
+core.onChange((markdown) => {
+  console.log('Content changed:', markdown);
+});
+
+// Cleanup
+view.destroy();
+core.destroy();
+```
+
+For backward compatibility, a legacy standalone editor API is also available:
+
+```ts
+import { createOwoMarkVanillaEditor } from '@owomark/view';
+
+const editor = createOwoMarkVanillaEditor();
+editor.setMarkdown('# Hello');
+editor.mount(document.getElementById('editor')!);
+editor.destroy();
+```
+
+## Core API
+
+### State
+
+| Method | Description |
+|--------|-------------|
+| `getMarkdown(): string` | Get current Markdown content |
+| `getDocument(): OwoMarkDocument` | Get immutable document model |
+| `getSelection(): OwoMarkSelection \| null` | Current selection as linear offsets |
+| `getVirtualSelection()` | Current selection as `{ blockId, offset }` pairs |
+| `getComposition()` | Current IME composition state |
+| `getSnapshot()` | Full state snapshot |
+
+### Input Handling
+
+| Method | Description |
+|--------|-------------|
+| `applyBeforeInput(intent, selection)` | Handle `beforeinput` events |
+| `applyKeyDown(intent, selection)` | Handle `keydown` events |
+| `applyPaste(intent, selection)` | Handle `paste` events |
+| `handleCompositionStart(selection)` | Enter IME composition mode |
+| `handleCompositionEnd(selection)` | Exit IME composition mode |
+| `syncText(text, selection)` | Sync DOM text back to model (IME fallback) |
+
+### Content Mutation
+
+| Method | Description |
+|--------|-------------|
+| `setMarkdown(md: string)` | Replace content (resets history) |
+| `replaceMarkdown(md, selection)` | Replace content with explicit selection (supports undo) |
+| `dispatch(command, payload?)` | Dispatch a named command |
+
+### Events
+
+| Method | Description |
+|--------|-------------|
+| `onChange(cb)` | Subscribe to content changes |
+| `onSelectionChange(cb)` | Subscribe to selection changes |
+| `onCompositionStateChange(cb)` | Subscribe to IME composition state |
+| `onDocumentChange(cb)` | Subscribe to document model changes (sovereign mode) |
+| `onStateChange(cb)` | Subscribe to any state change |
+
+## Pure Function Exports
+
+The package also exports pure functions that can be used independently:
+
+### Commands
+
+```ts
+import {
+  handleMarkdownEnter,
+  applyMarkdownIndent,
+  handleCharInput,
+  handleSmartBackspace,
+  toggleBold,
+  toggleItalic,
+  insertLink,
+  insertCodeFence,
+} from '@owomark/core';
+```
+
+### Parser
+
+```ts
+import { tokenizeBlock, tokenizeInline } from '@owomark/core';
+```
+
+### Model
+
+```ts
+import {
+  parseMarkdownToDocument,
+  serializeDocument,
+  getBlockAtOffset,
+} from '@owomark/core';
+```
+
+### Clipboard
+
+```ts
+import { normalizeMarkdownPaste } from '@owomark/core';
+```
+
+## Supported Markdown
+
+- Headings (`# ` through `###### `)
+- Bold (`**text**`) and italic (`*text*`)
+- Inline code (`` `code` ``)
+- Links (`[text](url)`)
+- Unordered and ordered lists
+- Blockquotes (`> `)
+- Fenced code blocks (`` ``` ``)
+- Thematic breaks (`---`)
+
+## Preview Projection
+
+Convert a parsed document into preview-ready blocks for incremental rendering:
+
+```ts
+import {
+  createSharedStateStore,
+  projectToPreviewBlocks,
+  computePreviewDirtyRange,
+  deriveBlockId,
+} from '@owomark/core';
+```
+
+### Shared State Store
+
+```ts
+const store = createSharedStateStore({ initialMarkdown: '# Hello' });
+
+// Connect an editor instance
+const disconnect = store.connectEditor(editorInstance);
+
+// Subscribe to state changes (consumed by preview engines)
+const unsubscribe = store.subscribe((state) => {
+  console.log('Version:', state.version);
+  console.log('Preview blocks:', state.previewBlocks.length);
+});
+
+// Cleanup
+unsubscribe();
+disconnect();
+```
+
+### Block Projection
+
+```ts
+const blocks = projectToPreviewBlocks(document, 'vitesse-light');
+const dirtyRange = computePreviewDirtyRange(previousBlocks, blocks);
+```
+
+- Adjacent same-type container blocks (lists, blockquotes) are grouped into a single `PreviewBlock`
+- Each block has a stable `blockId` (`L{startLine}-{endLine}`) for DOM reconciliation
+- `renderKey` (djb2 hash of `kind:theme:raw`) drives cache invalidation
+
+### Preview Types
+
+- `PreviewBlock` — block identity, kind, raw content, line range, render key
+- `PreviewBlockKind` — `'paragraph' | 'heading' | 'code-fence' | ...`
+- `PreviewDirtyReason` — `'text-edit' | 'structure-edit' | 'theme-change' | 'renderer-change' | 'custom-block-change' | 'full-rebuild'`
+- `OwoMarkSharedState` — full shared state snapshot (document, preview blocks, selection, version)
+- `OwoMarkSharedStateStore` — subscribe/getState store interface
+- `OwoMarkSharedStateController` — store + `setMarkdown()`, `connectEditor()`, `updateVisibleBlockIds()`, `setThemeKey()`, `notifyRendererChange()`, `notifyCustomBlockChange()`
+
+## Design Principles
+
+- **Input-first**: IME composition is never interrupted by rendering. Patches only run after `compositionend`.
+- **Incremental**: Only dirty blocks are re-parsed and re-rendered. No full DOM rebuilds on each keystroke.
+- **Framework-free**: Zero runtime dependencies. Works with any UI framework or vanilla JS.

package/dist/adapter/dom-adapter.d.ts

@@ -0,0 +1 @@
+export { v as DocumentChangeCallback, w as DomAdapterInstance, a6 as createDomAdapter } from '../dom-adapter-IZEW91gZ.js';

package/dist/adapter/dom-adapter.js

@@ -0,0 +1,261 @@
+import {
+  createOwoMarkCore,
+  detectAndRenderDirty,
+  fullRender,
+  readSelection,
+  restoreSelection
+} from "../chunk-RYTHPR7H.js";
+
+// src/adapter/dom-adapter.ts
+function createDomAdapter() {
+  const core = createOwoMarkCore();
+  let root = null;
+  let compositionJustEnded = false;
+  let documentChangeCallback = null;
+  function syncEmptyAttr() {
+    if (!root) return;
+    const doc = core.getDocument();
+    const empty = doc.blocks.length === 0 || doc.blocks.length === 1 && doc.blocks[0].raw === "";
+    if (empty) {
+      root.setAttribute("data-owo-empty", "true");
+    } else {
+      root.removeAttribute("data-owo-empty");
+    }
+  }
+  function syncFromDOM() {
+    if (!root) return;
+    const textContent = extractTextFromRoot(root);
+    const sel = readSelection(root);
+    const oldMarkdown = core.getMarkdown();
+    if (textContent !== oldMarkdown) {
+      const oldDoc = core.getDocument();
+      core.syncText(textContent, sel);
+      if (!documentChangeCallback && root) {
+        const newDoc = core.getDocument();
+        detectAndRenderDirty(root, oldDoc, newDoc, true);
+        if (sel) {
+          restoreSelection(root, sel);
+        }
+      }
+      syncEmptyAttr();
+    }
+  }
+  function onBeforeInput(e) {
+    if (core.getComposition().active) return;
+    const sel = readSelection(root);
+    const oldDoc = core.getDocument();
+    const result = core.applyBeforeInput(
+      { inputType: e.inputType, data: e.data },
+      sel
+    );
+    if (result.action === "handled") {
+      e.preventDefault();
+      if (!documentChangeCallback && root) {
+        const newDoc = core.getDocument();
+        if (oldDoc !== newDoc) {
+          detectAndRenderDirty(root, oldDoc, newDoc);
+          const linearSel = core.getSelection();
+          if (linearSel) restoreSelection(root, linearSel);
+        }
+      }
+      syncEmptyAttr();
+    }
+  }
+  function onInput() {
+    if (core.getComposition().active) return;
+    if (compositionJustEnded) {
+      compositionJustEnded = false;
+      syncFromDOM();
+    }
+  }
+  function onKeyDown(e) {
+    if (core.getComposition().active) return;
+    const sel = readSelection(root);
+    const oldDoc = core.getDocument();
+    const result = core.applyKeyDown(
+      {
+        key: e.key,
+        ctrlKey: e.ctrlKey,
+        metaKey: e.metaKey,
+        altKey: e.altKey,
+        shiftKey: e.shiftKey
+      },
+      sel
+    );
+    if (result.action === "handled") {
+      e.preventDefault();
+      if (!documentChangeCallback && root) {
+        const newDoc = core.getDocument();
+        if (oldDoc !== newDoc) {
+          detectAndRenderDirty(root, oldDoc, newDoc);
+          const linearSel = core.getSelection();
+          if (linearSel) restoreSelection(root, linearSel);
+        }
+      }
+      syncEmptyAttr();
+    }
+  }
+  function onPaste(e) {
+    e.preventDefault();
+    const raw = e.clipboardData?.getData("text/plain") ?? "";
+    const sel = readSelection(root);
+    const oldDoc = core.getDocument();
+    const result = core.applyPaste({ text: raw }, sel);
+    if (result.action === "handled" && !documentChangeCallback && root) {
+      const newDoc = core.getDocument();
+      if (oldDoc !== newDoc) {
+        detectAndRenderDirty(root, oldDoc, newDoc);
+        const linearSel = core.getSelection();
+        if (linearSel) restoreSelection(root, linearSel);
+      }
+    }
+    syncEmptyAttr();
+  }
+  function onCompositionStart() {
+    const sel = readSelection(root);
+    core.handleCompositionStart(sel);
+  }
+  function onCompositionUpdate() {
+    core.handleCompositionUpdate();
+  }
+  function onCompositionEnd(_e) {
+    const sel = readSelection(root);
+    core.handleCompositionEnd(sel);
+    compositionJustEnded = true;
+    requestAnimationFrame(() => {
+      if (compositionJustEnded) {
+        compositionJustEnded = false;
+        if (root) syncFromDOM();
+      }
+    });
+  }
+  function onSelectionChange() {
+    if (!root) return;
+    const sel = readSelection(root);
+    if (sel) {
+      core.updateSelection(sel);
+    }
+  }
+  let selectionObserver = null;
+  function mount(element) {
+    root = element;
+    root.contentEditable = "true";
+    root.setAttribute("role", "textbox");
+    root.setAttribute("aria-multiline", "true");
+    root.setAttribute("aria-label", "Markdown editor");
+    root.classList.add("owo-editor-root");
+    root.style.whiteSpace = "pre-wrap";
+    root.style.wordBreak = "break-word";
+    root.style.outline = "none";
+    if (!documentChangeCallback) {
+      fullRender(root, core.getDocument());
+    }
+    syncEmptyAttr();
+    root.addEventListener("beforeinput", onBeforeInput);
+    root.addEventListener("input", onInput);
+    root.addEventListener("compositionstart", onCompositionStart);
+    root.addEventListener("compositionupdate", onCompositionUpdate);
+    root.addEventListener("compositionend", onCompositionEnd);
+    root.addEventListener("keydown", onKeyDown);
+    root.addEventListener("paste", onPaste);
+    const onDocSelectionChange = () => onSelectionChange();
+    root.ownerDocument.addEventListener("selectionchange", onDocSelectionChange);
+    selectionObserver = () => {
+      root?.ownerDocument.removeEventListener("selectionchange", onDocSelectionChange);
+    };
+  }
+  function destroy() {
+    if (!root) return;
+    root.removeEventListener("beforeinput", onBeforeInput);
+    root.removeEventListener("input", onInput);
+    root.removeEventListener("compositionstart", onCompositionStart);
+    root.removeEventListener("compositionupdate", onCompositionUpdate);
+    root.removeEventListener("compositionend", onCompositionEnd);
+    root.removeEventListener("keydown", onKeyDown);
+    root.removeEventListener("paste", onPaste);
+    selectionObserver?.();
+    selectionObserver = null;
+    core.destroy();
+    root = null;
+  }
+  function focus() {
+    root?.focus();
+  }
+  function setMarkdown(markdown) {
+    core.setMarkdown(markdown);
+    if (!documentChangeCallback && root) {
+      fullRender(root, core.getDocument());
+      const linearSel = core.getSelection();
+      if (linearSel) restoreSelection(root, linearSel);
+    }
+    syncEmptyAttr();
+  }
+  function replaceMarkdown(markdown, selection) {
+    const oldDoc = core.getDocument();
+    core.replaceMarkdown(markdown, selection);
+    if (!documentChangeCallback && root) {
+      detectAndRenderDirty(root, oldDoc, core.getDocument());
+      restoreSelection(root, selection);
+    }
+    syncEmptyAttr();
+  }
+  function dispatch(command, payload) {
+    const oldDoc = core.getDocument();
+    core.dispatch(command, payload);
+    if (!documentChangeCallback && root) {
+      const newDoc = core.getDocument();
+      if (oldDoc !== newDoc) {
+        if (command === "undo" || command === "redo") {
+          fullRender(root, newDoc);
+        } else {
+          detectAndRenderDirty(root, oldDoc, newDoc);
+        }
+        const linearSel = core.getSelection();
+        if (linearSel) restoreSelection(root, linearSel);
+      }
+    }
+    syncEmptyAttr();
+  }
+  return {
+    mount,
+    destroy,
+    getMarkdown: () => core.getMarkdown(),
+    setMarkdown,
+    replaceMarkdown,
+    getSelection: () => core.getSelection(),
+    getDocument: () => core.getDocument(),
+    focus,
+    dispatch,
+    setIndentMode: (mode) => core.setIndentMode(mode),
+    onChange: (callback) => core.onChange(callback),
+    onSelectionChange: (callback) => core.onSelectionChange(callback),
+    onCompositionStateChange: (callback) => core.onCompositionStateChange(callback),
+    onDocumentChange(callback) {
+      documentChangeCallback = callback;
+      const unsub = core.onDocumentChange(callback);
+      return () => {
+        unsub();
+        if (documentChangeCallback === callback) {
+          documentChangeCallback = null;
+        }
+      };
+    },
+    getCore: () => core
+  };
+}
+function extractTextFromRoot(root) {
+  const parts = [];
+  for (const child of root.childNodes) {
+    if (child.nodeType === Node.ELEMENT_NODE) {
+      const el = child;
+      if (el.hasAttribute("data-owo-block")) {
+        if (parts.length > 0) parts.push("\n");
+        parts.push(el.textContent ?? "");
+      }
+    }
+  }
+  return parts.join("");
+}
+export {
+  createDomAdapter
+};