creo-edit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nik (xnimorz)
+
+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,169 @@
+# creo-edit
+
+A text editor framework, based on [Creo](https://github.com/xnim/creo). Row-based rich-text editing on a controlled `contentEditable`. Mountable inside any framework that gives you a DOM ref (React, Vue, Svelte, Solid) — see [Hosting inside other frameworks](#hosting-inside-other-frameworks).
+
+## Highlights
+
+- **Cursor lives outside the document state** — typing into a block doesn't dirty selection subscribers, and vice versa.
+- **CRDT-friendly row ordering** via base-62 fractional indexing — insert-between is O(log n), no renumber.
+- **Controlled `contentEditable`** — native browser selection and IME, with every `beforeinput` intercepted and translated into a command. The model is the source of truth.
+- **Per-keystroke render cost is O(1) blocks** — block immutability + `shouldUpdate` identity checks make the keyed reconciler skip every untouched block.
+- **Optional virtualization** — only blocks intersecting the viewport are mounted; documents with hundreds of thousands of blocks remain responsive.
+- **First-class mobile support** — native long-press OS menu, native selection handles, IME composition reconciled into a single undo step, `visualViewport`-aware caret-keeping.
+
+## Install
+
+```bash
+bun add creo creo-edit
+```
+
+## Quick start
+
+```ts
+import { createApp, HtmlRender } from "creo";
+import { createEditor } from "creo-edit";
+
+const editor = createEditor({
+  initial: {
+    blocks: [
+      { type: "h1", runs: [{ text: "Hello" }] },
+      { type: "p", runs: [{ text: "Type here." }] },
+    ],
+  },
+});
+
+createApp(
+  () => editor.EditorView(),
+  new HtmlRender(document.querySelector("#app")!),
+).mount();
+```
+
+## Hosting inside other frameworks
+
+The editor renders through Creo's `HtmlRender`, which mounts into any DOM element. Embed it inside a host framework by giving Creo a container element managed by that framework. There is no React/Vue/Svelte wrapper package — you write the ten-line bridge once.
+
+**React**
+
+```tsx
+import { useEffect, useRef } from "react";
+import { createApp, HtmlRender } from "creo";
+import { createEditor } from "creo-edit";
+
+export function CreoEdit() {
+  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    if (!ref.current) return;
+    const editor = createEditor();
+    const app = createApp(
+      () => editor.EditorView(),
+      new HtmlRender(ref.current),
+    ).mount();
+    return () => app.unmount?.();
+  }, []);
+  return <div ref={ref} />;
+}
+```
+
+**Vue 3**
+
+```vue
+<script setup lang="ts">
+import { onMounted, onBeforeUnmount, ref } from "vue";
+import { createApp as creoApp, HtmlRender } from "creo";
+import { createEditor } from "creo-edit";
+
+const host = ref<HTMLElement | null>(null);
+let app: ReturnType<typeof creoApp> | null = null;
+onMounted(() => {
+  const editor = createEditor();
+  app = creoApp(() => editor.EditorView(), new HtmlRender(host.value!)).mount();
+});
+onBeforeUnmount(() => app?.unmount?.());
+</script>
+
+<template>
+  <div ref="host" />
+</template>
+```
+
+**Svelte 5 / Solid / anything with a DOM ref**: same pattern — wait for the container to be mounted, call `createApp(...).mount()`, call `app.unmount()` on teardown. The `editor` handle (`createEditor()` return value) is plain JS; exposing `editor.dispatch`, `editor.toJSON`, `editor.docStore`, etc. from inside a hook / composable is straightforward.
+
+## Editor API
+
+```ts
+type Editor = {
+  docStore: Store<DocState>;
+  selStore: Store<Selection>;
+  dispatch(cmd: Command): void;
+  undo(): void;
+  redo(): void;
+  EditorView: PublicView<EditorViewProps, void>;
+  setDocFromHTML(html: string): void;
+  toJSON(): SerializedDoc;
+  focus(): void;
+  blur(): void;
+};
+```
+
+### Commands
+
+- `insertText`, `deleteBackward`, `deleteForward` — text editing
+- `splitBlock`, `mergeBackward`, `mergeForward` — structural
+- `setBlockType` — promote/demote between paragraph, headings, list items
+- `toggleMark` — bold, italic, underline, strikethrough, code
+- `toggleList`, `indentList`, `outdentList`
+- `insertImage`, `insertTable`
+- `tableInsertRow/Col`, `tableRemoveRow/Col`
+- `moveCursor`
+
+### Default keybindings
+
+| Chord | Action |
+|---|---|
+| `Cmd/Ctrl+B` / `+I` / `+U` | Toggle bold / italic / underline |
+| `Cmd/Ctrl+Shift+S` | Strikethrough |
+| `Cmd/Ctrl+Z` / `+Shift+Z` | Undo / redo |
+| `Cmd/Ctrl+Alt+1..6` | Heading levels |
+| `Cmd/Ctrl+Alt+0` | Paragraph |
+| `Tab` / `Shift+Tab` | List indent / outdent (or table cell nav) |
+| `Enter` / `Backspace` / `Delete` | Split / merge blocks |
+| Arrows / `Home` / `End` | Caret navigation (extend with `Shift`) |
+
+### Virtualization (large documents)
+
+```ts
+const editor = createEditor({
+  initial: { blocks: [...] },
+  virtualized: true,
+  virtualEstimatedHeight: 32,
+});
+```
+
+Only blocks intersecting `[scrollTop − overscan, scrollTop + viewport + overscan]` are mounted, with measured per-block heights stored in a Fenwick tree for O(log n) viewport resolution.
+
+### Image upload
+
+```ts
+const editor = createEditor({
+  uploadImage: async (file) => {
+    const fd = new FormData();
+    fd.append("file", file);
+    const res = await fetch("/upload", { method: "POST", body: fd });
+    return (await res.json()).url;
+  },
+});
+```
+
+Without `uploadImage`, dropped/pasted images use `URL.createObjectURL`.
+
+### Mobile
+
+`creo-edit` ships first-class mobile support. The editor root is a `contentEditable`, so the OS long-press menu, native selection handles, IME composition, and autocorrect work out of the box. `visualViewport` tracking exposes `--creo-vv-height` and `--creo-vv-top` as CSS custom properties so host pages can position floating UI above the soft keyboard, and scrolls the caret into the upper third of visible space when the keyboard opens.
+
+## Architecture
+
+See `AGENTS.md` in the repo root for engine-level notes. The editor is a pure consumer of Creo's public API — `view`, `use`, `store`, primitive functions — and uses raw DOM listeners only for events Creo's event map doesn't expose (composition, drag/drop, clipboard, visualViewport).
+
+## License
+
+MIT

package/dist/clipboard/drop.d.ts

@@ -0,0 +1,17 @@
+import type { Store } from "creo";
+import { type UploadFn } from "../commands/imageCommands";
+import type { DocState, Selection } from "../model/types";
+export type DropStores = {
+    docStore: Store<DocState>;
+    selStore: Store<Selection>;
+};
+export type DropHandle = {
+    destroy: () => void;
+};
+/**
+ * Wire dragover + drop on the editor root so dragged image files become
+ * image blocks. We only swallow the drop when at least one image file is
+ * present; other drops fall through to the browser's default behaviour
+ * (so dragging text from elsewhere keeps working).
+ */
+export declare function attachDrop(root: HTMLElement, stores: DropStores, upload?: UploadFn): DropHandle;

package/dist/clipboard/htmlParser.d.ts

@@ -0,0 +1,18 @@
+import type { BlockSpec } from "../model/types";
+/**
+ * Parse a fragment of HTML into a sanitized list of BlockSpec.
+ *
+ * Sanitization rules:
+ *  - `<script>`, `<style>`, `<link>`, `<meta>` content is dropped entirely.
+ *  - All `on*` attributes are stripped.
+ *  - `javascript:` URLs become "#".
+ *  - Unknown elements become inline (their text content is preserved, marks
+ *    of any ancestor mark elements still apply).
+ *  - Block elements outside our model (article, section, etc.) become
+ *    paragraphs (recursing into their children when those are themselves
+ *    block-level).
+ *
+ * Falls back to a single paragraph if no block-level structure is present.
+ */
+export declare function parseHTML(html: string): BlockSpec[];
+export declare function parsePlainText(text: string): BlockSpec[];

package/dist/clipboard/htmlSerializer.d.ts

@@ -0,0 +1,9 @@
+import type { DocState, Selection } from "../model/types";
+/** Whole-doc serialization (used by toJSON-ish helpers and copy-all). */
+export declare function docToHtml(doc: DocState): string;
+export declare function docToPlain(doc: DocState): string;
+export type ClipboardPayload = {
+    html: string;
+    plain: string;
+};
+export declare function selectionToClipboard(doc: DocState, sel: Selection): ClipboardPayload;

package/dist/commands/imageCommands.d.ts

@@ -0,0 +1,32 @@
+import type { Store } from "creo";
+import type { DocState, Selection } from "../model/types";
+export type Stores = {
+    docStore: Store<DocState>;
+    selStore: Store<Selection>;
+};
+export type UploadFn = (file: File) => Promise<string>;
+/**
+ * Pick an image source for a File. If `upload` is provided, await its URL;
+ * otherwise fall back to `URL.createObjectURL`.
+ */
+export declare function fileToImageSrc(file: File, upload?: UploadFn): Promise<string>;
+/**
+ * Drop / paste a single File into the editor as an image block. Async
+ * (must await an upload when configured).
+ */
+export declare function insertImageFile(stores: Stores, file: File, upload?: UploadFn): Promise<boolean>;
+/**
+ * Process a FileList (from paste or drop). Each image becomes its own block;
+ * non-image files are ignored.
+ */
+export declare function insertImageFiles(stores: Stores, files: FileList | File[], upload?: UploadFn): Promise<boolean>;
+/**
+ * Delete the atomic block currently under the caret. Backspace / Delete
+ * routes here whenever the caret sits on any atomic block (image, calendar,
+ * or any plugin block flagged `isAtomic`). The caret lands at the start of
+ * whatever block survives in that slot — preferring the next sibling, then
+ * the previous, then the first remaining block.
+ */
+export declare function deleteSelectedAtomic(stores: Stores): boolean;
+/** Backwards-compatible alias — img used to be the only atomic block. */
+export declare const deleteSelectedImage: typeof deleteSelectedAtomic;

package/dist/commands/insertCommands.d.ts

@@ -0,0 +1,33 @@
+import type { Store } from "creo";
+import type { BlockSpec, DocState, Selection } from "../model/types";
+export type Stores = {
+    docStore: Store<DocState>;
+    selStore: Store<Selection>;
+};
+/**
+ * Insert a list of pre-parsed blocks at the current caret. If the selection
+ * is a range, it is collapsed first.
+ *
+ * Splice rules (matches every consumer rich-text editor I'm aware of):
+ *  - Single text-bearing block: inline-merge into the current block.
+ *  - Multiple blocks: split the current block at the caret; the first
+ *    pasted block's runs join the LEFT half, the last pasted block's runs
+ *    are followed by the RIGHT half (in a new block of the last one's
+ *    type), and any blocks in between are inserted as new blocks.
+ *  - Non-text blocks (img / table): always become a separate block, with
+ *    the surrounding paragraph split if needed.
+ */
+export declare function insertBlocks(stores: Stores, blocks: BlockSpec[]): boolean;
+export declare function insertImage(stores: Stores, payload: {
+    src: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+}): boolean;
+export declare function insertColumns(stores: Stores, payload: {
+    cols: number;
+}): boolean;
+export declare function insertTable(stores: Stores, payload: {
+    rows: number;
+    cols: number;
+}): boolean;

package/dist/commands/listCommands.d.ts

@@ -0,0 +1,19 @@
+import type { Store } from "creo";
+import type { DocState, Selection } from "../model/types";
+export type Stores = {
+    docStore: Store<DocState>;
+    selStore: Store<Selection>;
+};
+/**
+ * Toggle whether the touched blocks are list items of the given `ordered`
+ * kind.
+ *  - If every touched text block is already a list item with that ordering,
+ *    convert them back to paragraphs (and reset depth to 0).
+ *  - Otherwise convert them to `li ordered=...` (preserving depth where
+ *    possible, defaulting to 0).
+ */
+export declare function toggleList({ docStore, selStore }: Stores, ordered: boolean): boolean;
+/** Tab — increase list depth (max 3). No-op for non-list blocks. */
+export declare function indentList({ docStore, selStore }: Stores): boolean;
+/** Shift+Tab — decrease list depth. At depth 0, convert back to paragraph. */
+export declare function outdentList({ docStore, selStore }: Stores): boolean;

package/dist/commands/markCommands.d.ts

@@ -0,0 +1,21 @@
+import type { Store } from "creo";
+import type { DocState, Mark, Selection } from "../model/types";
+export type Stores = {
+    docStore: Store<DocState>;
+    selStore: Store<Selection>;
+};
+/**
+ * Toggle a mark over the current selection.
+ *
+ * Behaviour:
+ *  - Caret-only: no-op (real editors track a "pending mark" that biases the
+ *    next character; we don't ship that in M6 to keep the API minimal).
+ *  - Single-block range: if every character in [start, end) already has the
+ *    mark, REMOVE it; otherwise ADD it everywhere in the range.
+ *  - Cross-block range: same rule applied per-block to the slice that
+ *    intersects the range.
+ *
+ * Run merging happens via `normalizeRuns`, so toggling repeatedly never
+ * fragments runs unbounded.
+ */
+export declare function toggleMark({ docStore, selStore }: Stores, mark: Mark): boolean;

package/dist/commands/navigationCommands.d.ts

@@ -0,0 +1,27 @@
+import type { Store } from "creo";
+import { blockAbove, blockBelow, endOfBlock, homeOfBlock, nextAnchor, nextWord, prevAnchor, prevWord } from "../controller/navigation";
+import type { Anchor, DocState, Selection } from "../model/types";
+export type NavStores = {
+    docStore: Store<DocState>;
+    selStore: Store<Selection>;
+};
+export type AnchorStep = (doc: DocState, a: Anchor) => Anchor;
+/**
+ * Move the cursor by applying `step` to the current focus side.
+ *  - `extend === false` → collapse to the new anchor.
+ *  - `extend === true`  → keep the original anchor, move the focus.
+ */
+export declare function moveBy({ docStore, selStore }: NavStores, step: AnchorStep, extend: boolean): void;
+export declare function moveTo({ selStore }: NavStores, anchor: Anchor, extend: boolean): void;
+export declare const STEP: {
+    next: typeof nextAnchor;
+    prev: typeof prevAnchor;
+    nextWord: typeof nextWord;
+    prevWord: typeof prevWord;
+    up: typeof blockAbove;
+    down: typeof blockBelow;
+    home: typeof homeOfBlock;
+    end: typeof endOfBlock;
+    docHome: (doc: DocState, _a: Anchor) => Anchor;
+    docEnd: (doc: DocState, _a: Anchor) => Anchor;
+};

package/dist/commands/structuralCommands.d.ts

@@ -0,0 +1,22 @@
+import type { Store } from "creo";
+import type { BlockType, DocState, Selection } from "../model/types";
+export type Stores = {
+    docStore: Store<DocState>;
+    selStore: Store<Selection>;
+};
+/**
+ * Split the current block at the caret. The right half becomes a NEW block
+ * placed immediately after the current one. Headings split into a paragraph
+ * (the convention every consumer-grade editor uses — pressing Enter at the
+ * end of a heading shouldn't create another heading by default). List items
+ * split into another list item of the same kind & depth.
+ */
+export declare function splitBlock({ docStore, selStore }: Stores): boolean;
+export declare function mergeBackward({ docStore, selStore }: Stores): boolean;
+export declare function mergeForward({ docStore, selStore }: Stores): boolean;
+export type SetBlockTypePayload = {
+    type: BlockType;
+    ordered?: boolean;
+    depth?: 0 | 1 | 2 | 3;
+};
+export declare function setBlockType({ docStore, selStore }: Stores, payload: SetBlockTypePayload): boolean;

package/dist/commands/textCommands.d.ts

@@ -0,0 +1,18 @@
+import type { DocState, Selection } from "../model/types";
+import type { Store } from "creo";
+export type Stores = {
+    docStore: Store<DocState>;
+    selStore: Store<Selection>;
+};
+/**
+ * Insert plain text at the current selection. If the selection is a range,
+ * the range is deleted first and the text is inserted at the start.
+ *
+ * Cross-block ranges are deferred to mergeBackward (M5) — this only handles
+ * the single-cell / single-block case.
+ */
+export declare function insertText({ docStore, selStore }: Stores, text: string): boolean;
+/** Delete one character backward, or collapse a range. */
+export declare function deleteBackward({ docStore, selStore }: Stores): boolean;
+/** Delete one character forward, or collapse a range. */
+export declare function deleteForward({ docStore, selStore }: Stores): boolean;

package/dist/controller/history.d.ts

@@ -0,0 +1,31 @@
+import type { Store } from "creo";
+import type { DocState, Selection } from "../model/types";
+/**
+ * Snapshot-based undo/redo. We don't synthesize inverse commands — we just
+ * stash the previous (doc, sel) before each mutation and let undo restore
+ * it.
+ *
+ * Coalescing rule: consecutive `insertText` / `deleteBackward` ops within
+ * 500ms collapse into a single undo entry. This matches Notion / Google
+ * Docs UX — typing a sentence then hitting Cmd+Z removes the whole sentence,
+ * not the last character.
+ */
+export type HistoryEntry = {
+    doc: DocState;
+    sel: Selection;
+    tag: string;
+    ts: number;
+};
+export type HistoryStores = {
+    docStore: Store<DocState>;
+    selStore: Store<Selection>;
+};
+export declare const COALESCE_MS = 500;
+export declare const HISTORY_CAP = 200;
+export declare function createHistory(stores: HistoryStores): {
+    record: (tag: string) => void;
+    undo: () => boolean;
+    redo: () => boolean;
+    reset: () => void;
+};
+export type History = ReturnType<typeof createHistory>;

package/dist/controller/navigation.d.ts

@@ -0,0 +1,18 @@
+import type { Anchor, DocState } from "../model/types";
+/**
+ * Move one character to the right. Crosses block boundaries: from the end of
+ * block i to the start of block i+1. At end-of-doc, returns the same anchor.
+ */
+export declare function nextAnchor(doc: DocState, a: Anchor): Anchor;
+/**
+ * Move one character to the left. Crosses block boundaries the same way.
+ */
+export declare function prevAnchor(doc: DocState, a: Anchor): Anchor;
+export declare function homeOfBlock(doc: DocState, a: Anchor): Anchor;
+export declare function endOfBlock(doc: DocState, a: Anchor): Anchor;
+export declare function homeOfDoc(doc: DocState): Anchor;
+export declare function endOfDocAnchor(doc: DocState): Anchor;
+export declare function blockAbove(doc: DocState, a: Anchor): Anchor;
+export declare function blockBelow(doc: DocState, a: Anchor): Anchor;
+export declare function nextWord(doc: DocState, a: Anchor): Anchor;
+export declare function prevWord(doc: DocState, a: Anchor): Anchor;

package/dist/controller/selection.d.ts

@@ -0,0 +1,25 @@
+import type { Anchor, BlockId, DocState, Selection } from "../model/types";
+export declare function caretAt(blockId: BlockId, offset: number): Anchor;
+export declare function caret(at: Anchor): Selection;
+export declare function range(anchor: Anchor, focus: Anchor): Selection;
+export declare function anchorOffset(a: Anchor): number;
+export declare function withCharOffset(a: Anchor, offset: number): Anchor;
+/** Returns true when the selection is a collapsed caret. */
+export declare function isCaret(s: Selection): s is {
+    kind: "caret";
+    at: Anchor;
+};
+/** Same anchor & focus → effectively a caret. */
+export declare function selectionStart(s: Selection): Anchor;
+export declare function selectionEnd(s: Selection): Anchor;
+/** Compares two anchors that point into the same doc. Returns -1/0/+1. */
+export declare function compareAnchors(doc: DocState, a: Anchor, b: Anchor): number;
+/** Anchor in document-order start..end ascending. */
+export declare function orderedRange(doc: DocState, s: Selection): {
+    start: Anchor;
+    end: Anchor;
+};
+/** Clamp an anchor so it points at a valid offset inside its block. */
+export declare function clampAnchor(doc: DocState, a: Anchor): Anchor;
+export declare function clampSelection(doc: DocState, s: Selection): Selection;
+export declare function endOfDoc(doc: DocState): Anchor;

package/dist/controller/wordBoundary.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Word-boundary helpers — compute "next/previous word" offsets within a
+ * single string. Used by Cmd/Ctrl+Arrow navigation and double-click word
+ * selection.
+ *
+ * Definition of a word — same as the OS conventions every consumer editor
+ * follows:
+ *   - A word run is one-or-more "word chars" (Unicode letters + digits +
+ *     underscore + apostrophes embedded inside a run).
+ *   - Whitespace and punctuation are treated as separators.
+ *   - "Next word from here" = scan forward over (separators), then over
+ *     (word chars), and land on the first non-word-char.
+ *   - "Prev word from here" = scan backward over (separators), then over
+ *     (word chars), and land on the first word-char.
+ */
+/** Offset of the start of the next word at or after `offset` in `text`. */
+export declare function nextWordOffset(text: string, offset: number): number;
+/** Offset of the start of the previous word strictly before `offset`. */
+export declare function prevWordOffset(text: string, offset: number): number;
+/**
+ * Find the word that contains `offset` in `text`. Returns [start, end).
+ * If `offset` is on a non-word char, returns [offset, offset+1) so callers
+ * still get a usable selection (single char).
+ */
+export declare function wordRangeAt(text: string, offset: number): [number, number];