@texuli/core 0.1.0-next.0 → 0.1.0-next.1

package/README.md

@@ -18,6 +18,7 @@ rest.
 | Controllable state | `createControllableState` | [core-controllable](docs/core-controllable.md) |
 | Direction and locale | `directionOf`, `inlineSideToPhysical`, `createCollator`, `compareLocale`, `resolveMessages` | [core-dir-locale](docs/core-dir-locale.md) |
 | Dismiss | `bindDismissLayer`, `isPointerOutside`, `isFocusOutside`, `createDismissOutsideEvent`, `createOpenGestureGuard` | [core-dismiss](docs/core-dismiss.md) |
+| Editor model | `loadEditorDocument`, `normalizeDocument`, `validateEditorDocument`, `caret`, `clampSelection`, `inlineToTree`; transforms (`insertText`, `splitBlock`, `deleteBackward`, `toggleMark`, `setLink`, `replaceSelection`, `applyInputRules`…), `editorHistoryReducer`, `createEditorKeymap`, `fromMarkdown`/`toMarkdown` (subpaths `@texuli/core/editor-model`, `editor-transforms`, `editor-history`, `editor-keymap`, `editor-markdown`; not in the root barrel) | [core-editor](docs/core-editor.md) |
 | Environment | `isBrowser`, `getOwnerDocument`, `getOwnerWindow`, `listen`, `matchesMedia`, `requestFrame` | [core-env](docs/core-env.md) |
 | Focus scope | `createFocusScope` | [core-focus-scope](docs/core-focus-scope.md) |
 | Form bridge | `createFormBridge` | [core-form-bridge](docs/core-form-bridge.md) |
@@ -37,6 +38,13 @@ rest.
 | URL policy (links) | `safeHref`, `type HrefTrust` | [core-url-policy](docs/core-url-policy.md) |
 | URL policy (media) | `safeImageSrc`, `safeImageSrcset`, `safeMediaSrc`, `MAX_DATA_IMAGE_BYTES` | [core-url-policy](docs/core-url-policy.md) |
 
+The editor texels are not in the root barrel: the barrel measures 22.63 of
+its 24 KiB budget. `pnpm size --filter core/editor` (2026-10-25) measures
+`editor-history` at 754 B and `editor-keymap` at 2.49 KiB, both within the 4
+KiB per-texel default. `editor-markdown` (7.03 KiB), `editor-model` (7.81
+KiB) and `editor-transforms` (10.36 KiB) are over it, so their budget rows
+are pending with the owner.
+
 The tables above name the headline exports per texel, not the full surface:
 read `src/index.ts` (and the per-area `index.ts`) for every exported symbol
 and type. The threat model behind the URL policy lives in
@@ -100,7 +108,7 @@ packages/core/
 ├── docs/            one contract doc per texel (core-*.md) + overlay-engine.md
 ├── src/index.ts     the public barrel (only what is exported here is public)
 ├── src/<area>/      one directory per texel (announcer, roving, layer-stack, …)
-└── tests/           22 test files, one or more per texel, including hostile
+└── tests/           26 test files, one or more per texel, including hostile
                      inputs for every policy that guards a sink
 ```
 

package/dist/editor/document.d.ts

@@ -0,0 +1,65 @@
+import { type EditorBlock, type EditorBlockId, type EditorDocument, type EditorInline, type EditorIssue, type EditorList, type EditorListItem, type EditorParagraph, type EditorQuote, type EditorTextBlock } from './types.js';
+/** A source of fresh block ids. */
+export type EditorIdSource = () => EditorBlockId;
+/** The default id source: unique for the page's lifetime. */
+export declare const nextEditorId: EditorIdSource;
+/** A deterministic id source (`b1`, `b2`…), for tests and server rendering. */
+export declare function createEditorIds(prefix?: string): EditorIdSource;
+export declare const LANG_PATTERN: RegExp;
+export declare const paragraph: (content?: readonly EditorInline[], id?: EditorBlockId) => EditorParagraph;
+/** A document with one empty paragraph. */
+export declare const emptyEditorDocument: (newId?: EditorIdSource) => EditorDocument;
+export declare const isTextBlock: (block: EditorBlock) => block is EditorTextBlock;
+export declare const isVoidBlock: (block: EditorBlock) => boolean;
+/** Length of a text block in UTF-16 code units (a break counts 1). */
+export declare const blockLength: (block: EditorTextBlock) => number;
+/** Text of a text block; a break is `\n`. */
+export declare const blockText: (block: EditorTextBlock) => string;
+/** What contains a block, outermost first. */
+export type EditorAncestor = {
+    kind: 'quote';
+    quote: EditorQuote;
+} | {
+    kind: 'item';
+    list: EditorList;
+    item: EditorListItem;
+    itemIndex: number;
+};
+export interface EditorLocation {
+    block: EditorBlock;
+    /** Index among `siblings`. */
+    index: number;
+    siblings: readonly EditorBlock[];
+    ancestors: readonly EditorAncestor[];
+}
+/** Where block `id` sits in the tree, or `null`. */
+export declare function locateBlock(doc: EditorDocument, id: EditorBlockId): EditorLocation | null;
+/** The leaves (text and void blocks) in document order, with their nesting depth. */
+export declare function editorLeaves(doc: EditorDocument): {
+    block: EditorBlock;
+    depth: number;
+}[];
+/** Replace block `id` with `replace(block)` (any number of blocks). Unchanged parts keep identity. */
+export declare function replaceBlock(doc: EditorDocument, id: EditorBlockId, replace: (block: EditorBlock) => readonly EditorBlock[]): EditorDocument;
+/** Replace list item `id` with `replace(item, list)` (any number of items). */
+export declare function replaceItem(doc: EditorDocument, id: EditorBlockId, replace: (item: EditorListItem, list: EditorList) => readonly EditorListItem[]): EditorDocument;
+/** Remove every block whose id is in `ids`, then prune emptied containers. */
+export declare function removeBlocks(doc: EditorDocument, ids: ReadonlySet<EditorBlockId>, newId?: EditorIdSource): EditorDocument;
+/**
+ * The model invariants, repaired: inline content canonical, empty containers
+ * removed, list items starting with a paragraph, `checked` only on todo items,
+ * `start` only on ordered lists, at least one block. Unchanged blocks keep
+ * their identity (structural sharing).
+ */
+export declare function normalizeDocument(doc: EditorDocument, newId?: EditorIdSource): EditorDocument;
+/** The plain text of a document: blocks joined by blank lines, breaks as `\n`. */
+export declare function editorPlainText(doc: EditorDocument): string;
+/** Characters of text in a document. */
+export declare const editorCharCount: (doc: EditorDocument) => number;
+/** Blocks in a document, containers and list items included. */
+export declare function editorBlockCount(blocks: readonly EditorBlock[]): number;
+/**
+ * Every broken invariant of `doc`, or `[]` for a valid document. Never throws,
+ * whatever the input; transforms are tested against it.
+ */
+export declare function validateEditorDocument(doc: unknown): EditorIssue[];

package/dist/editor/document.js

@@ -0,0 +1,394 @@
+import { cleanText, inlineLength, inlineText, markKey, normalizeInline, sortMarks, } from "./inline.js";
+import { EDITOR_LIMITS, } from "./types.js";
+let counter = 0;
+/** The default id source: unique for the page's lifetime. */
+export const nextEditorId = () => `tx-ed-${(++counter).toString(36)}`;
+/** A deterministic id source (`b1`, `b2`…), for tests and server rendering. */
+export function createEditorIds(prefix = 'b') {
+    let n = 0;
+    return () => `${prefix}${++n}`;
+}
+export const LANG_PATTERN = /^[a-z][a-z0-9+-]{0,31}$/;
+export const paragraph = (content = [], id = nextEditorId()) => ({ id, type: 'paragraph', content });
+/** A document with one empty paragraph. */
+export const emptyEditorDocument = (newId = nextEditorId) => ({
+    version: 1,
+    blocks: [paragraph([], newId())],
+});
+export const isTextBlock = (block) => block.type === 'paragraph' || block.type === 'heading' || block.type === 'code';
+export const isVoidBlock = (block) => block.type === 'divider' || block.type === 'media';
+/** Length of a text block in UTF-16 code units (a break counts 1). */
+export const blockLength = (block) => block.type === 'code' ? block.text.length : inlineLength(block.content);
+/** Text of a text block; a break is `\n`. */
+export const blockText = (block) => block.type === 'code' ? block.text : inlineText(block.content);
+/** Where block `id` sits in the tree, or `null`. */
+export function locateBlock(doc, id) {
+    const visit = (blocks, ancestors) => {
+        for (let index = 0; index < blocks.length; index += 1) {
+            const block = blocks[index];
+            if (block.id === id)
+                return { block, index, siblings: blocks, ancestors };
+            if (block.type === 'quote') {
+                const found = visit(block.blocks, [...ancestors, { kind: 'quote', quote: block }]);
+                if (found)
+                    return found;
+            }
+            else if (block.type === 'list') {
+                for (let itemIndex = 0; itemIndex < block.items.length; itemIndex += 1) {
+                    const item = block.items[itemIndex];
+                    const found = visit(item.blocks, [
+                        ...ancestors,
+                        { kind: 'item', list: block, item, itemIndex },
+                    ]);
+                    if (found)
+                        return found;
+                }
+            }
+        }
+        return null;
+    };
+    return visit(doc.blocks, []);
+}
+/** The leaves (text and void blocks) in document order, with their nesting depth. */
+export function editorLeaves(doc) {
+    const out = [];
+    const visit = (blocks, depth) => {
+        for (const block of blocks) {
+            if (block.type === 'quote')
+                visit(block.blocks, depth + 1);
+            else if (block.type === 'list')
+                for (const item of block.items)
+                    visit(item.blocks, depth + 1);
+            else
+                out.push({ block, depth });
+        }
+    };
+    visit(doc.blocks, 0);
+    return out;
+}
+const replaceAt = (list, index, items) => [
+    ...list.slice(0, index),
+    ...items,
+    ...list.slice(index + 1),
+];
+function rewrite(blocks, id, how) {
+    for (let i = 0; i < blocks.length; i += 1) {
+        const block = blocks[i];
+        if (block.id === id && how.block)
+            return replaceAt(blocks, i, how.block(block));
+        if (block.type === 'quote') {
+            const inner = rewrite(block.blocks, id, how);
+            if (inner)
+                return replaceAt(blocks, i, [{ ...block, blocks: inner }]);
+        }
+        else if (block.type === 'list') {
+            for (let j = 0; j < block.items.length; j += 1) {
+                const item = block.items[j];
+                if (item.id === id && how.item) {
+                    return replaceAt(blocks, i, [
+                        { ...block, items: replaceAt(block.items, j, how.item(item, block)) },
+                    ]);
+                }
+                const inner = rewrite(item.blocks, id, how);
+                if (inner) {
+                    const items = replaceAt(block.items, j, [{ ...item, blocks: inner }]);
+                    return replaceAt(blocks, i, [{ ...block, items }]);
+                }
+            }
+        }
+    }
+    return null;
+}
+/** Replace block `id` with `replace(block)` (any number of blocks). Unchanged parts keep identity. */
+export function replaceBlock(doc, id, replace) {
+    const blocks = rewrite(doc.blocks, id, { block: replace });
+    return blocks ? { ...doc, blocks } : doc;
+}
+/** Replace list item `id` with `replace(item, list)` (any number of items). */
+export function replaceItem(doc, id, replace) {
+    const blocks = rewrite(doc.blocks, id, { item: replace });
+    return blocks ? { ...doc, blocks } : doc;
+}
+/** Remove every block whose id is in `ids`, then prune emptied containers. */
+export function removeBlocks(doc, ids, newId = nextEditorId) {
+    const strip = (blocks) => {
+        let changed = false;
+        const out = [];
+        for (const block of blocks) {
+            if (ids.has(block.id)) {
+                changed = true;
+                continue;
+            }
+            let next = block;
+            if (block.type === 'quote') {
+                const inner = strip(block.blocks);
+                if (inner !== block.blocks)
+                    next = { ...block, blocks: inner };
+            }
+            else if (block.type === 'list') {
+                let itemsChanged = false;
+                const items = block.items.map((item) => {
+                    const inner = strip(item.blocks);
+                    if (inner === item.blocks)
+                        return item;
+                    itemsChanged = true;
+                    return { ...item, blocks: inner };
+                });
+                if (itemsChanged)
+                    next = { ...block, items };
+            }
+            if (next !== block)
+                changed = true;
+            out.push(next);
+        }
+        return changed ? out : blocks;
+    };
+    return normalizeDocument({ ...doc, blocks: strip(doc.blocks) }, newId);
+}
+/**
+ * The model invariants, repaired: inline content canonical, empty containers
+ * removed, list items starting with a paragraph, `checked` only on todo items,
+ * `start` only on ordered lists, at least one block. Unchanged blocks keep
+ * their identity (structural sharing).
+ */
+export function normalizeDocument(doc, newId = nextEditorId) {
+    const blocks = normalizeBlocks(doc.blocks, newId);
+    if (blocks.length === 0)
+        return { version: 1, blocks: [paragraph([], newId())] };
+    return blocks === doc.blocks && doc.version === 1 ? doc : { version: 1, blocks };
+}
+function normalizeBlocks(blocks, newId) {
+    let changed = false;
+    const out = [];
+    for (const block of blocks) {
+        const next = normalizeBlock(block, newId);
+        if (next !== block)
+            changed = true;
+        if (next)
+            out.push(next);
+    }
+    return changed ? out : blocks;
+}
+function normalizeBlock(block, newId) {
+    switch (block.type) {
+        case 'paragraph':
+        case 'heading': {
+            const content = normalizeInline(block.content);
+            return content === block.content ? block : { ...block, content };
+        }
+        case 'code':
+            return block.lang === undefined || LANG_PATTERN.test(block.lang)
+                ? block
+                : { id: block.id, type: 'code', text: block.text };
+        case 'quote': {
+            const inner = normalizeBlocks(block.blocks, newId);
+            if (inner.length === 0)
+                return null;
+            return inner === block.blocks ? block : { ...block, blocks: inner };
+        }
+        case 'list': {
+            let changed = false;
+            const items = [];
+            for (const item of block.items) {
+                const next = normalizeItem(item, block.kind, newId);
+                if (next !== item)
+                    changed = true;
+                if (next)
+                    items.push(next);
+            }
+            if (items.length === 0)
+                return null;
+            const start = block.kind === 'ordered' ? block.start : undefined;
+            const startOk = start === undefined || (Number.isInteger(start) && start >= 0);
+            if (!changed && startOk && start === block.start && start !== 1)
+                return block;
+            const list = { id: block.id, type: 'list', kind: block.kind, items };
+            if (startOk && start !== undefined && start !== 1)
+                list.start = start;
+            return list;
+        }
+        default:
+            return block;
+    }
+}
+function normalizeItem(item, kind, newId) {
+    let blocks = normalizeBlocks(item.blocks, newId);
+    if (blocks.length === 0)
+        return null;
+    const first = blocks[0];
+    if (first.type === 'heading')
+        blocks = [paragraph(first.content, first.id), ...blocks.slice(1)];
+    else if (first.type !== 'paragraph')
+        blocks = [paragraph([], newId()), ...blocks];
+    const checked = kind === 'todo' ? item.checked === true : undefined;
+    if (blocks === item.blocks && checked === item.checked)
+        return item;
+    return checked === undefined ? { id: item.id, blocks } : { id: item.id, checked, blocks };
+}
+/** The plain text of a document: blocks joined by blank lines, breaks as `\n`. */
+export function editorPlainText(doc) {
+    return editorLeaves(doc)
+        .map(({ block }) => isTextBlock(block) ? blockText(block) : block.type === 'media' ? block.alt : '')
+        .filter(Boolean)
+        .join('\n\n');
+}
+/** Characters of text in a document. */
+export const editorCharCount = (doc) => editorLeaves(doc).reduce((sum, { block }) => sum + (isTextBlock(block) ? blockLength(block) : 0), 0);
+/** Blocks in a document, containers and list items included. */
+export function editorBlockCount(blocks) {
+    let count = 0;
+    for (const block of blocks) {
+        count += 1;
+        if (block.type === 'quote')
+            count += editorBlockCount(block.blocks);
+        else if (block.type === 'list')
+            for (const item of block.items)
+                count += 1 + editorBlockCount(item.blocks);
+    }
+    return count;
+}
+const issue = (code, message, block) => block === undefined ? { code, message } : { code, message, block };
+/**
+ * Every broken invariant of `doc`, or `[]` for a valid document. Never throws,
+ * whatever the input; transforms are tested against it.
+ */
+export function validateEditorDocument(doc) {
+    const issues = [];
+    const record = doc;
+    if (!record || typeof record !== 'object' || !Array.isArray(record.blocks)) {
+        return [issue('invalid-shape', 'A document is { version: 1, blocks: [...] }.')];
+    }
+    if (record.version !== 1)
+        issues.push(issue('version-unsupported', 'Only version 1 is known.'));
+    if (record.blocks.length === 0)
+        issues.push(issue('invalid-shape', 'A document has at least one block.'));
+    const ids = new Set();
+    let chars = 0;
+    const seen = (id) => {
+        if (typeof id !== 'string' || id === '') {
+            issues.push(issue('invalid-shape', 'Every block and item has a non-empty string id.'));
+            return false;
+        }
+        if (ids.has(id))
+            issues.push(issue('duplicate-id', `Id "${id}" is used twice.`, id));
+        ids.add(id);
+        return true;
+    };
+    const text = (value, id, keep) => {
+        if (typeof value !== 'string') {
+            issues.push(issue('invalid-shape', 'Text must be a string.', id));
+            return;
+        }
+        chars += value.length;
+        if (cleanText(value, keep).text !== value) {
+            issues.push(issue('characters-stripped', 'Text holds characters the model never stores.', id));
+        }
+    };
+    const inline = (content, id) => {
+        if (!Array.isArray(content)) {
+            issues.push(issue('invalid-shape', 'Inline content must be an array.', id));
+            return;
+        }
+        for (const node of content) {
+            if (node?.type === 'break') {
+                chars += 1;
+                continue;
+            }
+            if (node?.type !== 'text' || !Array.isArray(node.marks)) {
+                issues.push(issue('invalid-shape', 'Inline nodes are text runs or breaks.', id));
+                return;
+            }
+            text(node.text, id, '');
+            for (const mark of node.marks) {
+                if (mark?.type === 'link' && (typeof mark.href !== 'string' || mark.href === '')) {
+                    issues.push(issue('invalid-shape', 'A link mark has an href.', id));
+                }
+                else if (!['link', 'strong', 'em', 'strike', 'code'].includes(mark?.type)) {
+                    issues.push(issue('unknown-mark', `Unknown mark "${String(mark?.type)}".`, id));
+                }
+            }
+            if (sortMarks(node.marks) !== node.marks ||
+                new Set(node.marks.map(markKey)).size !== node.marks.length) {
+                issues.push(issue('not-normalized', 'Marks are unique and in canonical order.', id));
+            }
+        }
+        if (normalizeInline(content) !== content) {
+            issues.push(issue('not-normalized', 'Runs are non-empty and neighbors differ in marks.', id));
+        }
+    };
+    const visit = (blocks, depth) => {
+        if (!Array.isArray(blocks)) {
+            issues.push(issue('invalid-shape', 'Blocks must be an array.'));
+            return;
+        }
+        for (const raw of blocks) {
+            const block = raw;
+            if (!block || typeof block !== 'object' || !seen(block.id))
+                continue;
+            const id = block.id;
+            switch (block.type) {
+                case 'paragraph':
+                    inline(block.content, id);
+                    break;
+                case 'heading':
+                    if (![1, 2, 3, 4].includes(block.level))
+                        issues.push(issue('invalid-shape', 'Heading levels are 1 to 4.', id));
+                    inline(block.content, id);
+                    break;
+                case 'code':
+                    text(block.text, id, '\n\t');
+                    if (block.lang !== undefined && !LANG_PATTERN.test(block.lang)) {
+                        issues.push(issue('invalid-shape', 'A code language is a short lowercase name.', id));
+                    }
+                    break;
+                case 'quote':
+                case 'list': {
+                    if (depth >= EDITOR_LIMITS.depth)
+                        issues.push(issue('depth-capped', 'Lists and quotes nest at most 4 levels.', id));
+                    if (block.type === 'quote') {
+                        if (!Array.isArray(block.blocks) || block.blocks.length === 0) {
+                            issues.push(issue('invalid-shape', 'A quote holds blocks.', id));
+                        }
+                        visit(block.blocks, depth + 1);
+                        break;
+                    }
+                    if (!['bullet', 'ordered', 'todo'].includes(block.kind))
+                        issues.push(issue('invalid-shape', 'Unknown list kind.', id));
+                    if (block.start !== undefined && block.kind !== 'ordered')
+                        issues.push(issue('not-normalized', 'Only ordered lists have a start.', id));
+                    if (!Array.isArray(block.items) || block.items.length === 0) {
+                        issues.push(issue('invalid-shape', 'A list holds items.', id));
+                        break;
+                    }
+                    for (const item of block.items) {
+                        if (!item || !seen(item.id))
+                            continue;
+                        if ((block.kind === 'todo') !== (typeof item.checked === 'boolean')) {
+                            issues.push(issue('not-normalized', 'Todo items, and only they, are checked or not.', item.id));
+                        }
+                        if (!Array.isArray(item.blocks) || item.blocks[0]?.type !== 'paragraph') {
+                            issues.push(issue('invalid-shape', 'A list item starts with a paragraph.', item.id));
+                        }
+                        visit(item.blocks, depth + 1);
+                    }
+                    break;
+                }
+                case 'divider':
+                    break;
+                case 'media':
+                    if (typeof block.ref !== 'string' || block.ref === '')
+                        issues.push(issue('invalid-shape', 'Media has a ref.', id));
+                    text(block.alt, id, '');
+                    break;
+                default:
+                    issues.push(issue('unknown-node', `Unknown block type "${String(block.type)}".`, id));
+            }
+        }
+    };
+    visit(record.blocks, 0);
+    if (ids.size > EDITOR_LIMITS.blocks)
+        issues.push(issue('blocks-capped', 'Too many blocks.'));
+    if (chars > EDITOR_LIMITS.chars)
+        issues.push(issue('text-truncated', 'Too much text.'));
+    return issues;
+}

package/dist/editor/edit.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `@texuli/core/editor-transforms`: pure editor transforms and Markdown input
+ * rules (ADR-003). Each takes an `EditorState` and returns a new state or the
+ * issues that refused the edit; unchanged blocks keep their identity.
+ */
+export { applyInputRules } from './input-rules.js';
+export { applyComposition, deleteBackward, deleteForward, deleteSelection, type EditorDeleteUnit, type EditorTransformOptions, type EditorVoidInsert, editorTextBlock, insertBlock, insertBreak, insertText, liftListItem, moveBlock, removeLink, replaceSelection, type SetLinkOptions, setBlockType, setLink, sinkListItem, splitBlock, toggleList, toggleMark, toggleQuote, toggleTodo, } from './transforms.js';

package/dist/editor/edit.js

@@ -0,0 +1,7 @@
+/**
+ * `@texuli/core/editor-transforms`: pure editor transforms and Markdown input
+ * rules (ADR-003). Each takes an `EditorState` and returns a new state or the
+ * issues that refused the edit; unchanged blocks keep their identity.
+ */
+export { applyInputRules } from "./input-rules.js";
+export { applyComposition, deleteBackward, deleteForward, deleteSelection, editorTextBlock, insertBlock, insertBreak, insertText, liftListItem, moveBlock, removeLink, replaceSelection, setBlockType, setLink, sinkListItem, splitBlock, toggleList, toggleMark, toggleQuote, toggleTodo, } from "./transforms.js";

package/dist/editor/graphemes.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Grapheme and word boundaries for caret movement and deletion, from
+ * `Intl.Segmenter` when the platform has it, else code points (a surrogate
+ * pair is never split). Offsets are UTF-16 code units.
+ */
+/** Every grapheme boundary of `text`, ascending, from 0 to `text.length`. */
+export declare function graphemeBoundaries(text: string): number[];
+/** The nearest grapheme boundary at or before `offset`. */
+export declare function snapToGrapheme(text: string, offset: number): number;
+/** The grapheme boundary before `offset` (0 at the start). */
+export declare function previousGrapheme(text: string, offset: number): number;
+/** The grapheme boundary after `offset` (`text.length` at the end). */
+export declare function nextGrapheme(text: string, offset: number): number;
+/** Start of the word before `offset`, skipping spaces and punctuation first. */
+export declare function previousWord(text: string, offset: number): number;
+/** End of the word after `offset`, skipping spaces and punctuation first. */
+export declare function nextWord(text: string, offset: number): number;

package/dist/editor/graphemes.js

@@ -0,0 +1,71 @@
+/**
+ * Grapheme and word boundaries for caret movement and deletion, from
+ * `Intl.Segmenter` when the platform has it, else code points (a surrogate
+ * pair is never split). Offsets are UTF-16 code units.
+ */
+const cache = new Map();
+function segmenter(granularity) {
+    if (!cache.has(granularity)) {
+        const Ctor = Intl
+            .Segmenter;
+        cache.set(granularity, Ctor ? new Ctor(undefined, { granularity }) : null);
+    }
+    return cache.get(granularity) ?? null;
+}
+/** Every grapheme boundary of `text`, ascending, from 0 to `text.length`. */
+export function graphemeBoundaries(text) {
+    const seg = segmenter('grapheme');
+    const out = [];
+    if (seg)
+        for (const part of seg.segment(text))
+            out.push(part.index);
+    else
+        for (let i = 0; i < text.length; i += (text.codePointAt(i) ?? 0) > 0xffff ? 2 : 1)
+            out.push(i);
+    out.push(text.length);
+    return out;
+}
+const clamp = (text, offset) => Math.max(0, Math.min(text.length, Math.trunc(offset) || 0));
+/** The nearest grapheme boundary at or before `offset`. */
+export function snapToGrapheme(text, offset) {
+    const at = clamp(text, offset);
+    return graphemeBoundaries(text).findLast((boundary) => boundary <= at) ?? 0;
+}
+/** The grapheme boundary before `offset` (0 at the start). */
+export function previousGrapheme(text, offset) {
+    const at = clamp(text, offset);
+    return graphemeBoundaries(text).findLast((boundary) => boundary < at) ?? 0;
+}
+/** The grapheme boundary after `offset` (`text.length` at the end). */
+export function nextGrapheme(text, offset) {
+    const at = clamp(text, offset);
+    return graphemeBoundaries(text).find((boundary) => boundary > at) ?? text.length;
+}
+function words(text) {
+    const seg = segmenter('word');
+    if (seg) {
+        return [...seg.segment(text)].map((part) => ({
+            start: part.index,
+            end: part.index + part.segment.length,
+            word: part.isWordLike === true,
+        }));
+    }
+    return [...text.matchAll(/[\p{L}\p{N}_]+|[^\p{L}\p{N}_]+/gu)].map((match) => ({
+        start: match.index ?? 0,
+        end: (match.index ?? 0) + match[0].length,
+        word: /[\p{L}\p{N}_]/u.test(match[0]),
+    }));
+}
+/** Start of the word before `offset`, skipping spaces and punctuation first. */
+export function previousWord(text, offset) {
+    const at = clamp(text, offset);
+    const before = words(text).filter((part) => part.start < at);
+    const word = before.findLast((part) => part.word);
+    return word ? word.start : 0;
+}
+/** End of the word after `offset`, skipping spaces and punctuation first. */
+export function nextWord(text, offset) {
+    const at = clamp(text, offset);
+    const word = words(text).find((part) => part.end > at && part.word);
+    return word ? word.end : text.length;
+}

package/dist/editor/history.d.ts

@@ -0,0 +1,57 @@
+import { type EditorIssue, type EditorSelection, type EditorState, type EditorTransformResult } from './types.js';
+/**
+ * What an edit was, for undo grouping. Consecutive `typing` (or `deletion`)
+ * in one block within `EDITOR_HISTORY_MERGE_MS` is one undo step; an
+ * `input-rule` is always its own step, so undo right after it restores the
+ * characters the user typed.
+ */
+export type EditorEditKind = 'typing' | 'deletion' | 'input-rule' | 'other';
+/** Pause after which typing starts a new undo step. */
+export declare const EDITOR_HISTORY_MERGE_MS = 500;
+export interface EditorHistory {
+    past: readonly EditorState[];
+    present: EditorState;
+    future: readonly EditorState[];
+    /** Why the last refused edit was refused (cleared by the next accepted action). */
+    errors: readonly EditorIssue[];
+    /** Snapshots kept in `past` (default 200). */
+    limit: number;
+    /** The last accepted edit, while it can still merge. */
+    last: {
+        kind: EditorEditKind;
+        block: string | null;
+        at: number;
+    } | null;
+}
+export type EditorHistoryAction = {
+    type: 'apply';
+    result: EditorTransformResult;
+    kind?: EditorEditKind;
+    at?: number;
+}
+/** A selection change: no undo step, and the next edit starts a new one. */
+ | {
+    type: 'select';
+    selection: EditorSelection;
+} | {
+    type: 'undo';
+} | {
+    type: 'redo';
+}
+/** A new document from outside: history restarts. */
+ | {
+    type: 'replace';
+    state: EditorState;
+};
+/** A history whose present is `state`. */
+export declare function createEditorHistory(state: EditorState, options?: {
+    limit?: number;
+}): EditorHistory;
+/**
+ * Snapshot-stack undo and redo (ADR-003). States are immutable and share
+ * unchanged blocks, so a snapshot costs only what changed. A refused edit
+ * keeps `present` and records `errors`.
+ */
+export declare function editorHistoryReducer(history: EditorHistory, action: EditorHistoryAction): EditorHistory;
+export declare const canUndo: (history: EditorHistory) => boolean;
+export declare const canRedo: (history: EditorHistory) => boolean;