@reformer/builder-plugin-api 1.0.0-beta.1

package/dist/services/workspace-save.d.ts

@@ -0,0 +1,18 @@
+import { Capability } from '../primitives/capability.js';
+import { ResourceId } from '../primitives/resource.js';
+export interface WorkspaceSaveService {
+    /**
+     * Сохраняет перечисленные ресурсы в источник проекта.
+     *
+     * `false` — проекта нет или хотя бы один ресурс не сохранился. Причины по одному ресурсу
+     * наружу не отдаются: показать их некому, кроме рабочей области, а она о них знает и так.
+     */
+    save(ids: readonly ResourceId[]): Promise<boolean>;
+}
+/**
+ * Возможность «сохранить в источник». Привилегированная: оболочка сверяет право
+ * `workspace.save` перед тем, как отдать её плагину.
+ */
+export declare const WorkspaceSaveCapability: Capability<WorkspaceSaveService>;
+/** Токен службы — ТОТ ЖЕ объект: возможность расширяет токен, второго реестра нет. */
+export declare const WorkspaceSaveServiceToken: Capability<WorkspaceSaveService>;

package/dist/tooling.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Вход для ИНСТРУМЕНТОВ автора плагина: сборщика, валидатора, упаковщика.
+ *
+ * Не для кода плагина — тому хватает `.`. Здесь то, что нужно тем, кто плагин проверяет
+ * и собирает ДО оболочки, и что обязано совпадать с оболочкой буквально:
+ *
+ * - **разбор манифеста** — тот же, которым оболочка решает, грузить ли плагин;
+ * - **список модулей рантайма** — те же спецификаторы, которые оболочка подставляет своими
+ *   объектами и которые сборка обязана держать внешними;
+ * - **нормализация пути модуля** — та же, которой линковщик ищет точку входа;
+ * - **раскладка каталога и разбор словаря** — те же потолок файлов, расширения кода и форма
+ *   `locales/*.json`, по которым загрузчик оболочки отказывает плагину;
+ * - **узнавание плагина в экспортах** точки входа — то же, что у загрузчика (`not-a-plugin`).
+ *
+ * В отличие от `./internal`, это контракт: он версионируется вместе с пакетом, потому что
+ * инструмент, собранный против одной версии, проверяет плагины для оболочек этой версии.
+ *
+ * @module @reformer/builder-plugin-api/tooling
+ */
+export { isPluginCodeFile, PLUGIN_CATALOG_DIR, PLUGIN_CODE_EXTENSIONS, PLUGIN_FILE_LIMIT, PLUGIN_SKIPPED_DIRS, } from './plugin/layout.js';
+export { parsePluginManifest, parsePluginManifestValue, parsePluginSourceManifest, } from './plugin/manifest-parser.js';
+export { parseMessagesBundle } from './plugin/messages-bundle.js';
+export { isPluginPermission, PLUGIN_PERMISSIONS, type PluginPermission, } from './plugin/permissions.js';
+export { pluginFromExports } from './plugin/plugin-exports.js';
+export { BUILDER_API_VERSION, PLUGIN_MANIFEST_FILE, type BuiltinDelivery, type BuiltinPluginManifest, type DeclaredKeybinding, type ManifestOf, type ManifestParseResult, type PluginContributes, type PluginManifest, type PluginManifestBase, type PluginProblem, type PluginProblemCode, type PluginRequirements, type PluginSource, type PluginSourceManifest, type PluginStyles, type ProjectPluginManifest, } from './plugin/manifest.js';
+export { PLUGIN_RUNTIME_MODULES } from './plugin/runtime-modules.js';
+export { isBundledPluginModule, packageNameOf, PLUGIN_BUNDLED_PACKAGES, } from './plugin/bundled-modules.js';
+export { normalizeModulePath } from './primitives/module-path.js';

package/dist/tooling.js

@@ -0,0 +1,35 @@
+import { B as t, P as I, a as P, b as l, h as u, j as _, c as N, i as E, n as L, f, p, d as S, e as U, g as c } from "./runtime-modules-CiUDFMIn.js";
+import { P as M, i as g } from "./permissions-BWlsUVPs.js";
+const a = Object.freeze([
+  "@reformer/builder-toolkit",
+  "@reformer/builder-stack-reformer",
+  "@reformer/builder-stack-plain"
+]);
+function r(e) {
+  const s = e.split("/");
+  return e.startsWith("@") ? s.slice(0, 2).join("/") : s[0];
+}
+function i(e) {
+  return a.includes(r(e));
+}
+export {
+  t as BUILDER_API_VERSION,
+  a as PLUGIN_BUNDLED_PACKAGES,
+  I as PLUGIN_CATALOG_DIR,
+  P as PLUGIN_CODE_EXTENSIONS,
+  l as PLUGIN_FILE_LIMIT,
+  u as PLUGIN_MANIFEST_FILE,
+  M as PLUGIN_PERMISSIONS,
+  _ as PLUGIN_RUNTIME_MODULES,
+  N as PLUGIN_SKIPPED_DIRS,
+  i as isBundledPluginModule,
+  E as isPluginCodeFile,
+  g as isPluginPermission,
+  L as normalizeModulePath,
+  r as packageNameOf,
+  f as parseMessagesBundle,
+  p as parsePluginManifest,
+  S as parsePluginManifestValue,
+  U as parsePluginSourceManifest,
+  c as pluginFromExports
+};

package/dist/ui/contributions/decorations.d.ts

@@ -0,0 +1,55 @@
+import { ComponentType } from 'react';
+import { Disposable } from '../../primitives/disposable.js';
+import { ResourceRef } from '../../primitives/resource.js';
+import { EditorProbe } from '../../workspace/model/provider.js';
+/**
+ * Тон пометки. Предметного смысла у Host нет: он переносит значение от вклада к отрисовке.
+ *
+ * Порядок значений несущий: при слиянии пометок нескольких вкладов побеждает более тревожный тон.
+ */
+export type DecorationTone = 'default' | 'accent' | 'warning' | 'danger';
+/** Пометка на ресурсе: короткий значок и подсказка, а не текст произвольной длины. */
+export interface Decoration {
+    /** Короткая пометка: «S», «3», «●». Строка, а не число: это и счётчик, и буква вида. */
+    readonly badge?: string;
+    readonly icon?: ComponentType;
+    /** Ключ i18n подсказки — в пространстве имён внёсшего плагина, как у заголовка панели. */
+    readonly tooltipKey?: string;
+    /**
+     * Параметры подсказки: подставляются в момент показа, вместе с ключом.
+     *
+     * Без них пометка «3» умеет сказать только «есть проблемы», а «три ошибки» — уже нет:
+     * счётчик пришлось бы вклеивать в строку самим, то есть переводить у себя. Ключ и его
+     * параметры путешествуют парой и при слиянии не разлучаются.
+     */
+    readonly tooltipParams?: Record<string, unknown>;
+    readonly tone?: DecorationTone;
+}
+export interface ResourceDecorationContribution {
+    /** Уникален среди декораций; попадает в диагностику и служит React-ключом. */
+    readonly id: string;
+    /**
+     * Пометка для ресурса или `null`, если этому вкладу сказать нечего.
+     *
+     * Синхронна и обязана быть дешёвой: её зовут для каждой строки видимого уровня дерева
+     * на каждую перерисовку. Содержимое через пробу читается лениво — см. шапку модуля.
+     */
+    decorate(ref: ResourceRef, probe: EditorProbe): Decoration | null;
+    /**
+     * «Мой ответ изменился» — повод спросить {@link decorate} заново.
+     *
+     * Необязателен, и большинству вкладов не нужен: пометка «это схема формы» зависит только
+     * от `ref`, а `ref` меняется вместе со строкой дерева. Нужен тем, чей ответ зависит от
+     * состояния СНАРУЖИ дерева — диагностике прежде всего: находки приходят от валидатора,
+     * дерево про них ничего не знает и перерисовываться ему не с чего.
+     *
+     * Пока этого крючка не было, единственным способом обновить пометку было снять вклад
+     * и внести заново (так и записано в шапке модуля — «объявить результат вторым проходом»).
+     * Для содержимого файла это годится: оно меняется редко. Для диагностики — нет: она
+     * меняется на каждой правке, и перерегистрация вклада означала бы две рассылки реестра
+     * на каждый набранный символ, а заодно потерю порядка вкладов.
+     */
+    onDidChange?(cb: () => void): Disposable;
+}
+/** Точка расширения декораций. Заполняется только плагинами. */
+export declare const ResourceDecorationPoint: import('../../internal.js').ExtensionPoint<ResourceDecorationContribution>;

package/dist/ui/contributions/editors.d.ts

@@ -0,0 +1,58 @@
+import { ComponentType } from 'react';
+import { CommandContribution } from '../../primitives/command.js';
+import { ResourceId, ResourceRef } from '../../primitives/resource.js';
+import { EditorProbe } from '../../workspace/model/provider.js';
+import { PanelContribution } from '../slots.js';
+/**
+ * Редактор — вклад, отвечающий на два вопроса: берётся ли он за ресурс и чем его рисовать.
+ *
+ * Панели и команды перечислены ЗДЕСЬ, а не вносятся отдельно, потому что у них другой срок
+ * жизни: инспектор без своего редактора бессмыслен. Вносит их тот, кто редактор подключает;
+ * видимостью по-прежнему управляет `when` (см. `../slots`), а не перерегистрация.
+ */
+export interface EditorContribution {
+    /** Уникален среди редакторов; служит ключом состояния вида и адресом в диагностике. */
+    readonly id: string;
+    /**
+     * Приоритет или отказ. Больше — предпочтительнее; `false` — «это не ко мне».
+     *
+     * Обязана быть синхронной, чистой и быстрой: её зовут для каждого кандидата на каждое
+     * открытие. Содержимое берётся из пробы, а не читается самостоятельно.
+     */
+    canOpen(ref: ResourceRef, probe: EditorProbe): number | false;
+    /**
+     * Ключ заголовка для выбора «открыть с помощью» — необязателен.
+     *
+     * Разрешается в пространстве имён ВНЁСШЕГО плагина, как у панели (см. `panelTitle`
+     * в `./panels`): словарь всегда чей-то, и `editor.label` двух разных плагинов — две
+     * разные строки. Редактор, который себя не назвал, показывается своим `id`: это честно
+     * (имя вклада — то, что про него известно) и не требует правки чужого плагина ради
+     * появления пункта в меню.
+     */
+    readonly titleKey?: string;
+    readonly Body: ComponentType<{
+        documentId: ResourceId;
+    }>;
+    readonly contributes?: {
+        readonly panels?: readonly PanelContribution[];
+        readonly commands?: readonly CommandContribution[];
+    };
+    /**
+     * Состояние вида: прокрутка, свёрнутые ветки, позиция каретки — и ничего больше.
+     *
+     * Обе операции адресуются документом, а не редактором: один редактор обслуживает много
+     * вкладок, и «восстанови прокрутку» без адреса означало бы одну прокрутку на всех.
+     */
+    readonly viewState?: {
+        capture(id: ResourceId): unknown;
+        restore(id: ResourceId, state: unknown): void;
+    };
+}
+/**
+ * Точка расширения редакторов.
+ *
+ * Заполняется только через `PluginContext.extensions`: у корневого реестра метода `contribute`
+ * нет вовсе, поэтому «редактор, внесённый самим Host» невыразим. Пока вкладов нет, центр
+ * оболочки показывает пустое состояние — это нормальное состояние Э5, а не незавершённость.
+ */
+export declare const EditorPoint: import('../../internal.js').ExtensionPoint<EditorContribution>;

package/dist/ui/contributions/plugin-settings.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Точка расширения «настройки плагина каталога».
+ *
+ * Плагин объявляет, что у него есть настраиваемое, и отдаёт ОПИСАНИЕ формы. Рисует эту форму
+ * раздел «Плагины» окна настроек, значения кладутся в службу настроек под ключом плагина
+ * (`platform/services/plugin-settings`).
+ *
+ * ## Почему полезная нагрузка непрозрачна для платформы
+ *
+ * `schema` объявлена как `unknown`, хотя на деле это `JsonFormSchema`. Сузить тип здесь значило
+ * бы, что ПЛАТФОРМА узнала про формы, — а она не знает предметных сущностей вовсе (правило
+ * слоёв, `eslint.config.js`). Сужение делает тот, кому предметное знание разрешено:
+ * композиция, когда собирает тело раздела. Платформа же переносит вклад, не заглядывая внутрь,
+ * ровно как переносит `Body` раздела настроек.
+ *
+ * ## Точка КАТАЛОЖНАЯ, и это сказано в имени
+ *
+ * Форма рисуется только в строке плагина каталога — у встроенных плагинов строки нет, и вклад
+ * от встроенного никто не покажет. Имя точки и этот абзац существуют, чтобы автор встроенного
+ * плагина узнал об этом отсюда, а не из пустого места в интерфейсе. Понадобятся настройки
+ * встроенному — это отдельное решение: у него есть свой раздел или своё место в чужом.
+ *
+ * @module @reformer/builder-plugin-api/ui/contributions/plugin-settings
+ */
+/**
+ * Что плагин рассказывает о своих настройках.
+ *
+ * Умолчаний здесь НЕТ намеренно: их объявляет сам плагин через `settings.registerDefault`
+ * в `activate` — тем же вызовом, каким это делает плагин китов. Второе поле с умолчаниями
+ * во вкладе дало бы два источника одной сущности и правило приоритета между ними.
+ */
+export interface CatalogPluginSettingsContribution {
+    /**
+     * Чьи это настройки. Обязателен: точка глобальная, а строка в списке — конкретного плагина.
+     *
+     * Проверяется на совпадение с `pluginId` вклада (его проставляет реестр, а не вносящий):
+     * плагин не настраивает соседа.
+     */
+    readonly pluginId: string;
+    /**
+     * Описание формы — `JsonFormSchema` пакета `@reformer/renderer-json`.
+     *
+     * Тип намеренно широкий: см. шапку модуля. Разбирает и проверяет схему композиция,
+     * непригодная показывается человеку как отказ, а не роняет раздел.
+     */
+    readonly schema: unknown;
+    /**
+     * Заголовок формы в карточке. Ключ СЛОВАРЯ ПЛАГИНА либо готовая строка — плагин решает сам,
+     * потому что его словарь знает только он.
+     */
+    readonly titleKey?: string;
+}
+/** Точка расширения. Вносят плагины каталога, читает раздел «Плагины» окна настроек. */
+export declare const CatalogPluginSettingsPoint: import('../../internal.js').ExtensionPoint<CatalogPluginSettingsContribution>;

package/dist/ui/keyboard/keybinding-rules.d.ts

@@ -0,0 +1,48 @@
+import { WhenExpr } from '../../primitives/when-expr.js';
+/**
+ * Откуда правило пришло. Порядок в {@link LAYER_RANK} и есть порядок старшинства.
+ *
+ * Плагин каталога стоит выше встроенного намеренно: встроенный набор — это то, что мы
+ * решили за человека, а плагин, положенный в проект, — то, что он решил сам.
+ */
+export type KeybindingLayer = 'host' | 'builtin-plugin' | 'catalog-plugin' | 'user';
+/** Привязка сочетания к команде. */
+export interface KeybindingRule {
+    /** Устойчивый адрес правила: его показывает редактор клавиш и называет диагностика. */
+    readonly id: string;
+    /**
+     * Ступени аккорда в каноническом написании. Одна ступень — обычное сочетание.
+     *
+     * Массив, а не строка, с самого начала: аккорд появляется позже, но переписывать под него
+     * указатель, редактор и диагностику дороже, чем сразу назвать вещь тем, что она есть.
+     */
+    readonly chord: readonly string[];
+    readonly commandId: string;
+    /** Аргументы вызова. Есть у правил из манифеста и раскладки, у команд их не бывает. */
+    readonly args?: unknown;
+    readonly when: WhenExpr;
+    readonly layer: KeybindingLayer;
+    /** Кто принёс правило: идентификатор плагина либо `undefined` у оболочки и человека. */
+    readonly pluginId?: string;
+    readonly allowInEditable: boolean;
+    /** Порядковый номер появления. Последний критерий сортировки. */
+    readonly seq: number;
+}
+/** Указатель по первой ступени сочетания. */
+export interface KeybindingIndex {
+    /** Правила, у которых первая ступень равна `binding`. Уже отсортированы. */
+    rulesFor(binding: string): readonly KeybindingRule[];
+    /** Является ли сочетание НАЧАЛОМ аккорда — признак входа в режим ожидания. */
+    isChordPrefix(binding: string): boolean;
+    /** Продолжения после уже нажатых ступеней. */
+    rulesAfter(prefix: readonly string[], binding: string): readonly KeybindingRule[];
+    /** Все действующие правила — редактору клавиш и справке. */
+    all(): readonly KeybindingRule[];
+}
+/** Пара правил на одном сочетании, которую разрешить нечем. */
+export interface KeybindingConflict {
+    readonly chord: readonly string[];
+    /** Не меньше двух, в порядке указателя: первый и есть победитель. */
+    readonly rules: readonly KeybindingRule[];
+    readonly winner: string;
+}

package/dist/ui/keyboard/keybindings.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Сочетания клавиш как текст: модификатор платформы и подпись для человека.
+ *
+ * Здесь то, что плагин показывает: подпись сочетания обязана совпадать с тем, что человек
+ * нажимает, поэтому форматирует её тот же код, что разбирает. Диспетчер нажатий и его
+ * установка в документ живут в оболочке билдера.
+ *
+ * @module @reformer/builder-plugin-api/ui/keyboard/keybindings
+ */
+/**
+ * Модификатор, в который разворачивается `mod` на этой платформе.
+ *
+ * `meta` — Cmd на macOS, `ctrl` на остальных. Значение вычисляется один раз при установке
+ * обработчика: платформа в течение сессии не меняется, а вычислять её на каждое нажатие
+ * означало бы читать `navigator` десятки раз в секунду при обычном наборе текста.
+ */
+export type PlatformModifier = 'ctrl' | 'meta';
+/**
+ * Определяет платформенный модификатор.
+ *
+ * Строка принимается параметром, а не читается изнутри безусловно: обе ветки — часть
+ * контракта, и проверять их надо обе, а `node` про macOS ничего не знает.
+ */
+export declare function detectPlatformModifier(platform?: string): PlatformModifier;
+/**
+ * Разворачивает `mod` в платформенный модификатор, сохраняя канонический порядок.
+ *
+ * Работает по каноническому виду, поэтому обходится без повторного разбора: `mod` в порядке
+ * модификаторов стоит первым (см. `MODIFIER_ORDER` в `primitives/command`), а за ним идут
+ * `ctrl`, `meta`, `alt`, `shift`. Вставка сводится к проверке начала строки.
+ *
+ * Совпадение с уже указанным модификатором не является ошибкой: `mod+ctrl+k` на Windows —
+ * это `ctrl+k`, потому что `mod` там и есть `ctrl`. Повторно нормализовать результат нельзя —
+ * `normalizeKeybinding` отвергает повторённый модификатор.
+ *
+ * @throws {CommandError} `invalid-keybinding`, если исходное сочетание не разбирается.
+ */
+export declare function resolvePlatformKeybinding(keybinding: string, modifier: PlatformModifier): string;
+/**
+ * Подпись сочетания для интерфейса: `mod+shift+p` → `Ctrl+Shift+P`.
+ *
+ * Не переводится и через словарь не идёт: `Ctrl` и `Shift` — это надписи на клавишах,
+ * а не текст интерфейса, и переводить их значило бы называть клавишу не тем, что на ней
+ * написано. Локализуется тут разве что порядок, а он у сочетаний один.
+ *
+ * Неразбираемое сочетание возвращается как есть: подпись — не то место, где стоит падать.
+ */
+export declare function formatKeybinding(keybinding: string, modifier: PlatformModifier): string;
+/**
+ * Подпись аккорда: `['mod+k', 'mod+s']` → `Ctrl+K Ctrl+S`.
+ *
+ * Ступени разделены, а не слиты: это два НАЖАТИЯ, и подпись `Ctrl+K+Ctrl+S` описывала бы
+ * несуществующее сочетание из четырёх одновременно зажатых клавиш.
+ */
+export declare function formatChord(chord: readonly string[], modifier: PlatformModifier): string;

package/dist/ui/keyboard/keymap.d.ts

@@ -0,0 +1,81 @@
+import { Disposable } from '../../primitives/disposable.js';
+import { KeybindingIndex, KeybindingLayer, KeybindingRule, KeybindingConflict } from './keybinding-rules.js';
+/**
+ * Запись раскладки, как её пишет человек.
+ *
+ * Строками, а не разобранными структурами: это содержимое файла настроек, и до разбора
+ * у него нет ничего, кроме текста.
+ */
+export interface UserKeybinding {
+    /** Сочетание как написал человек; нормализуется при сборке. */
+    readonly key: string;
+    /**
+     * Идентификатор команды. Ведущий минус означает СНЯТИЕ: `-files.delete` убирает привязку
+     * этой команды к этой клавише, одинокий `-` освобождает клавишу целиком.
+     *
+     * Форма взята у VS Code, и она правильная: снятие адресуется парой «клавиша + команда»,
+     * потому что снятие по одной клавише убило бы и те привязки, которых человек не видел.
+     */
+    readonly command: string;
+    readonly when?: string;
+    readonly args?: unknown;
+    readonly allowInEditable?: boolean;
+}
+/** Почему запись раскладки не применилась. */
+export type KeymapIssueKind = 'invalid-key' | 'invalid-when' | 'not-an-object';
+export interface KeymapIssue {
+    readonly kind: KeymapIssueKind;
+    /** Номер записи в списке — по нему человек находит строку в своём файле. */
+    readonly at: number;
+    readonly message: string;
+}
+export interface KeymapService {
+    /** Действующий указатель. Пересобирается лениво — см. шапку модуля. */
+    index(): KeybindingIndex;
+    /** Записи раскладки человека — как они лежат в настройках. */
+    userRules(): readonly UserKeybinding[];
+    /**
+     * Записывает раскладку человека целиком.
+     *
+     * Целиком, а не по одной записи: редактор клавиш правит список, и частичная запись
+     * потребовала бы от него знать, какая строка какой записи соответствует, — то есть
+     * держать вторую модель того же списка.
+     */
+    setUserRules(rules: readonly UserKeybinding[]): Promise<void>;
+    /** Записи, которые не применились. Считается вместе с указателем. */
+    issues(): readonly KeymapIssue[];
+    /** Уведомление о смене раскладки: подписаны меню, справка и редактор клавиш. */
+    onDidChange(cb: () => void): Disposable;
+    /**
+     * Правила внешнего источника. Замещает набор ЭТОГО источника целиком.
+     *
+     * Форма и довод те же, что у публикации диагностик: источник приносит «всё, что у меня
+     * есть сейчас», и его прошлое исчезает без отдельного вызова. Иначе снятие пришлось бы
+     * делать вторым вызовом, и первый же забытый оставил бы клавишу от плагина, которого нет.
+     */
+    registerRules(source: string, layer: KeybindingLayer, rules: readonly ExternalKeybinding[]): Disposable;
+    /** Неразрешимые пары. Считается лениво, вместе с указателем. */
+    conflicts(): readonly KeybindingConflict[];
+}
+/**
+ * Правило от внешнего источника — манифеста плагина или раскладки человека.
+ *
+ * Сочетание и условие здесь СТРОКАМИ: источник — это файл, и до разбора у него нет ничего,
+ * кроме текста. Разбор делает служба, а испорченную запись отбрасывает поштучно.
+ */
+export interface ExternalKeybinding {
+    readonly chord: readonly string[];
+    readonly commandId: string;
+    readonly when: KeybindingRule['when'];
+    readonly args?: unknown;
+    readonly allowInEditable?: boolean;
+    readonly pluginId?: string;
+}
+export declare const KeymapServiceToken: import('../../index.js').ServiceToken<KeymapService>;
+/**
+ * Каким сочетанием вызывается команда сейчас. `undefined` — ни одним.
+ *
+ * Берётся ПЕРВОЕ правило по порядку указателя, то есть то же, которое выиграет у диспетчера.
+ * Иначе подсказка называла бы одно сочетание, а срабатывало бы другое.
+ */
+export declare function chordOfCommand(index: KeybindingIndex, commandId: string): readonly string[] | undefined;

package/dist/ui/keyboard/scope.d.ts

@@ -0,0 +1,38 @@
+import { Disposable } from '../../primitives/disposable.js';
+/**
+ * Имя области: `palette`, `dialog`. Непрозрачная строка, как `activeResourceKind`.
+ *
+ * Платформа её не интерпретирует и списка не держит: окна заводят плагины, и перечислить
+ * их Host не может — ровно как пути подменю.
+ */
+export type ScopeId = string;
+export interface ScopeStack {
+    /** Верх стека или `null`, если окон нет. Это значение ключа `scope`. */
+    top(): ScopeId | null;
+    /**
+     * Весь стек снизу вверх. Значение ключа `scopes` — правая часть оператора `in`,
+     * которым пишут «где-то внутри диалога, пусть и не в самом верхнем».
+     *
+     * Ссылка стабильна между изменениями: её читает снимок контекстных ключей.
+     */
+    all(): readonly ScopeId[];
+    /**
+     * Кладёт область. `dispose()` снимает ИМЕННО эту запись, где бы она ни оказалась в стеке.
+     *
+     * Снятие по идентичности записи, а не «снять верхнюю»: два вложенных диалога, оба
+     * объявившие `dialog`, дают `['dialog', 'dialog']`, и закрытие внутреннего не должно
+     * снимать внешний. Тот же приём, что у реестра команд, где `dispose` сверяет значение,
+     * а не только ключ.
+     */
+    push(scope: ScopeId): Disposable;
+    subscribe(listener: () => void): Disposable;
+}
+export declare const ScopeStackServiceToken: import('../../index.js').ServiceToken<ScopeStack>;
+/**
+ * Область модального окна — общая для всех диалогов оболочки.
+ *
+ * Одна на всех, а не своя у каждого: условие «пока открыт какой-нибудь диалог» пишется
+ * человеком чаще, чем «пока открыт именно этот», а вложенные окна различает уже стек.
+ * Диалогу, которому нужна своя клавиша, ничто не мешает положить рядом собственную область.
+ */
+export declare const DIALOG_SCOPE = "dialog";

package/dist/ui/menu/editor-menu.d.ts

@@ -0,0 +1,25 @@
+import { ResourceId, ResourceRef } from '../../primitives/resource.js';
+import { WhenContext } from '../../primitives/when-context.js';
+import { ContextMenuId, MenuTarget } from './menu.js';
+/** Адрес ряда действий над активным документом. */
+export declare const EDITOR_TITLE_MENU: ContextMenuId;
+/** Документ, к которому относятся кнопки ряда. */
+export interface EditorMenuTarget {
+    /** Адрес активного документа. */
+    readonly documentId: ResourceId;
+    /** Ссылка на ресурс: по ней вклад решает, его ли это документ. */
+    readonly ref: ResourceRef;
+    /** Идентификатор редактора, который сейчас рисует документ; `null` — ещё не выбран. */
+    readonly editorId: string | null;
+}
+/**
+ * Сужает непрозрачную цель до цели ряда действий; `null` — кнопку рисуют не там.
+ *
+ * Проверка структурная, а не `instanceof`: цель проходит через модель меню как `unknown`,
+ * и вклад обязан уметь получить `null`, если его пункт по ошибке внесли в чужое меню.
+ */
+export declare function asEditorTarget(target: MenuTarget): EditorMenuTarget | null;
+/** Предикат видимости кнопки по открытому документу. */
+export declare function whenEditor(predicate: (target: EditorMenuTarget, ctx: WhenContext) => boolean): (ctx: WhenContext, target: MenuTarget) => boolean;
+/** Аргументы команды по открытому документу; для чужой цели их нет вовсе. */
+export declare function argsOfEditor<T>(compute: (target: EditorMenuTarget) => T): (target: MenuTarget) => T | undefined;