@rt-tools/agent-kit 0.5.3 → 0.7.0

package/assets/patterns/git-workflow-docker.md

@@ -0,0 +1,203 @@
+---
+name: git-workflow-docker
+kind: pattern
+rule: git-workflow
+description: Паттерн правила git-workflow. Брать при работе с образами на своей машине — подъём и перезапуск демона, диагностика «висящей» команды, сборка под платформу прод-сервера, одноразовый контейнер рядом с чужими, вход в реестр из службы. Не брать для команд прод-сервера и выбора образа — это паттерн git-workflow-restart, и не для наката миграций — это git-workflow-migration.
+---
+
+# Образы на своей машине
+
+Паттерн правила `git-workflow`. Что при этом должно быть верно — закон
+`docs/constitution/delivery.md`.
+
+Демон здесь чужой: на машине владельца в нём живут его хранилище разработки, его стенд и
+контейнеры других его работ. Любая команда пишется так, чтобы её отменяли, не спрашивая
+владельца, и чтобы она не задела ничего, кроме заведённого ею самой.
+
+## Когда брать
+
+- Команда демона не отвечает, и надо понять почему.
+- Нужен одноразовый контейнер рядом с уже работающими.
+- Собирается образ, который поедет на прод-сервер.
+- Раннер конвейера на этой машине не может войти в реестр.
+
+## Чужое не трогается
+
+Перед любым действием, которое задевает демон целиком, читается, что в нём живёт и переживёт
+ли оно перезапуск:
+
+```bash
+docker ps --format '{{.Names}} | {{.Image}} | {{.Status}}'
+docker inspect <контейнер> --format '{{.Name}} restart={{.HostConfig.RestartPolicy.Name}}'
+```
+
+`unless-stopped` поднимется сам, `no` — нет, и его возвращают руками сразу после подъёма
+демона. Стенд владельца обычно заведён с `no`: после перезапуска он остаётся лежать, а по его
+порту отвечает пустота — это выглядит поломкой стенда, а не следом перезапуска.
+
+Свои контейнеры именуются приставкой и снимаются по имени. `docker system prune`, `docker rm`
+по маске и `docker volume prune` не пишутся никогда: они уносят чужое молча.
+
+```bash
+docker rm -f <приставка>-ci-db >/dev/null 2>&1 || true   # снять прошлый прогон
+```
+
+Порт своего контейнера выбирается свободным: порт хранилища разработки занят, и попасть в него
+чужой миграцией нельзя.
+
+```bash
+lsof -nP -iTCP:<свободный порт> -sTCP:LISTEN     # пусто — порт свободен
+```
+
+## Место спрашивается до прогона
+
+Диск виртуальной машины отдельный от диска хоста: на хосте свободно, внутри пусто, и видно это
+только изнутри.
+
+```bash
+docker system df                       # образы, тома и кэш сборки с долей многоразового
+docker run --rm alpine:3 df -h /       # сколько осталось у самой виртуальной машины
+```
+
+Наружу нехватка выходит чужим лицом: контейнер поднимается и сразу гаснет, сверка схемы
+отвечает про ненакатываемую цепочку, гейт пуша краснеет целиком. По этим признакам чинят
+репозиторий, а причина в машине, — поэтому первое при любом из них `docker system df`.
+
+Освобождают отбором, а не общей чисткой: у сценария чистки образов сперва спрашивают, что он
+снял бы, и только потом дают снимать.
+
+## Демон поднимается своим CLI
+
+Открытие приложения виртуальную машину не поднимает: приложение считается запущенным, а демон
+не отвечает часами. Поднимает только собственная команда клиента, а готовность проверяется
+самим демоном:
+
+```bash
+docker desktop restart
+until docker info >/dev/null 2>&1; do sleep 5; done
+docker version --format 'демон: {{.Server.Version}}'
+```
+
+Состояние, которое печатает приложение, говорит про приложение: оно отвечает «работает» и
+тогда, когда демон не принимает ни одной команды. Единственный признак живого демона — ответ
+`docker info`. Первые полминуты после подъёма он отвечает ошибкой и пишет в лог, что маршрута
+до виртуальной машины нет: это нормальный старт, а не поломка.
+
+## «Команда висит» — сначала проверяется, вправду ли висит
+
+Вывод не заворачивается в `tail`, `head` и не глушится тихим режимом: они держат его в буфере
+до конца команды, и идущая работа выглядит зависшей. Читается прямой вывод:
+
+```bash
+docker pull alpine:3            # прогресс виден построчно
+```
+
+Скачивания не запускаются параллельно. Несколько одновременных забивают канал друг другу:
+образ, который тянется за три секунды, шёл полчаса — и это выглядело сломанным демоном, а было
+очередью, устроенной проверяющим.
+
+## Где рвётся: три яруса
+
+Ярусы проверяются по отдельности, иначе чинится не то. Каждый отвечает секундами:
+
+```bash
+# 1. Сеть машины: реестр отдаёт манифест
+curl -s -m 30 -w '%{http_code} за %{time_total}s\n' -o /dev/null '<адрес токена реестра>'
+
+# 2. Сеть контейнеров: объём проходит внутрь
+docker run --rm alpine:3 sh -c 'time wget -q -O /dev/null <адрес пробы канала>'
+
+# 3. Демон: тянет ли он сам
+docker pull busybox:latest
+```
+
+Хост тянет быстро, контейнер тянет быстро, а скачивание стоит — дело в демоне, и его
+перезапускают. Стоят все три — дело в сети машины, и демон ни при чём. Что делал сам демон,
+отвечают его логи: ходы к реестру, подъём и состояние, консоль виртуальной машины — три разных
+файла в каталоге данных клиента.
+
+## Команда из службы: свой каталог настроек и явный адрес демона
+
+Раннер конвейера запущен службой, и вход в реестр из неё отказывает: пароль сохраняет
+системный помощник хранения ключей, а сеанса пользователя у службы нет. Свой каталог настроек
+с пустым помощником от этого не спасает — клиент подставляет помощника сам и переписывает
+пустое значение молча. Поэтому вход не зовётся вовсе, а пароль пишется в файл настроек прямо:
+
+```bash
+export DOCKER_CONFIG="$(mktemp -d)"
+export DOCKER_HOST="unix://${HOME}/.docker/run/docker.sock"
+auth=$(printf '%s:%s' "${REGISTRY_USER}" "${REGISTRY_TOKEN}" | base64)
+printf '{"auths":{"<реестр>":{"auth":"%s"}}}' "${auth}" > "${DOCKER_CONFIG}/config.json"
+chmod 600 "${DOCKER_CONFIG}/config.json"
+```
+
+`DOCKER_HOST` здесь не для красоты: свой каталог уносит с собой и текущий контекст, а без него
+клиент идёт в общесистемный сокет, которого на машине с настольным клиентом нет вовсе, и
+отвечает «нет такого файла» на что угодно. Связь проверяется до сборки:
+
+```bash
+docker info --format 'демон: {{.ServerVersion}}'
+```
+
+Поле у `docker info` называется иначе, чем у `docker version`: имя из второй команды первая не
+понимает, и связь выглядит непроверенной, хотя демон отвечает.
+
+Что пароль принят, видно по ответу реестра: анонимному он отвечает `401`, авторизованному —
+содержимым или `403`, но не `401`. Каталог снимается в конце — раннер живёт между прогонами, и
+пароль реестра остался бы лежать на диске владельца.
+
+## Образ собирается под платформу прод-сервера
+
+Машина владельца и прод-сервер бывают разной архитектуры. Без явной платформы собирается образ
+под сборщика: он уходит в реестр, оттуда на сервер и не стартует там вовсе.
+
+```bash
+docker buildx build --platform <платформа сервера> -f <файл сборки> --output type=cacheonly .
+```
+
+`--output type=cacheonly` считает сборку, ничего не сохраняя, — этим замеряют время, не
+засоряя машину образом. Чужая платформа идёт эмуляцией, поэтому время сборки на машине и в
+облаке сравнивают числом, а не ожиданием.
+
+Сборщик с драйвером `docker-container` нужен для чужой платформы и заводится отдельно; его
+первый подъём тянет свой образ из реестра:
+
+```bash
+docker buildx create --name <приставка>-ci-builder --driver docker-container
+docker buildx inspect <приставка>-ci-builder --bootstrap    # покажет платформы и состояние
+docker buildx build --builder <приставка>-ci-builder …      # сборщик владельца не переключается
+```
+
+Сборщик не сносится после прогона: в его кэше живут слои и хранилище пакетов, а без них
+следующая сборка тянет все зависимости заново. Флаг `--use` тоже не пишется — он переключает
+сборщик владельца; вместо него `--builder` у самой сборки. Объявления сборщиков лежат в
+каталоге настроек, поэтому под своим каталогом их не видно вовсе — оставить их на месте
+помогает `BUILDX_CONFIG` с адресом каталога владельца.
+
+Установка зависимостей внутри сборки ограничивается по числу запросов, иначе она роняет сборку
+целиком — и не потому, что канал медленный, а потому, что сотни запросов забивают его сами
+себе.
+
+## Частые промахи
+
+- **Перезапуск демона объявлен сделанным по состоянию приложения.** Приложение говорит
+  «работает», а `docker info` в это же время отвечает ошибкой.
+- **Стенд не возвращён после перезапуска.** У него политика `no`, и владелец находит мёртвый
+  порт вместо стенда.
+- **Вывод команды заведён в `tail`** — и работающая команда объявлена зависшей.
+- **Несколько скачиваний разом** — и медленной объявлена машина, а не собственная очередь.
+- **Образ собран без указания платформы** — прод получает образ чужой архитектуры, и видно это
+  только на перезапуске контейнеров.
+- **Свой контейнер занял порт хранилища разработки** — конвейер пишет в данные владельца.
+- **Вход в реестр из службы сделан командой входа** — пароль уходит в помощник хранения ключей
+  даже из своего каталога настроек, и задание падает до сборки.
+- **Каталог настроек подменён, а адрес демона не задан** — и починка входа в реестр выглядит
+  как упавший демон.
+- **Сборщик снесён после прогона** — вместе с кэшем, и следующая сборка идёт как первая.
+- **Общая чистка ради места** — уносит чужие образы и тома, и восстановить их нечем.
+- **Место освобождено сценарием выкатки целиком.** Сценарий писан для прод-сервера: там
+  собирает конвейер, а сервер только тянет готовое, поэтому последним шагом сценарий сносит
+  кэш сборщика. На машине владельца собирает раннер, и тот же шаг оставляет сборщика без кэша.
+  Отбор самих образов у сценария годится и здесь — он идёт по имени своего реестра, оставляет
+  три последних sha и обходит поднятые контейнеры, — а вот его хвост на этой машине запускают,
+  только когда согласились ждать полную сборку.

package/assets/patterns/git-workflow-secrets.md

@@ -0,0 +1,93 @@
+---
+name: git-workflow-secrets
+kind: pattern
+rule: git-workflow
+description: Паттерн правила git-workflow. Брать при работе с ключами внешних служб — где они лежат, чем ключ, заводимый владельцем, отличается от ключа окружения, что означает каждое состояние строки интеграции и почему зелёная проба не обещает работающей возможности. Не брать для перезапуска прода и выбора образа — это паттерн git-workflow-restart.
+---
+
+# Ключи внешних служб
+
+Паттерн правила `git-workflow`. Что при этом должно быть верно — закон
+`docs/constitution/delivery.md`.
+
+## Когда брать
+
+- Возможность, которая ходит наружу, молчит: не уходят письма, не обновляются переводы.
+- Заводится или меняется ключ внешней службы.
+- Разбирается, что именно выкачено и чего приложению не хватает для работы, — включая ключ,
+  который живёт в окружении и экрана не имеет.
+
+## Ключ, заводимый владельцем, живёт в хранилище, а не в окружении
+
+Такой ключ лежит строкой в хранилище, зашифрованной ключом шифрования секретов; рядом открытая
+подсказка из последних знаков и исход последней пробы. Читает его одна служба и отдаёт тем, кто
+ходит наружу.
+
+**Запасного пути на окружение нет.** Одноимённая переменная в составе прода ничего не значит:
+приложение её не читает. Из окружения берётся один ключ — тот, которым шифруются все
+остальные. Его потеря делает записанные ключи нечитаемыми, и заводить их заново бесполезно,
+пока он не вернётся.
+
+Заводит такие ключи владелец сам, экраном интеграций. **Агент ключи не вводит:** ввод ключа
+доступа в поле ему запрещён независимо от того, кто просит.
+
+## Не всякий ключ внешней службы заводится владельцем
+
+В хранилище живут ключи, которые владелец заводит сам и по-разному у каждого владения. Ключ,
+одинаковый для всего приложения, остаётся в окружении, и экрана интеграций у него нет.
+
+Половины такой пары — ключ бэкенда и ключ, вшитый в сборку, — лежат по разные стороны
+поставки, и заполнить можно ровно одну. Тогда возможность не выключена и не включена: виджет
+не рисуется, сервер ждёт токен. Приложение называет такое состояние сломанным и говорит о нём
+строкой лога и сводкой старта — что в ней стоит, описывает правило `observability`.
+
+Отсюда порядок разбора для ключа из окружения: он читается не экраном интеграций, а сводкой
+старта в логах контейнера — в каком из её списков стоит имя возможности.
+
+## Строка интеграции говорит пятью состояниями
+
+Порядок разбора важен — состояние хранилища перекрывает всё остальное:
+
+| Что показано                         | Что это значит                                                         |
+| ------------------------------------ | ---------------------------------------------------------------------- |
+| состояние неизвестно                 | ответ ещё не пришёл; утверждать нечего                                 |
+| хранилище недоступно                 | ключа шифрования нет; заводить ключи нельзя, и владелец тут ни при чём |
+| не задан                             | строки секрета нет вовсе — ключ никогда не заводили                    |
+| расшифровать нечем                   | строка есть, а ключ шифрования сменился; заводить заново бесполезно    |
+| не проверен · работает · не работает | ключ записан; дальше судит проба                                       |
+
+Отсюда короткий путь разбора: молчит письмо или перевод — сначала открыть этот экран, а не
+логи. «Не задан» отвечает на вопрос целиком, и десять дней молчащей почты выяснились именно
+им, а не сервером.
+
+## Зелёная проба обещает меньше, чем кажется
+
+Проба спрашивает у службы то, что та отдаёт по ключу: список доменов, список моделей. Ни
+письма, ни запроса за деньги она не делает — но и работоспособности возможности не доказывает:
+
+- список моделей отдаётся и при пустом балансе, а сам запрос отвечает отказом по деньгам.
+  Строка при этом зелёная;
+- проба почты сверяет адрес отправителя со списком подтверждённых — но только если адрес уже
+  заполнен. При пустом адресе она отвечает «работает», а письма не уйдут.
+
+Поэтому после ввода ключа проверяется сама возможность, а не строка: сохранить запись и
+убедиться, что предупреждение не пришло; дождаться первого обращения и увидеть письмо.
+
+## Переезд ключа из окружения в хранилище не делается миграцией
+
+Секрет шифруется приложением, поэтому запросом к хранилищу его не перенести: миграция заводит
+таблицу и не трогает значения. Ключ, переведённый из окружения в настройки, обязан быть
+заведён владельцем в тот же день, что выкачена правка, — иначе возможность замолкает молча.
+Сверяется тем же экраном интеграций сразу после выкатки.
+
+## Частые промахи
+
+- **Искать ключ поиском по составу прода и делать вывод.** Значение там лежит, приложение его
+  не читает, а хвост из последних знаков совпадает с записанным в хранилище — совпадение
+  подсказки и переменной ничего не доказывает, кроме того, что владелец завёл тот же ключ.
+- **Идти в логи прежде экрана.** Логи скажут про отказ внешней службы, а экран — «не задан»;
+  второе точнее и стоит одного нажатия.
+- **Считать отсутствие ошибок признаком работы.** Ни почта, ни перевод не роняют запрос:
+  обращение сохранится, запись сохранится, а наружу ничего не уйдёт.
+- **Заводить ключ заново при «расшифровать нечем».** Это не про ключ, а про ключ шифрования;
+  новый ляжет рядом и тоже не прочитается.

package/assets/patterns/observability-record.md

@@ -0,0 +1,114 @@
+---
+name: observability-record
+kind: pattern
+rule: observability
+description: Паттерн правила observability. Брать, когда в коде заводится новая строка лога — готовый вызов логгера, выбор уровня, имя строки, поля объектом, отказ внешней службы и предел ожидания. Не брать для правки самого логгера и контекста запроса — это правило observability.
+---
+
+# Новая строка лога
+
+Паттерн правила `observability`. Что при этом должно быть верно — закон
+`docs/constitution/observability.md`.
+
+## Когда брать
+
+- В домене появилось место, о котором владелец должен узнать: не сработала автоматика,
+  отказала внешняя служба, упала процедура.
+- Хочется поставить `console.log` — вместо него ставится строка лога.
+
+## Логгер домена берётся один раз
+
+```ts
+const LOG_CONTEXT: string = 'PageCache';
+
+readonly #log: ScopedLogger;
+
+constructor(logger: AppLoggerService) {
+    this.#log = logger.scope(LOG_CONTEXT);
+}
+```
+
+Контекст задаётся один раз и константой модуля, а не литералом в вызове: соседние классы одного
+домена пишут под тем же источником, а отбор отказов судит именно по нему. Номер обращения,
+процедуру и того, кто в системе, логгер подставляет сам — передавать их полями не надо.
+
+## Имя строки постоянное, всё изменяемое — в поля
+
+```ts
+✓ this.#log.warn('cache.refresh.rejected', { url, attempt, status, durationMs });
+✗ this.#log.warn(`cache refresh rejected for ${url} after ${attempt} attempts`);
+```
+
+Первый аргумент — имя строки, а не предложение. По нему строки об одном и том же собираются
+вместе, и по нему же они схлопываются в одну строку ленты отказов. Подставленное в имя значение
+делает каждую строку уникальной.
+
+Имя пишется точками от общего к частному: `cache.refresh.rejected`, `mail.owner.skipped`.
+
+Поля вычищаются автоматически. Имя строки проходит вычистку только по пути в хранилище отказов
+— в выводе оно печатается как есть, — поэтому подставлять в него значения нельзя ещё и по этой
+причине.
+
+## Строке нижнего уровня нужна строка в списке отобранных
+
+Уровень отказа и всё, что выше, уезжает в хранилище отказов само. Строка уровнем ниже попадает
+туда, только если её имя стоит в списке отобранных имён. Список сравнивается по началу имени и
+правится тем же коммитом, что и место, которое эту строку пишет.
+
+Забыли дописать — строка останется только в выводе контейнера, и владелец о ней не узнает. Не
+сверяет это ничто.
+
+## Уровень выбирается по тому, сломалось ли что-то
+
+| Уровень     | Когда                                                                                                    |
+| ----------- | -------------------------------------------------------------------------------------------------------- |
+| отказ       | приложение не сделало того, что должно: упала процедура, не прошла запись в хранилище                    |
+| ниже        | не сработала автоматика: перевод, обновление кэша, опрос внешней службы. Сюда же отказ по вводу и правам |
+| сообщение   | состоявшееся действие, о котором стоит знать: вызов прошёл, письмо ушло                                  |
+| подробность | то, что нужно при разборе, а на проде не нужно                                                           |
+
+Отказ гостя пройти проверку, промах в форме и «не найдено» — это уровень ниже отказа. Проверка
+сработала, приложение работает.
+
+## Отказ внешней службы записывается разобранным
+
+```ts
+} catch (error: unknown) {
+    this.#log.error('mail.send.failed', { to: maskEmail(to), error: describeError(error) });
+}
+```
+
+Разбор причины кладёт класс, текст, код и срезанный стек одной формой — той же, что у остальных
+отказов. Подставлять ошибку в текст (`` `failed: ${String(error)}` ``) нельзя: так в лог уедет
+чужой текст целиком, вместе с адресом, ключом или почтой гостя.
+
+Почту маскируют на месте вызова, если она приходит отдельным значением: вычистка узнаёт её по
+имени поля, а имя вроде `to` на почту не похоже.
+
+## Отказ наступает только тогда, когда у обращения есть предел ожидания
+
+```ts
+/**
+ * Ожидание источника курсов. Курс справочный и обновляется раз в сутки: пять
+ * секунд ожидания и прежний курс на месте лучше, чем пять минут занятого
+ * расписания.
+ */
+const RATES_TIMEOUT_MS: number = 5_000;
+
+const response: Response = await fetch(RATES_URL, { signal: AbortSignal.timeout(RATES_TIMEOUT_MS) });
+```
+
+Без предела соединение с молчащей службой живёт до умолчания среды — минуты, — и всё это время
+`catch` не наступает: писать нечего. Число стоит рядом с клиентом со своим доводом, потому что
+цена ожидания у каждой службы своя: гость внутри запроса ждёт иначе, чем ночное расписание.
+
+## Частые промахи
+
+- **Одно и то же имя строки стоит в двух местах.** Тогда две разные ситуации читаются как одна.
+  Либо имена разные, либо место одно.
+- **`console.log` вместо строки лога.** У него нет ни уровня, ни номера обращения, и в отбор он
+  не попадает. На проде это строка, которую никто не увидит.
+- **Уровень выбран по тому, насколько неприятно.** Отказ гостя пройти проверку неприятен, но
+  приложение при этом работает.
+- **Ошибка положена в поле как есть, без разбора причины.** Объект ошибки сериализуется в
+  пустой `{}`, и в логе не останется ни текста, ни класса.

package/assets/patterns/seo-verify.md

@@ -32,7 +32,7 @@ PORT={{prodSitePort}} node dist/apps/site/server/server.mjs &
 ## Что смотреть в отданном HTML
 
 ```bash
-for locale in "" ru/ de/ zh-Hans/ zh-Hant/ ko/ th/ hi/; do
+for locale in "" <префиксы локалей>; do
     printf '%-10s ' "${locale:-en}"
     curl -s -H "Host: localhost" "http://localhost:{{prodSitePort}}/${locale}<адрес страницы>" \
         | grep -c -E '<title>|name="description"|property="og:|rel="canonical"|hreflang=|application/ld\+json'

package/assets/patterns/spec-driven-domain.md

@@ -48,8 +48,8 @@ docs/specs/<домен>/
 процедуры домен обслуживает.
 
 ```markdown
-**Зависимости:** `pricing` (сумма заявки), `availability` (занятость дат)
-**Законы:** `access`, `locales`, `money`, `ownership`
+**Зависимости:** `catalog` (состав заявки), `availability` (занятость дат)
+**Законы:** `access`, `locales`, `lists`
 **Процедуры:** `libs/api/<домен>`
 ```
 

package/assets/patterns/spec-driven-rule.md

@@ -125,3 +125,8 @@ description: Паттерн правила git-workflow. Брать … Не б
   проверка перестанет её находить.
 - В `description` не сказано, когда паттерн **не** брать, — соседний паттерн того же правила
   становится неотличимым.
+- Блок готового кода принят по виду, а не сверкой с объявлением. Вызов в примере повторяет имя,
+  число и порядок параметров живой функции: двухпараметрный вызов выглядел правдоподобно ровно
+  до того, как рядом открыли четырёхпараметрное объявление. Тем же проходом сверяется форма
+  кода — пример, объявляющий поля не так, как их объявляет дерево, учит нарушать правило о
+  языке, и запрещающее правило про это не узнает.

package/assets/patterns/styling-bem-sheet.md

@@ -0,0 +1,178 @@
+---
+name: styling-bem-sheet
+kind: pattern
+rule: styling-bem
+description: Паттерн правила styling-bem. Брать при заведении или правке шторки, окна и полноэкранного просмотра поверх страницы — чем открывается, что передаётся внутрь, как приезжает снизу, чем проверяется. Не брать для панели правки записи в админке — это паттерн entity-aside.
+---
+
+# Шторка и окно поверх страницы
+
+Паттерн правила `styling-bem`. Что при этом должно быть верно — закон
+`docs/constitution/frontend-application.md`.
+
+## Когда брать
+
+- На телефоне заводится шторка: выбор языка, валюты, дат.
+- Заводится окно или полноэкранный просмотр поверх страницы.
+- Шторку или окно что-то перекрывает, и хочется поднять им `z-index`.
+
+Панель правки записи в админке — это другое: там маршрут в своём аутлете, паттерн
+`entity-aside`.
+
+## Открывает служба, а не разметка рядом с кнопкой
+
+Компонент шторки — обычный элемент разметки. Он рисуется там, где написан, поэтому его
+`z-index` сравнивается только с соседями по этому месту. Липкая шапка размывает фон под собой —
+и всё, что написано внутри шапки, замкнуто в её слой.
+
+Открывает шторку служба окон кита — тем же вызовом открывается полноэкранный просмотр.
+Разметка уезжает к `<body>`, и сравнивать её становится не с чем.
+
+```typescript
+readonly #dialog: RtDialogService = inject(RtDialogService);
+
+readonly #sheetOpenedSource: Subject<RtDialogRef<string>> = new Subject<RtDialogRef<string>>();
+#sheetRef: RtDialogRef<string> | null = null;
+
+protected openLocalePicker(): void {
+    if (this.#sheetRef) {
+        return;
+    }
+
+    const data: ILocalePickerData = { locales: this.locales, value: this.currentLocale };
+    const ref: RtDialogRef<string> = this.#dialog.open<LocalePickerComponent, ILocalePickerData, string>(
+        LocalePickerComponent,
+        { data, panelClass: 'locale-picker-panel', backdropClass: 'locale-picker-backdrop' }
+    );
+    this.#sheetRef = ref;
+    this.#sheetOpenedSource.next(ref);
+}
+```
+
+Ответ шторки ждут подпиской из конструктора — подписываться в методе запрещает
+`angular-patterns`:
+
+```typescript
+this.#sheetOpenedSource
+    .pipe(
+        mergeMap((ref: RtDialogRef<string>): Observable<string | undefined> => ref.afterClosed()),
+        takeUntilDestroyed(this.#destroyRef)
+    )
+    .subscribe((code: string | undefined): void => {
+        this.#sheetRef = null;
+        if (code) {
+            this.onLocaleChange(code);
+        }
+    });
+```
+
+Ссылку обнуляют здесь, а не в обработчике кнопки: шторку закрывают ещё жестом вниз и нажатием
+мимо, и оба пути идут мимо кнопки.
+
+## Внутри шторки — только она сама
+
+Что показать, приходит токеном. Что выбрали, уходит вместе с закрытием. Своей кнопки у шторки
+нет: кнопку держит тот, кто шторку открывает.
+
+```typescript
+export interface ILocalePickerData {
+    readonly locales: readonly ISiteLocale[];
+    readonly value: string;
+}
+
+readonly #data: ILocalePickerData = inject<ILocalePickerData>(RT_DIALOG_DATA);
+readonly #dialogRef: RtDialogRef<string> = inject<RtDialogRef<string>>(RtDialogRef);
+
+protected confirm(): void {
+    this.#dialogRef.close(this.centeredLocale());
+}
+
+/** Закрыли, не подтвердив: значит, передумали — значение не меняем */
+protected onOpenChange(open: boolean): void {
+    this.open.set(open);
+    if (!open) {
+        this.#dialogRef.close();
+    }
+}
+```
+
+## Шторка приезжает снизу
+
+Служба поднимает её сразу открытой, и анимировать киту нечего: вместо движения гость видит
+подмену экрана. Поэтому открывают её на кадр позже:
+
+```typescript
+protected readonly open: WritableSignal<boolean> = signal<boolean>(false);
+
+constructor() {
+    afterNextRender((): void => {
+        this.open.set(true);
+    });
+}
+```
+
+`afterNextRender`, а не `ngAfterViewInit`: страницу отдаёт сервер, и разметка появляется позже.
+
+## Подложка
+
+Шторка сама затемняет фон и сама ловит нажатие мимо. Подложка окна поверх неё дала бы второе
+затемнение — фон стал бы вдвое темнее, чем у соседней шторки. Поэтому её делают прозрачной.
+Правило пишут в общий слой приложения: шторка уехала к `<body>`, и файл стилей компонента до
+неё не достаёт.
+
+```scss
+/* общий слой приложения; имя класса несёт приставку дерева */
+.locale-picker-backdrop {
+    background: transparent;
+}
+```
+
+Нажатие она ловит по-прежнему — закрытие по ней делает само окно.
+
+## Чем проверяется
+
+Скриншот тут не поможет: перекрытая шторка выглядит целой, а сборка и линт молчат. Спрашивают
+точку — кому достанется нажатие:
+
+```javascript
+const rect = button.getBoundingClientRect();
+document.elementFromPoint(rect.left + rect.width / 2, rect.top + rect.height / 2);
+```
+
+Ответом должна быть сама кнопка. Мерить надо на стенде из прод-сборки и на узком экране —
+паттерн `browser-verification-measure`.
+
+В сквозном тесте перед замером дожидаются, пока шторка доедет: видимая кнопка ещё может
+двигаться, и координаты через кадр будут другими.
+
+```typescript
+await page.locator('[qa-dataid="locale-picker-sheet"] [qa-dataid="bottom-sheet-panel"]').evaluate(
+    (panel: Element): Promise<void> =>
+        new Promise<void>((resolve: () => void): void => {
+            if (panel.getBoundingClientRect().bottom <= window.innerHeight) {
+                resolve();
+
+                return;
+            }
+            panel.addEventListener('transitionend', (): void => resolve(), { once: true });
+        })
+);
+```
+
+## Частые промахи
+
+- **Шторка написана рядом со своей кнопкой в шапке.** Шапка размывает фон, и шторка замкнута в
+  её слой. Так нижняя панель накрыла шторку вместе с кнопкой подтверждения, и значение на
+  телефоне стало не сменить.
+- **Шапке подняли номер слоя.** Дефект уходит, шторка остаётся замкнутой в чужой слой:
+  следующий сосед с номером повыше накроет её снова.
+- **Шторку перенесли в другое место разметки.** То же самое: заработает, пока над новым местом
+  никто не поставит `transform`, `filter` или свой `z-index`.
+- **Правило подложки положили в стили компонента.** Подложка уехала к `<body>`, и правило до
+  неё не достаёт — писать надо в общий слой приложения.
+- **Ссылку на открытую шторку обнулили в обработчике кнопки.** Закрытие жестом и нажатием мимо
+  идёт мимо него, и второй раз шторка уже не откроется.
+- **Тест померил сразу после проверки видимости.** Шторка ещё едет, `elementFromPoint`
+  возвращает `null`, и тест краснеет на исправном коде.
+- **Образец искали по именам библиотеки, поверх которой собран кит.** Она лежит внутри кита, её
+  имён в дереве нет — искать надо по именам кита.