@shelamkoff/rector 1.0.0

package/dist/renderer/inline.js

@@ -0,0 +1,61 @@
+// @ts-check
+import { highlightCode, loadHighlightRuntime } from '../shared/highlightRuntime.js'
+import { parseInline } from '../shared/sanitize/parseInline.js'
+
+/**
+ * Apply highlighting immediately when available, otherwise enhance the
+ * already-safe text node after the shared lazy runtime finishes loading.
+ * @param {HTMLElement} element
+ * @param {string} text
+ * @param {string} language
+ */
+function highlightElement(element, text, language) {
+  const apply = () => {
+    const result = highlightCode(text, language)
+    if (!result) return false
+    element.innerHTML = result.value
+    return true
+  }
+
+  if (apply()) return
+  element.textContent = text
+  void loadHighlightRuntime().then(apply).catch(() => {
+    element.textContent = text
+  })
+}
+
+/**
+ * Upgrade code elements that represent block code (contain newlines)
+ * with syntax highlighting. Mutates the fragment in place.
+ *
+ * Inline code (single line) is left as-is. It was already sanitized by
+ * parseInline and keeps its class/lang attributes.
+ *
+ * @param {DocumentFragment | HTMLElement} root
+ */
+function upgradeCodeBlocks(root) {
+  const codeEls = root.querySelectorAll('code')
+  for (const el of codeEls) {
+    const text = el.textContent || ''
+    if (!text.includes('\n')) continue
+
+    const lang = el.getAttribute('lang')
+    if (lang) {
+      highlightElement(el, text, lang)
+    } else {
+      el.textContent = text
+    }
+  }
+}
+
+/**
+ * Create inline parser function.
+ * @returns {import('./types').InlineParser}
+ */
+export function createInlineParser(_classPrefix) {
+  return (/** @type {string} */ text) => {
+    const fragment = parseInline(text)
+    upgradeCodeBlocks(fragment)
+    return fragment
+  }
+}

package/dist/renderer/locale/en.d.ts

@@ -0,0 +1,35 @@
+declare const _default: {
+    'renderer.spoiler.toggle': string;
+    'renderer.person.link': string;
+    'renderer.person.previous': string;
+    'renderer.person.next': string;
+    'renderer.code.copy': string;
+    'renderer.code.copied': string;
+    'renderer.attaches.download': string;
+    'renderer.attaches.downloadZip': string;
+    'renderer.attaches.files': {
+        one: string;
+        other: string;
+    };
+    'renderer.attaches.file': string;
+    'renderer.attaches.toggle': string;
+    'renderer.carousel.label': string;
+    'renderer.carousel.video': string;
+    'renderer.carousel.previous': string;
+    'renderer.carousel.next': string;
+    'renderer.carousel.page': string;
+    'renderer.carousel.slide': string;
+    'renderer.gallery.open': string;
+    'renderer.poll.selectOption': string;
+    'renderer.poll.vote': string;
+    'renderer.poll.loading': string;
+    'renderer.poll.submitting': string;
+    'renderer.poll.loadError': string;
+    'renderer.poll.emptyResults': string;
+    'renderer.poll.voters': string;
+    'renderer.poll.anonymousVoter': string;
+    'renderer.embed.play': string;
+    'renderer.embed.video': string;
+    __lang: string;
+};
+export default _default;

package/dist/renderer/locale/en.js

@@ -0,0 +1,29 @@
+import attaches from '../renderers/attaches/locale/en.js'
+import code from '../renderers/code/locale/en.js'
+import person from '../renderers/person/locale/en.js'
+import spoiler from '../renderers/spoiler/locale/en.js'
+
+export default {
+  'renderer.carousel.label': 'Content carousel',
+  'renderer.carousel.video': 'Video slide',
+  'renderer.carousel.previous': 'Previous slide',
+  'renderer.carousel.next': 'Next slide',
+  'renderer.carousel.page': 'Go to page',
+  'renderer.carousel.slide': 'Go to slide',
+  'renderer.gallery.open': 'Open image',
+  'renderer.poll.selectOption': 'Select option',
+  'renderer.poll.vote': 'Vote',
+  'renderer.poll.loading': 'Loading results…',
+  'renderer.poll.submitting': 'Submitting…',
+  'renderer.poll.loadError': 'Could not load poll results',
+  'renderer.poll.emptyResults': 'No votes yet',
+  'renderer.poll.voters': 'Voters',
+  'renderer.poll.anonymousVoter': 'Anonymous voter',
+  'renderer.embed.play': 'Play video',
+  'renderer.embed.video': 'Video',
+  __lang: 'en',
+  ...attaches,
+  ...code,
+  ...person,
+  ...spoiler,
+}

package/dist/renderer/locale/ru.d.ts

@@ -0,0 +1,37 @@
+declare const _default: {
+    'renderer.embed.play': string;
+    'renderer.embed.video': string;
+    'renderer.spoiler.toggle': string;
+    'renderer.person.link': string;
+    'renderer.person.previous': string;
+    'renderer.person.next': string;
+    'renderer.code.copy': string;
+    'renderer.code.copied': string;
+    'renderer.attaches.download': string;
+    'renderer.attaches.downloadZip': string;
+    'renderer.attaches.files': {
+        one: string;
+        few: string;
+        many: string;
+        other: string;
+    };
+    'renderer.attaches.file': string;
+    'renderer.attaches.toggle': string;
+    'renderer.carousel.label': string;
+    'renderer.carousel.video': string;
+    'renderer.carousel.previous': string;
+    'renderer.carousel.next': string;
+    'renderer.carousel.page': string;
+    'renderer.carousel.slide': string;
+    'renderer.gallery.open': string;
+    'renderer.poll.selectOption': string;
+    'renderer.poll.vote': string;
+    'renderer.poll.loading': string;
+    'renderer.poll.submitting': string;
+    'renderer.poll.loadError': string;
+    'renderer.poll.emptyResults': string;
+    'renderer.poll.voters': string;
+    'renderer.poll.anonymousVoter': string;
+    __lang: string;
+};
+export default _default;

package/dist/renderer/locale/ru.js

@@ -0,0 +1,29 @@
+import attaches from '../renderers/attaches/locale/ru.js'
+import code from '../renderers/code/locale/ru.js'
+import person from '../renderers/person/locale/ru.js'
+import spoiler from '../renderers/spoiler/locale/ru.js'
+
+export default {
+  'renderer.carousel.label': 'Карусель материалов',
+  'renderer.carousel.video': 'Видеослайд',
+  'renderer.carousel.previous': 'Предыдущий слайд',
+  'renderer.carousel.next': 'Следующий слайд',
+  'renderer.carousel.page': 'Перейти к странице',
+  'renderer.carousel.slide': 'Перейти к слайду',
+  'renderer.gallery.open': 'Открыть изображение',
+  'renderer.poll.selectOption': 'Выбрать вариант',
+  'renderer.poll.vote': 'Проголосовать',
+  'renderer.poll.loading': 'Загрузка результатов…',
+  'renderer.poll.submitting': 'Отправка голоса…',
+  'renderer.poll.loadError': 'Не удалось загрузить результаты опроса',
+  'renderer.poll.emptyResults': 'Голосов пока нет',
+  'renderer.poll.voters': 'Проголосовали',
+  'renderer.poll.anonymousVoter': 'Анонимный участник',
+  __lang: 'ru',
+  ...attaches,
+  ...code,
+  ...person,
+  ...spoiler,
+  'renderer.embed.play': 'Воспроизвести видео',
+  'renderer.embed.video': 'Видео',
+}

package/dist/renderer/renderers/README.md

@@ -0,0 +1,7 @@
+# Block renderers
+
+Every built-in editor block has a matching renderer. Import an individual factory from `@shelamkoff/rector/renderer/renderers/<path>`, the complete synchronous preset from `@shelamkoff/rector/renderer/renderers`, or lazy factories from `@shelamkoff/rector/renderer/renderers/async`.
+
+Renderer objects return DOM, declare stylesheet URLs, optionally map inline-widget fields, and expose deterministic per-element cleanup through the owning `EditorRenderer`.
+
+The VitePress rendering and extension guides document registration, inline parsing, stylesheet ownership, cleanup, and the custom renderer contract.

package/dist/renderer/renderers/README.ru.md

@@ -0,0 +1,5 @@
+# Рендереры блоков
+
+Для каждого встроенного блока существует фабричная функция. Импортируйте его из `@shelamkoff/rector/renderer/renderers/<path>`, полный готовый набор — из `@shelamkoff/rector/renderer/renderers`, ленивые фабричные функции — из `@shelamkoff/rector/renderer/renderers/async`.
+
+Фабричная функция создаёт DOM, объявляет фактически необходимые URL стилей (массив может быть пустым), при необходимости преобразует поля с виджетами и предоставляет освобождение ресурсов владельцу `EditorRenderer`. Контракт расширения описан в последовательном руководстве VitePress.

package/dist/renderer/renderers/async.d.ts

@@ -0,0 +1,51 @@
+/**
+ * List every built-in block type supported by the asynchronous renderer loader.
+ * @returns {import('../types.js').BlockType[]}
+ */
+export function getAsyncRendererTypes(): import("../types.js").BlockType[];
+/**
+ * Load the renderer factory for one built-in block type without creating it.
+ * @param {string} type
+ * @returns {Promise<RendererFactory>}
+ * @throws {RangeError} when `type` is not a built-in renderer type
+ */
+export function loadRendererFactory(type: string): Promise<RendererFactory>;
+/**
+ * Preload factories for explicit types or for the types present in a document.
+ * Duplicate type names are loaded once and map order follows first occurrence.
+ *
+ * @param {readonly string[] | { blocks?: readonly { type: string }[] }} [source]
+ * @returns {Promise<Map<string, RendererFactory>>}
+ */
+export function preloadRendererFactories(source?: readonly string[] | {
+    blocks?: readonly {
+        type: string;
+    }[];
+}): Promise<Map<string, RendererFactory>>;
+/**
+ * Load and create one built-in renderer.
+ *
+ * @param {string} type
+ * @param {string} classPrefix
+ * @param {Record<string, import('../../shared/localeTypes.js').LocaleValue>} [locale]
+ * @param {unknown} [config]
+ * @returns {Promise<import('../types.js').BlockRenderer>}
+ */
+export function createRendererAsync(type: string, classPrefix: string, locale?: Record<string, import("../../shared/localeTypes.js").LocaleValue>, config?: unknown): Promise<import("../types.js").BlockRenderer>;
+/**
+ * Load and create a renderer map for explicit types or document block types.
+ * Per-renderer configuration is selected from `configs` by block type.
+ *
+ * @param {string} classPrefix
+ * @param {Record<string, import('../../shared/localeTypes.js').LocaleValue>} [locale]
+ * @param {readonly string[] | { blocks?: readonly { type: string }[] }} [source]
+ * @param {Record<string, unknown>} [configs]
+ * @returns {Promise<Map<string, import('../types.js').BlockRenderer>>}
+ */
+export function createDefaultRenderersAsync(classPrefix: string, locale?: Record<string, import("../../shared/localeTypes.js").LocaleValue>, source?: readonly string[] | {
+    blocks?: readonly {
+        type: string;
+    }[];
+}, configs?: Record<string, unknown>): Promise<Map<string, import("../types.js").BlockRenderer>>;
+export type RendererFactory = (prefix: string, locale: Record<string, import("../../shared/localeTypes.js").LocaleValue>, config?: unknown) => import("../types.js").BlockRenderer;
+export type RendererLoader = () => Promise<RendererFactory>;

package/dist/renderer/renderers/async.js

@@ -0,0 +1,99 @@
+// @ts-check
+import { BLOCK_TYPES } from '../../shared/blockTypes.js'
+
+/** @typedef {(prefix: string, locale: Record<string, import('../../shared/localeTypes').LocaleValue>, config?: unknown) => import('../types').BlockRenderer} RendererFactory */
+/** @typedef {() => Promise<RendererFactory>} RendererLoader */
+
+/** @type {Record<import('../types').BlockType, RendererLoader>} */
+const rendererLoaders = {
+  paragraph: () => import('./paragraph/index.js').then(module => module.createParagraphRenderer),
+  heading: () => import('./heading/index.js').then(module => module.createHeaderRenderer),
+  list: () => import('./list/index.js').then(module => module.createListRenderer),
+  quote: () => import('./quote/index.js').then(module => module.createQuoteRenderer),
+  code: () => import('./code/index.js').then(module => module.createCodeRenderer),
+  image: () => import('./image/index.js').then(module => module.createImageRenderer),
+  delimiter: () => import('./delimiter/index.js').then(module => module.createDelimiterRenderer),
+  table: () => import('./table/index.js').then(module => module.createTableRenderer),
+  checklist: () => import('./checklist/index.js').then(module => module.createChecklistRenderer),
+  warning: () => import('./warning/index.js').then(module => module.createWarningRenderer),
+  embed: () => import('./embed/index.js').then(module => module.createEmbedRenderer),
+  raw: () => import('./raw/index.js').then(module => module.createRawRenderer),
+  gallery: () => import('./gallery/index.js').then(module => module.createGalleryRenderer),
+  carousel: () => import('./carousel/index.js').then(module => module.createCarouselRenderer),
+  attaches: () => import('./attaches/index.js').then(module => module.createAttachesRenderer),
+  linkPreview: () => import('./link-preview/index.js').then(module => module.createLinkPreviewRenderer),
+  toggle: () => import('./toggle/index.js').then(module => module.createToggleRenderer),
+  columns: () => import('./columns/index.js').then(module => module.createColumnsRenderer),
+  spoiler: () => import('./spoiler/index.js').then(module => module.createSpoilerRenderer),
+  poll: () => import('./poll/index.js').then(module => module.createPollRenderer),
+  person: () => import('./person/index.js').then(module => module.createPersonRenderer),
+}
+
+/** @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)]
+}
+
+/**
+ * List every built-in block type supported by the asynchronous renderer loader.
+ * @returns {import('../types').BlockType[]}
+ */
+export function getAsyncRendererTypes() {
+  return [...BLOCK_TYPES]
+}
+
+/**
+ * Load the renderer factory for one built-in block type without creating it.
+ * @param {string} type
+ * @returns {Promise<RendererFactory>}
+ * @throws {RangeError} when `type` is not a built-in renderer type
+ */
+export async function loadRendererFactory(type) {
+  const loader = rendererLoaders[/** @type {import('../types').BlockType} */ (type)]
+  if (!loader) throw new RangeError(`Unknown editor renderer type: ${type}`)
+  return loader()
+}
+
+/**
+ * Preload factories for explicit types or for the types present in a document.
+ * Duplicate type names are loaded once and map order follows first occurrence.
+ *
+ * @param {readonly string[] | { blocks?: readonly { type: string }[] }} [source]
+ * @returns {Promise<Map<string, RendererFactory>>}
+ */
+export async function preloadRendererFactories(source) {
+  const types = requestedTypes(source)
+  const factories = await Promise.all(types.map(loadRendererFactory))
+  return new Map(types.map((type, index) => [type, factories[index]]))
+}
+
+/**
+ * Load and create one built-in renderer.
+ *
+ * @param {string} type
+ * @param {string} classPrefix
+ * @param {Record<string, import('../../shared/localeTypes').LocaleValue>} [locale]
+ * @param {unknown} [config]
+ * @returns {Promise<import('../types').BlockRenderer>}
+ */
+export async function createRendererAsync(type, classPrefix, locale = {}, config) {
+  const factory = await loadRendererFactory(type)
+  return factory(classPrefix, locale, config)
+}
+
+/**
+ * Load and create a renderer map for explicit types or document block types.
+ * Per-renderer configuration is selected from `configs` by block type.
+ *
+ * @param {string} classPrefix
+ * @param {Record<string, import('../../shared/localeTypes').LocaleValue>} [locale]
+ * @param {readonly string[] | { blocks?: readonly { type: string }[] }} [source]
+ * @param {Record<string, unknown>} [configs]
+ * @returns {Promise<Map<string, import('../types').BlockRenderer>>}
+ */
+export async function createDefaultRenderersAsync(classPrefix, locale = {}, source, configs = {}) {
+  const factories = await preloadRendererFactories(source)
+  return new Map([...factories].map(([type, factory]) => [type, factory(classPrefix, locale, configs[type])]))
+}

package/dist/renderer/renderers/attaches/README.md

@@ -0,0 +1,48 @@
+# Attaches renderer
+
+Renderer for the `attaches` block. It converts persisted block data into renderer-owned DOM.
+
+The `@shelamkoff/rector/renderer` entry contains the synchronous built-in preset, so `@shelamkoff/carousel` and `@shelamkoff/expose` must be installed before importing it. Passing `blockTypes: []` prevents default renderer construction but does not change ESM module resolution.
+
+## Usage
+
+```js
+import { createEditorRenderer } from '@shelamkoff/rector/renderer'
+import { createAttachesRenderer } from '@shelamkoff/rector/renderer/renderers/attaches'
+
+const renderer = createEditorRenderer({ classPrefix: 'article', blockTypes: [] })
+renderer.registerRenderer(createAttachesRenderer('article', {}))
+const rendererStyles = renderer.injectStyles()
+renderer.renderTo(documentData, document.querySelector('#article'))
+
+// When the mounted output is removed:
+renderer.destroy()
+rendererStyles.destroy()
+```
+
+## Typical data
+
+```json
+{
+  "files": [{ "url": "https://cdn.example/a.pdf", "name": "a.pdf", "size": 1024, "extension": "pdf" }],
+  "variant": "f"
+}
+```
+
+The [attaches plugin field reference](../../../plugins/attaches/README.md#field-reference) is the canonical persisted-data contract shared by the editor and renderer.
+
+Links use the download URL policy. Archive work, cancellation, object URLs, and interactive controls belong to the block and are released by `destroy()`. The renderer declares one stylesheet.
+
+## Archive helpers
+
+The renderer subpath also exports the same archive primitives used by its “download all” control:
+
+- `ARCHIVE_LIMITS` is an immutable object with `files` (50), `fileBytes` (25 MiB), `totalBytes` (100 MiB), and `concurrency` (4). These are hard limits, not configuration options.
+- `sanitizeArchiveFilename(value, index?)` returns a flat portable ZIP-entry name. It removes path separators and control characters, avoids Windows reserved names, trims unsafe trailing characters, limits the result to 128 characters, and falls back to `file-${index + 1}`.
+- `downloadArchive(files, { signal })` fetches safe download URLs, skips individual network failures, creates `files.zip`, starts a browser download, and resolves with no value. It rejects when cancelled, when a hard size/count limit is exceeded, or when no file can be archived. Pass an `AbortSignal`; the function requires browser `document`, `fetch`, `Blob`, and object-URL APIs.
+
+Files with rejected URL schemes are omitted. Filenames are made unique inside an archive. The helper does not return the generated `Blob` and does not upload or persist anything.
+
+When styles are declared, the explicit `EditorRenderer.injectStyles()` call shown above acquires them and its returned owner releases them.
+
+The VitePress guide documents renderer ownership, inline widget reconstruction, styles, cleanup, and security boundaries.

package/dist/renderer/renderers/attaches/README.ru.md

@@ -0,0 +1,48 @@
+# Рендерер Attaches
+
+Преобразует сохранённый блок `attaches` в принадлежащий рендереру DOM.
+
+Синхронная точка входа `@shelamkoff/rector/renderer` включает все встроенные рендереры, поэтому до её импорта установите `@shelamkoff/carousel` и `@shelamkoff/expose`. Значение `blockTypes: []` отключает создание встроенных рендереров, но не меняет правила разрешения модулей ESM.
+
+## Использование
+
+```js
+import { createEditorRenderer } from '@shelamkoff/rector/renderer'
+import { createAttachesRenderer } from '@shelamkoff/rector/renderer/renderers/attaches'
+
+const renderer = createEditorRenderer({ classPrefix: 'article', blockTypes: [] })
+renderer.registerRenderer(createAttachesRenderer('article', {}))
+const rendererStyles = renderer.injectStyles()
+renderer.renderTo(documentData, document.querySelector('#article'))
+
+// При удалении добавленного результата:
+renderer.destroy()
+rendererStyles.destroy()
+```
+
+## Типичные данные
+
+```json
+{
+  "files": [{ "url": "https://cdn.example/a.pdf", "name": "a.pdf", "size": 1024, "extension": "pdf" }],
+  "variant": "f"
+}
+```
+
+Канонический контракт сохраняемых данных, общий для редактора и рендерера, приведён в [справочнике полей плагина вложений](../../../plugins/attaches/README.ru.md#поля-данных).
+
+Ссылки проходят политику URL для загрузок. Создание архива, отмена запросов, объектные URL и элементы управления принадлежат блоку и освобождаются в `destroy()`. Рендерер объявляет одну таблицу стилей.
+
+## Вспомогательные средства архива
+
+Точка входа рендерера также экспортирует средства, которые использует кнопка загрузки всех вложений:
+
+- `ARCHIVE_LIMITS` — неизменяемый объект с полями `files` (50), `fileBytes` (25 МиБ), `totalBytes` (100 МиБ) и `concurrency` (4). Это жёсткие ограничения, а не параметры настройки.
+- `sanitizeArchiveFilename(value, index?)` возвращает плоское переносимое имя элемента архива `.zip`. Функция удаляет разделители пути и управляющие символы, не допускает имена, зарезервированные операционной системой `Windows`, убирает небезопасные символы в конце, ограничивает результат 128 символами и при необходимости возвращает `file-${index + 1}`.
+- `downloadArchive(files, { signal })` получает файлы только по разрешённым адресам, пропускает отдельные сетевые ошибки, создаёт `files.zip`, запускает загрузку в браузере и завершается без возвращаемого значения. Функция отклоняет промис при отмене, превышении жёсткого ограничения размера или количества, а также когда в архив не удалось добавить ни одного файла. Передавайте `AbortSignal`; необходимы браузерные API `document`, `fetch`, `Blob` и объектных URL.
+
+Файлы с запрещённой схемой адреса исключаются, а совпадающие имена делаются уникальными внутри архива. Функция не возвращает созданный `Blob`, ничего не загружает на сервер и не сохраняет данные приложения.
+
+Если рендерер объявляет стили, показанный выше явный вызов `EditorRenderer.injectStyles()` подключает их, а возвращённый владелец освобождает.
+
+Жизненный цикл, восстановление внутристрочных виджетов, стили и границы безопасности описаны в последовательном руководстве VitePress.

package/dist/renderer/renderers/attaches/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Convert an untrusted attachment name into a flat, portable ZIP entry name.
+ * @param {unknown} value
+ * @param {number} [index]
+ * @returns {string}
+ */
+export function sanitizeArchiveFilename(value: unknown, index?: number): string;
+/**
+ * Download attachments and package them into one ZIP archive.
+ * @param {Array<{url: string, name: string, size?: number}>} files
+ * @param {{ signal: AbortSignal }} context
+ * @returns {Promise<void>}
+ */
+export function downloadArchive(files: Array<{
+    url: string;
+    name: string;
+    size?: number;
+}>, { signal }: {
+    signal: AbortSignal;
+}): Promise<void>;
+/**
+ * Create the attachment-list renderer and its archive-download lifecycle.
+ * @param {string} classPrefix
+ * @param {Record<string, import('../../../shared/localeTypes.js').LocaleValue>} locale
+ * @returns {import('../../types.js').BlockRenderer<import('../../types.js').AttachesBlock>}
+ */
+export function createAttachesRenderer(classPrefix: string, locale: Record<string, import("../../../shared/localeTypes.js").LocaleValue>): import("../../types.js").BlockRenderer<import("../../types.js").AttachesBlock>;
+/**
+ * Hard safety and concurrency limits used by {@link downloadArchive}.
+ * Values are expressed as file counts or bytes and are immutable.
+ */
+export const ARCHIVE_LIMITS: Readonly<{
+    files: 50;
+    fileBytes: number;
+    totalBytes: number;
+    concurrency: 4;
+}>;