@shelamkoff/rector 1.0.0

package/dist/core/uid.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Generate a random block ID.
+ * Uses rejection sampling to eliminate modulo bias.
+ * @returns {string}
+ */
+export function uid(): string;

package/dist/core/uid.js

@@ -0,0 +1,29 @@
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'
+const ID_LENGTH = 6
+// Largest multiple of 62 that fits in a byte (62 * 4 = 248)
+const MAX_VALID = 247
+
+/**
+ * Generate a random block ID.
+ * Uses rejection sampling to eliminate modulo bias.
+ * @returns {string}
+ */
+export function uid() {
+  const bytes = crypto.getRandomValues(new Uint8Array(ID_LENGTH * 2))
+  let id = ''
+  for (let i = 0; i < bytes.length && id.length < ID_LENGTH; i++) {
+    const b = /** @type {number} */ (bytes[i])
+    if (b <= MAX_VALID) {
+      id += ALPHABET[b % ALPHABET.length]
+    }
+  }
+  // Extremely unlikely fallback: if too many bytes rejected, generate more
+  while (id.length < ID_LENGTH) {
+    const extra = crypto.getRandomValues(new Uint8Array(1))
+    const b = /** @type {number} */ (extra[0])
+    if (b <= MAX_VALID) {
+      id += ALPHABET[b % ALPHABET.length]
+    }
+  }
+  return id
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './core/index.js'
+export type * from './types.js'

package/dist/index.js

@@ -0,0 +1 @@
+export * from './core/index.js'

package/dist/inline-plugins/README.md

@@ -0,0 +1,35 @@
+# Inline plugins
+
+Inline plugins store structured data inside text without turning it into opaque HTML. Rector persists a stable `{{widgetId}}` token in the text field and the corresponding `{ type, data }` record in the block-level `inline` map.
+
+## Built-in plugins
+
+| Plugin | Package entry | Purpose |
+| --- | --- | --- |
+| [Color](./color/README.md) | `@shelamkoff/rector/inline-plugins/color` | Persisted color sample with an editable value |
+| [Mention](./mention/README.md) | `@shelamkoff/rector/inline-plugins/mention` | Searchable entity mention with host-provided data |
+
+## Register in the editor
+
+```js
+import { createEditor } from '@shelamkoff/rector'
+import { createColorSwatchPlugin } from '@shelamkoff/rector/inline-plugins/color'
+import { createMentionPlugin } from '@shelamkoff/rector/inline-plugins/mention'
+
+const editor = createEditor({
+  holder,
+  plugins,
+  inlinePlugins: [
+    createColorSwatchPlugin(),
+    createMentionPlugin({
+      searchFunction: async query => searchPeople(query),
+    }),
+  ],
+})
+```
+
+A plugin owns `createWidget(data, id)` and `getData(element)`. It may additionally implement `hydrate`, `onEdit`, `onCommit`, `pasteConfig`, `destroy`, and a matching renderer widget. Preserve the id supplied to `createWidget`; changing it breaks the token-to-data relation.
+
+Mounted changes must use the mutation context supplied by Rector so one completed interaction produces one undo step. Release popup DOM, timers, requests, listeners, and object URLs from the plugin lifecycle.
+
+The VitePress extension guide documents the full contract, security rules, renderer counterpart, history boundary, and lifecycle requirements.

package/dist/inline-plugins/README.ru.md

@@ -0,0 +1,35 @@
+# Внутристрочные плагины
+
+Внутристрочные плагины сохраняют структурированные данные внутри текста, не превращая их в непрозрачный HTML. Rector записывает устойчивый заполнитель `{{widgetId}}` в текстовое поле и соответствующий объект `{ type, data }` в карту `inline` блока.
+
+## Встроенные плагины
+
+| Плагин | Точка входа | Назначение |
+| --- | --- | --- |
+| [Образец цвета](./color/README.ru.md) | `@shelamkoff/rector/inline-plugins/color` | Сохраняемый образец с редактируемым значением цвета |
+| [Упоминание](./mention/README.ru.md) | `@shelamkoff/rector/inline-plugins/mention` | Поиск и вставка сущности из источника приложения |
+
+## Регистрация
+
+```js
+import { createEditor } from '@shelamkoff/rector'
+import { createColorSwatchPlugin } from '@shelamkoff/rector/inline-plugins/color'
+import { createMentionPlugin } from '@shelamkoff/rector/inline-plugins/mention'
+
+const editor = createEditor({
+  holder,
+  plugins,
+  inlinePlugins: [
+    createColorSwatchPlugin(),
+    createMentionPlugin({
+      searchFunction: async query => searchPeople(query),
+    }),
+  ],
+})
+```
+
+Плагин реализует `createWidget(data, id)` и `getData(element)`. Дополнительно доступны `hydrate`, `onEdit`, `onCommit`, `pasteConfig`, `destroy` и соответствующий виджет рендерера. Переданный в `createWidget` идентификатор необходимо сохранить: его замена разрывает связь токена с данными.
+
+Интерактивные изменения выполняются через предоставленный Rector контекст изменения, чтобы одно завершённое действие создавало один шаг отмены. DOM всплывающего элемента, таймеры, запросы, обработчики событий и объектные URL освобождаются в жизненном цикле плагина.
+
+Полный контракт, правила безопасности, соответствующий рендерер, граница истории и жизненный цикл описаны в последовательном руководстве VitePress.

package/dist/inline-plugins/color/README.md

@@ -0,0 +1,61 @@
+# Color swatch inline plugin
+
+Persistent, atomic color sample embedded in a text block. It displays a dot and its color value; it does not format the surrounding text.
+
+## Install and register
+
+```bash
+npm install @shelamkoff/rector @shelamkoff/color-picker
+```
+
+```js
+import { createEditor } from '@shelamkoff/rector'
+import { Paragraph } from '@shelamkoff/rector/plugins/paragraph'
+import { createColorSwatchPlugin } from '@shelamkoff/rector/inline-plugins/color'
+import '@shelamkoff/rector/styles/editor.css'
+import '@shelamkoff/color-picker/styles.css'
+
+const editor = createEditor({
+  holder: document.querySelector('#editor'),
+  plugins: [new Paragraph()],
+  inlinePlugins: [createColorSwatchPlugin()],
+})
+```
+
+The plugin type is `color`. Register it only once per editor. Blocks that enable inline plugins can insert it from the inline-plugin menu; a pasted supported color literal can also be converted to a swatch.
+
+## Stored data
+
+The text field stores a stable placeholder while the block-level `inline` map owns the payload:
+
+```json
+{
+  "text": "Brand color: {{w_brand}}",
+  "inline": {
+    "w_brand": {
+      "type": "color",
+      "data": { "value": "#4357b4" }
+    }
+  }
+}
+```
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `value` | yes | CSS color displayed by the sample. A fresh menu insertion defaults to `#4357b4`; malformed legacy data falls back to `#000000` when read. |
+
+The paste matcher recognizes 3-, 6-, and 8-digit hexadecimal colors plus `rgb()`, `rgba()`, `hsl()`, and `hsla()` forms. The picker converts an applied value to six-digit hexadecimal form. Existing accepted values remain readable even before the user opens the picker.
+
+## Interaction and history
+
+Clicking the sample opens `@shelamkoff/color-picker`. Picker movement is a temporary preview. Apply commits one widget-local command and therefore one undo/redo step; closing the popup without applying restores the previous value and creates no history entry. Insertion and removal use the editor's normal inline-widget commands.
+
+In read-only mode the widget remains visible but does not open the picker. `editor.destroy()` closes the popup, destroys the picker, removes listeners, and releases reference-counted styles.
+
+## Styles and document output
+
+Import the color-picker stylesheet in addition to the Rector editor stylesheet. The widget root uses `.oe-ip.oe-ip--color`; its dot and label use `.oe-ip__dot` and `.oe-ip__label`. Scope host overrides under the editor or renderer container.
+
+For document output, pass `createColorSwatchPlugin()` in `EditorRenderer`'s `inlinePlugins` array. The renderer uses its `createWidget()` and `getData()` subset; the picker is not mounted by the renderer.
+
+The sequential VitePress guide explains the complete inline-plugin contract, placeholder storage, security rules, command boundary, and cleanup requirements.

package/dist/inline-plugins/color/README.ru.md

@@ -0,0 +1,61 @@
+# Внутристрочный плагин образца цвета
+
+Постоянный неделимый образец цвета внутри текстового блока. Он показывает точку и значение цвета, но не форматирует окружающий текст.
+
+## Установка и регистрация
+
+```bash
+npm install @shelamkoff/rector @shelamkoff/color-picker
+```
+
+```js
+import { createEditor } from '@shelamkoff/rector'
+import { Paragraph } from '@shelamkoff/rector/plugins/paragraph'
+import { createColorSwatchPlugin } from '@shelamkoff/rector/inline-plugins/color'
+import '@shelamkoff/rector/styles/editor.css'
+import '@shelamkoff/color-picker/styles.css'
+
+const editor = createEditor({
+  holder: document.querySelector('#editor'),
+  plugins: [new Paragraph()],
+  inlinePlugins: [createColorSwatchPlugin()],
+})
+```
+
+Тип плагина — `color`. Регистрируйте его один раз на экземпляр редактора. В поддерживающем внутристрочные плагины блоке образец вставляется через меню; вставленное из буфера распознанное значение цвета также можно преобразовать в образец.
+
+## Сохраняемые данные
+
+Текстовое поле содержит устойчивый заполнитель, а карта `inline` блока — данные виджета:
+
+```json
+{
+  "text": "Фирменный цвет: {{w_brand}}",
+  "inline": {
+    "w_brand": {
+      "type": "color",
+      "data": { "value": "#4357b4" }
+    }
+  }
+}
+```
+
+| Поле | Обязательное | Назначение |
+| --- | --- | --- |
+| `value` | да | Цвет CSS, отображаемый образцом. При вставке из меню используется `#4357b4`; при чтении некорректных старых данных — `#000000`. |
+
+При вставке распознаются трёх-, шести- и восьмизначные шестнадцатеричные цвета, а также формы `rgb()`, `rgba()`, `hsl()` и `hsla()`. Применённое в окне выбора значение преобразуется в шестизначную шестнадцатеричную форму. Ранее сохранённые распознанные формы остаются читаемыми до открытия окна выбора.
+
+## Взаимодействие и история
+
+Нажатие на образец открывает `@shelamkoff/color-picker`. Перемещение элементов управления показывает временный предварительный результат. Кнопка применения создаёт одну команду виджета и один шаг отмены и повтора; закрытие без применения восстанавливает прежнее значение и не меняет историю. Вставка и удаление используют обычные команды внутристрочных виджетов.
+
+В режиме чтения образец отображается, но окно выбора не открывается. `editor.destroy()` закрывает окно, уничтожает его экземпляр, удаляет обработчики и освобождает стили с подсчётом владельцев.
+
+## Стили и отображение документа
+
+Кроме стилей редактора импортируйте таблицу стилей средства выбора цвета. Корневой элемент использует `.oe-ip.oe-ip--color`, а точка и подпись — `.oe-ip__dot` и `.oe-ip__label`. Ограничивайте переопределения контейнером редактора или рендерера.
+
+Для отображения документа передайте `createColorSwatchPlugin()` в массив `inlinePlugins` конструктора `EditorRenderer`. Рендерер использует только `createWidget()` и `getData()`; окно выбора цвета в нём не подключается.
+
+Последовательное руководство VitePress описывает полный контракт внутристрочного плагина, хранение заполнителей, безопасность, границы команд и освобождение ресурсов.

package/dist/inline-plugins/color.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Color swatch inline plugin.
+ * Renders as an atomic inline widget: ● #066fd1
+ * Click opens a full color picker popup.
+ *
+ * @returns {import('../types.js').InlinePlugin}
+ */
+export function createColorSwatchPlugin(): import("../types.js").InlinePlugin;

package/dist/inline-plugins/color.js

@@ -0,0 +1,184 @@
+import { ColorPicker } from '@shelamkoff/color-picker'
+import { generateInlineId } from '../shared/inlineMarshal.js'
+import { normalizeTextValue } from '../shared/textFormat.js'
+
+/**
+ * Color swatch inline plugin.
+ * Renders as an atomic inline widget: ● #066fd1
+ * Click opens a full color picker popup.
+ *
+ * @returns {import('../types').InlinePlugin}
+ */
+export function createColorSwatchPlugin() {
+  /** @type {import('../core/types').IScopedI18n | null} */
+  let i18n = null
+
+  return {
+    type: 'color',
+    get title() { return i18n?.has('title') ? i18n.t('title') : 'Color' },
+    icon: '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 21a9 9 0 0 1 0-18c4.97 0 9 3.582 9 8c0 1.06-.474 2.078-1.318 2.828S17.938 15 16.5 15H14a2 2 0 0 0-1 3.75A1.3 1.3 0 0 1 12 21"/><circle cx="7.5" cy="10.5" r=".5" fill="currentColor"/><circle cx="12" cy="7.5" r=".5" fill="currentColor"/><circle cx="16.5" cy="10.5" r=".5" fill="currentColor"/></svg>',
+    /** @param {import('../core/types').IScopedI18n} _i18n */
+    setI18n(_i18n) { i18n = _i18n },
+    pasteConfig: {
+      patterns: [
+        /^#[0-9a-fA-F]{3}$/,
+        /^#[0-9a-fA-F]{6}$/,
+        /^#[0-9a-fA-F]{8}$/,
+        /^rgb\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}\s*\)$/,
+        /^rgba\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*[\d.]+\s*\)$/,
+        /^hsl\(\s*\d{1,3}\s*,\s*\d{1,3}%\s*,\s*\d{1,3}%\s*\)$/,
+        /^hsla\(\s*\d{1,3}\s*,\s*\d{1,3}%\s*,\s*\d{1,3}%\s*,\s*[\d.]+\s*\)$/,
+      ],
+    },
+    onPatternMatch(match) {
+      return { value: match }
+    },
+
+    createWidget(data, id) {
+      const value = normalizeTextValue(data.value).trim() || '#4357b4'
+
+      const span = document.createElement('span')
+      span.contentEditable = 'false'
+      span.setAttribute('data-inline-plugin', 'color')
+      span.setAttribute('data-id', id || generateInlineId())
+      span.setAttribute('data-value', value)
+      span.className = 'oe-ip oe-ip--color'
+
+      const dot = document.createElement('span')
+      dot.className = 'oe-ip__dot'
+      dot.style.backgroundColor = value
+
+      const label = document.createElement('span')
+      label.className = 'oe-ip__label'
+      label.textContent = value
+
+      span.appendChild(dot)
+      span.appendChild(label)
+
+      return span
+    },
+
+    hydrate(element, ctx) {
+      element.addEventListener('click', (e) => {
+        if (ctx.readOnly) return
+        e.preventDefault()
+        e.stopPropagation()
+        openColorPicker(element, ctx)
+      })
+    },
+
+    getData(element) {
+      return {
+        value: element.dataset.value || '#000000',
+      }
+    },
+  }
+}
+
+/**
+ * Normalize any color value to a 6-digit hex string.
+ * @param {string} value
+ * @returns {string}
+ */
+function normalizeToHex6(value) {
+  // Short hex: #rgb → #rrggbb
+  const m3 = value.match(/^#([0-9a-fA-F])([0-9a-fA-F])([0-9a-fA-F])$/)
+  if (m3) return '#' + m3[1] + m3[1] + m3[2] + m3[2] + m3[3] + m3[3]
+
+  // 8-digit hex: strip alpha
+  const m8 = value.match(/^#([0-9a-fA-F]{6})[0-9a-fA-F]{2}$/)
+  if (m8) return '#' + m8[1]
+
+  // Already 6-digit hex
+  if (/^#[0-9a-fA-F]{6}$/.test(value)) return value
+
+  // Non-hex (rgb, hsl, etc.) — convert via DOM
+  const temp = document.createElement('span')
+  temp.style.color = value
+  document.body.appendChild(temp)
+  const computed = getComputedStyle(temp).color
+  temp.remove()
+  const m = computed.match(/(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/)
+  if (m) return '#' + [m[1], m[2], m[3]].map(n => Number(n).toString(16).padStart(2, '0')).join('')
+
+  return '#000000'
+}
+
+/**
+ * @param {HTMLElement} widget
+ * @param {import('../types').InlinePluginContext} ctx
+ */
+function openColorPicker(widget, ctx) {
+  const current = normalizeToHex6(widget.dataset.value || '#000000')
+  const originalLabel = widget.querySelector('.oe-ip__label')?.textContent ?? current
+  let committed = false
+
+  const picker = new ColorPicker({
+    onApply(cssColor) {
+      const next = normalizeToHex6(cssColor)
+      restoreWidget(widget, current, originalLabel)
+      ctx.mutate(widget, () => updateWidget(widget, next))
+      committed = true
+      ctx.hidePopup()
+    },
+    onChange(cssColor) {
+      updateWidget(widget, normalizeToHex6(cssColor))
+    },
+    onFormatChange(formatted) {
+      updateWidgetLabel(widget, formatted)
+    },
+    showRemove: false,
+  })
+
+  const popupContent = picker.element
+  // Position picker as static inside popup (popup handles positioning)
+  popupContent.style.display = ''
+  popupContent.style.position = 'static'
+  popupContent.style.transform = 'none'
+
+  picker.open(current, 1)
+
+  ctx.showPopup(widget, popupContent, () => {
+    if (!committed) restoreWidget(widget, current, originalLabel)
+    picker.destroy()
+  })
+}
+
+/**
+ * @param {HTMLElement} widget
+ * @param {string} value
+ */
+function updateWidget(widget, value) {
+  widget.dataset.value = value
+
+  const dot = /** @type {HTMLElement | null} */ (widget.querySelector('.oe-ip__dot'))
+  if (dot) dot.style.backgroundColor = value
+
+  const label = widget.querySelector('.oe-ip__label')
+  if (label) label.textContent = value
+
+}
+
+/**
+ * Restore both the stored color and the human-readable label.
+ *
+ * @param {HTMLElement} widget
+ * @param {string} value
+ * @param {string} label
+ * @returns {void}
+ */
+function restoreWidget(widget, value, label) {
+  updateWidget(widget, value)
+  const labelElement = widget.querySelector('.oe-ip__label')
+  if (labelElement) labelElement.textContent = label
+}
+
+/**
+ * Update only the label text (e.g. when format changes in picker).
+ * @param {HTMLElement} widget
+ * @param {string} formatted
+ */
+function updateWidgetLabel(widget, formatted) {
+  const label = widget.querySelector('.oe-ip__label')
+  if (label) label.textContent = formatted
+}

package/dist/inline-plugins/locale/en.d.ts

@@ -0,0 +1,7 @@
+declare const _default: {
+    'inlinePlugin.color.title': string;
+    'inlinePlugin.mention.title': string;
+    'inlinePlugin.mention.noResults': string;
+    'inlinePlugin.mention.loading': string;
+};
+export default _default;

package/dist/inline-plugins/locale/en.js

@@ -0,0 +1,6 @@
+export default {
+  'inlinePlugin.color.title': 'Color',
+  'inlinePlugin.mention.title': 'Mention',
+  'inlinePlugin.mention.noResults': 'No results found',
+  'inlinePlugin.mention.loading': 'Loading...',
+}

package/dist/inline-plugins/locale/ru.d.ts

@@ -0,0 +1,7 @@
+declare const _default: {
+    'inlinePlugin.color.title': string;
+    'inlinePlugin.mention.title': string;
+    'inlinePlugin.mention.noResults': string;
+    'inlinePlugin.mention.loading': string;
+};
+export default _default;

package/dist/inline-plugins/locale/ru.js

@@ -0,0 +1,6 @@
+export default {
+  'inlinePlugin.color.title': 'Цвет',
+  'inlinePlugin.mention.title': 'Упоминание',
+  'inlinePlugin.mention.noResults': 'Ничего не найдено',
+  'inlinePlugin.mention.loading': 'Загрузка...',
+}

package/dist/inline-plugins/mention/README.md

@@ -0,0 +1,97 @@
+# Mention inline plugin
+
+Trigger-driven entity search with keyboard navigation, cursor pagination, custom result rendering, and stable saved widget identities.
+
+## Register in the editor
+
+```js
+import { createEditor } from '@shelamkoff/rector'
+import { Paragraph } from '@shelamkoff/rector/plugins/paragraph'
+import { createMentionPlugin } from '@shelamkoff/rector/inline-plugins/mention'
+import '@shelamkoff/rector/styles/editor.css'
+
+const mention = createMentionPlugin({
+  async searchFunction(query, nextPageUrl, { signal }) {
+    const url = nextPageUrl ?? `/api/people?q=${encodeURIComponent(query)}`
+    const response = await fetch(url, { signal })
+    if (!response.ok) throw new Error(`Mention search failed: ${response.status}`)
+    return response.json()
+  },
+})
+
+const editor = createEditor({
+  holder: document.querySelector('#editor'),
+  plugins: [new Paragraph()],
+  inlinePlugins: [mention],
+})
+```
+
+The plugin type is `mention`. The trigger must be exactly one Unicode code point. Typing it at the beginning of a text node or after a regular or non-breaking space opens search. `query` excludes the trigger. Arrow keys move the active result, Enter or Tab commits it, Escape closes the popup, and scrolling near the end requests `nextPageUrl` when supplied.
+
+## Search contract
+
+`searchFunction` returns either `MentionItem[]` or `{ items: MentionItem[], nextPageUrl?: string | null }`:
+
+```ts
+interface MentionItem {
+  id: string | number
+  name: string
+  avatar?: string
+  details?: string
+  [applicationField: string]: unknown
+}
+```
+
+For the first page, `nextPageUrl` passed to the callback is `null`. For later pages it is the opaque cursor previously returned by the application. Pass the supplied `AbortSignal` to the network or data client. A newer query, popup closure, or `editor.destroy()` aborts the current signal and stale responses are ignored even if the underlying client cannot cancel.
+
+An omitted `searchFunction` is valid but yields no suggestions. Errors other than cancellation are written to `console.warn` and leave the current session without replacement results.
+
+## Options
+
+| Option | Type | Default and behavior |
+| --- | --- | --- |
+| `trigger` | `string` | `@`. Exactly one Unicode code point that starts and visually prefixes a mention; any other value throws during plugin creation. Multi-code-point grapheme clusters such as a flag are therefore rejected. |
+| `searchFunction` | `MentionSearchFunction \| null` | `null`; no results until the host supplies a source. |
+| `debounceDelay` | `number` | `300` ms for non-empty first-page queries. Empty and subsequent-page queries run immediately. |
+| `noResultsText` | `string` | Current locale message (`No results found` in English). |
+| `dropdownClass` | `string` | Empty string. Extra class on the popup root. |
+| `onMentionSelect` | `({ id, name }) => void` | No callback. Observes a committed selection; callback exceptions do not roll back the commit. |
+| `renderItem` | `(item, index, isActive) => HTMLElement \| null` | Built-in item with optional avatar and details. Return `null` or `undefined` to use it. |
+| `renderNoResults` | `(text) => HTMLElement \| null` | Built-in empty-result row. |
+| `renderLoading` | `() => HTMLElement \| null` | Built-in loading row. |
+
+Extra item fields are available only to `renderItem`. They are not persisted and are not passed to `onMentionSelect`.
+
+Each renderer must return a fresh, detached `HTMLElement` for that call. Rector adds the listbox classes, indices, ids, and ARIA attributes required for keyboard navigation to custom result rows. It also marks custom empty and loading rows as live status content. Returning `null`, `undefined`, or a non-element value selects the built-in row.
+
+## Stored data and editing
+
+The text field stores `{{widgetId}}`, while the block-level `inline` map stores only the stable entity identity and display name:
+
+```json
+{
+  "text": "Owner: {{w_owner}}",
+  "inline": {
+    "w_owner": {
+      "type": "mention",
+      "data": { "id": "42", "name": "Ada Lovelace" }
+    }
+  }
+}
+```
+
+The saved `id` is normalized to a string. `onMentionSelect` receives the source item's original string or number id. Editing an existing pill starts a new query. Choosing a result updates the widget atomically; leaving without a choice converts the edited pill to ordinary visible text. If autosave occurs while that query is still in progress, the transient pill is likewise serialized as text rather than as an invalid mention.
+
+## History, lifecycle, and styles
+
+A fresh commit or replacement of an existing mention is one undo/redo step. Search text, active-row movement, loading state, and opening or closing the popup are transient UI state and do not create commands.
+
+The plugin owns one popup, its document/window listeners, debounce timer, request controller, and a reference-counted stylesheet handle. `editor.destroy()` releases all of them. Register one separately created mention plugin per editor; mounting the same instance twice is rejected.
+
+Use `.oe-ip--mention` for saved pills and `.oe-mention-dropdown` plus its child classes for the suggestion UI. `avatar` URLs pass the shared media URL policy, and built-in rows assign names/details through text-safe DOM operations.
+
+## Document output
+
+Pass `createMentionWidget()` in `EditorRenderer`'s `inlinePlugins` array. It contains only the widget DOM round-trip and does not include search, popup code, or editor listeners. If the editor uses a non-default trigger, pass that same character to the renderer factory, for example `createMentionWidget('#')`. The trigger is presentation configuration and is not repeated in every saved widget.
+
+The sequential VitePress guide documents the complete inline-widget contract, storage format, history boundaries, custom plugin creation, security, and cleanup.