@pgcorp/ui-kit 0.12.0 → 0.14.0

package/docs/rich-document.md

@@ -25,11 +25,13 @@ import SRichDocument from '@pgcorp/ui-kit/shared/data-display/SRichDocument.vue'
 import {
   SRichDocumentContractError,
   validateRichDocument,
+  validateRichDocumentModel,
   validateRichDocumentResources,
   type SRichDocumentActionIntent,
   type SRichDocumentResource,
   type SRichDocumentResourceActivate,
   type SRichDocumentV1,
+  type SRichHeadingPresentation,
 } from '@pgcorp/ui-kit/shared/data-display/richDocument'
 ```
 
@@ -50,6 +52,7 @@ at the application boundary.
 ```ts
 const document = validateRichDocument(workerMessage.document)
 const resources = validateRichDocumentResources(apiResponse.resources)
+const model = validateRichDocumentModel(document, resources)
 ```
 
 `SRichDocumentContractError` содержит стабильный `code`, точный `path` и
@@ -73,16 +76,21 @@ try {
 ```
 
 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.
+`tel:`, `irc:`, `ircs:`, `xmpp:`. Resource records принимают относительные paths,
+`http:`, `https:` и `blob:`. Только image resources допускают raster data URL
+по отдельному строгому контракту. Скриптовые, scheme-relative, неизвестные
+protocols, пробелы, control characters и backslashes отклоняются. HTTP(S) URLs
+не допускают userinfo (`username`/`password`); адресная семантика `irc:`,
+`ircs:` и `xmpp:` сохраняется без общего запрета символа `@`. Валидатор не
+переписывает URL, не исправляет protocol и не авторизует origin.
+
+Links accept relative application paths and the listed inert link protocols.
+Resources accept relative paths, HTTP(S), and blob URLs; image resources also
+support the strict raster data contract below. Script and unknown protocols,
+scheme-relative URLs, whitespace, control characters, and backslashes are
+rejected. HTTP(S) userinfo is forbidden; other admitted protocols retain their
+own address semantics. Validation preserves the exact URL and does not authorize
+its origin.
 
 ## Модель документа / Document model
 
@@ -94,28 +102,29 @@ The closed model supports:
 
 - paragraph, heading, strong, emphasis, inline code и links с optional
   `current`-состоянием;
-- deletion, `keyboard`, superscript и subscript inline semantics;
+- distinct attention/importance, idiomatic/emphasis и strikethrough/deletion;
+- insertion, quotation, sample, variable, monospace, ruby, rich
+  `keyboard`, superscript и subscript inline semantics;
+- `hardBreak`, inline images, passive inline/block groups и sections;
+- definition lists с отдельными rich terms и block descriptions;
 - 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;
+- quote, divider и keyboard-operable `disclosure` с текстовым или rich summary;
+- scoped anchors и повторные footnote reference/definition/backlink, где DOM
+  targets вычисляет renderer, а payload передаёт логические identities;
 - code blocks с optional language, line numbers и label;
 - inline/block math;
-- semantic tables и callouts;
-- image/file resources по ID;
+- прямоугольные rich tables и структурные semantic tables с head/body/foot;
+- callouts и image/file resources по ID, responsive image candidates;
 - action groups с serializable action IDs.
 
-Внутренняя навигация сносок — единственный link-like эффект, которым владеет
-renderer: адреса reference и backlink вычисляются из валидированных ID и
-instance-scoped DOM-префикса. Обычные `link`-узлы остаются управляемыми
-intent-действиями. Task checkbox отображает readonly-состояние документа и не
-эмитит обновления.
+Внутренняя навигация anchors и сносок принадлежит renderer. Обычные `link`-узлы
+остаются управляемыми intent-действиями. Task и inline 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.
+The renderer owns local anchor and footnote navigation. Ordinary links remain
+controlled intents. Task and inline checkboxes show read-only document state
+without emitting updates.
 
 ```ts
 const document = {
@@ -158,6 +167,342 @@ const resources = [{
 }] as const satisfies readonly SRichDocumentResource[]
 ```
 
+## Safe HTML projection profile
+
+Таблица задаёт явное преобразование всех 53 тегов
+[`hast-util-sanitize` defaultSchema 5.0.2](https://github.com/syntax-tree/hast-util-sanitize/blob/5.0.2/lib/schema.js)
+в закрытые типы кита. Это producer boundary, а не HTML allowlist renderer.
+Sanitized HAST не передаётся в `SRichDocument` напрямую. Legacy-теги получают
+указанный semantic owner; произвольные HTML attributes и визуальные свойства
+не становятся полями AST.
+
+The table defines an explicit producer projection, not a raw HTML renderer.
+Sanitized HAST is projected to the closed types; visual attributes, arbitrary
+attributes, and unsupported structure are not passed through.
+
+| Sanitized tag | Типизированное представление |
+| --- | --- |
+| `a` | `link`; local fragment → `anchorLink`; standalone ID target → metadata `anchorId` или `anchorTarget`; GFM footnote → explicit footnote node |
+| `b` | `attention` → `b`, без семантики strong importance |
+| `blockquote` | `quote`, optional `cite`, block children |
+| `br` | `hardBreak` внутри inline content |
+| `code` | `inlineCode`; внутри `pre` — содержимое `codeBlock` |
+| `dd` | `definitionList.entries[].descriptions[]`, block children и metadata |
+| `del` | `deletion`, optional `cite`/`dateTime` |
+| `details` | `disclosure`, `summary`, optional `summaryChildren`/`open`, block children |
+| `div` | `blockGroup` с block children |
+| `dl` | `definitionList` с `entries` |
+| `dt` | `definitionList.entries[].terms[]`, inline children и metadata |
+| `em` | `emphasis` |
+| `h1` | `heading`, `level: 1` |
+| `h2` | `heading`, `level: 2`; explicit sanitized assistive semantics → `presentation: 'assistive'` |
+| `h3` | `heading`, `level: 3` |
+| `h4` | `heading`, `level: 4` |
+| `h5` | `heading`, `level: 5` |
+| `h6` | `heading`, `level: 6` |
+| `hr` | `divider` |
+| `i` | `idiomatic` → `i`, без семантики emphasis |
+| `img` | `inlineImage` в phrasing content; `image` в block content; resource admission обязателен |
+| `input` | Только disabled checkbox: `inlineCheckbox` или task `listItem.checked`, с доступной меткой |
+| `ins` | `insertion`, optional `cite`/`dateTime` |
+| `kbd` | `keyboard` с `value` **либо** inline `children`, в том числе вложенными `keyboard` |
+| `li` | `listItem`; optional `value` только внутри ordered list |
+| `ol` | `list`, `ordered: true`, optional `start` |
+| `p` | `paragraph` с inline children |
+| `picture` | `inlineImage` или `image` с `pictureSources` и base `resourceId` |
+| `pre` | `codeBlock`, код как строка; optional language/label/line numbers |
+| `q` | `quotation`, optional `cite`, inline children |
+| `rp` | `rubyFallback`, только прямой child `ruby` |
+| `rt` | `rubyText`, только прямой child `ruby` |
+| `ruby` | `ruby`, последовательность inline base/`rubyText`/`rubyFallback` |
+| `s` | `strikethrough` → `s`, не deletion/edit |
+| `samp` | `sample` |
+| `section` | `section` с block children; GFM footnote section сохраняет label `heading` и explicit `footnoteDefinition` nodes |
+| `source` | `pictureSources[]`, только admitted typed candidate IDs |
+| `span` | `inlineGroup`; math-inline marker → `mathInline` с source строкой |
+| `strike` | `strikethrough` → `s` по явному producer projection contract |
+| `strong` | `strong` |
+| `sub` | `subscript` |
+| `summary` | `disclosure.summary` + optional rich `summaryChildren`; отдельный root-node не принимается |
+| `sup` | `superscript`; footnote markup → explicit `footnoteReference` |
+| `table` | `table` для прямоугольной модели или `semanticTable` для структуры/объединений |
+| `tbody` | `semanticTable.body`, optional `bodyMetadata` |
+| `td` | `semanticTable` cell `type: 'data'` |
+| `tfoot` | `semanticTable.foot`, optional `footMetadata` |
+| `th` | `semanticTable` cell `type: 'header'`; rich column header в прямоугольной модели |
+| `thead` | `semanticTable.head`, optional `headMetadata` |
+| `tr` | Row со своим `cells` и semantic metadata |
+| `tt` | `monospace` → `code` DOM owner, без obsolete `tt` |
+| `ul` | `list`, `ordered: false` |
+| `var` | `variable` |
+
+`tt` и `strike` относятся к
+[obsolete HTML features](https://html.spec.whatwg.org/multipage/obsolete.html#non-conforming-features).
+Проекция сохраняет явно выбранную семантику кита, а не воспроизводит obsolete
+HTML. Для исходника с иной доменной семантикой producer выбирает подходящий
+typed node до сериализации; downstream renderer не угадывает намерение.
+
+`attention`/`strong`, `idiomatic`/`emphasis`, `strikethrough`/`deletion` —
+отдельные типы с отдельными native semantic owners. Типография принадлежит
+киту, но визуальное сходство не заменяет значение HTML-элемента.
+
+## Представление заголовка / Heading presentation
+
+`heading.presentation` принимает `visible | assistive`; отсутствие поля
+означает `visible`. Тип экспортируется как `SRichHeadingPresentation`.
+`assistive` визуально скрывает сам native `h1`–`h6` вне normal flow: heading не
+создаёт строку или дополнительный gap в document/section/group layout. Уровень,
+phrasing content, `anchorId`, naming и description metadata сохраняются.
+`hidden`, `aria-hidden` и `display: none` для этого режима не применяются.
+
+Скрытый heading не содержит `link`, `anchorLink`, `footnoteReference`,
+`footnoteBacklink` или `inlineCheckbox`, в том числе внутри formatting/ruby.
+Нарушение даёт `invalid_structure` по пути конкретного потомка. Неизвестное
+значение presentation даёт `invalid_value` по `.presentation`. Passive semantic
+anchors и heading anchor сохраняют programmatic `tabindex=-1`, без Tab stop;
+явный `anchorLink` переводит фокус на локальный heading, следующая Tab продолжает
+native focus order. Native `th` content restrictions действуют независимо от
+presentation.
+
+A heading defaults to `visible`. The `assistive` presentation preserves its
+native level, content and scoped metadata without consuming a normal-flow row
+or layout gap. Interactive descendants are rejected recursively at their exact
+source path; programmatic semantic anchors remain available without adding Tab
+stops. The native table-header content model is unchanged.
+
+GFM producer проецирует admitted `h2#footnote-label` с семантикой `sr-only` в
+`heading` с `level: 2`, `presentation: 'assistive'` и точным sanitized
+`anchorId`. `section[data-footnotes]` сохраняет этот heading вместе с
+definitions; references сохраняют `describedBy` на тот же logical ID.
+Sanitizer prefix, текст и уровень не угадываются и не переписываются.
+Произвольный `className` не входит в AST: semantic mapping выполняется явно на
+producer boundary. Удаление label или `describedBy` не является преобразованием
+этого профиля.
+Default GFM footer не объявляет имя section: producer не добавляет ей
+`labelledBy` только из-за наличия hidden heading. Явные section naming fields
+сохраняются, если они присутствуют в source contract.
+
+```ts
+const footnoteLabel = {
+  type: 'heading',
+  level: 2,
+  presentation: 'assistive',
+  anchorId: 'user-content-footnote-label',
+  children: [{ type: 'text', value: 'Footnotes' }],
+} as const
+```
+
+A GFM projection retains its sanitized footnote-label heading, definitions and
+reference `describedBy` relationships. It maps admitted assistive semantics
+explicitly rather than forwarding raw CSS classes, dropping labels or changing
+sanitizer identities.
+The default GFM footer does not name its section. Section naming is preserved
+only when declared by the source; it is not inferred from the hidden heading.
+The [GFM footer implementation](https://github.com/syntax-tree/mdast-util-to-hast/blob/13.2.1/lib/footer.js)
+declares the heading, while the [reference implementation](https://github.com/syntax-tree/mdast-util-to-hast/blob/13.2.1/lib/handlers/footnote-reference.js)
+declares its description relationship.
+
+## Metadata, anchors и сноски / Metadata and local navigation
+
+`SRichSemanticMetadata` содержит только `anchorId`, `title`, `lang`, `direction`,
+`accessibleLabel`, `labelledBy`, `describedBy`. `lang` — well-formed BCP47 tag,
+`direction` — `ltr | rtl | auto`. Accessibility references — массивы logical
+anchor IDs того же документа. `class`, `style`, DOM `id`, `tabindex`, handlers,
+произвольные ARIA/HTML attrs не принимаются. Plain `text` и `hardBreak` не имеют
+semantic metadata.
+
+Metadata naming соответствует native semantics, а не применяется ко всем
+элементам одинаково. `SRichPassiveMetadata` запрещает `accessibleLabel` и
+`labelledBy`, сохраняя `anchorId`, `title`, `lang`, `direction`, `describedBy`.
+
+| Metadata owner | Допустимые naming fields |
+| --- | --- |
+| `strong`, `emphasis`, `attention`, `idiomatic`, `deletion`, `strikethrough`, `insertion`, `quotation`, `sample`, `monospace`, `variable`, `keyboard`, `superscript`, `subscript`, `inlineCode`, `inlineGroup`, `anchorTarget`, `rubyText`, `rubyFallback`, `paragraph`, `blockGroup` | Passive metadata: без `accessibleLabel`/`labelledBy` |
+| `mathInline`, `mathBlock`, `codeBlock`, `callout`, `resource`, `action`, `inlineCheckbox` | Passive wrapper metadata; собственные canonical `label`/`title` fields и control names принадлежат owner API |
+| `ruby`, `link`, `anchorLink`, `footnoteReference`, `footnoteBacklink`, `inlineImage`, `image`, `heading`, `list`, `listItem`, `quote`, `disclosure`, `footnoteDefinition`, `section`, `divider`, `table`, `semanticTable`, table row/cell/row-group metadata, definition list/term/description, `actionGroup` | Semantic metadata с `accessibleLabel`/`labelledBy`; owner сохраняет соответствующую native/group семантику |
+| `text`, `hardBreak` | Metadata отсутствует |
+
+Программная focus target identity (`tabindex=-1` внутри owner) не добавляет
+остановку последовательной Tab-навигации. Она не разрешает naming там, где
+семантика HTML запрещает accessible name.
+
+Одновременные `accessibleLabel` и `labelledBy` сохраняются на допустимом native
+owner: `aria-labelledby` имеет стандартный приоритет над `aria-label` при
+вычислении доступного имени. / Both explicit naming attributes are preserved;
+the browser applies native `aria-labelledby` precedence over `aria-label`.
+
+Metadata is closed and follows native naming rules. Passive owners reject
+accessible-label/labelled-by metadata; canonical control labels remain in their
+own API. Accessibility references resolve inside the same document. Consumers
+do not supply DOM IDs, classes, styles, tab stops, or handlers through nodes.
+
+Текстовый контент и доступное имя имеют разные контракты. Пустые `text`,
+paragraph, inline code и пустые ordered/unordered lists сохраняются как
+допустимая семантика документа. Canonical `summary`, column `header`, table и
+action-group `label`, action/resource/footnote/checkbox labels содержат хотя бы
+один непробельный символ. Optional naming fields проверяются по тому же правилу
+при наличии; валидатор сохраняет строку, а не обрезает её.
+
+`link` и `anchorLink` требуют объявленный источник имени: `accessibleLabel`,
+`labelledBy`, непустой `title` либо читаемый phrasing content. Image-only link
+получает имя из `alt` admitted image resource; этот инвариант проверяет
+`validateRichDocumentModel(document, resources)`, поскольку отдельный document
+не содержит resource descriptors. Structural acceptance не заменяет проверку
+итогового accessible name в браузере.
+
+Empty content is valid where native document semantics permits it. Control,
+summary and table labels must contain non-whitespace content. Links require a
+declared naming source; image-only link names are checked against admitted alt
+text at the complete model boundary. The validator preserves strings and does
+not emulate the browser's accessible-name computation.
+
+Идентификаторы anchors/occurrences сохраняют точный Unicode, без case folding,
+slugification, trim или удаления sanitizer prefix. Пробелы, control characters
+и malformed surrogate pairs запрещены; unknown/duplicate targets дают ошибку
+по точному source path. Anchor IDs имеют предел 256 символов, footnote IDs —
+128. Producer задаёт identity явно: heading text не используется для её
+угадывания.
+
+`anchorLink.anchorId` ссылается на объявленный metadata anchor или
+`anchorTarget`. HTML-fragment producer декодирует и сопоставляет в своей
+serialization boundary; renderer получает уже точный logical ID, не raw hash.
+Application URL и fragment navigation — разные typed nodes.
+
+Renderer создаёт injective, mount-scoped DOM IDs, включая две копии документа
+с одинаковым `document.id`. Локальный переход раскрывает закрытые ancestor
+`details`, прокручивает цель и передаёт ей фокус. Следующая `Tab` продолжает
+порядок фокуса от цели. `location.hash`, URL и browser history не меняются.
+
+The renderer owns mount-scoped DOM identities. Navigation reveals closed
+ancestor disclosures, scrolls and focuses the target, and preserves the URL,
+hash, and browser history. Identical documents mounted together remain isolated.
+
+`footnoteReference` и `footnoteBacklink` адресуют пару `id` + `occurrenceId`.
+Для единственного reference `occurrenceId` можно опустить; для повторных
+references producer задаёт уникальные occurrence IDs. Definition объявляется
+один раз на `id`, а backlink выбирает конкретный reference occurrence. Метки
+`label` обязательны, визуальный `marker` необязателен.
+
+```ts
+const repeatedNotes = {
+  version: 1,
+  id: 'notes',
+  nodes: [
+    { type: 'heading', level: 2, anchorId: 'Раздел_日本', children: [{ type: 'text', value: 'Details' }] },
+    { type: 'paragraph', children: [
+      { type: 'anchorLink', anchorId: 'Раздел_日本', children: [{ type: 'text', value: 'Open details' }] },
+      { type: 'footnoteReference', id: 'Примечание', occurrenceId: 'first', label: 'First note reference', marker: '1' },
+      { type: 'footnoteReference', id: 'Примечание', occurrenceId: 'second', label: 'Second note reference', marker: '1' },
+    ] },
+    { type: 'footnoteDefinition', id: 'Примечание', label: 'Note', children: [
+      { type: 'paragraph', children: [
+        { type: 'text', value: 'Note content. ' },
+        { type: 'footnoteBacklink', id: 'Примечание', occurrenceId: 'second', label: 'Return to second reference' },
+      ] },
+    ] },
+  ],
+} as const satisfies SRichDocumentV1
+```
+
+## Таблицы / Tables
+
+`table` задаёт прямоугольную модель: непустые `columns`, стабильные column/row
+IDs и одинаковое число inline cells в каждой строке. Column `header` —
+обязательная непустая доступная метка. `headerChildren` задаёт rich inline
+presentation, `headerPresentation: 'assistive'` визуально скрывает заголовок,
+`align` принимает `left | center | right`.
+
+`semanticTable` задаёт обязательные `label`/`body`, optional `caption` с inline
+children, `head`, `foot` и соответствующие `headMetadata`, `bodyMetadata`,
+`footMetadata`. Optional `columnGroups: readonly { span: number }[]` объявляет
+native column groups, чья суммарная ширина равна ширине полной сетки; `scope:
+'colgroup'` ссылается на диапазон объявленной группы. Row содержит `cells` и
+metadata. Cell имеет:
+
+- `type: 'header' | 'data'`;
+- `content: 'inline' | 'block'` и соответствующий union `children`;
+- optional `cellId`, `headers`, `rowSpan`, `colSpan`, `align` и metadata;
+- `scope: 'row' | 'col' | 'rowgroup' | 'colgroup'` только у header cell.
+
+`cellId` уникален в своей таблице. `headers` ссылается только на другие header
+cells той же таблицы, а не на произвольные DOM IDs. Header content соблюдает
+HTML-модель `th`: без heading/sectioning/header/footer descendants. Ограничение
+рекурсивно включает `footnoteDefinition`, создающий named note, и neutral callout
+с `title`, чей shared owner создаёт heading. Block data cells сохраняют
+paragraph/list и другие допустимые block nodes.
+
+Каждая row group образует полную прямоугольную сетку, ширина групп совпадает.
+Spans не пересекаются; `rowSpan: 0` означает остаток текущей row group,
+положительный `rowSpan` не выходит за её границы. `colSpan` — 1..100.
+Некорректная сетка и missing header references отвергаются до DOM. Table,
+sections, rows и cells используют общие semantic owners со `STable`; rich
+document table не становится интерактивным data-grid и не добавляет row tab
+stops.
+
+The rectangular model supports rich/assistive column headers. The structural
+model preserves head/body/foot groups, captions, row headers, explicit header
+relations, spans, alignment, and inline/block cell content. Invalid grids,
+cross-table references, and unsupported header descendants fail before render.
+
+## Изображения и admission / Images and admission
+
+`inlineImage` — phrasing content: отображается внутри paragraph/link/summary
+без block `figure`. `image` — block content с optional inline `caption`.
+Оба используют общий image presentation owner и `resourceId`, а не `src`.
+Image resource содержит `id`, `kind: 'image'`, `url`, `alt` и optional `title`.
+Пустой `alt` означает декоративное изображение.
+
+`candidates` задаёт responsive набор resource IDs. Каждый candidate имеет
+ровно один descriptor: положительный safe integer `width` либо положительный
+finite `density`. Набор не смешивает descriptor families, значения уникальны.
+`pictureSources` содержит optional `media` и отдельный `candidates` набор.
+Каждый base/candidate/source resource должен существовать и иметь `kind:
+'image'`. Raw `srcset`, `src`, HTML source strings и callbacks запрещены.
+
+Raster data URL принимает canonical `data:image/<format>;base64,...`, где
+`<format>` — только `png`, `jpeg`, `gif`, `webp` или `avif`, без дополнительных
+parameters. Base64 и format signature должны
+соответствовать заявленному MIME. SVG/HTML data, MIME mismatch и malformed data
+отвергаются. Эта проверка admission не является полным декодером raster файла;
+декодирование и выбор responsive source выполняет браузер.
+
+Inline and block images resolve separately admitted resource IDs. Every
+responsive candidate is validated, including picture-source branches. Raster
+data admission verifies MIME, canonical base64, and format signatures; it does
+not accept SVG or HTML payloads and is not a complete image decoder.
+
+**Producer владеет network admission.** URL protocol validation не заменяет
+origin/permissions policy. В privacy-preserving Markdown projection локальные
+same-origin/blob/raster resources объявляются в `resources`; внешний media URL
+представляется обычным controlled `link`, если его загрузка не разрешена.
+Renderer не делает скрытое преобразование внешнего image в link: такое решение
+принимается явно до AST serialization. Admitted image URL создаёт browser image
+load; обычные link/resource intents не создают загрузку до consumer action.
+Candidate URL проходит тот же admission, что и base image; добавление raw URL
+через `pictureSources` не является отдельным каналом разрешения.
+
+Producers own origin authorization. A declared image resource authorizes the
+browser image load; protocol validation alone is not an origin policy. A
+privacy-preserving producer projects unadmitted external media to controlled
+links explicitly, without hidden renderer substitution or candidate bypasses.
+
+## Rich summary
+
+`disclosure.summary` — обязательная текстовая метка. `summaryChildren` задаёт
+rich phrasing content: emphasis, code, keyboard, image и links. Без этого поля
+отображается `summary`. Пассивный summary использует native `details`/`summary`.
+Summary с links или inline control отображается рядом с отдельным SButton
+disclosure toggle; содержимое и порядок rich nodes сохраняются. `Enter`/`Space`
+на toggle переключают секцию, `open` задаёт начальное отображение. Ссылки имеют
+собственный focus и intent, не являются потомками toggle и не переключают секцию.
+Локальная anchor navigation раскрывает оба вида disclosure ancestors.
+
+Passive summaries use native details/summary. Interactive rich summaries use a
+separate native button owner beside the complete rich content, preserving link
+focus and activation without nested interactive elements. The toggle exposes
+aria-expanded/aria-controls; local navigation reveals native and composed owners.
+Footnote definitions expose named note semantics, not page navigation landmarks.
+
 ## Controlled intents
 
 Ссылки, resources и actions не выполняют application effects. Компонент эмитит
@@ -219,6 +564,78 @@ 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.
 
+## Worker snapshots и producer migration
+
+Markdown parsing, `rehypeRaw`, sanitizer и HAST projection принадлежат
+consumer worker. Main thread принимает сериализованный typed AST/resources,
+проверяет `validateRichDocumentModel` и отображает результат. UI-kit не
+включает Markdown parser в renderer и не принимает HAST, HTML или VNodes как
+альтернативный вход. JSON text и structured-clone payloads используют один
+контракт данных.
+
+Parsing, sanitation, and HAST projection belong to the consumer worker. The
+main thread receives and validates the serialized typed document/resources;
+it does not rerun the document parser or mount sanitized HAST directly.
+
+Producer выполняет проекцию законченного документа или согласованного
+streaming snapshot целиком: forward anchors, footnote definitions и resource
+references должны быть доступны в том же model. Неполная ссылка не становится
+угадываемым target. Для streamed append immutable replacement сохраняет
+порядок и содержимое существующего prefix и добавляет nodes в конец; renderer
+сохраняет mounted prefix, focus и пользовательское раскрытие существующих
+`details`. Изменения и переупорядочение содержимого — отдельные snapshots, не
+implicit patch protocol.
+
+Worker scheduling, cancellation и отбрасывание результатов отменённых jobs
+принадлежат типизированному application job contract. Ошибка worker/parser/
+projection/validation должна попадать в управляемое error state с диагностикой;
+пустой документ, пропуск неизвестного tag, invalid resource или неприменённая
+новая версия не служат silent fallback. Валидатор создаёт frozen result; он не
+мутирует входной snapshot.
+
+The application owns worker scheduling and cancellation. Complete snapshots
+must resolve forward references. Immutable append preserves the unchanged
+mounted prefix and its focus/disclosure state. Worker and contract errors are
+explicit error states, not empty-document or dropped-node fallbacks.
+
+Граница миграции existing producer adapter:
+
+1. Сохранить worker parser/sanitizer и текущую origin/media admission policy.
+2. Преобразовать каждый admitted tag по таблице profile, с точными metadata,
+   heading/HTML anchors и repeated footnote identities. Unknown или
+   непредставимая семантика даёт явную source-coordinate ошибку.
+   GFM footnote section сохраняет assistive label heading и reference
+   `describedBy`, включая точный sanitizer prefix.
+3. Разделить inline/block image context. Все responsive candidates пройти
+   через тот же admission; не копировать raw `srcset` в AST.
+4. Прямоугольные таблицы описать `table`; rich headers передать через
+   `headerChildren`. Row groups, spans, row headers и block cells описать
+   `semanticTable`, без consumer table markup/CSS.
+5. Rich summary передать как `summaryChildren` и сохранить `summary` как
+   доступную текстовую метку. Обычные ссылки оставить controlled intents,
+   local fragments — `anchorLink`.
+6. Валидировать document/resources совместно, передавать immutable snapshots,
+   обрабатывать точные ошибки и typed intents на application boundary.
+7. Проверить реальные consumer документы: две одинаковые копии, Unicode IDs,
+   повторные сноски, закрытые nested sections, keyboard summary/link,
+   responsive local resources, streaming focus, SSR/hydration, обе темы и
+   узкий viewport.
+
+Migration keeps the producer's worker and admission owners. Project explicitly
+to typed semantic families; preserve exact identities, separate image context,
+use structural tables where required, validate complete immutable models, and
+verify the real consumer scenarios rather than a raw-HTML compatibility path.
+
+## Пределы / Limits
+
+`S_RICH_DOCUMENT_MAX_NODES` — 10 000 структурных узлов документа,
+`S_RICH_DOCUMENT_MAX_DEPTH` — 32,
+`S_RICH_DOCUMENT_MAX_TEXT_LENGTH` — 1 048 576 символов. Таблица имеет максимум
+100 колонок. Nested implicit structures — cells, rows, definition members,
+picture sources и column groups — входят в document budget; массивы и strings
+имеют дополнительные field-level bounds. Превышение даёт `limit_exceeded` с
+точным path; документ не обрезается.
+
 ## Версионирование / Versioning
 
 `version` является частью persisted/transport contract. Не добавляйте

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgcorp/ui-kit",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Typed Vue 3 design system with accessible components, semantic themes, and workbench patterns.",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -176,6 +176,9 @@
       "shared/containers/SModal.vue": [
         "dist/src/components/shared/containers/SModal.vue.d.ts"
       ],
+      "shared/containers/SOverlayHost.vue": [
+        "dist/src/components/shared/containers/SOverlayHost.vue.d.ts"
+      ],
       "shared/containers/SPageHeader.vue": [
         "dist/src/components/shared/containers/SPageHeader.vue.d.ts"
       ],
@@ -582,7 +585,7 @@
       "import": "./dist/src/components/layout/types.js",
       "default": "./dist/src/components/layout/types.js"
     },
-    "./reference.css": "./src/styles/reference.css",
+    "./reference.css": "./dist/reference.css",
     "./shared/codeLanguages": {
       "types": "./dist/src/components/shared/codeLanguages.d.ts",
       "import": "./dist/src/components/shared/codeLanguages.js",
@@ -673,6 +676,11 @@
       "import": "./dist/src/components/shared/containers/SModal.vue.js",
       "default": "./dist/src/components/shared/containers/SModal.vue.js"
     },
+    "./shared/containers/SOverlayHost.vue": {
+      "types": "./dist/src/components/shared/containers/SOverlayHost.vue.d.ts",
+      "import": "./dist/src/components/shared/containers/SOverlayHost.vue.js",
+      "default": "./dist/src/components/shared/containers/SOverlayHost.vue.js"
+    },
     "./shared/containers/SPageHeader.vue": {
       "types": "./dist/src/components/shared/containers/SPageHeader.vue.d.ts",
       "import": "./dist/src/components/shared/containers/SPageHeader.vue.js",
@@ -1159,7 +1167,7 @@
       "default": "./dist/src/stores/useNotifierStore.js"
     },
     "./style.css": "./src/styles/style.css",
-    "./tailwind.css": "./src/styles/tailwind.css",
+    "./tailwind.css": "./dist/tailwind.css",
     "./theme": {
       "types": "./dist/src/theme.d.ts",
       "import": "./dist/src/theme.js",
@@ -1194,7 +1202,6 @@
     "highlight.js": "^11.12.0",
     "katex": "0.18.7",
     "@lucide/vue": "^1.47.0",
-    "@tailwindcss/typography": "^0.5.20",
     "marked": "^18.0.13",
     "sigma": "^3.0.3",
     "tailwindcss": "^4.3.3",
@@ -1204,6 +1211,7 @@
   "devDependencies": {
     "@storybook/vue3-vite": "10.6.0",
     "@tailwindcss/postcss": "^4.3.3",
+    "@tailwindcss/typography": "0.5.20",
     "@types/node": "^22.20.4",
     "@vitejs/plugin-vue": "^6.0.9",
     "@vitest/coverage-v8": "^5.0.1",