@pgcorp/ui-kit 0.13.0 → 0.15.0

package/README.md

@@ -23,6 +23,80 @@ complete workbench interfaces.**
 - Только явные package exports: wildcard и private source imports отсутствуют.
   Explicit package exports only, with no wildcards or private source imports.
 
+### Полные option-каталоги / Complete option catalogs
+
+`SListbox.virtualization` задаёт measured viewport над полным набором `options`:
+`{ viewportHeight, estimatedItemHeight, overscan? }`. Keyboard navigation, groups,
+clear, disabled и multiple selection работают по всему каталогу. Для external
+focus owner событие `active-descendant-change` передаёт ID смонтированной option
+в `STextarea.suggestions`. Полный контракт и примеры включены в пакет: `docs/listbox.md`.
+
+`SListbox.virtualization` provides a measured viewport over the complete option
+catalog. Keyboard navigation and selection use the full inventory; the
+`active-descendant-change` event supplies a mounted option ID to an external
+focus owner. The package includes the complete contract and examples in `docs/listbox.md`.
+
+### Измеряемый прогресс / Measured progress
+
+`SProgressBar` использует один numerical/accessibility owner для `shape="linear"`
+и `shape="circular"`. Линейная форма является default. Круговая форма имеет
+размеры `xs/sm/md = 24/28/32 px` и требует явный `value` от 0 до 100 в
+`mode="determinate"`. `showValue` выводит округлённое число в центре;
+`aria-valuenow` сохраняет точное значение, включая дробную часть.
+`valueText` передаёт доступное предметное описание, например tokens/limit.
+Существующий scoped default slot форматирует только linear label и получает
+точный `value`; circular label принадлежит владельцу и отклоняет default slot.
+
+`accuracy="estimated"` требует `valueText` и показывает приблизительность.
+`mode="unknown"` требует `valueText`, не принимает `value` и не сообщает
+`aria-valuenow`. Эти состояния статичны. `mode="indeterminate"` обозначает
+выполняющуюся операцию, не принимает `showValue` и учитывает reduced motion.
+`severity` управляет semantic palette, а не выводится из процента автоматически.
+
+```vue
+<SProgressBar
+  :accessibility="{ mode: 'label', label: 'Заполнение контекста' }"
+  shape="circular"
+  size="md"
+  :value="37.5"
+  value-text="37 500 из 100 000 токенов"
+  show-value
+  severity="info"
+/>
+<SProgressBar
+  :accessibility="{ mode: 'label', label: 'Заполнение контекста' }"
+  shape="circular"
+  mode="unknown"
+  value-text="Размер контекста недоступен"
+  show-value
+/>
+```
+
+Для действия показатель помещается в default slot `SButton` с
+`iconOnly`, `shape="circle"`, `size="lg"`, `density="default"` и
+`appearance="ghost"`: штатная
+контрольная область равна **48×48 px**, то есть не меньше 44 px. Внутренний
+показатель использует `accessibility.mode="decorative"`; действие, доступное
+имя с точным значением и tooltip bindings принадлежат внешней кнопке.
+Показатель не создаёт вложенный control или дополнительную остановку Tab.
+
+`SProgressBar` shares numerical and accessibility ownership across linear and
+circular shapes. Circular `xs/sm/md` sizes are 24/28/32 px. Determinate circular
+progress requires an explicit value in 0–100; central display rounds the
+percentage while `aria-valuenow` retains its exact precision. `valueText`
+supplies a domain description such as tokens/limit. Estimated progress requires
+`valueText` and a visible approximation marker. Explicit unknown progress
+requires `valueText`, rejects `value`, omits `aria-valuenow`, and remains static.
+Severity is consumer-selected rather than inferred from a percentage. The
+existing scoped default slot formats linear labels and receives the exact
+value. Circular labels are owner-controlled and reject a supplied default slot.
+
+For an actionable indicator, place decorative progress in the default slot of
+a circular `SButton` with `iconOnly`, `size="lg"`, default density, and
+`appearance="ghost"`: its target is
+48×48 px, not exactly 44 px. The inner progress is decorative; the button owns
+focus, the action, the accessible name, and tooltip bindings.
+
 ## Установка / Installation
 
 ```bash
@@ -45,6 +119,23 @@ npm install @pgcorp/ui-kit @vue/devtools-api vue pinia vue-router
 `vue`, `pinia`, `@vue/devtools-api`, and `vue-router` are peer dependencies. The consumer application
 owns their single runtime instances.
 
+Tailwind/PostCSS принадлежат build-контуру приложения и объявляются его прямыми
+dev dependencies. / Tailwind/PostCSS belong to the application's build pipeline
+and must be declared as its direct dev dependencies.
+
+```bash
+npm install -D tailwindcss@^4.3.3 @tailwindcss/postcss@^4.3.3 postcss@^8.5.28
+```
+
+`postcss.config.mjs`:
+
+```js
+export default { plugins: { '@tailwindcss/postcss': {} } }
+```
+
+Контракт установки: [Tailwind CSS с PostCSS](https://tailwindcss.com/docs/installation/using-postcss).
+/ Setup contract: [Tailwind CSS with PostCSS](https://tailwindcss.com/docs/installation/using-postcss).
+
 ## Быстрый старт / Quick start
 
 Создайте корневой CSS entrypoint приложения. Интеграционный stylesheet подключает
@@ -177,6 +268,16 @@ link/resource/action effects возвращаются как typed intents. Link
 `current: true` выражает текущее назначение через `aria-current="page"`.
 Task lists, deletion, `keyboard`, sup/sub, disclosure и scoped footnotes имеют
 собственные serializable nodes; raw markup для этих семантик не требуется.
+Типизированный semantic profile включает hard breaks, inline/picture media,
+rich summary/header content, definitions, ruby и структурные таблицы с
+header associations, spans и footer. `STable`, `SDataGrid` и rich tables
+используют общих native table owners. Якоря и повторные сноски имеют локальный
+scope, раскрывают целевую секцию и переводят фокус без изменения истории.
+`heading.presentation: 'assistive'` сохраняет нативный уровень, содержимое,
+scoped anchors и IDREFs, визуально скрывая сам heading вне normal flow.
+Значение по умолчанию — `visible`; интерактивные потомки в assistive heading
+отклоняются с точным node path. GFM producer сохраняет скрытый heading сносок
+и его `describedBy` references, не передавая raw `class`.
 
 `SRichDocument` renders the closed, versioned `SRichDocumentV1` AST without raw
 HTML, VNodes, callbacks, or trust flags. External JSON is checked with
@@ -186,6 +287,26 @@ link/resource/action effects are emitted as typed intents. A link node with
 `current: true` exposes the current destination through `aria-current="page"`.
 Task lists, deletion, `keyboard`, sup/sub, disclosure, and scoped footnotes use
 dedicated serializable nodes; these semantics never require raw markup.
+The typed semantic profile includes hard breaks, inline/picture media, rich
+summary/header content, definitions, ruby, and structural tables with header
+associations, spans, and a footer. `STable`, `SDataGrid`, and rich tables share
+native table owners. Anchors and repeated footnotes are scoped locally, reveal
+their target disclosure, and move focus without changing browser history.
+`heading.presentation: 'assistive'` retains the native level, content, scoped
+anchors, and IDREFs while placing the heading outside normal flow. The default
+is `visible`; interactive descendants fail at their exact node path. A GFM
+producer preserves its hidden footnote heading and description references
+without passing raw classes.
+
+`SCheckbox presentation="inline"` и `SField contentFlow="phrasing"` сохраняют
+phrasing content model внутри текста. `SLink` предоставляет actual native
+`getElement()`/`focus()` и semantic props `domId`, `language`, `direction`,
+`ariaLabel`, `ariaLabelledby`, `ariaDescribedby`; IDREFs задаются непустыми DOM
+идентификаторами через один ASCII-пробел без автоматического исправления ввода.
+/ `SCheckbox presentation="inline"` and `SField contentFlow="phrasing"` preserve
+the phrasing content model inside text. `SLink` exposes the actual native
+`getElement()`/`focus()` and the semantic props listed above; IDREFs are explicit
+non-empty DOM identities separated by one ASCII space, without input repair.
 
 ```ts
 import SRichDocument from '@pgcorp/ui-kit/shared/data-display/SRichDocument.vue'
@@ -210,12 +331,32 @@ semantic block size, overscroll policy и root-only keyboard navigation.
 semantic offsets. Exposed API предоставляет `focus`, `scrollToBoundary` и
 `reveal`, но не открывает DOM owner.
 
+`focusPolicy="always"` сохраняет именованную region; `focusPolicy="overflow"`
+добавляет region и Tab stop только при переполнении разрешённой оси. Имя задаётся
+ровно одним из `accessibleLabel` и `accessibleLabelledby`. `blockSize="content"`
+сохраняет естественную высоту, `maxBlockSize="none|sm|md|lg"` ограничивает её
+общей шкалой viewport. Таблицы `STable`, `SDataGrid` и rich-document используют
+этот общий scroll owner: пустые и пассивные таблицы доступны клавиатуре при
+переполнении, вложенные controls сохраняют собственную клавиатуру.
+При исчезновении переполнения focused root сохраняет `tabindex="-1"` до blur;
+он не добавляет остановку Tab и не переносит фокус.
+
 `SScrollViewport` owns a named scroll region, `x`/`y`/`both` axes, semantic
 block size, overscroll policy, and root-only keyboard navigation. The
 `scroll-state` event provides normalized physical and writing-mode-aware
 semantic offsets. Its exposed API provides `focus`, `scrollToBoundary`, and
 `reveal` without exposing the DOM owner.
 
+`focusPolicy="always"` retains the named region; `focusPolicy="overflow"`
+adds a region and Tab stop only when an enabled axis overflows. Exactly one
+of `accessibleLabel` and `accessibleLabelledby` supplies its name.
+`blockSize="content"` retains intrinsic height; `maxBlockSize="none|sm|md|lg"`
+uses the shared viewport limit scale. `STable`, `SDataGrid`, and rich-document
+tables compose this scroll owner: overflowing empty and passive tables are
+keyboard reachable, while nested controls retain their own keyboard behavior.
+When overflow disappears, a focused root retains `tabindex="-1"` until blur;
+it adds no Tab stop and does not move focus.
+
 ```ts
 import SScrollViewport from '@pgcorp/ui-kit/shared/data-display/SScrollViewport.vue'
 import type {
@@ -521,7 +662,179 @@ reserved for runtime catalog values and intentionally includes the complete
 registry.
 
 ```ts
-import { Bell, Cable, GitCompare, PanelLeftOpen } from '@pgcorp/ui-kit/icons'
+import {
+  ArrowUpRight, Bell, Cable, CalendarDays, Disc, GitCompare, GitFork,
+  ChevronLeft, HardDrive, PanelLeftOpen, Paperclip, Pause, Radio, RotateCw, Usb, Volume2, Zap, ZoomIn, ZoomOut,
+} from '@pgcorp/ui-kit/icons'
+```
+
+`HardDrive`, `Usb` и `Disc` обозначают локальный накопитель, USB-подключение
+и оптический диск; `CalendarDays` — дату, `ArrowUpRight` — переход или открытие.
+`Paperclip` обозначает прикрепление файла, `GitFork` — разветвление разговора;
+`ZoomIn`/`ZoomOut` — изменение масштаба изображения, `RotateCw` — поворот по
+часовой стрелке, `Volume2` — аудио. Поворот против часовой стрелки представлен
+отдельным `RotateCcw`, а не alias для `RotateCw`.
+`Radio` обозначает сетевое вещание или фоновое уведомление, не radio input.
+`Pause` обозначает состояние паузы задачи; `ChevronLeft` — переход влево.
+`Zap` обозначает молнию и подходит для роли быстрой модели. Это primary-only
+силуэт: duotone сохраняет одну цветовую роль, без дополнительного accent.
+Все используют общий icon contract: `iconSetMode` (`classic`, `sputnig`),
+`colorMode` (`auto`, `duotone`, `monochrome`), тему и tree-shakeable ESM exports.
+Внутри control иконка передаётся через его icon slot; размер и состояние
+задаёт control owner.
+
+`HardDrive`, `Usb`, and `Disc` represent a local drive, a USB connection, and
+an optical disc; `CalendarDays` represents a date, and `ArrowUpRight` represents
+navigation or opening. All share the icon contract: `iconSetMode` (`classic`, `sputnig`),
+`colorMode` (`auto`, `duotone`, `monochrome`), theme support, and tree-shakeable ESM
+exports. Pass an icon through a control's icon slot; the control owner defines
+its size and state.
+
+`Paperclip` represents file attachment and `GitFork` conversation branching.
+`ZoomIn`/`ZoomOut` represent image zoom, `RotateCw` clockwise rotation, and
+`Volume2` audio. Counterclockwise rotation has a distinct `RotateCcw` export;
+the two rotation actions are not aliases.
+`Radio` represents network broadcast or a background notification, not a radio input.
+`Pause` represents a paused task; `ChevronLeft` represents leftward navigation.
+`Zap` represents a lightning bolt and can identify the fast-model role. Its
+primary-only silhouette retains one color role in duotone, without an accent shape.
+
+```vue
+<SButton label="Выбрать локальный накопитель">
+  <template #leading-icon><HardDrive /></template>
+</SButton>
+```
+
+### Скачивание через ссылку / Native link downloads
+
+`SButton` и `SLink` поддерживают typed `download?: string | boolean` только в
+`href`-режиме. Filename передаётся native anchor буквально; `true`/`""` оставляют
+выбор имени браузеру, `false` не создаёт download attribute. Router `to` и action
+button не принимают этот prop. Consumer владеет полным Blob и object URL;
+ограниченный preview не становится источником скачивания. `SLink.disabled` и
+`SButton.disabled/loading` блокируют activation и удаляют `href`/`download`.
+
+`SButton` and `SLink` support typed `download?: string | boolean` in `href` mode
+only. The filename is passed verbatim to the native anchor; `true`/`""` let the
+browser choose it, and `false` omits the attribute. Router `to` and action buttons
+reject this prop. The consumer owns the complete Blob and its object URL; a
+limited preview is not the download source. `SLink.disabled` and
+`SButton.disabled/loading` block activation and remove `href`/`download`.
+
+Контракт, Blob lifecycle и ограничения браузера включены в пакет: `docs/link-download.md`.
+The package includes the contract, Blob lifecycle, and browser limitations in `docs/link-download.md`.
+
+### Идентичность динамических вкладок / Dynamic tab identity
+
+В managed-композиции `STabs` значение `modelValue`, `STab.name` и
+`STabPanel.name` используют один стабильный ID сущности. Vue `key` также
+основан на этом ID. Добавление элемента и выбор его ID допускаются в одной
+reactive update, включая вставку в начало массива. Порядковый номер и подпись
+вкладки являются отображением, а не идентичностью.
+
+Для E2E consumer задаёт собственные `data-*` маркеры по ID и проверяет роль
+`tab`, `aria-selected`, связь `aria-controls` с ID панели и обратную
+`aria-labelledby`. Внутренний формат DOM ID, `nth()` и индекс в подписи не
+являются selector-контрактом. Сохранённые панели сохраняют свой input при
+переключении; ручная DOM-активация и remount для выбора не требуются.
+
+In managed `STabs`, `modelValue`, `STab.name`, `STabPanel.name`, and Vue `key`
+use the same stable entity ID. Adding a keyed item and selecting its ID can
+occur in one reactive update, including insertion at the beginning. An ordinal
+or label is presentation, not identity. E2E tests use consumer-owned `data-*`
+IDs, the `tab` role, `aria-selected`, and the matching `aria-controls` /
+`aria-labelledby` relationship. Internal DOM ID formats, `nth()`, and label
+indices are not selector contracts. Retained panels preserve their input;
+selection does not require manual DOM activation or remounting.
+
+### Подсказка на интерактивной поверхности / Tooltip on an interactive surface
+
+`SInteractiveSurface` принимает полный combined `trigger` от `STooltip` через
+prop `tooltipTrigger`. Binding относится к primary activation owner: кнопке
+для `surface.mode="action"` или ссылке для `surface.mode="link"`.
+Link surface принимает ровно один target: `href` либо Vue Router `to`.
+Для `to` приложение подключает Vue Router. `accessibleLabel` обязателен
+в обоих интерактивных режимах; static surface не принимает tooltip binding.
+Подсказка открывается по pointer/focus и закрывается через Escape.
+Дополнительные controls передаются в `#actions` и сохраняют собственные
+focus и activation независимо от primary owner.
+
+`showDelay` задаёт задержку открытия (120 мс), `hideDelay` — закрытия после
+выхода указателя и фокуса (80 мс). Указатель может переходить с target на
+пассивную панель подсказки: она остаётся видимой, не получает focus и не
+добавляет Tab stop. Escape закрывает открытую панель и отменяет pending
+открытие; pending-подсказка не забирает событие у меню или диалога.
+Blur окна, скрытие документа, disabled и освобождение target отменяют
+таймеры и слушатели. Новый вход указателя или получение фокуса открывает
+подсказку по действующему `showDelay`.
+Canonical focus owner допускает binding внутри сохранённой скрытой секции.
+Скрытый или недоступный owner не активирует подсказку. Скрытие ancestor
+отменяет pending-таймеры, сразу исключает открытую панель из взаимодействия
+и снимает description. Reveal сохраняет owner; новый pointer/focus вход
+открывает подсказку без дополнительного Tab stop.
+
+Пассивная tooltip-поверхность передаёт полный `text`/`title`/`description`,
+`details` и `sections` как доступное описание focus owner через
+`aria-describedby`; внешние `triggerDescribedBy` сохраняются. Визуальный
+portal имеет `aria-hidden="true"`, исключая повторное самостоятельное чтение
+того же текста вне landmark. Пассивная поверхность прозрачна для указателя:
+нажатие достигает расположенного под ней действия, а наведение на видимый
+контент сохраняет текущую подсказку. Имя и роль owner не изменяются. Подсказка не
+содержит интерактивных действий; для popup с controls используется другой
+overlay-компонент. Описание связывается при показе панели, включая открытие
+по возвращённому фокусу после закрытия dialog.
+
+The passive tooltip surface exposes all text, title, description, details,
+and sections as the focus owner's accessible description through
+`aria-describedby`, preserving external `triggerDescribedBy` references.
+The visual portal has `aria-hidden="true"` to avoid duplicating that description
+as independent content outside a landmark. The passive surface is pointer-transparent:
+native activation reaches the underlying action while hovering the displayed content
+keeps its current tooltip lease open. The owner's name and role remain
+unchanged. A tooltip contains no interactive actions; use another overlay
+component for a popup with controls. The description is associated when the
+surface is shown, including focus restored after a dialog closes.
+
+`SInteractiveSurface` accepts the complete combined `STooltip` trigger through
+the `tooltipTrigger` prop. The binding belongs to the primary activation owner:
+a button for `surface.mode="action"` or a link for `surface.mode="link"`.
+A link surface accepts exactly one target: `href` or Vue Router `to`.
+The application installs Vue Router when using `to`. `accessibleLabel` is
+required in both interactive modes; a static surface rejects a tooltip binding.
+The tooltip opens on pointer/focus and closes with Escape. Additional controls
+use `#actions` and retain independent focus and activation.
+
+`showDelay` controls the opening delay (120ms); `hideDelay` controls closing
+after pointer hover and focus leave (80ms). The pointer can move from the
+target onto the passive tooltip panel: it remains visible, receives no focus,
+and adds no Tab stop. Escape closes the visible panel or cancels a pending
+opening; a pending tooltip does not consume the event from a menu or dialog.
+Window blur, a hidden document, disabled state, and released target identity
+cancel timers and listeners. Fresh pointer entry or acquired focus opens the
+tooltip according to its current `showDelay`.
+A canonical focus owner can bind inside a retained hidden section. A hidden
+or unavailable owner cannot activate the tooltip. Hiding its ancestor
+cancels pending timers, immediately retires the open panel from interaction,
+and removes its description. Revealing the section retains the owner;
+fresh pointer/focus entry opens the tooltip without another Tab stop.
+
+```vue
+<STooltip text="/workspace/repository" v-slot="{ trigger }">
+  <SInteractiveSurface
+    :surface="{
+      mode: 'link',
+      to: '/projects/repository',
+      accessibleLabel: 'Открыть проект',
+    }"
+    :tooltip-trigger="trigger"
+    actions-layout="responsive"
+  >
+    Проект Repository
+    <template #actions>
+      <SButton label="Параметры проекта" size="sm" />
+    </template>
+  </SInteractiveSurface>
+</STooltip>
 ```
 
 ### Подсказка на части действия / Tooltip for part of an action
@@ -567,6 +880,69 @@ the multiline textbox with a consumer-owned popup without private attributes.
 The textarea keeps its native role; `role="combobox"` is not assigned to this
 HTML element. Pixel bounds belong to the auto-resize contract.
 
+Слоты `empty-content` и `helper-content` располагаются обычным потоком внутри
+единой field surface. `empty-content` доступен при пустом тексте вне IME
+composition; native input скрывает его до подтверждения `v-model` родителем.
+`helper-content` не зависит от значения. Оба слота получают
+`STextareaContentContext`: `empty`, `disabled`, `readonly`, `invalid`, `composing`,
+`hasMultipleVisualLines` и `focus()`. Действия в слотах создаются через UI-kit controls; их доступность
+задаётся через `disabled`/`readonly` контекста. `focus()` возвращает фокус
+native textarea без изменения selection. `helpText` и `errorMessage` сохраняют
+свой supporting-text contract снаружи surface.
+
+При наличии content slots `minHeight`/`maxHeight` ограничивают всю surface:
+textarea, supporting regions, интервалы и внутренние поля. Редактор сохраняет
+место минимум для одной строки; длинный helper прокручивается в своей in-flow
+области, а его keyboard actions доступны Tab. Конфигурация, в которой
+`maxHeight` не вмещает editable line и обязательный surface chrome, отклоняется
+с `RangeError`. `rows` задаёт исходную высоту редактора, `maxRows` ограничивает
+редактируемые строки с учётом присутствующего supporting content. Content slots
+не требуют абсолютного позиционирования, consumer padding или дополнительного
+resize handler. Изменение естественной высоты slot-контента автоматически
+увеличивает или уменьшает surface в заданных пределах; самостоятельно
+обновляемые дочерние компоненты наблюдаются тем же resize owner.
+
+The `empty-content` and `helper-content` slots participate in normal flow inside
+the shared field surface. Empty content is visible only for an empty editor
+outside IME composition; native input hides it before a delayed parent model
+acknowledgement. Helper content is independent of the value. Both slots receive
+`STextareaContentContext` with editing-state flags and the native `focus()`
+method. Pixel bounds include the whole surface and preserve at least one
+editable line; oversized supporting content has its own bounded scroll region.
+Intrinsic slot-content changes automatically grow or shrink the surface within
+its bounds, including independently updated child components. Use UI-kit
+controls for slot actions, without consumer overlays, padding or resize calls.
+
+`hasMultipleVisualLines` описывает native текст с учётом переносов по текущей
+ширине: `false` — одна визуальная строка, `true` — несколько. `null` означает
+недоступную геометрию: SSR, скрытый editor или нулевую ширину. Пустое значение
+при доступной геометрии занимает одну строку; placeholder не определяет это
+состояние. Измерение обновляется для fixed и auto-resize полей, native ввода до
+подтверждения controlled модели, изменений ширины и типографики. Consumer
+задаёт политику показа helper через slot context, без доступа к private DOM:
+
+`hasMultipleVisualLines` describes native text wrapping at the current editor
+width: `false` is one visual line, `true` is multiple lines, and `null` denotes
+unavailable layout during SSR, hidden rendering or zero width. An empty value
+has one editable line once layout is available; placeholder text does not
+determine this state. Fixed and auto-resizing editors update the state for
+native input, delayed model acknowledgement, width and typography changes.
+Helper visibility is an explicit consumer policy expressed through slot state:
+
+```vue
+<STextarea v-model="message" label="Сообщение" :rows="1" auto-resize :min-height="64" :max-height="240">
+  <template #helper-content="{ hasMultipleVisualLines, composing, disabled, focus }">
+    <SButton
+      v-if="hasMultipleVisualLines === false && !composing && !disabled"
+      label="Справка по вводу"
+      size="sm"
+      appearance="text"
+      @click="focus()"
+    />
+  </template>
+</STextarea>
+```
+
 `minLength` и `maxLength` используют тот же строгий native contract, что и
 `SInputText`: принимают неотрицательные safe integers и требуют
 `minLength <= maxLength`. Ограничение применяется к пользовательскому вводу;
@@ -597,7 +973,128 @@ correction.
   @focus="handleFocus"
   @blur="handleBlur"
   @paste="handlePaste"
-/>
+>
+  <template #empty-content="{ disabled, readonly, focus }">
+    <SButton
+      label="Прикрепить файл"
+      size="sm"
+      appearance="text"
+      :disabled="disabled || readonly"
+      @click="selectAttachment(); focus()"
+    />
+  </template>
+  <template #helper-content="{ focus }">
+    <SButton label="Справка по вводу" size="sm" appearance="text" @click="openInputHelp(); focus()" />
+  </template>
+</STextarea>
+```
+
+Контекстное меню native textarea подключается через
+`SContextMenu` slot `textInputTriggerProps`. Он содержит `aria-haspopup="menu"`,
+`aria-controls` смонтированного открытого меню и `onKeydown` для ContextMenu/Shift+F10. Фокус, ввод и
+selection принадлежат `STextarea`; меню владеет pointer/keyboard activation,
+позиционированием, Escape и возвратом фокуса. ArrowUp/Down сохраняют native
+редактирование. IME composition и отменённое keydown не открывают меню.
+Для действий-кнопок используется отдельный `triggerProps` с
+`aria-expanded`: [WAI-ARIA textbox](https://www.w3.org/TR/wai-aria-1.2/#textbox)
+этого состояния не поддерживает. Raw button-oriented `triggerProps` не
+передаётся в textarea, её HTML-роль не заменяется.
+
+`triggerProps` открывает контекстное меню через ContextMenu и Shift+F10;
+при `trigger="click"` или `"both"` также доступны ArrowDown/ArrowUp.
+Событие компонента `before-open` синхронно передаёт исходный
+`SContextMenuBeforeOpenEvent = MouseEvent | KeyboardEvent` до перехвата native
+действия, монтажа меню и перемещения фокуса. Обработчик сохраняет точный текст
+выделения и обновляет реактивный `items`. `event.preventDefault()` отменяет
+открытие. Меню применяет текущий список после Vue commit; consumer не вызывает
+`nextTick`, таймер или повторное событие. Отменённое событие, `enabled=false`
+и IME composition не запускают подготовку и не открывают меню. Неактивная
+граница сохраняет native propagation.
+
+Подготовленный запрос принадлежит конкретной boundary и вызывающему элементу.
+Повторная активация заменяет его; отключение, удаление вызывающего элемента
+или boundary, unmount и Escape во время подготовки отменяют его без позднего
+открытия и захвата фокуса. Вложенные активные boundaries обрабатывают событие
+только в ближайшем владельце. Позиционирование, выбор действия, Escape и
+возврат фокуса принадлежат общему menu owner.
+
+Полный `triggerProps` предназначен для кнопки-триггера. Пассивная область
+`role="group"` получает только поддерживаемую её семантикой `aria-controls`.
+Этот атрибут присутствует только при открытом смонтированном меню;
+`aria-expanded` и `aria-haspopup` кнопки группе не передаются. Boundary кита
+делегирует ContextMenu/Shift+F10 от реально сфокусированного потомка, сохраняя
+его владельцем фокуса. Обычные клавиши редактирования не перехватываются.
+Consumer не добавляет группе native contextmenu/keydown handlers и не меняет
+роль ради открытия меню.
+
+```vue
+<SContextMenu
+  :items="selectionActions"
+  boundary-layout="contents"
+  v-slot="{ triggerProps }"
+  @before-open="captureSelection"
+>
+  <div
+    role="group"
+    aria-label="Действия с выделенным текстом"
+    tabindex="0"
+    :aria-controls="triggerProps['aria-controls']"
+  >
+    <slot />
+  </div>
+</SContextMenu>
+```
+
+```ts
+import type { SContextMenuBeforeOpenEvent } from '@pgcorp/ui-kit/shared/controls/SContextMenu.vue'
+
+function captureSelection(event: SContextMenuBeforeOpenEvent): void {
+  const selection = window.getSelection()
+  if (!selection) throw new Error('Native selection is unavailable')
+  selectedText.value = selection.toString()
+  if (!selectedText.value) event.preventDefault()
+}
+```
+
+The synchronous `before-open` component event receives the original admitted
+`MouseEvent | KeyboardEvent` before interception, mounting or menu focus.
+Update reactive items in that handler; `preventDefault()` cancels opening.
+The kit commits current items and owns initial focus, dismissal and request
+cleanup. Disabled, already-cancelled and composing events do not prepare a menu.
+Passive groups bind only the optional mounted-menu `aria-controls` relationship;
+the kit boundary delegates ContextMenu/Shift+F10 from the actual focused
+descendant. No native consumer listeners, fabricated button role or timer are
+required. Full `triggerProps` belongs to a button; `textInputTriggerProps`
+preserves native textbox editing and selection semantics.
+
+При сочетании menu и suggestions `suggestions.active` явно выбирает участие
+suggestion popup; default — `true`. Активные suggestions задают
+`aria-haspopup`, `aria-autocomplete` и `aria-activedescendant`. При
+`active=false` `activeDescendant` запрещён, `aria-haspopup` принадлежит
+внешнему context-menu owner. `aria-controls` объединяет проверенные canonical
+ID обоих owners без потери связи. Native `aria-controls` принимает один DOM ID
+внешнего popup; `suggestions.controls` — один DOM ID suggestion popup.
+Кит не определяет активность по DOM, не меняет ID и не создаёт focusable wrapper.
+
+The `textInputTriggerProps` slot binds a context menu to the native textarea
+without button-only `aria-expanded` or arrow-key menu activation. ContextMenu
+and Shift+F10 use the shared menu owner; Escape restores the editing owner's
+focus and selection. `suggestions.active` explicitly selects the suggestion
+popup's ARIA participation, while validated control references are merged.
+
+```vue
+<SContextMenu :items="editingActions" v-slot="{ textInputTriggerProps }">
+  <STextarea
+    v-model="message"
+    v-bind="textInputTriggerProps"
+    label="Сообщение"
+    :suggestions="{
+      controls: 'mention-listbox',
+      active: suggestionsVisible,
+      ...(suggestionsVisible && activeMentionId ? { activeDescendant: activeMentionId } : {}),
+    }"
+  />
+</SContextMenu>
 ```
 
 ```ts
@@ -614,6 +1111,8 @@ function handleFocus(event: FocusEvent): void {
 }
 
 composer.value?.setSelection({ start, end, direction: 'forward' })
+composer.value?.selectAll()
+composer.value?.selectAll(false)
 composer.value?.replaceSelection('@file README.md')
 ```
 
@@ -629,6 +1128,26 @@ IME composition fails with an explicit diagnostic. The `selection-change`,
 `compositionstart`, `compositionupdate`, `compositionend`, and `state-change`
 events synchronize a popup without reading internal DOM.
 
+`selectAll(focusOwner?: boolean): void` выделяет весь текущий native API value
+вперёд через общий selection owner. По умолчанию запрашивается focus;
+`false` сохраняет внешний focus. Readonly-текст доступен для выделения;
+disabled и detached элементы соблюдают native eligibility фокуса.
+Метод использует длину текущего `textarea.value`, включая ввод до подтверждения
+controlled model, и не изменяет исходные CRLF/Unicode bytes, model или input
+history. HTML API value исключает CR; consumer не переписывает source и не
+считает native offsets через `source.length`. Unmounted/disposed owner и
+неboolean focus policy дают явную ошибку.
+
+`selectAll(focusOwner?: boolean): void` selects the complete current native
+API value forward through the shared selection owner. It requests focus by
+default; `false` preserves external focus. Readonly text remains selectable;
+disabled and detached elements follow native focus eligibility.
+The method uses the current `textarea.value.length`, including edits awaiting
+controlled-model acknowledgement, and does not change the source CRLF/Unicode
+bytes, model, or input history. The HTML API value excludes CR; consumers do not
+rewrite the source or calculate native offsets from `source.length`.
+An unmounted/disposed owner or non-boolean focus policy throws an explicit error.
+
 ### Карточки и строки выбора / Choice cards and rows
 
 `SChoiceCards` использует `appearance="cards"` для крупных плиток и
@@ -672,6 +1191,20 @@ focus, and keyboard contracts remain unchanged.
 </SButton>
 ```
 
+### Доступность действий / Action availability
+
+`SButton.disabled` и `loading` исключают native activation и Tab focus;
+недоступная `href`-кнопка не содержит navigation target. При разрешении
+действия foreground и background применяются одной контрастной парой без
+интерполяции цветов. Действие доступно сразу, без ожидания декоративной
+анимации; transition тени и transform не меняет читаемость подписи.
+
+`SButton.disabled` and `loading` prevent native activation and Tab focus;
+an unavailable `href` button has no navigation target. Enabling an action
+applies its foreground/background contrast pair atomically, without color
+interpolation. The action is immediately available, independently of
+decorative shadow or transform transitions.
+
 ### Controlled checkbox и switch / Controlled checkbox and switch
 
 `SCheckbox` и `SSwitch` всегда отражают authoritative `modelValue` в native
@@ -688,6 +1221,22 @@ supports asynchronous persistence or rejection without rekeying, manual DOM
 resets, or an optimistic model. The consumer updates `modelValue` normally
 after confirmation.
 
+У `SCheckbox` единственный focus owner — native checkbox. Прозрачный input
+покрывает индикатор и его pointer target; нажатие на индикатор или связанную
+подпись выполняет одно действие. Обычный field использует semantic hitbox
+`--s-control-hitbox-2xs`, inline-представление — размер индикатора, согласованный
+со строкой документа. Tab переводит фокус на input, Space переключает его,
+focus-visible отображается на индикаторе. `disabled` и `readonly` не эмитят
+изменение или click; `indeterminate` показывает частичный выбор через минус.
+
+`SCheckbox` has one focus owner: the native checkbox. Its transparent input
+covers the indicator and its pointer target; activating the indicator or its
+associated label performs one action. Field presentation uses the semantic
+`--s-control-hitbox-2xs` target; inline presentation uses the indicator size
+aligned with document text. Tab focuses the input, Space toggles it, and the
+indicator renders focus-visible. `disabled` and `readonly` emit neither change
+intent nor click; `indeterminate` represents partial selection with a minus.
+
 ```vue
 <SSwitch
   :model-value="autoPublish"
@@ -721,17 +1270,145 @@ contract applies only to textual types: `text`, `search`, `password`, `email`,
 
 ### Drawer placement
 
-`SDrawer` использует `placement="right"` по умолчанию. Нижняя панель задаётся
-`placement="bottom"`; semantic sizes соответствуют 50, 70 и 90 процентам
-dynamic viewport height. Body остаётся единственным scroll owner, а overlay,
-focus trap/restore, Escape, backdrop и nested layer stack совпадают с боковой
-панелью.
+`SDrawer.placement` принимает `left | right | bottom`, по умолчанию — `right`.
+`left` и `right` обозначают физическую сторону независимо от направления текста.
+Боковые панели используют общую шкалу `sm/md/lg`: максимальная ширина
+`30/36/44rem`, ограниченная viewport. При `scope="viewport"` нижняя панель
+`placement="bottom"` занимает `50/70/90` процентов dynamic viewport height.
+`mobileFullScreen` задаёт полноширинную боковую viewport-панель на узком экране;
+размещение, header/body/footer и доступность действий сохраняются.
+При `scrollBehavior="body"` body — единственный scroll owner. Все размещения
+используют общие viewport overlay, focus trap/restore, Escape, backdrop и nested
+layer stack.
+
+Viewport `SModal` и `SDrawer` используют единственный нативный `dialog` в
+modal top layer. Фон, включая SVG, MathML и shadow-композиции, исключён из
+pointer/focus interaction и accessibility tree. Дочерние select, меню, popover
+и tooltip используют принадлежащий этому dialog portal вне transform и
+scroll clipping. Вложенный viewport dialog изолирует родителя до закрытия.
+Native blocking освобождается синхронно при retirement; общая focus lease
+управляет возвратом, независимо от завершения visual leave.
+
+`SDrawer.placement` accepts `left | right | bottom`, defaulting to `right`.
+`left` and `right` are physical sides independent of text direction. Side
+drawers share the `sm/md/lg` scale: viewport-bounded maximum widths of
+`30/36/44rem`. With `scope="viewport"`, a `placement="bottom"` sheet occupies
+`50/70/90` percent of the dynamic viewport height. `mobileFullScreen` provides
+a full-width side viewport drawer on a narrow screen while preserving its
+placement, header/body/footer and reachable actions. With
+`scrollBehavior="body"`, the body is the sole scroll owner. All placements
+share viewport overlay, focus trap/restore, Escape, backdrop and the nested
+layer stack.
+
+Viewport `SModal` and `SDrawer` use one native `dialog` in the modal top layer.
+Background content, including SVG, MathML, and shadow compositions, is excluded
+from pointer/focus interaction and the accessibility tree. Descendant selects,
+menus, popovers, and tooltips use that dialog's portal outside transforms and
+scroll clipping. A nested viewport dialog isolates its parent until closed.
+Retirement releases native blocking synchronously; the shared focus lease
+controls restoration independently of visual leave completion.
+
+Для обновления на `0.15` готовые `SModal`/`SDrawer` сохраняют публичные props,
+slots и events. Собственный viewport leaf на экспортируемом `useDialogOverlay`
+требует миграции: `setPanelElement` получает native `HTMLDialogElement`, а
+`setPortalElement` — его непосредственный дочерний HTMLElement portal.
+Разметка, стили принадлежащих leaf surfaces и controlled close описаны в
+[`docs/overlay-lifecycle.md`](https://github.com/pglyanenko/sputnig/blob/master/packages/ui-kit/docs/overlay-lifecycle.md),
+включая карту binding исполняемой story `SModal.NativeOwnerContract`.
+
+For an upgrade to `0.15`, the ready-made `SModal`/`SDrawer` preserve their public
+props, slots, and events. A custom viewport leaf using the exported
+`useDialogOverlay` requires migration: `setPanelElement` receives a native
+`HTMLDialogElement`, and `setPortalElement` receives its direct-child HTMLElement
+portal. The owned markup, styles, and controlled close contract are documented in
+[`docs/overlay-lifecycle.md`](https://github.com/pglyanenko/sputnig/blob/master/packages/ui-kit/docs/overlay-lifecycle.md),
+including the binding map of the executable `SModal.NativeOwnerContract` story.
+
+`scope="contained"` требует ближайший `SOverlayHost`. Его default-слот содержит
+основную историю, `#overlay` — панель. Размеры `sm/md/lg` означают 50/70/90%
+доступной области по оси `placement`; `extent` принимает конечный процент больше
+0 и не больше 100. Для `left/right` это ширина host, для `bottom` — высота.
+`extent` применим только к contained-режиму. Размеры host
+принадлежат композиции страницы; размер и оформление панели принадлежат киту.
+`mobileFullScreen` не переводит contained-панель за границы host.
+`scope` меняется только при `open=false`; переход между владельцами не переносит
+открытый overlay lifetime.
+
+Contained drawer — немодальный `dialog`: composer и terminal вне host остаются
+доступны, global body lock и собственный Tab trap отсутствуют. Основное
+содержимое host имеет `inert` на время открытой панели и сохраняет DOM/прокрутку.
+Нативный диапазон выделения сохраняет text owner и координаты; видимое выделение
+следует браузерному `inert`-контракту и доступно после закрытия панели.
+Escape и нажатие backdrop обрабатываются внутри host; внешний ввод не закрывает
+панель и не получает отложенный возврат чужого фокуса. Вложенный `SModal`
+использует общий stack, глобальную модальность и свой focus trap.
+
+`scrollBehavior="body"` оставляет padded body единственным scroll owner.
+`scrollBehavior="content"` предоставляет растягиваемый слот без полей и второго
+скролла для `SVirtualList` или `SScrollViewport block-size="fill"`.
+Consumer обрабатывает `update:open`, в том числе при retirement host. Удаление,
+замена или ошибка host завершают его слои и pending focus/`opened`; повторное
+открытие — явный переход `open=false` → `true`. Новый host с новым drawer и
+`open=true` является новым запросом, а не продолжением предыдущего lifetime.
+
+`scope="contained"` requires the nearest `SOverlayHost`. Its default slot owns
+the main history, and `#overlay` owns the drawer. Sizes `sm/md/lg` mean
+50/70/90% of the available host extent along the placement axis; `extent` is a
+finite percentage greater than 0 and at most 100, valid only for contained
+drawers. The axis is host width for `left/right` and host height for `bottom`.
+Page composition owns host dimensions; the kit owns drawer geometry
+and presentation. `mobileFullScreen` does not move a contained drawer outside
+its host.
+`scope` changes only while `open=false`; changing owners does not transfer an
+open overlay lifetime.
+
+A contained drawer is a nonmodal dialog: external composer/terminal remain
+available, without global body locking or its own Tab trap. Host background
+content is inert while the drawer is open and retains its DOM/scroll position.
+Native selection ranges retain their text owner and offsets; visible selection
+follows the browser's inert contract and is available after the drawer closes.
+Escape and backdrop dismissal are host-scoped; external input neither closes
+the drawer nor receives a stale focus restoration. A nested `SModal` uses the
+same layer stack with global modality and its own focus trap.
+
+`scrollBehavior="body"` provides the padded body scroll owner.
+`scrollBehavior="content"` provides a stretching slot without padding or a
+second scroll container for `SVirtualList` or `SScrollViewport block-size="fill"`.
+The consumer handles `update:open`, including host retirement. Host removal,
+replacement, or failure retires its layers and pending focus/`opened`; reopen
+requires an explicit `open=false` → `true` transition. A new host and a new
+drawer with `open=true` represent a new request, not the previous lifetime.
+
+```vue
+<SDrawer
+  v-model:open="navigationOpen"
+  title="Проекты и чаты"
+  placement="left"
+  size="md"
+>
+  <ProjectChatNavigation />
+</SDrawer>
+```
 
-`SDrawer` uses `placement="right"` by default. Set `placement="bottom"` for a
-bottom sheet; semantic sizes map to 50, 70, and 90 percent of the dynamic
-viewport height. The body remains the sole scroll owner, while overlay,
-focus trap/restore, Escape, backdrop, and the nested layer stack are shared
-with the side drawer.
+```vue
+<SOverlayHost>
+  <ConversationHistory />
+  <template #overlay>
+    <SDrawer
+      v-model:open="historyOpen"
+      title="История подагента"
+      scope="contained"
+      placement="bottom"
+      size="lg"
+      scroll-behavior="content"
+    >
+      <VirtualSubagentHistory />
+    </SDrawer>
+  </template>
+</SOverlayHost>
+<Composer />
+<Terminal />
+```
 
 ```vue
 <SDrawer
@@ -745,19 +1422,47 @@ with the side drawer.
 </SDrawer>
 ```
 
+### Передача фокуса из меню / Menu focus handoff
+
+Открытие `SDrawer` из действия `SDropdownMenu` передаёт initial focus
+диалогу и сохраняет устойчивый menu trigger для возврата при закрытии.
+Меню и его trigger могут находиться вне contained host. Удаление временного
+menuitem в render-cycle не делает его целью возврата и не расширяет
+Escape boundary за пределы host. Повторные открытия используют отдельный
+open-cycle. Внешний переход фокуса отменяет незавершённую передачу и stale
+return; consumer не восстанавливает фокус DOM-вызовом.
+
+Передача относится к текущему open intent и связанному завершению menu
+lifetime. Произвольное ожидание сервера перед первым запросом открытия не
+сохраняет право перехватить последующий внешний фокус.
+
+Opening `SDrawer` from an `SDropdownMenu` action transfers initial focus
+to the dialog and retains the stable menu trigger for restoration on close.
+The menu and its trigger may live outside a contained host. Removing the
+transient menu item during rendering neither makes it a restoration target
+nor extends Escape handling beyond the host. Repeated openings have separate
+open cycles. An external focus change cancels pending handoff and stale
+restoration; consumers do not restore focus with DOM calls.
+
+Handoff belongs to the current opening intent and the associated menu
+retirement. Arbitrary server work before the first opening request does not
+preserve permission to take subsequent external focus.
+
 ### Dialog heading hierarchy
 
 `SModal` и `SDrawer` используют `heading-level="2"` по умолчанию: самостоятельный
 диалог следует за основным `h1` страницы. Для диалога, вложенного в секцию или
 другой dialog surface, consumer передаёт фактический уровень document outline
-числом от `1` до `6`. Видимый заголовок при любом уровне остаётся accessible name
+числом от `1` до `6`. Локальная шапка диалога не создаёт page-level `banner`.
+Видимый заголовок при любом уровне остаётся accessible name
 через `aria-labelledby`; заменять его локальным заголовком или DOM-обходом не
 нужно.
 
 `SModal` and `SDrawer` default to `heading-level="2"`, so a standalone dialog
 follows the page's primary `h1`. A dialog nested in a section or another dialog
 surface receives its actual document-outline level from the consumer as an
-integer from `1` through `6`. At every level the visible title remains the
+integer from `1` through `6`. Local dialog chrome does not create a page-level
+`banner` landmark. At every level the visible title remains the
 accessible name through `aria-labelledby`; no local heading or DOM workaround
 is required.
 
@@ -783,6 +1488,62 @@ responsive and shrinks to the available viewport. If a child mount fails, the
 modal releases its body lock, layer registration, and owned teleport nodes
 before the error reaches the host application.
 
+### Управляемое открытие popover / Controlled popover opening
+
+`SPopover` поддерживает `v-model:open` и программные `open(triggerId?)`/`close()`.
+Запрос от trigger сохраняет его native anchor и исходный focus owner до
+подтверждения `open`, включая отложенное применение prop. Если фокус переведён
+во внешний редактор, появление панели не перехватывает его. Открытие напрямую
+через prop использует текущий focus owner. `close()` отменяет ожидающий запрос
+через `update:open=false`; закрытие восстанавливает фокус только из принадлежащей
+панели, не из внешнего поля. Каждый новый цикл использует актуального invoker.
+Удаление или отключение текущего focused action оставляет панель открытой;
+Принятое закрытие через Escape восстанавливает focus доступному
+зарегистрированному trigger. Явный blur
+доступного элемента и переход во внешний focus owner закрывают панель
+по outside-политике без перехвата внешнего focus.
+
+`SPopover` supports `v-model:open` and the programmatic `open(triggerId?)`/`close()`
+API. A trigger request preserves its native anchor and original focus owner
+through acknowledgement, including delayed prop application. A panel does not
+take focus from an external editor focused in the meantime. Direct prop-driven
+opening uses the current focus owner. `close()` cancels a pending request with
+`update:open=false`; closing restores focus only from the owned panel, not an
+external field. Each new cycle uses its current invoker.
+Removing or disabling the currently focused action keeps the panel open;
+An accepted Escape close restores focus to the available registered trigger.
+Explicitly blurring an
+available element or moving to an external focus owner dismisses the panel
+under its outside policy without taking external focus.
+
+`width="trigger"` задаёт минимальную ширину anchor; `content` сохраняет
+intrinsic-ширину содержимого. `sm`, `md`, `lg` задают `20rem`, `28rem`, `36rem`
+с viewport-ограничением. Фон, тень и focus surface занимают полный dialog;
+`surface="transparent"` задаёт максимальную ширину всего dialog `90vw`;
+при `width="trigger"` минимальная ширина anchor имеет приоритет над этим максимумом.
+
+`width="trigger"` sets the anchor's minimum width; `content` keeps the content's
+intrinsic width. `sm`, `md`, and `lg` specify `20rem`, `28rem`, and `36rem`,
+bounded by the viewport. Background, shadow, and focus surface occupy the full
+dialog; `surface="transparent"` sets the entire dialog's maximum width to `90vw`.
+With `width="trigger"`, the anchor minimum takes precedence over this maximum.
+
+### Читаемость всплывающих поверхностей / Overlay motion readability
+
+`SDrawer`, `SPopover`, `STooltip`, `SContextMenu` и
+`SControlledToastViewport` сохраняют `opacity: 1` содержимого
+при открытии и закрытии. Прозрачность выбранного фона принадлежит surface
+контракту, а не анимации. Анимация использует перемещение и масштаб;
+backdrop имеет отдельный opacity transition. Reduced-motion предпочтение,
+focus ownership и keyboard dismissal принадлежат общим owners кита.
+
+`SDrawer`, `SPopover`, `STooltip`, `SContextMenu`, and
+`SControlledToastViewport` keep content at `opacity: 1` during entry and
+exit. Background translucency belongs to the selected surface contract,
+not the animation. Motion uses translation and scale; the backdrop has an independent
+opacity transition. Reduced-motion preference, focus ownership, and keyboard
+dismissal belong to the kit's shared owners.
+
 ### Управляемое dropdown menu / Controlled dropdown menu
 
 `SDropdownMenu` поддерживает controlled `v-model:open`, начальное
@@ -799,6 +1560,31 @@ for asynchronous operations and repeated selection. `kind="group"` creates a
 semantic group with a visible label, while `description` adds an accessible
 item hint through `aria-describedby` without another tab stop.
 
+Dropdown, контекстные и вложенные меню автоматически ограничиваются доступной
+областью viewport. `placement` задаёт предпочтительную сторону; collision
+handling допускает переход на другую сторону. Полный список пунктов сохраняется,
+а высокий список прокручивается внутри menu surface с единым chrome и scroll
+owner. Высота учитывает размеры viewport и содержимого; consumer не задаёт
+`max-height` и не переоформляет внутренности меню. Arrow/Home/End раскрывают
+сфокусированный пункт в этом viewport без прокрутки фонового документа.
+Внутренняя прокрутка сохраняет открытое меню и его родительский layer.
+Home/End повторно раскрывают текущую строку после ручной прокрутки. Если ни одна
+inline-сторона не вмещает вложенную menu surface, общий collision owner выбирает
+доступную верхнюю или нижнюю сторону.
+Escape закрывает текущий уровень и возвращает фокус его trigger.
+
+Dropdown, context, and nested menus are automatically bounded by the available
+viewport. `placement` specifies the preferred side; collision handling can
+choose the opposite side. The complete item inventory is retained, while a
+tall list scrolls inside the menu surface with one chrome and scroll owner.
+Its height follows the viewport and content dimensions; consumers do not set
+`max-height` or restyle menu internals. Arrow/Home/End reveal the focused item
+inside this viewport without scrolling the background document. Internal
+scrolling preserves the open menu and its parent layer. Home/End reveal the
+current row after manual scrolling. If neither inline side can fit a submenu
+surface, the shared collision owner selects the available top or bottom side.
+Escape closes the current level and returns focus to its trigger.
+
 ```vue
 <SDropdownMenu
   v-model:open="workspaceMenuOpen"
@@ -820,6 +1606,63 @@ item hint through `aria-describedby` without another tab stop.
 `SButton` disclosure hitbox at `32px`; `comfortable` retains the default
 geometry. Consumers do not set height, padding, or internal selectors.
 
+### Семантика сворачиваемой панели / Collapsible panel semantics
+
+`SCollapsiblePanel.contentRole` принимает `region | group`; по умолчанию
+`region`. Самостоятельные, значимые для навигации разделы используют
+`region`; повторяемые и вложенные сведения — `group`, не создающий
+landmark. Обе роли сохраняют доступное имя из видимого `summary` через
+`aria-labelledby` и связь с disclosure trigger через `aria-controls`.
+Повторяемые группы могут иметь одинаковые пользовательские заголовки.
+Роль задаётся prop, не raw `role` attr; неизвестное значение вызывает
+ошибку контракта. `lazy` монтирует slot при первом принятом раскрытии
+и удерживает содержимое после сворачивания, включая анимированный
+неуправляемый режим.
+
+Controlled `open` эмитит `update:open` как намерение до подтверждения prop;
+uncontrolled режим изменяет собственное состояние без этого события.
+
+Принятое сворачивание сразу исключает content из клавиатурного обхода и
+дерева доступности через `inert` и `aria-hidden`; завершающая визуальная
+анимация сохраняет mounted slot. Фокус внутри закрываемого content
+возвращается доступному trigger через его публичный focus API. Внешний
+фокус и неподтверждённое controlled намерение не перехватываются.
+Motion завершается по фактическому переходу высоты или сразу при его
+отсутствии; reduced motion, повторное раскрытие и изменение содержимого
+не требуют ожиданий или DOM-вызовов consumer.
+
+`SCollapsiblePanel.contentRole` accepts `region | group` and defaults to
+`region`. Independently significant, navigable sections use `region`;
+repeated and nested details use the non-landmark `group`. Both roles
+retain an accessible name from the visible `summary` through
+`aria-labelledby` and the trigger relationship through `aria-controls`.
+Repeated groups may share the same user-facing heading. The role is
+specified by a prop, not a raw `role` attr; an unknown value fails the
+contract. `lazy` mounts the slot on its first accepted opening and retains
+the content after collapse, including animated uncontrolled mode.
+
+Controlled `open` emits an `update:open` intent before prop acknowledgement;
+uncontrolled mode updates its owned state without that event.
+
+An accepted collapse immediately excludes content from keyboard navigation
+and the accessibility tree using `inert` and `aria-hidden`; the closing
+visual transition retains the mounted slot. Focus inside the collapsing
+content returns to an available trigger through its public focus API.
+External focus and unacknowledged controlled intent are not intercepted.
+Motion settles on the actual height transition or immediately when none
+exists; reduced motion, reopening, and content changes require no consumer
+waits or DOM calls.
+
+```vue
+<SCollapsiblePanel summary="Технические сведения" content-role="group" lazy>
+  <SInputText v-model="connectionName" label="Имя подключения" />
+</SCollapsiblePanel>
+```
+
+[APG Accordion](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) рассматривает
+landmark role как необязательный; [ARIA group](https://www.w3.org/TR/wai-aria-1.2/#group)
+предназначен для локальной группировки без включения в оглавление страницы.
+
 ### Dialog open lifecycle
 
 `SModal` и `SDrawer` эмитят `opened` один раз для каждого подтверждённого цикла
@@ -836,13 +1679,65 @@ focus. The handler can call a nested leaf's public exposed API, such as
 cancels the event; Escape, focus trapping, and focus restoration remain owned
 by the dialog surface.
 
+Закрытие через `open=false` и удаление открытой feature-формы через `v-if`
+поддерживают один focus-контракт, включая удаление формы в том же обработчике,
+который закрывает вложенное или соседнее подтверждение. После удаления
+владеющего фокусом dialog focus возвращается подключённому, видимому инициатору,
+допустимому в текущей modal boundary. Consumer не ожидает отдельное событие
+закрытия и не вызывает DOM `focus()`/`nextTick()` для восстановления. Новый
+overlay или явное перемещение фокуса отменяют отложенный возврат. Скрытие
+retained dock и аварийное освобождение overlay не возвращают focus скрытому
+или inert инициатору.
+
+Retained dialog сохраняет право возврата после удаления или отключения
+focused action во время асинхронной операции. Утрата native focus
+определяется по завершённому DOM-обновлению: focus остаётся на BODY, а
+наблюдённый descendant удалён или потерял native focus capability.
+Отдельный blur живого enabled элемента, завершённый до его удаления,
+отменяет это право. Перемещение фокуса на другой owner отменяет его сразу,
+включая последующий blur этого owner. Consumer не подавляет blur/removal
+events и не управляет порядком native focus fixup.
+
+Closing with `open=false` and removing an open feature form with `v-if` share
+one focus contract, including removal in the same handler that closes a nested
+or sibling confirmation. After removing the focus-owning dialog, focus returns
+to its connected, visible invoker if allowed by the current modal boundary.
+Consumers need no separate close acknowledgement or DOM `focus()`/`nextTick()`
+for restoration. A new overlay or explicit focus move cancels pending
+restoration. Retained dock hiding and error cleanup do not restore focus to a
+hidden or inert invoker.
+
+A retained dialog preserves focus return after a focused action is removed
+or disabled during asynchronous work. Native focus loss is evaluated after
+the DOM update: focus remains on BODY and the observed descendant is removed
+or loses its native focus capability. A separate blur of a live enabled
+element, completed before removal, cancels this ownership. Moving focus to
+another owner cancels it immediately, including a later blur of that owner.
+Consumers do not suppress blur/removal events or manage native focus-fixup order.
+
 ```vue
-<SModal v-model:open="open" title="Исходный текст" @opened="selectAll">
+<SModal v-model:open="open" title="Исходный текст" @opened="textarea?.selectAll()">
   <STextarea ref="textarea" :model-value="source" label="Текст" readonly />
 </SModal>
 ```
 
-### Assistive live status
+### Status presentation and assistive announcements
+
+Видимый `SStatus` использует общую feedback-пару `tone`; `neutral` соответствует
+нейтральной `secondary`-паре. `appearance="soft"` владеет своим непрозрачным
+фоном и foreground. Текстовый статус внутри пассивного slot `SButton` использует
+foreground интерактивного владельца, включая solid, hover, active и focus;
+`tone`, текст и семантическая иконка сохраняются. `SCollapsiblePanel.summaryStatus`
+использует этот же контракт в compact/dense заголовке. Локальные color overrides
+для вложенных статусов не требуются.
+
+Visible `SStatus` uses the shared feedback `tone` pair; `neutral` maps to the
+neutral `secondary` pair. `appearance="soft"` owns its opaque background and
+foreground. A text status in an `SButton` passive slot uses the interactive
+owner's foreground across solid, hover, active, and focus states; `tone`, its
+label, and the semantic icon are preserved. `SCollapsiblePanel.summaryStatus`
+uses the same contract in compact/dense headers. Nested statuses require no
+local color overrides.
 
 `SStatus` с `visibility="assistive"` выводит всю status surface из layout,
 сохраняя текст сообщения в accessibility tree. `live="polite"` или
@@ -899,7 +1794,7 @@ snapshot can move between instances or be retained while switching chats.
   @viewport-change="viewport = $event"
 >
   <template #header>
-    <SButton variant="ghost" @click="loadPreviousPage">
+    <SButton appearance="ghost" @click="loadPreviousPage">
       Загрузить предыдущие
     </SButton>
   </template>
@@ -913,10 +1808,13 @@ snapshot can move between instances or be retained while switching chats.
 ```
 
 ```ts
-const snapshot = history.value?.captureViewport()
-await history.value?.restoreViewport(snapshot)
-history.value?.scrollToKey(messageId, 'center')
-history.value?.scrollToEnd({ follow: true })
+const historyOwner = history.value
+if (historyOwner) {
+  const snapshot = historyOwner.captureViewport()
+  await historyOwner.restoreViewport(snapshot)
+  historyOwner.scrollToKey(messageId, 'center')
+  historyOwner.scrollToEnd({ follow: true })
+}
 ```
 
 `viewport-change` сообщает keyed anchor, visible range, `nearStart`, `atEnd` и
@@ -928,6 +1826,11 @@ Paging, status и end-marker рендерятся через `header`/`footer`,
 синтетические элементы domain-списка. Home, End, Page и Arrow keys владеют
 viewport navigation только при focus самого `SVirtualList`; вложенный
 editable/control сохраняет свою keyboard-семантику.
+Строка с фактическим DOM-фокусом сохраняет keyed DOM identity при изменении
+измерений, viewport и rendered range. Вложенный редактор сохраняет focus и
+selection без программного перевода фокуса. Lease удерживает только одну
+дополнительную строку вне виртуального окна и снимается при focusout из строки,
+удалении её domain key или unmount. `header`/`footer` не входят в keyed lease.
 
 `viewport-change` reports the keyed anchor, visible range, `nearStart`, `atEnd`,
 and `pinnedToEnd`. An upward wheel, keyboard, or scrollbar gesture detaches
@@ -939,6 +1842,12 @@ Paging, status, and end markers belong in `header`/`footer`, not in the keyed
 domain items. Home, End, Page, and Arrow keys control the viewport only while
 `SVirtualList` itself owns focus; a nested editable/control retains its own
 keyboard semantics.
+The row containing actual DOM focus retains its keyed DOM identity across
+measurement, viewport, and rendered-range changes. A nested editor preserves
+focus and selection without programmatic refocusing. This lease retains only
+one additional row outside the virtual window and ends when focus leaves that
+row, its domain key is removed, or the list unmounts. `header`/`footer` regions
+do not own a keyed row lease.
 
 ## Темы и стили / Themes and styles
 
@@ -960,6 +1869,26 @@ application's own `@import "tailwindcss"`:
 typography plugin. `reference.css` is a compile-time `@reference` target for
 component styles.
 
+Оба CSS entrypoint используют полную сборку upstream typography plugin внутри
+пакета. Устанавливать `@tailwindcss/typography` или переопределять его transitive
+зависимости в consumer не требуется. Лицензии включённых модулей находятся в
+`dist/typography.LICENSE.txt`. / Both CSS entrypoints use the complete upstream
+typography plugin bundled in the package. Consumers do not need to install
+`@tailwindcss/typography` or override its transitive dependencies. The included
+module licenses are provided in `dist/typography.LICENSE.txt`.
+
+`dist/typography.js` — build-time Node ESM plugin. Он использует native
+`node:util`, сохраняет upstream options API `className`/`target` для
+`modern` и `legacy`, полный prose handler и theme. Импорты
+`tailwind.css`/`reference.css` не требуют browser Web Storage, DOM globals
+или дополнительных Node flags в consumer build.
+
+`dist/typography.js` is a build-time Node ESM plugin. It uses native
+`node:util` and retains the upstream `className`/`target` options for
+`modern` and `legacy`, the complete prose handler, and theme. Building
+`tailwind.css`/`reference.css` needs neither browser Web Storage nor
+DOM globals or additional Node flags.
+
 Для token-only интеграции доступен отдельный entrypoint:
 
 A separate entrypoint is available for token-only integration:
@@ -1000,8 +1929,12 @@ Components consume semantic custom properties. Consumers override documented
 tokens on the root theme container and do not depend on internal CSS classes or
 template structure.
 
-Floating surfaces teleport to `document.body`; toast, drag fallbacks, modal, and
-drawer also use root-level bands. The values `--s-layer-floating`,
+Unscoped floating surfaces teleport to `document.body`. Floating descendants of
+a viewport dialog use its untransformed portal. Native modal top-layer order
+belongs to the browser, not to a larger `z-index`. Global notifications remain
+background content during viewport modality; a modal-local notification viewport
+uses its own dialog's portal. Toast and drag root bands do not override native
+top-layer isolation. The values `--s-layer-floating`,
 `--s-layer-toast`, `--s-layer-drag`, and `--s-layer-overlay-backdrop` are base
 anchors. Registered nested layers advance by `--s-layer-overlay-step`, while a
 modal surface uses `--s-layer-overlay-surface-offset` above its backdrop.
@@ -1017,6 +1950,7 @@ Integrate a host overlay scale through one root offset:
 
 `--host-overlay-surface` belongs to the host application. The offset shifts all
 root UI-kit bands together and leaves local content/navigation anchors intact.
+It integrates ordinary host stacking contexts, not another native top layer.
 Do not combine it with manual shifts of individual layer tokens. The complete
 owner map, dynamic-stack contract, and verification checklist are published in
 `docs/theming.md` inside the npm package.
@@ -1036,6 +1970,79 @@ separator по умолчанию использует `compact`, overlay handle
 Для 12-пиксельной границы workbench-панели используйте `standard`, не изменяя
 внутренние стили компонента.
 
+Pointer resize имеет отдельные `resize-end` и `resize-cancel`: завершение
+принимает конечную координату, отмена возвращает snapshot без сохранения
+preview. `SDockRegion` передаёт `hitbox` и поддерживает opt-in
+`collapseThreshold` с отдельным `collapse({ preferredSize })` intent.
+Клавиатурный Home остаётся установкой минимального размера. Типы, transaction
+ownership и примеры включены в пакет: `docs/resize.md`.
+
+### Сохранение скрытой рабочей панели / Hidden dock content retention
+
+`SDockRegion.keepMounted` — boolean с default `false`: скрытие освобождает
+slot owner. При `true` один slot owner сохраняется, включая начальное
+`visible=false`. Скрытый регион имеет нулевой layout, `hidden`/`inert`,
+не участвует в Tab, pointer или accessibility tree и не содержит resize handle.
+Скрытие во время drag отменяет resize через его общий lifecycle без terminal
+commit. Повторное отображение сохраняет экземпляр и native состояние содержимого,
+но не забирает focus у внешнего editor. Выключение retention у скрытого региона
+или unmount освобождает его содержимое.
+
+Вложенные UI-kit menu, listbox, popover, tooltip и dialog следуют `visible`,
+включая Teleport-поверхности: скрытие завершает открытые и ожидающие циклы,
+освобождает overlay leases/body lock и не возвращает focus скрытому trigger.
+Начальный hidden state запрещает открытие. Controlled `open=true` получает
+один close intent; для нового открытия требуется запрос `false → true`.
+Отображение retained content не возобновляет завершённый цикл. Вложенные dock
+сочетают visibility через логическое AND, независимые sibling overlays не
+затрагиваются. Произвольные consumer-owned portals остаются ответственностью
+consumer.
+
+Содержимое, transport и output buffer принадлежат consumer. Для imperative
+терминала экземпляр получает output и при скрытом регионе; `Terminal.open()`
+вызывается только для connected, видимого host с положительными размерами.
+UI-kit не импортирует xterm и не пересоздаёт PTY. Политика едина для
+`left | right | bottom` и `fixed | fill-on-narrow`.
+
+`SDockRegion.keepMounted` is a boolean defaulting to `false`: hiding disposes
+the slot owner. With `true`, the same owner remains mounted, including initial
+`visible=false`. The hidden region has zero layout footprint, is `hidden` and
+`inert`, participates in no Tab/pointer/accessibility navigation, and contains
+no resize handle. Hiding during a drag cancels the shared resize lifecycle
+without a terminal commit. Showing retains the instance and its native state
+without stealing focus from an external editor. Disabling retention while
+hidden or unmounting disposes the content.
+
+Nested UI-kit menus, listboxes, popovers, tooltips, and dialogs follow `visible`,
+including their Teleport surfaces. Hiding retires open and pending cycles,
+releases overlay leases/body locks, and never restores focus to a hidden trigger.
+Initially hidden content cannot open an overlay. Controlled `open=true` receives
+one close intent and requires a fresh `false → true` request. Showing retained
+content does not resurrect a retired cycle. Nested docks compose visibility with
+logical AND; independent sibling overlays are unaffected. Arbitrary
+consumer-owned portals remain the consumer's responsibility.
+
+Content, transport, and output buffers belong to the consumer. An imperative
+terminal can receive output while hidden; call `Terminal.open()` only for a
+connected, visible host with positive dimensions. The UI-kit does not import
+xterm or restart a PTY. The policy applies to `left | right | bottom` and
+`fixed | fill-on-narrow`.
+
+```vue
+<SDockRegion
+  placement="bottom"
+  :visible="terminalVisible"
+  keep-mounted
+  :size="terminalHeight"
+  :min-size="160"
+  :max-size="480"
+  resize-label="Высота терминала"
+  @resize="terminalHeight = $event"
+>
+  <TerminalViewport :visible="terminalVisible" />
+</SDockRegion>
+```
+
 ## Публичный контракт / Public contract
 
 `package.json#exports` — источник истины для импортов. Публичный контракт
@@ -1087,16 +2094,33 @@ local DOM listeners or CSS.
 
 ## Версии / Versioning
 
-Пакет следует Semantic Versioning:
+Пакет следует [Semantic Versioning](https://semver.org/). В серии `0.x`
+контракт развивается по явной политике:
+
+The package follows [Semantic Versioning](https://semver.org/). The `0.x` series
+uses an explicit development policy:
+
+- `0.y.patch` сохраняет документированный public API;
+  `0.y.patch` preserves the documented public API;
+- `0.minor.0` может расширять API или требовать явно описанной миграции.
+  Затронутая поверхность и действия consumer фиксируются в release notes и guide;
+  `0.minor.0` may extend the API or require an explicitly documented migration.
+  Release notes and a guide identify the affected surface and consumer actions.
+
+Обновление между minor-сериями `0.x` требует чтения migration notes и проверки
+своей композиции; один только minor номер не обещает отсутствие миграции.
+
+Upgrading between `0.x` minor series requires reviewing migration notes and
+verifying the consumer composition; a minor number alone does not guarantee a
+migration-free upgrade.
 
-The package follows Semantic Versioning:
+Начиная с `1.0.0` действует стабильный public API: `patch` — совместимое
+исправление, `minor` — совместимое расширение, `major` — несовместимое изменение
+exports, props, events, tokens или поведения.
 
-- `patch` — исправление с сохранением документированного контракта;
-  a fix that preserves the documented contract;
-- `minor` — обратно совместимое расширение public API;
-  a backward-compatible public API extension;
-- `major` — несовместимое изменение exports, props, events, tokens или поведения;
-  an incompatible change to exports, props, events, tokens, or behavior.
+From `1.0.0`, the public API is stable: `patch` is a compatible fix, `minor` is
+a compatible extension, and `major` is an incompatible change to exports,
+props, events, tokens, or behavior.
 
 Один и тот же номер версии не публикуется повторно.