@brandup/ui-richeditor 1.0.36

package/README.md

@@ -0,0 +1,118 @@
+# @brandup/ui-richeditor
+
+[![Build Status](https://dev.azure.com/brandup/BrandUp%20Core/_apis/build/status%2FBrandUp%2Fbrandup-ui-kit?branchName=main)](https://dev.azure.com/brandup/BrandUp%20Core/_build/latest?definitionId=81&branchName=main)
+
+Редактор текста на базе `contenteditable`. Получает в конструкторе элемент, делает его редактируемым и берёт на себя всю работу с вводом: форматирование (жирный, курсив, зачёркивание, подчёркивание), панель инструментов, режим набора, нормализацию пробелов и сериализацию значения в HTML или Markdown.
+
+Реализован на чистом Selection/Range API — без устаревшего `document.execCommand`, поэтому разметка всегда семантическая и предсказуема между браузерами.
+
+## Установка
+
+```
+npm i @brandup/ui-richeditor
+```
+
+## Использование
+
+```typescript
+import RichEditor from "@brandup/ui-richeditor";
+
+const elem = document.getElementById("editor") as HTMLElement;
+const editor = new RichEditor(elem, {
+    format: true,
+    tools: ["bold", "italic", "strike", "underline"],
+    storage: "html", // или "markdown"
+    placeholder: "Введите текст",
+    multiline: true,
+});
+
+editor.onChange(({ value }) => console.log(value));
+```
+
+Конструктор оборачивает переданный элемент в `div.ui-richeditor` (к нему привязан `UIElement`) и делает элемент редактируемым (`div.ui-richeditor-input`).
+
+### Панель форматирования
+
+Панель — **общая для всех редакторов** (`div.ui-richeditor-toolbar`). При фокусе редактора она перестраивается под его инструменты, позиционируется над ним и показывается; при потере фокуса — скрывается. Кнопки диспатчат форматирование напрямую активному редактору.
+
+По умолчанию панель живёт в `document.body` (`position: fixed`) — это защищает её от обрезки `overflow: hidden` у родителей. Если задан `toolbarContainer`, панель монтируется в него и позиционируется относительно него (`position: absolute`, над контейнером) — например, `TextBox` передаёт свой контейнер `.ui-textbox`.
+
+## Опции (`RichEditorOptions`)
+
+| Опция | Тип | Описание |
+|---|---|---|
+| `format` | `boolean` | Включает форматирование и панель инструментов |
+| `tools` | `FormatTool[]` | Состав инструментов (по умолчанию все) |
+| `storage` | `"html" \| "markdown"` | Формат сериализации значения (по умолчанию `html`) |
+| `markers` | `Partial<FormatMarkers>` | Переопределение markdown-маркеров по инструментам |
+| `placeholder` | `string \| null` | Текст-заглушка |
+| `multiline` | `boolean` | Многострочный режим |
+| `readonly` | `boolean` | Только для чтения — запрещает ввод и изменение текста (выделение и копирование остаются) |
+| `toolbarContainer` | `HTMLElement \| null` | Контейнер для панели; по умолчанию `document.body` (`position: fixed`). Если задан — панель монтируется в него и позиционируется над ним (`position: absolute`). Контейнер должен быть `position: relative` |
+| `value` | `string` | Начальное значение |
+| `filterChar` | `(char) => boolean` | Хук: `false` — отклонить вводимый символ |
+| `filterPaste` | `(text) => string \| null` | Хук: `null` — отклонить вставку; иначе очищенный текст |
+| `onReject` | `() => void` | Хук: ввод отклонён (символ/вставка) |
+| `onEnter` | `() => void` | Хук: Enter в однострочном режиме |
+
+Хуки `filterChar`/`filterPaste`/`onReject`/`onEnter` позволяют хосту (например, `@brandup/ui-textbox`) накладывать собственные ограничения — фильтрацию по типу, submit формы, индикацию ошибки — не вмешиваясь в работу редактора.
+
+## API
+
+| Член | Описание |
+|---|---|
+| `editable` | Редактируемый элемент |
+| `format`, `formatTools`, `formatStorage`, `formatMarkers`, `multiline` | Параметры экземпляра |
+| `getValue(): string` | Сериализованное значение (по `storage`) |
+| `setValue(value: string): void` | Установить значение (нормализует, генерирует `change`) |
+| `getLength(): number` | Длина текста (без учёта переводов строк) |
+| `focus(): void` | Установить фокус |
+| `onChange(handler)` | Подписка на событие `richeditor-change` |
+| `destroy(): void` | Разворачивает элемент обратно и освобождает ресурсы |
+
+## Поведение форматирования
+
+- Формат — переключатель (toggle): повторное применение снимает его.
+- Применяется к слову целиком: курсор внутри слова или выделение его части → формат охватывает всё слово; исходное выделение/каретка сохраняются.
+- **Режим набора**: на пустом месте (между пробелами / в пустом поле) кнопка/хоткей включают «ожидающий» формат — он применится к следующему введённому тексту. Сбрасывается при перемещении каретки, клике или потере фокуса.
+- Хоткеи `Ctrl/Cmd+B/I/U`. Зачёркивание — только кнопкой.
+- **Отмена/повтор**: `Ctrl/Cmd+Z` — отмена, `Ctrl+Y` или `Ctrl/Cmd+Shift+Z` — повтор. История форматирования, абзацев, переносов и печати ведётся редактором (нативный undo не видит ручных DOM-правок), поэтому **доступна только при включённом форматировании** (`format: true`). Печать коалесится в один шаг отмены по паузе ~300 мс; глубина истории — 100 шагов.
+- При потере фокуса и после `setValue` пробелы нормализуются (схлопывание повторов + обрезка краёв строк).
+
+## Многострочный режим: абзацы и переносы
+
+При `multiline: true` контент структурируется по абзацам:
+
+- **Enter** → новый абзац (`<p>`);
+- **Shift+Enter** или **Ctrl/Cmd+Enter** → мягкий перенос (`<br>`) внутри абзаца;
+- блуждающий текст и `<div>` нормализуются в `<p>` при вводе.
+
+Хвостовой перенос абзаца отбрасывается (это `<br>`-заполнитель); пустая строка делается отдельным абзацем.
+
+При нормализации (потеря фокуса, `setValue`, инициализация) пустые абзацы удаляются.
+
+## Вставка форматированного текста
+
+При включённом форматировании вставка (`paste`) сохраняет форматирование из буфера обмена (`text/html`):
+
+- разметка санитизируется до включённых инструментов (синонимы `STRONG/EM/DEL/INS` → канонические `b/i/s/u`, всё прочее — `span`, стили, классы, `<style>`/`<script>` — отбрасывается, текст сохраняется);
+- **multiline** сохраняет абзацы `<p>` и мягкие переносы `<br>`, разбивая текущий абзац по каретке; **single-line** — инлайн, абзацы/переносы становятся пробелами;
+- если `text/html` нет — простая текстовая вставка (как раньше);
+- хук `filterPaste` остаётся в силе: вернул `null` — вставка отклоняется; изменил текст (обрезка по длине, фильтр по типу) — форматирование не сохраняется, вставляется очищенный текст.
+
+Вся вставка — один шаг истории (Ctrl+Z откатывает целиком).
+
+## Формат хранения
+
+| `storage` | Хранение | Абзац / мягкий перенос | Маркеры форматирования |
+|---|---|---|---|
+| `html` | Санитизированный HTML | `<p>…</p>` / `<br>` | `<b>`, `<i>`, `<s>`, `<u>` |
+| `markdown` | Лёгкая разметка | `\n\n` / `\n` | `**жирный**`, `*курсив*`, `~~зачёркнутый~~`, `++подчёркнутый++` |
+
+Без форматирования (plain) значение хранится как markdown без инструментов: абзацы `\n\n`, мягкий перенос `\n`.
+
+Маркеры markdown настраиваются через `markers`. При разборе применяются по убыванию длины, поэтому длинный маркер срабатывает раньше короткого-префикса. Глубоко вложенные комбинации гарантированно сохраняются только в режиме `html`.
+
+## CSS
+
+Подключается `richeditor.less`. Цветовые переменные `--input-*` берутся из `@brandup/ui-kit` (с fallback-значениями для standalone). Классы: `focused` на обёртке (поле в фокусе), `visible` на общей панели (показана), `active` на кнопке инструмента (формат активен на выделении).

package/package.json

@@ -0,0 +1,41 @@
+{
+  "publishConfig": {
+    "access": "public"
+  },
+  "name": "@brandup/ui-richeditor",
+  "description": "Rich text editor over a contenteditable element (bold, italic, strike, underline).",
+  "keywords": [
+    "brandup",
+    "javascript",
+    "typescript",
+    "ui",
+    "editor",
+    "richtext",
+    "contenteditable"
+  ],
+  "author": {
+    "name": "Dmitry Kovyazin",
+    "email": "it@brandup.online"
+  },
+  "homepage": "https://github.com/brandup-online/brandup-ui-kit/npm/brandup-ui-richeditor",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/brandup-online/brandup-ui-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/brandup-online/brandup-ui-kit/issues",
+    "email": "it@brandup.online"
+  },
+  "license": "Apache-2.0",
+  "version": "1.0.36",
+  "main": "source/index.ts",
+  "types": "source/index.ts",
+  "dependencies": {
+    "@brandup/ui": "^2.0.5"
+  },
+  "files": [
+    "source",
+    "svg",
+    "README.md"
+  ]
+}

package/source/editing.ts

@@ -0,0 +1,238 @@
+// Низкоуровневые операции редактирования на чистом Selection/Range: абзацы, мягкие переносы,
+// каретка, расширение/обрезка выделения. Без состояния редактора и без истории —
+// вызывающий сам решает, когда записывать undo-шаг.
+
+function isBlock(node: Node): boolean {
+	return (
+		node.nodeType === Node.ELEMENT_NODE &&
+		((node as Element).tagName === "P" || (node as Element).tagName === "DIV")
+	);
+}
+
+function emptyParagraph(): HTMLParagraphElement {
+	const p = document.createElement("p");
+	p.appendChild(document.createElement("br"));
+	return p;
+}
+
+// убирает пустые текст-узлы и ставит <br>-заполнитель в пустой абзац (для видимости и каретки)
+function fillEmptyParagraph(p: HTMLElement) {
+	p.normalize(); // удаляет пустые Text-узлы, склеивает соседние
+	if (!p.firstChild) p.appendChild(document.createElement("br"));
+}
+
+function caretToStart(node: Node) {
+	const range = document.createRange();
+	range.setStart(node, 0);
+	range.collapse(true);
+	const selection = window.getSelection();
+	if (selection) {
+		selection.removeAllRanges();
+		selection.addRange(range);
+	}
+}
+
+/** Каретка в конец содержимого: в multiline — в конец последнего абзаца, иначе в конец редактора. */
+export function caretToEnd(editable: HTMLElement, multiline: boolean) {
+	const range = document.createRange();
+	// multiline: каретку в конец последнего абзаца (а не на уровень редактора),
+	// иначе и ввод, и Enter попадают мимо <p>
+	const last = multiline ? editable.lastElementChild : null;
+	range.selectNodeContents(last && isBlock(last) ? last : editable);
+	range.collapse(false);
+	const sel = window.getSelection();
+	if (sel) {
+		sel.removeAllRanges();
+		sel.addRange(range);
+	}
+}
+
+/** Фокус и выделение всего содержимого (например, readonly-режим). */
+export function selectAllContent(editable: HTMLElement) {
+	editable.focus();
+	window.getSelection()?.selectAllChildren(editable);
+}
+
+/** Enter в multiline: разбить текущий абзац по каретке на два <p>. */
+export function insertParagraph(editable: HTMLElement) {
+	const selection = window.getSelection();
+	if (!selection || selection.rangeCount === 0 || !editable.contains(selection.anchorNode)) return;
+
+	const range = selection.getRangeAt(0);
+	range.deleteContents();
+
+	// текущий абзац (ближайший <p>/<div> внутри редактора)
+	let para: Node | null = range.startContainer;
+	while (para && para !== editable && !isBlock(para)) para = para.parentNode;
+
+	// каретка не внутри абзаца — создаём абзац сразу с видимым результатом (иначе Enter «срабатывает со 2-го раза»)
+	if (!para || para === editable) {
+		const next = emptyParagraph();
+		if (editable.childNodes.length === 0) {
+			// пустой редактор: пустая строка-источник + новая строка с кареткой
+			editable.appendChild(emptyParagraph());
+			editable.appendChild(next);
+		} else {
+			// каретка на уровне редактора между/после абзацев — вставляем новый абзац в эту позицию
+			const ref = editable.childNodes[range.startOffset] ?? null;
+			editable.insertBefore(next, ref);
+		}
+		caretToStart(next);
+		return;
+	}
+
+	// выносим содержимое от каретки до конца абзаца в новый <p>
+	const tail = document.createRange();
+	tail.selectNodeContents(para);
+	tail.setStart(range.endContainer, range.endOffset);
+	const fragment = tail.extractContents();
+
+	const next = document.createElement("p");
+	next.appendChild(fragment);
+	(para as ChildNode).after(next);
+
+	// extractContents в конце абзаца оставляет пустой текст-узел → <p></p> без заполнителя
+	// (невидим/нефокусируем, каретка не встаёт). Чистим и ставим <br> в опустевшие абзацы.
+	fillEmptyParagraph(para as HTMLElement);
+	fillEmptyParagraph(next);
+
+	caretToStart(next);
+}
+
+/** Shift/Ctrl+Enter в multiline: вставить мягкий перенос <br>. */
+export function insertSoftBreak(editable: HTMLElement) {
+	const selection = window.getSelection();
+	if (!selection || selection.rangeCount === 0 || !editable.contains(selection.anchorNode)) return;
+
+	const range = selection.getRangeAt(0);
+	range.deleteContents();
+
+	const br = document.createElement("br");
+	range.insertNode(br);
+
+	// insertNode в конце текст-узла расщепляет его и оставляет пустой хвост — убираем,
+	// иначе br.nextSibling != null и заполнитель не ставится (перенос в конце строки не виден)
+	const next = br.nextSibling;
+	if (next && next.nodeType === Node.TEXT_NODE && (next.textContent ?? "") === "") next.remove();
+
+	const after = document.createRange();
+	if (!br.nextSibling) {
+		// перенос в конце строки — нужен второй <br>-заполнитель, иначе новая строка не отображается
+		// (хвостовой <br> отбрасывается при сериализации)
+		const pad = document.createElement("br");
+		br.after(pad);
+		after.setStartBefore(pad);
+	} else {
+		after.setStartAfter(br);
+	}
+	after.collapse(true);
+	selection.removeAllRanges();
+	selection.addRange(after);
+}
+
+/** Вставляет санитизированные абзацы <p> в позицию каретки, разбивая текущий абзац. */
+export function insertPastedParagraphs(editable: HTMLElement, paras: HTMLElement[], range: Range) {
+	let para: Node | null = range.startContainer;
+	while (para && para !== editable && !isBlock(para)) para = para.parentNode;
+
+	// каретка не внутри абзаца (пустой редактор / уровень редактора) — вставляем абзацы как есть
+	if (!para || para === editable) {
+		const ref = editable.childNodes[range.startOffset] ?? null;
+		for (const p of paras) editable.insertBefore(p, ref);
+		return;
+	}
+
+	const block = para as HTMLElement;
+
+	// хвост текущего абзаца после каретки — выносим, чтобы вернуть в конец вставки
+	const tailRange = document.createRange();
+	tailRange.selectNodeContents(block);
+	tailRange.setStart(range.startContainer, range.startOffset);
+	const tail = tailRange.extractContents();
+
+	// первый вставляемый абзац вливается в текущий (после содержимого до каретки)
+	while (paras[0].firstChild) block.appendChild(paras[0].firstChild);
+
+	if (paras.length === 1) {
+		block.appendChild(tail); // один абзац: содержимое-до + вставка + хвост в одном <p>
+		return;
+	}
+
+	// остальные абзацы — отдельными <p> после текущего; хвост — в конец последнего
+	let anchor: ChildNode = block;
+	for (let i = 1; i < paras.length; i++) {
+		anchor.after(paras[i]);
+		anchor = paras[i];
+	}
+	paras[paras.length - 1].appendChild(tail);
+}
+
+/** Обрезает пробелы по краям абзаца (после схлопывания) — у крайних текстовых узлов. */
+export function trimParagraphEdges(p: HTMLElement) {
+	const walker = document.createTreeWalker(p, NodeFilter.SHOW_TEXT);
+	const texts: Text[] = [];
+	for (let t = walker.nextNode() as Text | null; t; t = walker.nextNode() as Text | null) texts.push(t);
+	if (!texts.length) return;
+
+	texts[0].textContent = (texts[0].textContent ?? "").replace(/^ /, "");
+	const last = texts[texts.length - 1];
+	last.textContent = (last.textContent ?? "").replace(/ $/, "");
+}
+
+/** Расширяет выделение до целых слов на границах (для применения формата к слову целиком). */
+export function expandSelectionToWords(editable: HTMLElement, selection: Selection) {
+	const range = selection.getRangeAt(0);
+
+	const { startContainer, endContainer } = range;
+	let startOffset = range.startOffset;
+	let endOffset = range.endOffset;
+
+	if (startContainer.nodeType === Node.TEXT_NODE && editable.contains(startContainer)) {
+		const text = startContainer.textContent ?? "";
+		while (startOffset > 0 && !/\s/.test(text[startOffset - 1])) startOffset--;
+	}
+
+	if (endContainer.nodeType === Node.TEXT_NODE && editable.contains(endContainer)) {
+		const text = endContainer.textContent ?? "";
+		while (endOffset < text.length && !/\s/.test(text[endOffset])) endOffset++;
+	}
+
+	if (startOffset === range.startOffset && endOffset === range.endOffset) return;
+
+	const expanded = document.createRange();
+	expanded.setStart(startContainer, startOffset);
+	expanded.setEnd(endContainer, endOffset);
+	selection.removeAllRanges();
+	selection.addRange(expanded);
+}
+
+/** Убирает пробелы по краям выделения (например, после двойного клика по слову). */
+export function trimSelectionWhitespace(editable: HTMLElement) {
+	const selection = window.getSelection();
+	if (!selection || selection.rangeCount === 0 || selection.isCollapsed) return;
+
+	const range = selection.getRangeAt(0);
+	if (!editable.contains(range.startContainer) || !editable.contains(range.endContainer)) return;
+
+	const { startContainer, endContainer } = range;
+	let startOffset = range.startOffset;
+	let endOffset = range.endOffset;
+
+	if (startContainer.nodeType === Node.TEXT_NODE) {
+		const text = startContainer.textContent ?? "";
+		while (startOffset < text.length && /\s/.test(text[startOffset])) startOffset++;
+	}
+	if (endContainer.nodeType === Node.TEXT_NODE) {
+		const text = endContainer.textContent ?? "";
+		while (endOffset > 0 && /\s/.test(text[endOffset - 1])) endOffset--;
+	}
+
+	if (startContainer === endContainer && startOffset >= endOffset) return;
+	if (startOffset === range.startOffset && endOffset === range.endOffset) return;
+
+	const trimmed = document.createRange();
+	trimmed.setStart(startContainer, startOffset);
+	trimmed.setEnd(endContainer, endOffset);
+	selection.removeAllRanges();
+	selection.addRange(trimmed);
+}

package/source/format-config.ts

@@ -0,0 +1,89 @@
+// Конфигурация форматирования: типы, набор инструментов, markdown-маркеры и Ctrl/Cmd-хоткеи.
+
+export type FormatTool = "bold" | "italic" | "strike" | "underline";
+export type FormatStorage = "html" | "markdown";
+
+export const ALL_FORMAT_TOOLS: FormatTool[] = ["bold", "italic", "strike", "underline"];
+
+interface FormatToolDef {
+	/** Имя команды (атрибут command у кнопки и registerCommand). */
+	command: string;
+	/** Канонический тег при оборачивании и сериализации. */
+	tag: string;
+	/** Теги, распознаваемые при разборе входного HTML. */
+	matchTags: string[];
+	/** Маркер в Markdown. */
+	md: string;
+	/** Клавиша для Ctrl/Cmd-хоткея (пусто — без хоткея). */
+	hotkey: string;
+	/** Подсказка на кнопке. */
+	title: string;
+}
+
+export const FORMAT_TOOLS: Record<FormatTool, FormatToolDef> = {
+	bold: {
+		command: "format-bold",
+		tag: "b",
+		matchTags: ["B", "STRONG"],
+		md: "**",
+		hotkey: "b",
+		title: "Жирный",
+	},
+	italic: {
+		command: "format-italic",
+		tag: "i",
+		matchTags: ["I", "EM"],
+		md: "*",
+		hotkey: "i",
+		title: "Курсив",
+	},
+	strike: {
+		command: "format-strike",
+		tag: "s",
+		matchTags: ["S", "STRIKE", "DEL"],
+		md: "~~",
+		hotkey: "",
+		title: "Зачёркнутый",
+	},
+	underline: {
+		command: "format-underline",
+		tag: "u",
+		matchTags: ["U", "INS"],
+		md: "++",
+		hotkey: "u",
+		title: "Подчёркнутый",
+	},
+};
+
+/** Markdown-маркер для каждого инструмента форматирования. */
+export type FormatMarkers = Record<FormatTool, string>;
+
+/** Маркеры по умолчанию (из FORMAT_TOOLS): bold=**, italic=*, strike=~~, underline=++. */
+export function defaultFormatMarkers(): FormatMarkers {
+	const markers = {} as FormatMarkers;
+	for (const tool of ALL_FORMAT_TOOLS) markers[tool] = FORMAT_TOOLS[tool].md;
+	return markers;
+}
+
+/** Карта Ctrl/Cmd-хоткеев: клавиша → инструмент. */
+export const HOTKEY_TOOLS: Record<string, FormatTool> = (() => {
+	const map: Record<string, FormatTool> = {};
+	for (const tool of ALL_FORMAT_TOOLS) {
+		const hotkey = FORMAT_TOOLS[tool].hotkey;
+		if (hotkey) map[hotkey] = tool;
+	}
+	return map;
+})();
+
+/** Разбирает значение атрибута data-format-tools, оставляя только известные инструменты. */
+export function parseFormatTools(value: string | null): FormatTool[] {
+	if (value === null) return ALL_FORMAT_TOOLS.slice();
+
+	const tools = value
+		.split(/\s+/)
+		.filter(Boolean)
+		.filter((t): t is FormatTool => (ALL_FORMAT_TOOLS as string[]).includes(t));
+
+	// убираем дубли, сохраняя порядок объявления
+	return ALL_FORMAT_TOOLS.filter((t) => tools.includes(t));
+}

package/source/format.ts

@@ -0,0 +1,19 @@
+// Баррель форматирования — единая точка импорта. Реализация разнесена по модулям:
+//   format-config — типы, набор инструментов, markdown-маркеры, хоткеи
+//   serialize     — разбор/сериализация значения (HTML | Markdown), абзацы и переносы
+//   selection     — переключение формата на выделении и вставка текста (Selection/Range)
+//   paragraphs    — нормализация пробелов и приведение к абзацам <p>
+
+export {
+	ALL_FORMAT_TOOLS,
+	FORMAT_TOOLS,
+	HOTKEY_TOOLS,
+	defaultFormatMarkers,
+	parseFormatTools,
+	type FormatMarkers,
+	type FormatStorage,
+	type FormatTool,
+} from "./format-config";
+export { serialize, deserialize } from "./serialize";
+export { selectionCharBounds, restoreSelection, toggleFormat, insertFormattedText, isFormatActive } from "./selection";
+export { normalizeWhitespace, normalizeParagraphs, ensureParagraphs } from "./paragraphs";

package/source/history.ts

@@ -0,0 +1,92 @@
+// Собственная история undo/redo для редактора.
+//
+// Форматирование и работа с абзацами выполняются ручными DOM-операциями (Selection/Range),
+// которые проходят мимо нативного стека истории браузера — нативный Ctrl+Z их не видит и,
+// хуже того, ломается при смешивании с ручными мутациями. Поэтому ведём свою историю снимков
+// (innerHTML + позиция выделения). Используется только при включённом форматировании.
+
+import { restoreSelection, selectionCharBounds } from "./format";
+
+interface Snapshot {
+	html: string;
+	start: number;
+	end: number;
+}
+
+/** Вид правки: печать коалесится в один шаг, структурные операции — всегда отдельный шаг. */
+export type HistoryKind = "type" | "op";
+
+const COALESCE_MS = 300; // печать в пределах паузы — один шаг отмены
+const MAX_DEPTH = 100; // ограничение глубины истории (память)
+
+export class EditorHistory {
+	private readonly __root: HTMLElement;
+	private __undo: Snapshot[] = [];
+	private __redo: Snapshot[] = [];
+	private __lastKind: HistoryKind | null = null;
+	private __lastTime = 0;
+
+	constructor(root: HTMLElement) {
+		this.__root = root;
+	}
+
+	private __snapshot(): Snapshot {
+		const sel = window.getSelection();
+		let start = 0;
+		let end = 0;
+		if (sel && sel.rangeCount > 0 && this.__root.contains(sel.anchorNode))
+			[start, end] = selectionCharBounds(this.__root, sel.getRangeAt(0));
+
+		return { html: this.__root.innerHTML, start, end };
+	}
+
+	/**
+	 * Запомнить текущее (до изменения) состояние. Вызывается перед каждой правкой.
+	 * Печать (kind="type") коалесится: подряд идущие символы в пределах паузы — один шаг.
+	 */
+	record(kind: HistoryKind): void {
+		const now = Date.now();
+		if (kind === "type" && this.__lastKind === "type" && now - this.__lastTime < COALESCE_MS) {
+			this.__lastTime = now;
+			return;
+		}
+		this.__lastKind = kind;
+		this.__lastTime = now;
+
+		const snap = this.__snapshot();
+		const top = this.__undo[this.__undo.length - 1];
+		if (top && top.html === snap.html) return; // состояние не изменилось — не дублируем
+
+		this.__undo.push(snap);
+		if (this.__undo.length > MAX_DEPTH) this.__undo.shift();
+		this.__redo = [];
+	}
+
+	/** Откатить на шаг назад. Возвращает false, если откатывать нечего. */
+	undo(): boolean {
+		const prev = this.__undo.pop();
+		if (!prev) return false;
+
+		this.__redo.push(this.__snapshot());
+		this.__restore(prev);
+		this.__lastKind = null; // следующая печать начнёт новый шаг
+		return true;
+	}
+
+	/** Повторить отменённый шаг. Возвращает false, если повторять нечего. */
+	redo(): boolean {
+		const next = this.__redo.pop();
+		if (!next) return false;
+
+		this.__undo.push(this.__snapshot());
+		this.__restore(next);
+		this.__lastKind = null;
+		return true;
+	}
+
+	private __restore(snap: Snapshot): void {
+		this.__root.innerHTML = snap.html;
+		const sel = window.getSelection();
+		if (sel) restoreSelection(this.__root, snap.start, snap.end, sel);
+	}
+}

package/source/index.ts

@@ -0,0 +1,12 @@
+export { default } from "./richeditor";
+export * from "./richeditor";
+export {
+	ALL_FORMAT_TOOLS,
+	FORMAT_TOOLS,
+	parseFormatTools,
+	defaultFormatMarkers,
+	normalizeWhitespace,
+	type FormatTool,
+	type FormatStorage,
+	type FormatMarkers,
+} from "./format";