@pgcorp/ui-kit 0.9.0 → 0.10.1

package/docs/getting-started.md

@@ -5,16 +5,17 @@
 ### Установка
 
 ```bash
-npm install @pgcorp/ui-kit vue pinia vue-router
+npm install @pgcorp/ui-kit @vue/devtools-api vue pinia vue-router
 ```
 
-UI-kit поставляется как Vue 3 SFC/TypeScript package для Vite-based приложений.
-Consumer отвечает за единственные экземпляры `vue`, `pinia` и `vue-router`.
+UI-kit поставляется как собранные Vue 3 ESM-модули и declaration-файлы для
+Vite-based приложений. Consumer отвечает за единственные экземпляры `vue`,
+`pinia`, `@vue/devtools-api` и `vue-router`.
 
 ### Подключение
 
-UI-kit публикует source-SFC и использует Tailwind 4 utilities. Подключите Tailwind
-и package integration entrypoint в корневом CSS приложения:
+UI-kit публикует собранные component-модули и использует Tailwind 4 utilities.
+Подключите Tailwind и package integration entrypoint в корневом CSS приложения:
 
 ```css
 @import "tailwindcss";
@@ -39,6 +40,94 @@ import App from './App.vue'
 createApp(App).use(createPinia()).use(router).mount('#app')
 ```
 
+### Локаль UI-kit
+
+Без provider UI-kit использует `ru`. Для локали конкретного Vue subtree
+оберните его в DOM-less `SUiKitLocaleProvider`. Поддерживаются `en`, `ru`,
+`zh-CN` и `zh-TW`:
+
+```vue
+<script setup lang="ts">
+import SUiKitLocaleProvider from '@pgcorp/ui-kit/shared/containers/SUiKitLocaleProvider.vue'
+import type { UiKitLocale } from '@pgcorp/ui-kit/composables/useUiKitLocale'
+
+const locale: UiKitLocale = 'en'
+</script>
+
+<template>
+  <SUiKitLocaleProvider :locale="locale">
+    <AppWorkspace />
+  </SUiKitLocaleProvider>
+</template>
+```
+
+Provider локализует только текст, принадлежащий UI-kit: labels controls,
+assistive names, loading/empty copy и системные UI-сообщения. Доменные данные,
+заголовки экранов и пользовательский контент передаются consumer-ом уже на
+нужном языке. Вложенный provider наследует locale и messages ближайшего
+родителя; prop `messages` принимает типизированный deep-partial override для
+своего subtree. Неизвестная locale, неизвестный ключ override или неверные
+параметры интерполяции завершаются явной диагностикой.
+
+### Controlled-уведомления
+
+`SControlledToastViewport` принимает readonly-массив сериализуемых records.
+Consumer владеет ID, порядком, application state и durable history; viewport не
+изменяет входной массив. Действия records содержат только ID, label и appearance,
+без callback-полей.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import SControlledToastViewport from '@pgcorp/ui-kit/shared/data-display/SControlledToastViewport.vue'
+import type {
+  SToastActionIntent,
+  SToastDismissIntent,
+  SToastPresentation,
+} from '@pgcorp/ui-kit/shared/data-display/toast'
+
+const notifications = ref<readonly SToastPresentation[]>([
+  {
+    id: 'sync-ready',
+    severity: 'success',
+    title: 'Синхронизация завершена',
+    message: 'Данные рабочего пространства обновлены.',
+    actions: [{ id: 'open', label: 'Открыть', appearance: 'outline' }],
+  },
+])
+const selectedAction = ref<SToastActionIntent | null>(null)
+
+function dismiss(intent: SToastDismissIntent): void {
+  notifications.value = notifications.value.filter(({ id }) => id !== intent.id)
+}
+
+function act(intent: SToastActionIntent): void {
+  selectedAction.value = intent
+}
+</script>
+
+<template>
+  <SControlledToastViewport
+    :notifications="notifications"
+    accessible-label="Системные уведомления"
+    lifetime-owner="consumer"
+    position="top-end"
+    @dismiss="dismiss"
+    @action="act"
+  />
+</template>
+```
+
+`lifetime-owner="consumer"` не создаёт auto-dismiss timers. В режиме
+`viewport` record задаёт `durationMs`; истечение эмитит `lifetime-expired`, а
+consumer удаляет record. Hover и focus приостанавливают оставшееся время.
+Удаление record и unmount очищают связанные timers.
+
+Для автономного сценария разместите `SToastContainer` один раз в app root и
+вызывайте `useNotifier`. Его store принадлежит конкретному Pinia root, хранит
+100 последних history records и очищает timers при `$dispose()` или `$reset()`.
+Не создавайте локальную копию notifier store с тем же Pinia ID.
+
 Каждый компонент импортируется через точный публичный subpath:
 
 ```ts
@@ -59,17 +148,17 @@ monorepo и без копирования файлов UI-kit. TypeScript и Vue
 ### Installation
 
 ```bash
-npm install @pgcorp/ui-kit vue pinia vue-router
+npm install @pgcorp/ui-kit @vue/devtools-api vue pinia vue-router
 ```
 
-The UI kit is distributed as a Vue 3 SFC/TypeScript package for Vite-based
-applications. The consumer owns the single `vue`, `pinia`, and `vue-router`
-instances.
+The UI kit is distributed as built Vue 3 ESM modules and declaration files for
+Vite-based applications. The consumer owns the single `vue`, `pinia`,
+`@vue/devtools-api`, and `vue-router` instances.
 
 ### Setup
 
-The UI kit publishes source SFCs and uses Tailwind 4 utilities. Import Tailwind
-and the package integration entrypoint from the application's root CSS:
+The UI kit publishes built component modules and uses Tailwind 4 utilities.
+Import Tailwind and the package integration entrypoint from the application's root CSS:
 
 ```css
 @import "tailwindcss";
@@ -94,6 +183,53 @@ import App from './App.vue'
 createApp(App).use(createPinia()).use(router).mount('#app')
 ```
 
+### UI-kit locale
+
+Without a provider, the UI kit uses `ru`. Wrap a Vue subtree in the DOM-less
+`SUiKitLocaleProvider` to select its locale. Supported locales are `en`, `ru`,
+`zh-CN`, and `zh-TW`:
+
+```vue
+<script setup lang="ts">
+import SUiKitLocaleProvider from '@pgcorp/ui-kit/shared/containers/SUiKitLocaleProvider.vue'
+import type { UiKitLocale } from '@pgcorp/ui-kit/composables/useUiKitLocale'
+
+const locale: UiKitLocale = 'en'
+</script>
+
+<template>
+  <SUiKitLocaleProvider :locale="locale">
+    <AppWorkspace />
+  </SUiKitLocaleProvider>
+</template>
+```
+
+The provider localizes UI-kit-owned copy only: control labels, assistive names,
+loading and empty copy, and system UI messages. Domain data, screen titles, and
+user content are supplied by the consumer in the required language. A nested
+provider inherits the nearest parent's locale and messages; the `messages` prop
+accepts a typed deep-partial override for that subtree. An unknown locale,
+unknown override key, or invalid interpolation parameters fail with an explicit
+diagnostic.
+
+### Controlled notifications
+
+`SControlledToastViewport` accepts a readonly array of serializable records.
+The consumer owns IDs, ordering, application state, and durable history; the
+viewport never mutates the input array. Record actions contain IDs, labels, and
+an optional appearance without callback fields.
+
+Use `lifetime-owner="consumer"` when the application owns expiry; this mode
+creates no auto-dismiss timers. In `viewport` mode, a record supplies
+`durationMs`, expiry emits `lifetime-expired`, and the consumer removes the
+record. Hover and focus pause the remaining duration. Record removal and
+component unmount release associated timers.
+
+For the autonomous path, mount `SToastContainer` once at the application root
+and call `useNotifier`. Its store belongs to one Pinia root, retains 100 history
+records, and clears timers on `$dispose()` or `$reset()`. Do not create a local
+notifier store with the same Pinia ID.
+
 Import every component through an exact public subpath:
 
 ```ts

package/docs/public-api.md

@@ -13,7 +13,7 @@
 - `shared/data-display/*` — badges, tables, code, JSON, progress, status и tooltips;
 - `shared/navigation/*` — tabs, breadcrumbs, catalog navigation и wizard steps;
 - `shared/database/*`, `shared/graph/*`, `shared/persona/*` — доменные сложные поверхности;
-- `composables/*`, `stores/*`, `theme`, `variants`, `icons` — typed runtime modules;
+- `composables/*`, `stores/*`, `theme`, `variants`, `icons` — typed runtime modules, включая locale context;
 - `tailwind.css` — полный Tailwind 4 integration entrypoint;
 - `style.css`, `tokens.css`, `reference.css` — global styles, token-only и compile-time reference entrypoints.
 
@@ -22,12 +22,18 @@ methods. Внутренний DOM, CSS-классы и private modules не яв
 UI-kit-owned атрибуты `data-s-*` относятся к внутренней presentation boundary и
 не являются стабильными consumer selectors. Произвольные consumer-owned
 `data-*` остаются поддерживаемыми test/tour hooks canonical owner.
-Публичные source-SFC объявляют runtime props и events локально: consumer Vue
-compiler регистрирует их без межфайлового filesystem type resolver.
-Публикуемый production-source компилируется с `target/lib: ES2020`, совпадающим
-с baseline `@vue/tsconfig/tsconfig.dom.json`, и не требует скрытых полифиллов.
+Публичные component-subpaths разрешаются в собранные ESM-модули и declaration-
+файлы. Consumer type checker не компилирует внутренние SFC и не разрешает их
+runtime-зависимости через layout конкретного package manager. Сборка использует
+`target/lib: ES2020`, совпадающий с baseline `@vue/tsconfig/tsconfig.dom.json`,
+и не требует скрытых полифиллов.
 Типы таблицы импортируются из `shared/data-display/table`, типы графиков — из
-`shared/data-display/chart`. `SChart` объединяет line/area/bar/pie/donut,
+`shared/data-display/chart`, типы и чистая функция diff — из
+`shared/data-display/diff`. `SDiffViewer` принимает exact-text snapshots,
+показывает unified/split представление, виртуализирует строки и управляет
+вычислением в worker для больших входов. Смена source и unmount отменяют
+неактуальную работу; завершившийся устаревший результат не публикуется.
+`SChart` объединяет line/area/bar/pie/donut,
 responsive geometry, semantic palette и доступную таблицу данных. `SMetricCard`
 принимает компактный график через `#chart`. `SCodeBlock` сохраняет CodeMirror за
 async boundary; `presentation="plain"` является lightweight read-only контрактом
@@ -37,6 +43,30 @@ async boundary; `presentation="plain"` является lightweight read-only к
 `SActionListItem` держат primary activation и дополнительные controls
 sibling-элементами внутри одного chrome; `actionsLayout`/`trailingLayout`
 управляют inline, stacked и container-responsive раскладкой.
+`SUiKitLocaleProvider` задаёт `en | ru | zh-CN | zh-TW` для одного Vue subtree,
+а `composables/useUiKitLocale` экспортирует readonly context, полный список
+локалей и типы messages/overrides/ключей. Provider не создаёт DOM owner и
+поддерживает независимые локали в соседних app roots.
+`shared/data-display/SControlledToastViewport.vue` является controlled owner
+стека уведомлений; `shared/data-display/toast` экспортирует presentation records,
+action/dismiss/lifetime intents, position и lifetime types. `SToastContainer`
+является adapter над `stores/useNotifierStore`, а не вторым layout owner.
+`shared/data-display/SRichDocument.vue` отображает только валидированную
+`SRichDocumentV1` AST. `shared/data-display/richDocument` экспортирует закрытую
+модель, consumer-owned resource records, typed intents и validators со stable
+error code/path. Link-node поддерживает `current: true` для
+`aria-current="page"`; task lists, deletion, keyboard/sup/sub, disclosure и
+scoped footnotes выражаются отдельными serializable nodes. Raw HTML, VNodes,
+callbacks и trust flags не входят в API.
+`SButton.density="compact"` сохраняет semantic size hierarchy с hitbox
+`sm/md/lg = 32/36/40 px` и label typography `12/14/14 px`; тот же
+`density="compact"` у `SInputText` даёт совместимую геометрию поля без
+consumer CSS.
+`shared/data-display/SScrollViewport.vue` владеет accessible scroll region,
+разрешёнными осями, semantic block size, root-only keyboard navigation и
+ResizeObserver lifecycle. `shared/data-display/scrollViewport` экспортирует
+сериализуемое physical/semantic state и exposed API `focus`,
+`scrollToBoundary`, `reveal` без доступа к внутреннему DOM.
 
 ## English
 
@@ -51,7 +81,7 @@ Primary groups:
 - `shared/data-display/*` — badges, tables, code, JSON, progress, status, and tooltips;
 - `shared/navigation/*` — tabs, breadcrumbs, catalog navigation, and wizard steps;
 - `shared/database/*`, `shared/graph/*`, `shared/persona/*` — complex domain surfaces;
-- `composables/*`, `stores/*`, `theme`, `variants`, `icons` — typed runtime modules;
+- `composables/*`, `stores/*`, `theme`, `variants`, `icons` — typed runtime modules, including locale context;
 - `tailwind.css` — the complete Tailwind 4 integration entrypoint;
 - `style.css`, `tokens.css`, `reference.css` — global styles, token-only, and compile-time reference entrypoints.
 
@@ -60,12 +90,18 @@ methods. Internal DOM, CSS classes, and private modules are not API.
 UI-kit-owned `data-s-*` attributes belong to the internal presentation boundary
 and are not stable consumer selectors. Arbitrary consumer-owned `data-*`
 attributes remain supported test and tour hooks on the canonical owner.
-Public source SFCs declare runtime props and events locally, so the consumer Vue
-compiler registers them without a cross-file filesystem type resolver.
-Published production source compiles with the `target/lib: ES2020` baseline from
-`@vue/tsconfig/tsconfig.dom.json` and does not require implicit polyfills.
+Public component subpaths resolve to built ESM modules and declaration files.
+Consumer type checkers do not compile internal SFCs or resolve their runtime
+dependencies through a package-manager-specific layout. The build uses the
+`target/lib: ES2020` baseline from `@vue/tsconfig/tsconfig.dom.json` and does not
+require implicit polyfills.
 Table types are imported from `shared/data-display/table`; chart types are
-imported from `shared/data-display/chart`. `SChart` unifies
+imported from `shared/data-display/chart`; diff types and its pure computation
+function are imported from `shared/data-display/diff`. `SDiffViewer` accepts
+exact-text snapshots, renders unified or split presentation, virtualizes lines,
+and manages worker computation for large inputs. Source replacement and unmount
+cancel obsolete work, and a completed stale result is never published.
+`SChart` unifies
 line/area/bar/pie/donut charts, responsive geometry, the semantic palette, and
 an accessible data table. `SMetricCard` accepts a compact chart through
 `#chart`. `SCodeBlock` keeps CodeMirror behind an async boundary;
@@ -76,3 +112,28 @@ the editor runtime. `SChip.surface` owns action/link semantics, while
 compositions keep primary activation and additional controls as siblings inside
 one chrome; `actionsLayout`/`trailingLayout` control inline, stacked, and
 container-responsive layout.
+`SUiKitLocaleProvider` selects `en | ru | zh-CN | zh-TW` for one Vue subtree,
+while `composables/useUiKitLocale` exports the readonly context, the complete
+locale list, and message/override/key types. The provider renders no DOM owner
+and supports independent locales in adjacent application roots.
+`shared/data-display/SControlledToastViewport.vue` is the controlled owner of
+the notification stack; `shared/data-display/toast` exports presentation
+records, action/dismiss/lifetime intents, positions, and lifetime types.
+`SToastContainer` is an adapter over `stores/useNotifierStore`, not a second
+layout owner.
+`shared/data-display/SRichDocument.vue` renders validated `SRichDocumentV1` AST
+only. `shared/data-display/richDocument` exports the closed model,
+consumer-owned resource records, typed intents, and validators with stable
+error code/path diagnostics. Link nodes support `current: true` for
+`aria-current="page"`; task lists, deletion, keyboard/sup/sub, disclosure, and
+scoped footnotes use dedicated serializable nodes. Raw HTML, VNodes, callbacks,
+and trust flags are not part of the API.
+`SButton.density="compact"` keeps the semantic size hierarchy at
+`sm/md/lg = 32/36/40 px` with `12/14/14 px` label typography. The matching
+`SInputText.density="compact"` exposes the same field geometry without consumer
+CSS.
+`shared/data-display/SScrollViewport.vue` owns the accessible scroll region,
+enabled axes, semantic block size, root-only keyboard navigation, and
+ResizeObserver lifecycle. `shared/data-display/scrollViewport` exports
+serializable physical and semantic state plus the `focus`, `scrollToBoundary`,
+and `reveal` exposed API without access to internal DOM.

package/docs/rich-document.md

@@ -0,0 +1,232 @@
+# Безопасные rich documents / Safe rich documents
+
+## Назначение / Purpose
+
+`SRichDocument` отображает сериализуемый документ по закрытому контракту
+`SRichDocumentV1`. Компонент предназначен для содержимого, которое приходит из
+worker, backend или persisted state и должно содержать типографику, ссылки,
+таблицы, код, формулы, изображения, файлы и типизированные действия.
+
+`SRichDocument` renders a serializable document described by the closed
+`SRichDocumentV1` contract. It is intended for content received from a worker,
+backend, or persisted state that needs typography, links, tables, code, math,
+images, files, and typed actions.
+
+Markdown и HTML strings относятся к контракту `SDocBlock`. `SRichDocument` не
+принимает raw HTML, VNodes, callbacks, component names или trust flags.
+
+Markdown and HTML strings belong to the `SDocBlock` contract. `SRichDocument`
+does not accept raw HTML, VNodes, callbacks, component names, or trust flags.
+
+## Импорты / Imports
+
+```ts
+import SRichDocument from '@pgcorp/ui-kit/shared/data-display/SRichDocument.vue'
+import {
+  SRichDocumentContractError,
+  validateRichDocument,
+  validateRichDocumentResources,
+  type SRichDocumentActionIntent,
+  type SRichDocumentResource,
+  type SRichDocumentResourceActivate,
+  type SRichDocumentV1,
+} from '@pgcorp/ui-kit/shared/data-display/richDocument'
+```
+
+## Граница данных / Data boundary
+
+Внешний JSON проверяется в месте получения. Валидатор возвращает новый
+типизированный результат только после проверки версии, структуры, полей,
+лимитов, идентификаторов, ссылок на resources и URL policy. Renderer повторяет
+валидацию перед созданием DOM; это защищает прямое использование компонента, но
+не заменяет проверку на application boundary.
+
+Validate external JSON at the receiving boundary. The validator returns a
+typed result only after checking the version, structure, fields, limits, IDs,
+resource references, and URL policy. The renderer validates again before
+creating DOM; this protects direct component use but does not replace validation
+at the application boundary.
+
+```ts
+const document = validateRichDocument(workerMessage.document)
+const resources = validateRichDocumentResources(apiResponse.resources)
+```
+
+`SRichDocumentContractError` содержит стабильный `code`, точный `path` и
+диагностическое сообщение. Не исправляйте payload downstream и не отбрасывайте
+неизвестные nodes: ошибка означает несовместимый или опасный вход.
+
+`SRichDocumentContractError` exposes a stable `code`, an exact `path`, and a
+diagnostic message. Do not repair the payload downstream or drop unknown nodes:
+the error represents incompatible or unsafe input.
+
+```ts
+try {
+  const document = validateRichDocument(payload)
+  useDocument(document)
+} catch (error) {
+  if (error instanceof SRichDocumentContractError) {
+    reportContractFailure(error.code, error.path)
+  }
+  throw error
+}
+```
+
+Links принимают относительные application paths и `http:`, `https:`, `mailto:`,
+`tel:`. Resource records принимают относительные paths, `http:`, `https:` и
+`blob:`. Скриптовые, data, scheme-relative и неизвестные protocols отклоняются.
+Resources передаются отдельными consumer-owned records и связываются с AST по
+stable ID; UI-kit не читает filesystem и не выполняет URL самостоятельно.
+
+Links accept relative application paths plus `http:`, `https:`, `mailto:`, and
+`tel:`. Resource records accept relative paths, `http:`, `https:`, and `blob:`.
+Script, data, scheme-relative, and unknown protocols are rejected. Resources
+are supplied as separate consumer-owned records and joined to the AST by stable
+ID; the UI kit does not read the filesystem or activate URLs itself.
+
+## Модель документа / Document model
+
+`SRichDocumentV1` содержит `version: 1`, стабильный `id` и readonly `nodes`.
+Закрытая модель поддерживает:
+
+`SRichDocumentV1` contains `version: 1`, a stable `id`, and readonly `nodes`.
+The closed model supports:
+
+- paragraph, heading, strong, emphasis, inline code и links с optional
+  `current`-состоянием;
+- deletion, `keyboard`, superscript и subscript inline semantics;
+- ordered/unordered и task lists с inert checked-state и обязательной доступной
+  меткой каждого task checkbox;
+- quote, divider и keyboard-operable `disclosure` с текстовым summary;
+- scoped footnote reference/definition/backlink, где DOM targets вычисляет
+  renderer, а payload передаёт только stable footnote ID;
+- code blocks с optional language, line numbers и label;
+- inline/block math;
+- semantic tables и callouts;
+- image/file resources по ID;
+- action groups с serializable action IDs.
+
+Внутренняя навигация сносок — единственный link-like эффект, которым владеет
+renderer: адреса reference и backlink вычисляются из валидированных ID и
+instance-scoped DOM-префикса. Обычные `link`-узлы остаются управляемыми
+intent-действиями. Task checkbox отображает readonly-состояние документа и не
+эмитит обновления.
+
+Internal footnote navigation is the only link-like effect owned by the renderer:
+reference and backlink URLs are derived from validated IDs and an
+instance-scoped DOM prefix. Ordinary `link` nodes remain controlled intents.
+Task checkboxes are read-only document state and do not emit updates.
+
+```ts
+const document = {
+  version: 1,
+  id: 'release-notes',
+  nodes: [
+    {
+      type: 'heading',
+      level: 1,
+      children: [{ type: 'text', value: 'Release notes' }],
+    },
+    {
+      type: 'paragraph',
+      children: [{
+        type: 'link',
+        href: '/releases/current',
+        current: true,
+        children: [{ type: 'text', value: 'Current release' }],
+      }],
+    },
+    {
+      type: 'resource',
+      resourceId: 'report',
+      label: 'Open report',
+    },
+    {
+      type: 'actionGroup',
+      label: 'Review actions',
+      actions: [{ type: 'action', id: 'approve', label: 'Approve' }],
+    },
+  ],
+} as const satisfies SRichDocumentV1
+
+const resources = [{
+  id: 'report',
+  kind: 'file',
+  url: '/reports/release.pdf',
+  label: 'Release report',
+  mediaType: 'application/pdf',
+}] as const satisfies readonly SRichDocumentResource[]
+```
+
+## Controlled intents
+
+Ссылки, resources и actions не выполняют application effects. Компонент эмитит
+`link-activate`, `resource-activate` и `action` с `documentId`, точным node
+`path` и целевым ID/URL. Consumer проверяет разрешения, выполняет навигацию,
+скачивание или доменное действие.
+
+Links, resources, and actions never execute application effects. The component
+emits `link-activate`, `resource-activate`, and `action` with the `documentId`,
+exact node `path`, and target ID or URL. The consumer authorizes and performs
+navigation, download, or domain actions.
+
+`current: true` у link-node передаёт каноническому `SLink` состояние текущего
+назначения и публикует `aria-current="page"`. Поле описывает состояние
+навигации, но не запускает переход и не меняет typed intent.
+
+`current: true` on a link node delegates the current-destination state to the
+canonical `SLink` and publishes `aria-current="page"`. The field describes
+navigation state without triggering navigation or changing the typed intent.
+
+```vue
+<SRichDocument
+  :document="document"
+  :resources="resources"
+  accessible-label="Release notes"
+  @link-activate="openLink"
+  @resource-activate="openResource"
+  @action="runDocumentAction"
+/>
+```
+
+`accessible-label` обязателен и задаёт имя root article. Consumer-owned
+`data-*` разрешены как test/tour hooks; private classes и `data-s-*` не являются
+selector API.
+
+`accessible-label` is required and names the root article. Consumer-owned
+`data-*` are supported as test and tour hooks; private classes and `data-s-*`
+are not selector APIs.
+
+## Code, math, SSR и производительность
+
+Подсветка кода и KaTeX загружаются отдельными lazy chunks. Code block использует
+read-only token presentation, а не CodeMirror editor runtime. KaTeX работает с
+`trust: false` и создаёт HTML+MathML внутри leaf renderer. Невалидная формула
+показывает локализованную диагностируемую ошибку и не превращается в trusted
+markup.
+
+Syntax highlighting and KaTeX load as separate lazy chunks. Code blocks use a
+read-only token presentation rather than the CodeMirror editor runtime. KaTeX
+runs with `trust: false` and produces HTML+MathML inside a leaf renderer. An
+invalid formula produces a localized, diagnosable error and never becomes
+trusted markup.
+
+SSR выводит стабильный безопасный fallback для code/math. Client runtime после
+mount заменяет его подсвеченным кодом и формулой. Package не использует CDN и
+не выполняет document parser в main-thread component.
+
+SSR renders stable safe fallbacks for code and math. After mount, the client
+runtime replaces them with highlighted code and rendered math. The package uses
+no CDN and runs no document parser inside the main-thread component.
+
+## Версионирование / Versioning
+
+`version` является частью persisted/transport contract. Не добавляйте
+неизвестные поля и не подменяйте версию. Новая несовместимая схема получает
+новую public version и явную migration policy; silent compatibility branches
+не используются.
+
+`version` is part of the persisted and transport contract. Do not add unknown
+fields or rewrite the version. A new incompatible schema receives a new public
+version and an explicit migration policy; silent compatibility branches are not
+used.