@shelamkoff/rector 1.0.0

package/dist/locale/ru.js

@@ -0,0 +1,52 @@
+import core from '../core/locale/ru.js'
+import paragraph from '../plugins/paragraph/locale/ru.js'
+import heading from '../plugins/heading/locale/ru.js'
+import list from '../plugins/list/locale/ru.js'
+import quote from '../plugins/quote/locale/ru.js'
+import code from '../plugins/code/locale/ru.js'
+import image from '../plugins/image/locale/ru.js'
+import embed from '../plugins/embed/locale/ru.js'
+import gallery from '../plugins/gallery/locale/ru.js'
+import carousel from '../plugins/carousel/locale/ru.js'
+import checklist from '../plugins/checklist/locale/ru.js'
+import warning from '../plugins/warning/locale/ru.js'
+import raw from '../plugins/raw/locale/ru.js'
+import poll from '../plugins/poll/locale/ru.js'
+import person from '../plugins/person/locale/ru.js'
+import attaches from '../plugins/attaches/locale/ru.js'
+import linkPreview from '../plugins/link-preview/locale/ru.js'
+import toggle from '../plugins/toggle/locale/ru.js'
+import columns from '../plugins/columns/locale/ru.js'
+import spoiler from '../plugins/spoiler/locale/ru.js'
+import delimiter from '../plugins/delimiter/locale/ru.js'
+import table from '../plugins/table/locale/ru.js'
+import color from '../inline-plugins/locale/ru.js'
+import renderer from '../renderer/locale/ru.js'
+
+export default {
+  __lang: 'ru',
+  ...core,
+  ...paragraph,
+  ...heading,
+  ...list,
+  ...quote,
+  ...code,
+  ...image,
+  ...embed,
+  ...gallery,
+  ...carousel,
+  ...checklist,
+  ...warning,
+  ...raw,
+  ...poll,
+  ...person,
+  ...attaches,
+  ...linkPreview,
+  ...toggle,
+  ...columns,
+  ...spoiler,
+  ...delimiter,
+  ...table,
+  ...color,
+  ...renderer,
+}

package/dist/plugins/BlockPluginAbstract.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Abstract base for block plugins.
+ *
+ * Implements the boilerplate that every plugin previously duplicated:
+ *  - storing the i18n instance (a `ScopedI18n` wrapper auto-prefixed with
+ *    `plugin.<type>.`, so plugin code can use short keys like `'title'`
+ *    instead of `'plugin.heading.title'`)
+ *  - protected `_t(key, fallback, params?)` for plain translations
+ *  - protected `_p(key, count, params?)` for pluralized translations
+ *  - storing the constructor config in `_config`
+ *
+ * Subclasses must implement the `BlockPlugin` contract proper:
+ *  - `type`, `icon`, `render(data, context)`, `save(element)`
+ *  - usually `static styles`, `static locale`, `static isTextBlock`
+ *  - optional `validate`, `merge`, `renderSettings`, `onPaste`, etc.
+ *
+ * Not instantiable directly — `new BlockPluginAbstract()` throws.
+ *
+ * @template {object} [TConfig=Record<string, any>]
+ */
+export class BlockPluginAbstract<TConfig extends unknown = Record<string, any>> {
+    /** @param {TConfig} [config] */
+    constructor(config?: TConfig);
+    /** @type {TConfig} */
+    _config: TConfig;
+    /**
+     * Public accessor for plugin configuration.
+     * Used by the editor core to read config knobs (e.g. `injectStyles`, `css`).
+     * @returns {TConfig}
+     */
+    getPluginConfig(): TConfig;
+    /**
+     * Receive the editor's i18n. `createEditor` passes a `ScopedI18n` wrapper
+     * already prefixed with `plugin.<type>.`, so subsequent `_t('foo')` calls
+     * resolve to `plugin.<type>.foo` in the underlying dictionary.
+     *
+     * Backward-compat: if a subclass calls `_t('plugin.heading.title')` with the
+     * full key, ScopedI18n detects the matching prefix and passes through
+     * untouched.
+     *
+     * @param {import('../core/types.js').IScopedI18n} i18n
+     * @returns {void}
+     */
+    setI18n(i18n: import("../core/types.js").IScopedI18n): void;
+    /**
+     * Resolve a translation key, returning a fallback when i18n is missing
+     * or the key is not in the dictionary.
+     *
+     * Uses the explicit `has()` check rather than comparing the result to the
+     * key — that comparison gave a false positive when a translation message
+     * happened to literally equal the key string.
+     *
+     * @protected
+     * @param {string} key                                       short key (auto-namespaced)
+     * @param {string} [fallback]                                value when i18n is absent or key missing
+     * @param {Record<string, string | number>} [params]        `{name}` interpolation params
+     * @returns {string}
+     */
+    protected _t(key: string, fallback?: string, params?: Record<string, string | number>): string;
+    /**
+     * Resolve a plural-form translation. The locale value can be:
+     *  - a `PluralForms` object (`{ one, few, many, other }`) — selected by CLDR rules
+     *  - a plain string with `{count}` placeholder — interpolated with count
+     *
+     * @protected
+     * @param {string} key
+     * @param {number} count
+     * @param {string} [fallback]
+     * @param {Record<string, string | number>} [params]
+     * @returns {string}
+     */
+    protected _p(key: string, count: number, fallback?: string, params?: Record<string, string | number>): string;
+    /**
+     * Direct access to the i18n instance for cases where subclasses need to
+     * pass it to nested helpers.
+     *
+     * @protected
+     * @returns {import('../core/types.js').IScopedI18n | null}
+     */
+    protected get _i18n(): import("../core/types.js").IScopedI18n | null;
+    #private;
+}

package/dist/plugins/BlockPluginAbstract.js

@@ -0,0 +1,111 @@
+/**
+ * Abstract base for block plugins.
+ *
+ * Implements the boilerplate that every plugin previously duplicated:
+ *  - storing the i18n instance (a `ScopedI18n` wrapper auto-prefixed with
+ *    `plugin.<type>.`, so plugin code can use short keys like `'title'`
+ *    instead of `'plugin.heading.title'`)
+ *  - protected `_t(key, fallback, params?)` for plain translations
+ *  - protected `_p(key, count, params?)` for pluralized translations
+ *  - storing the constructor config in `_config`
+ *
+ * Subclasses must implement the `BlockPlugin` contract proper:
+ *  - `type`, `icon`, `render(data, context)`, `save(element)`
+ *  - usually `static styles`, `static locale`, `static isTextBlock`
+ *  - optional `validate`, `merge`, `renderSettings`, `onPaste`, etc.
+ *
+ * Not instantiable directly — `new BlockPluginAbstract()` throws.
+ *
+ * @template {object} [TConfig=Record<string, any>]
+ */
+export class BlockPluginAbstract {
+  /** @type {import('../core/types').IScopedI18n | null} */
+  #i18n = null
+
+  /** @type {TConfig} */
+  _config
+
+  /** @param {TConfig} [config] */
+  constructor(config) {
+    if (new.target === BlockPluginAbstract) {
+      throw new Error('BlockPluginAbstract is abstract — extend it')
+    }
+    // Freeze Rector's own shallow copy. Freezing the object supplied by the
+    // consumer would unexpectedly make application configuration immutable.
+    this._config = /** @type {TConfig} */ (Object.freeze({ ...(config || {}) }))
+  }
+
+  /**
+   * Public accessor for plugin configuration.
+   * Used by the editor core to read config knobs (e.g. `injectStyles`, `css`).
+   * @returns {TConfig}
+   */
+  getPluginConfig() {
+    return this._config
+  }
+
+  /**
+   * Receive the editor's i18n. `createEditor` passes a `ScopedI18n` wrapper
+   * already prefixed with `plugin.<type>.`, so subsequent `_t('foo')` calls
+   * resolve to `plugin.<type>.foo` in the underlying dictionary.
+   *
+   * Backward-compat: if a subclass calls `_t('plugin.heading.title')` with the
+   * full key, ScopedI18n detects the matching prefix and passes through
+   * untouched.
+   *
+   * @param {import('../core/types').IScopedI18n} i18n
+   * @returns {void}
+   */
+  setI18n(i18n) {
+    this.#i18n = i18n
+  }
+
+  /**
+   * Resolve a translation key, returning a fallback when i18n is missing
+   * or the key is not in the dictionary.
+   *
+   * Uses the explicit `has()` check rather than comparing the result to the
+   * key — that comparison gave a false positive when a translation message
+   * happened to literally equal the key string.
+   *
+   * @protected
+   * @param {string} key                                       short key (auto-namespaced)
+   * @param {string} [fallback]                                value when i18n is absent or key missing
+   * @param {Record<string, string | number>} [params]        `{name}` interpolation params
+   * @returns {string}
+   */
+  _t(key, fallback = '', params) {
+    if (!this.#i18n) return fallback
+    if (!this.#i18n.has(key)) return fallback
+    return this.#i18n.t(key, params)
+  }
+
+  /**
+   * Resolve a plural-form translation. The locale value can be:
+   *  - a `PluralForms` object (`{ one, few, many, other }`) — selected by CLDR rules
+   *  - a plain string with `{count}` placeholder — interpolated with count
+   *
+   * @protected
+   * @param {string} key
+   * @param {number} count
+   * @param {string} [fallback]
+   * @param {Record<string, string | number>} [params]
+   * @returns {string}
+   */
+  _p(key, count, fallback = '', params) {
+    if (!this.#i18n) return fallback
+    if (!this.#i18n.has(key)) return fallback
+    return this.#i18n.plural(key, count, params)
+  }
+
+  /**
+   * Direct access to the i18n instance for cases where subclasses need to
+   * pass it to nested helpers.
+   *
+   * @protected
+   * @returns {import('../core/types').IScopedI18n | null}
+   */
+  get _i18n() {
+    return this.#i18n
+  }
+}

package/dist/plugins/README.md

@@ -0,0 +1,44 @@
+# Block plugins
+
+The package ships 21 editable block plugins. Import a single plugin from `@shelamkoff/rector/plugins/<path>`, the complete synchronous preset from `@shelamkoff/rector/plugins`, or a document-driven subset from `@shelamkoff/rector/plugins/async`.
+
+| Plugin | Block type | Purpose |
+| --- | --- | --- |
+| [Paragraph](./paragraph/README.md) | `paragraph` | Editable rich-text paragraph with alignment, inline tools, inline widgets, merge, and block conversion support. |
+| [Heading](./heading/README.md) | `heading` | Heading levels 2-6 with alignment, inline formatting, inline widgets, paste handling, and level controls. |
+| [List](./list/README.md) | `list` | Ordered and unordered rich-text lists with item splitting, merging, block exit, and conversion of selected items. |
+| [Quote](./quote/README.md) | `quote` | Quotation text with an optional caption. |
+| [Code](./code/README.md) | `code` | Code block with a language selector and optional syntax highlighting. |
+| [Image](./image/README.md) | `image` | Uploadable image with caption, sizing, border, background, and object-fit controls. |
+| [Delimiter](./delimiter/README.md) | `delimiter` | A visual section separator with no content payload. |
+| [Table](./table/README.md) | `table` | Editable table with an optional heading row. |
+| [Checklist](./checklist/README.md) | `checklist` | Checklist with independently checked rich-text items. |
+| [Warning](./warning/README.md) | `warning` | Callout block with editable title and message fields. |
+| [Embed](./embed/README.md) | `embed` | YouTube and Vimeo embed block with caption, cover image, and preview metadata. |
+| [Raw](./raw/README.md) | `raw` | Raw HTML authoring block. |
+| [Gallery](./gallery/README.md) | `gallery` | Multi-image gallery with layouts, captions, appearance settings, reordering, and viewer options. |
+| [CarouselBlock](./carousel/README.md) | `carousel` | Mixed image, video, and sanitized HTML slides with navigation, pagination, thumbnails, autoplay, and ordering controls. |
+| [Attaches](./attaches/README.md) | `attaches` | One or more downloadable files with selectable presentation variants. |
+| [LinkPreview](./link-preview/README.md) | `linkPreview` | Link preview card with seven visual templates and optional application-provided metadata. |
+| [Toggle](./toggle/README.md) | `toggle` | Collapsible block with editable title, rich content, and persistent open state. |
+| [Columns](./columns/README.md) | `columns` | Two- or three-column rich-content layouts. |
+| [Spoiler](./spoiler/README.md) | `spoiler` | User-revealed hidden content with an editable label. |
+| [Poll](./poll/README.md) | `poll` | Single- or multiple-choice poll with local results or an application-provided live data source. |
+| [Person](./person/README.md) | `person` | One or more profile cards with cropped avatars, biography, role, and social links. |
+
+## Loading only document types
+
+```js
+import { createBlockPluginsAsync } from '@shelamkoff/rector/plugins/async'
+
+const plugins = await createBlockPluginsAsync(documentData, {
+  image: { uploadFile },
+  gallery: { uploadFile },
+})
+```
+
+The async loader deduplicates imports and preserves the first-occurrence order from the supplied type list or document. When no source is supplied, it uses the built-in catalog order. Unknown types reject instead of being silently ignored.
+
+## Authoring
+
+The VitePress extension guide documents the required contract, optional capabilities, command boundaries, text-field mapping, styles, localization, lifecycle, security, and the matching renderer contract.

package/dist/plugins/README.ru.md

@@ -0,0 +1,40 @@
+# Блочные плагины
+
+Пакет содержит 21 блок. Импортируйте один класс из `@shelamkoff/rector/plugins/<path>`, полный синхронный набор из `@shelamkoff/rector/plugins` или набор по типам документа из `@shelamkoff/rector/plugins/async`.
+
+| Плагин | Тип | Назначение |
+| --- | --- | --- |
+| [Paragraph](./paragraph/README.ru.md) | `paragraph` | Абзац с форматированием, выравниванием, внутристрочными инструментами и виджетами. |
+| [Heading](./heading/README.ru.md) | `heading` | Заголовок уровня 2–6 с выравниванием, форматированием, виджетами и выбором уровня. |
+| [List](./list/README.ru.md) | `list` | Нумерованный или маркированный список с разделением и объединением пунктов, выходом из блока и преобразованием выделенных пунктов. |
+| [Quote](./quote/README.ru.md) | `quote` | Цитата с текстом и необязательной подписью. |
+| [Code](./code/README.ru.md) | `code` | Блок кода с выбором языка и необязательной подсветкой синтаксиса. |
+| [Image](./image/README.ru.md) | `image` | Изображение с загрузкой, подписью, размерами, рамкой, фоном и режимом вписывания. |
+| [Delimiter](./delimiter/README.ru.md) | `delimiter` | Визуальный разделитель без содержимого. |
+| [Table](./table/README.ru.md) | `table` | Редактируемая таблица с необязательной строкой заголовков. |
+| [Checklist](./checklist/README.ru.md) | `checklist` | Контрольный список с независимым состоянием каждого пункта. |
+| [Warning](./warning/README.ru.md) | `warning` | Выделенный информационный блок с редактируемыми заголовком и сообщением. |
+| [Embed](./embed/README.ru.md) | `embed` | Видео YouTube или Vimeo с подписью, обложкой и сведениями предварительного просмотра. |
+| [Raw](./raw/README.ru.md) | `raw` | Блок для ввода произвольного HTML. |
+| [Gallery](./gallery/README.ru.md) | `gallery` | Галерея изображений с макетами, подписями, настройками вида, сортировкой и параметрами просмотра. |
+| [CarouselBlock](./carousel/README.ru.md) | `carousel` | Карусель из изображений, видео и очищенного HTML с навигацией, пагинацией, миниатюрами, автопрокруткой и управлением порядком. |
+| [Attaches](./attaches/README.ru.md) | `attaches` | Один или несколько скачиваемых файлов с вариантами представления. |
+| [LinkPreview](./link-preview/README.ru.md) | `linkPreview` | Предварительный просмотр ссылки с семью шаблонами и необязательными метаданными приложения. |
+| [Toggle](./toggle/README.ru.md) | `toggle` | Сворачиваемый блок с заголовком, форматируемым содержимым и сохраняемым состоянием. |
+| [Columns](./columns/README.ru.md) | `columns` | Двух- и трёхколоночные макеты для форматируемого содержимого. |
+| [Spoiler](./spoiler/README.ru.md) | `spoiler` | Скрываемое содержимое с редактируемой подписью. |
+| [Poll](./poll/README.ru.md) | `poll` | Опрос с одиночным или множественным выбором и локальными либо предоставленными приложением актуальными результатами. |
+| [Person](./person/README.ru.md) | `person` | Одна или несколько карточек профиля с обрезанным аватаром, биографией, ролью и ссылками. |
+
+## Загрузка типов документа
+
+```js
+import { createBlockPluginsAsync } from '@shelamkoff/rector/plugins/async'
+const plugins = await createBlockPluginsAsync(documentData, { image: { uploadFile }, gallery: { uploadFile } })
+```
+
+Загрузчик удаляет дубликаты и сохраняет порядок первого появления типов в переданном списке или документе. Если источник не передан, используется порядок встроенного каталога. Неизвестные типы приводят к ошибке. Контракт плагина, история, стили, локализация, жизненный цикл и безопасность описаны в последовательном руководстве VitePress.
+
+## Разработка плагинов
+
+Последовательное руководство VitePress описывает обязательный контракт, необязательные возможности, границы команд, сопоставление текстовых полей, стили, локализацию, жизненный цикл, безопасность и контракт соответствующего рендерера.

package/dist/plugins/async.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Return every block type supported by the asynchronous plugin registry.
+ * @returns {import('../renderer/types.js').BlockType[]}
+ */
+export function getAsyncBlockPluginTypes(): import("../renderer/types.js").BlockType[];
+/**
+ * Resolve one block plugin constructor without instantiating it.
+ * @param {string} type
+ * @returns {Promise<AsyncBlockPluginConstructor>}
+ */
+export function loadBlockPlugin(type: string): Promise<AsyncBlockPluginConstructor>;
+/**
+ * Preload unique plugin constructors for a type list or an existing document.
+ * The input document remains untouched if a chunk fails to load.
+ * @param {readonly string[] | { blocks?: readonly { type: string }[] }} [source]
+ * @returns {Promise<Map<string, AsyncBlockPluginConstructor>>}
+ */
+export function preloadBlockPlugins(source?: readonly string[] | {
+    blocks?: readonly {
+        type: string;
+    }[];
+}): Promise<Map<string, AsyncBlockPluginConstructor>>;
+/**
+ * Create a deterministic plugin preset after every requested chunk loaded.
+ * @param {readonly string[] | { blocks?: readonly { type: string }[] }} [source]
+ * @param {Partial<Record<import('../renderer/types.js').BlockType, Record<string, unknown>>>} [configs]
+ * @returns {Promise<import('../core/types.js').BlockPlugin[]>}
+ */
+export function createBlockPluginsAsync(source?: readonly string[] | {
+    blocks?: readonly {
+        type: string;
+    }[];
+}, configs?: Partial<Record<import("../renderer/types.js").BlockType, Record<string, unknown>>>): Promise<import("../core/types.js").BlockPlugin[]>;
+export type AsyncBlockPluginConstructor = new (config?: Record<string, unknown>) => import("../core/types.js").BlockPlugin;
+export type BlockPluginLoader = () => Promise<AsyncBlockPluginConstructor>;

package/dist/plugins/async.js

@@ -0,0 +1,79 @@
+// @ts-check
+import { BLOCK_TYPES } from '../shared/blockTypes.js'
+
+/** @typedef {new (config?: Record<string, unknown>) => import('../core/types').BlockPlugin} AsyncBlockPluginConstructor */
+/** @typedef {() => Promise<AsyncBlockPluginConstructor>} BlockPluginLoader */
+
+/** @type {Record<import('../renderer/types').BlockType, BlockPluginLoader>} */
+const pluginLoaders = {
+  paragraph: () => import('./paragraph/index.js').then(module => module.Paragraph),
+  heading: () => import('./heading/index.js').then(module => module.Heading),
+  list: () => import('./list/index.js').then(module => module.List),
+  quote: () => import('./quote/index.js').then(module => module.Quote),
+  code: () => import('./code/index.js').then(module => module.Code),
+  image: () => import('./image/index.js').then(module => module.Image),
+  delimiter: () => import('./delimiter/index.js').then(module => module.Delimiter),
+  table: () => import('./table/index.js').then(module => module.Table),
+  checklist: () => import('./checklist/index.js').then(module => module.Checklist),
+  warning: () => import('./warning/index.js').then(module => module.Warning),
+  embed: () => import('./embed/index.js').then(module => module.Embed),
+  raw: () => import('./raw/index.js').then(module => module.Raw),
+  gallery: () => import('./gallery/index.js').then(module => module.Gallery),
+  carousel: () => import('./carousel/index.js').then(module => module.CarouselBlock),
+  attaches: () => import('./attaches/index.js').then(module => module.Attaches),
+  linkPreview: () => import('./link-preview/index.js').then(module => module.LinkPreview),
+  toggle: () => import('./toggle/index.js').then(module => module.Toggle),
+  columns: () => import('./columns/index.js').then(module => module.Columns),
+  spoiler: () => import('./spoiler/index.js').then(module => module.Spoiler),
+  poll: () => import('./poll/index.js').then(module => module.Poll),
+  person: () => import('./person/index.js').then(module => module.Person),
+}
+
+/** @param {readonly string[] | { blocks?: readonly { type: string }[] } | undefined} source */
+function requestedTypes(source) {
+  const document = /** @type {{ blocks?: readonly { type: string }[] } | undefined} */ (source)
+  const types = Array.isArray(source) ? source : document?.blocks?.map(block => block.type) ?? BLOCK_TYPES
+  return [...new Set(types)]
+}
+
+/**
+ * Return every block type supported by the asynchronous plugin registry.
+ * @returns {import('../renderer/types').BlockType[]}
+ */
+export function getAsyncBlockPluginTypes() {
+  return [...BLOCK_TYPES]
+}
+
+/**
+ * Resolve one block plugin constructor without instantiating it.
+ * @param {string} type
+ * @returns {Promise<AsyncBlockPluginConstructor>}
+ */
+export async function loadBlockPlugin(type) {
+  const loader = pluginLoaders[/** @type {import('../renderer/types').BlockType} */ (type)]
+  if (!loader) throw new RangeError(`Unknown editor block plugin type: ${type}`)
+  return loader()
+}
+
+/**
+ * Preload unique plugin constructors for a type list or an existing document.
+ * The input document remains untouched if a chunk fails to load.
+ * @param {readonly string[] | { blocks?: readonly { type: string }[] }} [source]
+ * @returns {Promise<Map<string, AsyncBlockPluginConstructor>>}
+ */
+export async function preloadBlockPlugins(source) {
+  const types = requestedTypes(source)
+  const constructors = await Promise.all(types.map(loadBlockPlugin))
+  return new Map(types.map((type, index) => [type, constructors[index]]))
+}
+
+/**
+ * Create a deterministic plugin preset after every requested chunk loaded.
+ * @param {readonly string[] | { blocks?: readonly { type: string }[] }} [source]
+ * @param {Partial<Record<import('../renderer/types').BlockType, Record<string, unknown>>>} [configs]
+ * @returns {Promise<import('../core/types').BlockPlugin[]>}
+ */
+export async function createBlockPluginsAsync(source, configs = {}) {
+  const constructors = await preloadBlockPlugins(source)
+  return [...constructors].map(([type, Plugin]) => new Plugin(configs[/** @type {import('../renderer/types').BlockType} */ (type)]))
+}

package/dist/plugins/attaches/README.md

@@ -0,0 +1,86 @@
+# Attaches block plugin
+
+One or more downloadable files with selectable presentation variants.
+
+## Install and register
+
+```bash
+npm install @shelamkoff/rector
+```
+
+```js
+import { createEditor } from '@shelamkoff/rector'
+import { Attaches } from '@shelamkoff/rector/plugins/attaches'
+import '@shelamkoff/rector/styles/editor.css'
+
+const editor = createEditor({
+  holder: document.querySelector('#editor'),
+  plugins: [new Attaches()],
+})
+```
+
+The registered block type is `attaches`. The class is also exported by the complete `@shelamkoff/rector/plugins` preset and can be loaded through `@shelamkoff/rector/plugins/async`.
+
+## Data
+
+```json
+{
+  "files": [{ "url": "https://cdn.example/a.pdf", "name": "a.pdf", "size": 1024, "extension": "pdf" }],
+  "variant": "f"
+}
+```
+
+### Field reference
+
+| Field | Required | Meaning and constraints |
+| --- | --- | --- |
+| `files` | yes | Non-empty array. Saves always use this plural form. |
+| `files[].url` | yes | Canonical URL allowed by the download policy. |
+| `files[].name`, `files[].extension` | yes | Strings used for the displayed file name and extension. |
+| `files[].size` | yes | Finite non-negative byte count. |
+| `variant` | no | Presentation variant `a`, `b`, `f`, or `g`; the plugin default is `f`. |
+
+Legacy input may contain one `file` object instead of `files`; the next save normalizes it to the array contract. Callback URLs must pass the shared download URL policy. Without `uploadFile`, selected files use temporary object URLs; configure an uploader for data that must survive cleanup or page reload.
+
+## Configuration
+
+Every built-in block plugin accepts two style ownership options: `injectStyles?: boolean` defaults to `true`; set it to `false` when the host bundles that plugin's CSS. `css?: string` adds one host-provided stylesheet URL after the plugin default, or acts as the replacement URL when default injection is disabled.
+
+`uploadFile?: (file: File, context: { signal: AbortSignal }) => Promise<{ url: string; size?: number }>` persists a selected browser file. `actions?: Array<{ icon?; label; handler({ signal }): Promise<Array<{ url; name; size?; extension? }> | null> }>` adds application file sources such as a media library. Both callbacks must respect the supplied abort signal.
+
+## Application file sources
+
+Use `uploadFile` for browser `File` objects and `actions` for existing downloads selected from a file library, cloud drive, or another application-owned catalog. An action may return several files in one selection.
+
+```js
+const attaches = new Attaches({
+  actions: [{
+    label: 'File library',
+    async handler({ signal }) {
+      const assets = await openFileLibrary({ multiple: true, signal })
+      return assets?.map(asset => ({
+        url: asset.downloadUrl,
+        name: asset.name,
+        size: asset.size,
+        extension: asset.extension,
+      })) ?? null
+    },
+  }],
+})
+```
+
+`url` and `name` are required. `size` and `extension` are optional; the extension is inferred from `name` when omitted. Return `null` when selection is cancelled. The complete selection becomes one undo/redo step. See [File sources and media libraries](https://shelamkoff.github.io/editor/guide/file-sources) for upload, cancellation, validation, and reusable adapter guidance.
+
+## Capabilities
+
+Multiple files; device upload and application sources; editable names; presentation variants; listener/object-URL cleanup; stale results are ignored after disposal.
+
+## Undo, lifecycle, and styles
+
+User actions exposed by the plugin enter the command pipeline through the supplied `context.mutate()` capability, so each completed action is one undo/redo step. The editor reference-counts the plugin's declared stylesheet URLs. Removing a block calls its cleanup hook; removing the editor calls `destroy()` for every remaining block and then releases shared plugin resources.
+
+Do not remove the editor holder without first calling `editor.destroy()`.
+
+## Document output
+
+Use the matching renderer from `@shelamkoff/rector/renderer/renderers/attaches`. The VitePress guide documents configuration, commands and history, extension contracts, document migrations, styling, security, and lifecycle in a sequential form.

package/dist/plugins/attaches/README.ru.md

@@ -0,0 +1,87 @@
+# Блочный плагин Attaches
+
+Один или несколько скачиваемых файлов с вариантами представления.
+
+## Установка и регистрация
+
+```bash
+npm install @shelamkoff/rector
+```
+
+```js
+import { createEditor } from '@shelamkoff/rector'
+import { Attaches } from '@shelamkoff/rector/plugins/attaches'
+import '@shelamkoff/rector/styles/editor.css'
+
+const editor = createEditor({
+  holder: document.querySelector('#editor'),
+  plugins: [new Attaches()],
+})
+```
+
+Тип блока — `attaches`. Класс также экспортируется общей точкой входа `@shelamkoff/rector/plugins` и может загружаться по типу документа через `@shelamkoff/rector/plugins/async`.
+
+## Данные
+
+```json
+{
+  "files": [{ "url": "https://cdn.example/a.pdf", "name": "a.pdf", "size": 1024, "extension": "pdf" }],
+  "variant": "f"
+}
+```
+
+### Поля данных
+
+| Поле | Обязательное | Назначение и ограничения |
+| --- | --- | --- |
+| `files` | да | Непустой массив. Сохранение всегда использует эту форму во множественном числе. |
+| `files[].url` | да | Канонический адрес, разрешённый политикой загрузок. |
+| `files[].name`, `files[].extension` | да | Строки с отображаемым именем и расширением файла. |
+| `files[].size` | да | Конечный неотрицательный размер в байтах. |
+| `variant` | нет | Вариант представления `a`, `b`, `f` или `g`; по умолчанию плагин использует `f`. |
+
+Старые данные могут содержать один объект `file` вместо `files`; следующее сохранение нормализует его в массив. Адреса из обработчиков должны пройти общую политику загрузок. Без `uploadFile` выбранные файлы используют временные объектные URL, поэтому для данных, которые должны пережить очистку или перезагрузку страницы, настройте постоянное хранилище.
+
+## Конфигурация
+
+Каждый встроенный блочный плагин принимает два параметра владения стилями: `injectStyles?: boolean` по умолчанию равен `true`; укажите `false`, если приложение само включает CSS этого плагина. `css?: string` добавляет URL таблицы стилей приложения после стандартной, а при отключённой стандартной инъекции служит URL замены.
+
+`uploadFile(file, { signal })` сохраняет выбранный браузерный файл и возвращает `{ url, size? }`; исходное имя и определённое расширение сохраняются. `actions` добавляет источники приложения, например медиатеку, и возвращает массив `{ url, name, size?, extension? }` либо `null`. Оба вида обработчиков должны учитывать переданный `AbortSignal`, а возвращённые URL — пройти общую политику адресов загрузки.
+
+## Источники файлов приложения
+
+Используйте `uploadFile` для браузерных объектов `File`, а `actions` — для готовых файлов из файловой библиотеки, облачного диска или другого каталога приложения. Одно действие может вернуть несколько файлов.
+
+```js
+const attaches = new Attaches({
+  actions: [{
+    label: 'Библиотека файлов',
+    async handler({ signal }) {
+      const assets = await openFileLibrary({ multiple: true, signal })
+      return assets?.map(asset => ({
+        url: asset.downloadUrl,
+        name: asset.name,
+        size: asset.size,
+        extension: asset.extension,
+      })) ?? null
+    },
+  }],
+})
+```
+
+Поля `url` и `name` обязательны. `size` и `extension` необязательны; если расширение пропущено, оно определяется из `name`. При отмене выбора верните `null`. Весь выбор становится одним шагом отмены и повтора. Загрузка, отмена, проверка данных и общий адаптер описаны в разделе [«Источники файлов и медиатека»](https://shelamkoff.github.io/editor/ru/guide/file-sources).
+
+
+## Возможности
+
+Несколько файлов; редактируемые имена; варианты представления; источники файлов приложения; освобождение обработчиков и объектных URL; защита от устаревшего результата загрузки.
+
+## История, жизненный цикл и стили
+
+Действия плагина входят в конвейер команд через предоставленный контекст `mutate()`, поэтому одно завершённое действие создаёт один шаг отмены и повтора. Редактор подсчитывает владельцев объявленных URL стилей. Удаление блока вызывает его метод освобождения ресурсов; `editor.destroy()` освобождает оставшиеся блоки и общие ресурсы.
+
+Не удаляйте контейнер редактора до вызова `editor.destroy()`.
+
+## Вывод документа
+
+Используйте фабричную функцию из `@shelamkoff/rector/renderer/renderers/attaches`. Последовательное руководство VitePress описывает проверку данных, миграции, разработку расширений, диагностику, безопасность и стили.