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

package/dist/services/diagnostics/service.d.ts

@@ -0,0 +1,34 @@
+import { Disposable } from '../../primitives/disposable.js';
+import { ResourceId } from '../../primitives/resource.js';
+import { Diagnostic } from './types.js';
+export interface DiagnosticsService {
+    /**
+     * Замещает результаты источника по ресурсу.
+     *
+     * Пустой список снимает всё, что этот источник публиковал раньше. Записи других
+     * источников не затрагиваются: они сосуществуют и складываются в общий свод.
+     */
+    publish(resource: ResourceId, source: string, items: readonly Diagnostic[]): void;
+    /**
+     * Все диагностики ресурса: сначала по источнику (в алфавитном порядке), внутри источника —
+     * в порядке публикации. Между изменениями — та же ссылка.
+     */
+    get(resource: ResourceId): readonly Diagnostic[];
+    /**
+     * Ресурсы, у которых сейчас есть находки, — в алфавитном порядке идентификатора.
+     *
+     * Без перечисления свод читается только по одному адресу, а панель проблем спрашивает
+     * ровно обратное: «что вообще найдено». Собрать этот ответ снаружи нечем — обход открытых
+     * вкладок дал бы другой список, потому что публикуют не только по открытым документам,
+     * а перечисление источников не заменяет перечисления адресов.
+     *
+     * Порядок алфавитный по той же причине, по которой алфавитен порядок источников в {@link
+     * DiagnosticsService.get}: «кто успел раньше» перескакивало бы при каждом перезапуске
+     * валидаторов, и глаз терял бы строку, на которую смотрел. Между изменениями СОСТАВА —
+     * та же ссылка: список читает `useSyncExternalStore`.
+     */
+    resources(): readonly ResourceId[];
+    /** Свод ресурса изменился. Полезная нагрузка — какого именно. */
+    onDidChange(cb: (resource: ResourceId) => void): Disposable;
+}
+export declare const DiagnosticsServiceToken: import('../../index.js').ServiceToken<DiagnosticsService>;

package/dist/services/diagnostics/types.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Форма диагностики: во что валидатор облекает найденную проблему.
+ *
+ * Два свойства, из которых следует всё остальное:
+ *
+ * **У диагностики ровно одна цель.** Не «и диапазон, и узел». Синтаксическая ошибка адресуется
+ * диапазоном, потому что узла ещё нет — текст не разобрался. Структурная адресуется
+ * идентификатором узла, потому что он не съезжает при вставке соседей, а путь съезжает.
+ * Двойная адресация означала бы, что валидатор обязан посчитать оба адреса, и один из них
+ * (диапазон структурной ошибки) он вычислял бы симуляцией печати — то есть врал бы.
+ * Перевод «узел → диапазон» делает тот, кто рисует, по тексту, который сейчас в редакторе.
+ *
+ * Узловая цель при этом умеет СУЖАТЬСЯ до свойства внутри узла ({@link DiagnosticTarget.within}),
+ * и это не вторая адресация: адрес по-прежнему один — узел, — а путь отсчитывается ОТ НЕГО
+ * и потому съезжает не больше, чем сам идентификатор. Запрет на путь в находке — про путь
+ * УЗЛА от корня документа: тот двигается вставкой соседа где угодно выше и потому спрашивается
+ * у модели в момент показа. Путь ВНУТРИ узла двигается только вместе со своим узлом, а из
+ * текста его не восстановить: про то, что виноват именно `readOnly`, знает валидатор и никто
+ * больше. Без сужения «у компонента нет свойства readOnly» подчёркивало бы `$nodeId` —
+ * единственное место узла, которое к ошибке не относится.
+ *
+ * Правило для потребителя: **уточнение можно игнорировать**. Кто читает только `kind`
+ * и `nodeId`, остаётся прав — поэтому поле и необязательное, а не отдельный вид цели:
+ * новый вид молча выпал бы из проверок `kind === 'node'` в панели проблем и на канвасе.
+ *
+ * **Сообщение — это код и параметры, а не готовая строка.** По коду ассистент чинится сам,
+ * по переведённой фразе не может. И одна ошибка выглядит одинаково в интерфейсе, в логе
+ * и в тесте, потому что переводится в момент показа, а не в момент возникновения.
+ *
+ * @module @reformer/builder-plugin-api/services/diagnostics/types
+ */
+/**
+ * Полуинтервал `[start, end)` в тексте ресурса, **в кодовых единицах UTF-16**.
+ *
+ * Единицы названы намеренно и совпадают с `TextEdit.offset` из журнала изменений: JavaScript
+ * и Monaco считают именно так, и потребитель, решивший, что это байты или кодовые точки,
+ * сломается на первом эмодзи. Смещения, а не «строка/колонка», потому что смещение — это то,
+ * что отдаёт разбор с позициями, и то, что Monaco переводит в позицию одним вызовом;
+ * обратный перевод потребовал бы считать начала строк и разъезжался бы на разных переводах
+ * строки.
+ */
+export interface TextRange {
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * Что подчеркнуть у свойства, на которое показывает `within` узловой цели.
+ *
+ * `name` — токен имени вместе с кавычками, он всегда короткий. `value` — само значение,
+ * и только там, где виновато ОНО: `$component(Inpit)`, «must be boolean». Значение-поддерево
+ * при этом не подчёркивается — см. заметку о выборе места в `editor-monaco/diagnostics`.
+ */
+export type NodePart = 'name' | 'value';
+/** Куда показывает диагностика. Ровно один вариант — см. заголовок модуля. */
+export type DiagnosticTarget = {
+    readonly kind: 'node';
+    readonly nodeId: string;
+    /**
+     * Уточнение места ВНУТРИ узла: путь от самого узла до свойства-виновника
+     * (`['componentProps', 'readOnly']`). Отсутствует или пуст — находка о узле целиком.
+     *
+     * Это по-прежнему ОДНА цель, а не вторая: адресом остаётся узел, путь лишь сужает место
+     * внутри него. И он не съезжает ровно по той причине, по которой не съезжает
+     * идентификатор: он отсчитывается ОТ УЗЛА, поэтому вставка соседей где угодно в документе
+     * его не двигает. Абсолютный путь в находку класть по-прежнему нельзя — он устаревает
+     * вместе с показом.
+     *
+     * Перевод «путь → диапазон» остаётся за тем, кто РИСУЕТ: свойство ищется в тексте,
+     * который сейчас в редакторе. Не нашлось — подчёркивается узел, как и раньше.
+     */
+    readonly within?: readonly (string | number)[];
+    /** Что подчеркнуть у найденного свойства. По умолчанию — имя: оно всегда коротко. */
+    readonly at?: NodePart;
+} | {
+    readonly kind: 'range';
+    readonly range: TextRange;
+}
+/** Проблема всего ресурса: файл не читается, схема не того вида. */
+ | {
+    readonly kind: 'resource';
+}
+/**
+ * Проблема ресурса, которой НЕТ в его тексте: она в приложенном файле, который этот ресурс
+ * тянет за собой, — для формы это сайдкар правил.
+ *
+ * Ресурс остаётся адресом, потому что через него проблема и чинится: команда правки правил
+ * получает адрес СХЕМЫ, а файл правил находит по нему сама. Но подчеркнуть в схеме нечего —
+ * правило указывает на поле, которого в ней нет, в том и находка. `resource` тут не годится:
+ * он означает «ошибка уровня документа», и рисующий ставит на неё маркер первой строки —
+ * то есть на `{` файла, к которому находка не относится.
+ *
+ * Отдельный вид, а не флаг у `resource`, потому что все, кто различает цели, должны решить
+ * заново: рисующий — не ставить маркер, канвас — посчитать в неразмещённые (как и `resource`),
+ * панель проблем — показать строку без бейджа узла. Проверка `kind !== 'node'` даёт всё это
+ * сама, а `switch` у рисующего заставит компилятор напомнить.
+ */
+ | {
+    readonly kind: 'attached';
+};
+/**
+ * Готовое исправление: ассистент получает не только «что не так», но и «чем чинить»,
+ * и чинит той же командой, что и человек.
+ */
+export interface QuickFix {
+    /** Ключ i18n подписи. */
+    readonly titleKey: string;
+    readonly commandId: string;
+    readonly args?: unknown;
+}
+export type DiagnosticSeverity = 'error' | 'warning' | 'info';
+/**
+ * Порядок строгости: чем больше, тем строже.
+ *
+ * Живёт рядом со словарём, а не у каждого потребителя. Сравнивать строгости нужно всем,
+ * кто показывает диагностику — дереву (какой тон у значка), канвасу (метка на узле),
+ * панели проблем (что показать первым), — а плагины не видят друг друга и завели бы по
+ * копии. Копии совпадали бы «по договорённости», то есть до первой правки словаря.
+ */
+export declare const SEVERITY_RANK: Readonly<Record<DiagnosticSeverity, number>>;
+export interface Diagnostic {
+    /** Идентификатор валидатора. По нему `publish` замещает прошлый результат. */
+    readonly source: string;
+    readonly severity: DiagnosticSeverity;
+    /**
+     * Ключ i18n, не текст. Голый код (`schema.unknown-component`) переводится словарём
+     * оболочки по ключу `errors.<code>`; код вида `<plugin-id>:<code>` — словарём ВНЁСШЕГО
+     * плагина по ключу `errors.<code>` (см. {@link pluginDiagnosticCode}).
+     */
+    readonly code: string;
+    readonly params?: Record<string, unknown>;
+    readonly target: DiagnosticTarget;
+    readonly fixes?: readonly QuickFix[];
+}
+/**
+ * Код находки, текст которой лежит в словаре плагина-владельца.
+ *
+ * Словарь оболочки общий (`errors.<code>`): одна ошибка звучит одинаково в подчёркивании,
+ * на канвасе и в панели проблем. Но стек, пришедший плагином, в словарь оболочки писать
+ * не может — и не должен: оболочка тогда знала бы его ошибки. Такой код несёт владельца,
+ * и переводчик ищет `errors.<code>` в его пространстве имён; плагин кладёт текст туда же,
+ * куда и остальные свои строки (`ctx.i18n.contribute`).
+ */
+export declare function pluginDiagnosticCode(pluginId: string, code: string): string;
+/** Владелец кода находки (`null` — оболочка) и сам код без владельца. */
+export declare function splitDiagnosticCode(code: string): {
+    readonly pluginId: string | null;
+    readonly code: string;
+};

package/dist/services/document-models.d.ts

@@ -0,0 +1,20 @@
+import { Capability } from '../primitives/capability.js';
+import { ResourceId } from '../primitives/resource.js';
+import { ModelDocumentHandle } from '../workspace/model/model-document.js';
+export interface DocumentModelsService {
+    /**
+     * Ручка модельного документа открытой вкладки.
+     *
+     * `null` — три разные вещи, одинаковые для редактора: вкладка ещё открывается, её закрыли,
+     * документ текстовый (провайдер не взялся или первый разбор не удался). Во всех трёх случаях
+     * править нечего.
+     */
+    handleOf(id: ResourceId): ModelDocumentHandle<unknown> | null;
+}
+/**
+ * Возможность «модели документов». Провайдер — оболочка (`platform/services/host-capabilities`):
+ * модели заводит она, и без проекта служба честно отвечает `null`.
+ *
+ * Версия `1.0.0` — исходная.
+ */
+export declare const DocumentModelsCapability: Capability<DocumentModelsService>;

package/dist/services/documents.d.ts

@@ -0,0 +1,94 @@
+import { Disposable } from '../primitives/disposable.js';
+import { ResourceId } from '../primitives/resource.js';
+import { Capability } from '../primitives/capability.js';
+import { Document } from '../workspace/document.js';
+import { WriteOptions } from '../workspace/write-options.js';
+/**
+ * Чем править открытие вкладки.
+ *
+ * Объявлено здесь, а не взято у хранилища вкладок: служба лежит НИЖЕ интерфейса и на его
+ * состояние ссылаться не должна. Совместимость с настоящими опциями вкладки проверяет
+ * компиляция порта — там значение уходит в `documents.open` без приведения.
+ */
+export interface OpenDocumentOptions {
+    /**
+     * Временная вкладка (`true` по умолчанию, как у щелчка в дереве): следующая такая же
+     * займёт её место. `false` — закрепить: человек пришёл править, а не посмотреть.
+     */
+    readonly preview?: boolean;
+}
+export interface DocumentsService {
+    /** Открыт ли проект. Без него остальное отвечает `null` и отказом — см. шапку. */
+    hasProject(): boolean;
+    /** Ресурс активной вкладки; `null` без проекта и без вкладок. */
+    activeResource(): ResourceId | null;
+    /**
+     * Ресурсы ВСЕХ открытых вкладок, в порядке вкладок. Без проекта — пусто.
+     *
+     * Не то же, что {@link activeResource}, и нужен тем, чьё состояние живёт дольше активной
+     * вкладки: превью помнит значения формы и находки сборки, пока открыт хоть один файл её
+     * каталога, и «хоть один» из активного не выводится — активным в этот миг бывает файл
+     * из совсем другого места.
+     *
+     * Список, а не событие «вкладку закрыли»: у хранилища вкладок событие одно — «снимок
+     * сменился», — и сведение по снимку не пропускает закрытие, случившееся мимо уведомления
+     * (смена проекта закрывает все вкладки разом).
+     */
+    openDocuments(): readonly ResourceId[];
+    /**
+     * Документ открытой вкладки. Настоящий {@link Document}, а не копия: `getText()` — то,
+     * что уйдёт в файл при сохранении, а {@link Document.onDidChangeContent} — единственный
+     * способ узнать о правке текста (в том числе чужой: ассистента, слияния, отката).
+     */
+    documentOf(id: ResourceId): Document | null;
+    /**
+     * Записывает текст в рабочую копию. Без проекта — отказ обещанием, а не тишина:
+     * правка, ушедшая в никуда, выглядит как сохранённая.
+     *
+     * Третий аргумент обязателен к пробросу до рабочей области: без него ход ассистента
+     * попадает в журнал как правка человека.
+     */
+    writeText(id: ResourceId, text: string, options?: WriteOptions): Promise<void>;
+    /** Открывает вкладку и делает её активной. Без проекта — отказ, как у записи. */
+    open(id: ResourceId, options?: OpenDocumentOptions): Promise<void>;
+    /**
+     * Выполнить отложенную перерисовку буфера по модели. Зовётся на уходе фокуса.
+     *
+     * Нужен редактору модельного документа, и без него контракт редактора не закрывается. Пока
+     * человек печатает, платформа откладывает перерисовку буфера из модели — она спрашивает
+     * реестр фокуса (`TextEditorFocusToken`), в который редактор и пишет. Снятый фокус и есть
+     * тот момент, когда откладывать больше не из-за чего, поэтому порядок несущий: сперва
+     * `setFocused(id, false)`, потом `flush(id)`.
+     *
+     * У текстового документа модели нет и откладывать нечего: вызов безвреден.
+     */
+    flush(id: ResourceId): void | Promise<void>;
+    /**
+     * Сменился проект или вкладки: открытие, закрытие, активация. Нагрузки нет намеренно —
+     * подписчик перечитывает снимок ({@link activeResource}, {@link documentOf}).
+     */
+    onDidChange(cb: () => void): Disposable;
+}
+/**
+ * Рабочая область как ВОЗМОЖНОСТЬ: токен службы плюс версия контракта.
+ *
+ * Провайдер — сама оболочка, а не плагин (`services/host-capabilities`): служба существует
+ * с запуска, потому что без неё редактор из каталога проекта не редактор, и ставить её
+ * появление в зависимость от состава плагинов значило бы, что профиль без превью отнимает
+ * у внешнего редактора текст документа.
+ *
+ * Идентификатор ПРЕЖНИЙ — `shell.documents`, хотя RFC зовёт эту возможность
+ * `reformer.workspace`: смена `id` службы — это миграция сохранённых данных и чужих
+ * манифестов, и она отложена целиком в фазу 7 плана v4 (там же переименование `kits.active`).
+ *
+ * Версия `1.0.0` — исходная: {@link DocumentsService} на момент объявления, вместе
+ * с `openDocuments`. Растит её тот, кто интерфейс меняет: минор — добавленный метод,
+ * мажор — удалённый или сменивший смысл.
+ */
+export declare const DocumentsCapability: Capability<DocumentsService>;
+/**
+ * Токен службы. ТОТ ЖЕ объект, что {@link DocumentsCapability}: возможность расширяет токен,
+ * второго реестра нет (`primitives/capability`). Имя оставлено — им пользуется `@reformer/builder-plugin-api`
+ * и каждый плагин, который уже берёт службу.
+ */
+export declare const DocumentsServiceToken: Capability<DocumentsService>;

package/dist/services/host-messages.d.ts

@@ -0,0 +1,10 @@
+import { Capability } from '../primitives/capability.js';
+import { PluginI18n } from './i18n.js';
+/** Словарь оболочки: локаль, перевод ключа без приставки плагина, смена локали. */
+export type HostMessagesService = Pick<PluginI18n, 'locale' | 't' | 'onDidChangeLocale'>;
+/**
+ * Возможность «словарь оболочки». Провайдер — оболочка.
+ *
+ * Версия `1.0.0` — исходная.
+ */
+export declare const HostMessagesCapability: Capability<HostMessagesService>;

package/dist/services/i18n.d.ts

@@ -0,0 +1,43 @@
+import { Disposable } from '../primitives/disposable.js';
+/** Вид сервиса для плагина: ключи автоматически префиксуются его идентификатором. */
+export interface PluginI18n {
+    /**
+     * Действующая локаль — та же, что у корня: у вида своей быть не может.
+     *
+     * Нужна не для показа, а для перерисовки: снимок для `useSyncExternalStore` обязан меняться
+     * вместе с языком, иначе панель плагина осталась бы на прежних строках до следующей правки
+     * своего состояния (см. `ui/useTranslate`).
+     */
+    readonly locale: string;
+    t(key: string, params?: Record<string, unknown>): string;
+    /**
+     * Локаль сменилась. Тот же канал, что у корня: подписка идёт НАПРЯМУЮ к нему, потому что
+     * язык у приложения один, а вид — всего лишь пространство имён ключей.
+     */
+    onDidChangeLocale(cb: (locale: string) => void): Disposable;
+    /**
+     * Регистрирует словарь в пространстве имён плагина.
+     *
+     * Повторный вызов для той же локали **дополняет** словарь, а не заменяет его: плагин вправе
+     * везти словарь по частям — например, догружать раздел вместе с панелью.
+     *
+     * Бросает, если сообщение не разбирается, называя ключ. Ни одно сообщение этого вызова
+     * при этом не регистрируется.
+     */
+    contribute(locale: string, messages: Readonly<Record<string, string>>): void;
+}
+/**
+ * Ключ сообщения, текст которого лежит в словаре плагина-владельца: `<plugin-id>:<key>`.
+ *
+ * Нужен там, где строку переводит НЕ плагин, а тот, кто показывает, — уведомления и находки.
+ * Показывающий общий на всех, и без владельца он знал бы только свой словарь: стек, пришедший
+ * плагином, либо писал бы в словарь оболочки (которой его строки не принадлежат), либо
+ * показывал бы маркер промаха. Ключ с владельцем переводится словарём владельца, голый — словарём
+ * оболочки, как раньше.
+ */
+export declare function pluginMessageKey(pluginId: string, key: string): string;
+/** Владелец ключа (`null` — оболочка) и сам ключ без владельца. */
+export declare function splitMessageKey(key: string): {
+    readonly pluginId: string | null;
+    readonly key: string;
+};

package/dist/services/modules.d.ts

@@ -0,0 +1,49 @@
+import { Capability } from '../primitives/capability.js';
+import { TextRange } from './diagnostics/types.js';
+/** Сбой загрузки одного файла. */
+export interface ModuleLoadProblem {
+    readonly file: string;
+    readonly phase: 'resolve' | 'transpile' | 'evaluate';
+    readonly message: string;
+    /** Место в исходнике файла, если фаза его знает (транспиляция — знает). */
+    readonly range?: TextRange;
+}
+/** Результат загрузки графа модулей. */
+export interface ModuleGraph {
+    readonly entry: unknown;
+    readonly modules: ReadonlyMap<string, unknown>;
+    readonly errors: readonly ModuleLoadProblem[];
+    /** Что пришлось транспилировать: путь → JS. Уходит обратно в кэш сборки. */
+    readonly compiled?: ReadonlyMap<string, string>;
+}
+/** Прогретая компиляция набора: готовое из кэша и способ вернуть собранное. */
+export interface PrimedCompile {
+    /** Готовый JS, взятый из кэша: путь → код. */
+    readonly ready: ReadonlyMap<string, string>;
+    /** Нашлось ли всё. `false` означает, что движок транспиляции уже разбужен. */
+    readonly complete: boolean;
+    /** Отдать на хранение то, что собралось. Зовётся после линковки — до неё состав неизвестен. */
+    commit(compiled: ReadonlyMap<string, string>): Promise<void>;
+}
+export interface ModuleLoaderService {
+    /**
+     * Прогрев перед линковкой; ОБЯЗАН завершиться до {@link load}: внутри `require` асинхронного
+     * шага быть не может. Принимает ФАЙЛЫ, а не имена: ответить «движок не нужен, всё собрано»
+     * можно, только зная содержимое.
+     */
+    prepare(files: ReadonlyMap<string, string>): Promise<PrimedCompile>;
+    load(files: ReadonlyMap<string, string>, entry: string, options?: {
+        /** Готовый JS из кэша: путь → код. */
+        readonly ready?: ReadonlyMap<string, string>;
+        /** Подстановки импортов: спецификатор → готовые экспорты. */
+        readonly overrides?: ReadonlyMap<string, unknown>;
+        /** Лексически подставляемое окружение: `fetch`, `Date`, `Math`. */
+        readonly ambient?: Readonly<Record<string, unknown>>;
+    }): Promise<ModuleGraph>;
+}
+/**
+ * Возможность «загрузчик модулей». Провайдер — оболочка: движок один на приложение.
+ *
+ * Версия `1.0.0` — исходная.
+ */
+export declare const ModuleLoaderCapability: Capability<ModuleLoaderService>;

package/dist/services/notifications.d.ts

@@ -0,0 +1,56 @@
+import { Disposable } from '../primitives/disposable.js';
+/** Уровень тоста. Определяет вид и озвучку для скринридера, но не поведение очереди. */
+export type NotificationLevel = 'info' | 'success' | 'warning' | 'error';
+/** Необязательное действие: одна кнопка на тосте. */
+export interface NotificationAction {
+    /** Ключ i18n подписи кнопки. */
+    readonly titleKey: string;
+    /** Что сделать по нажатию. Закрытие тоста — дело отрисовки, здесь только действие. */
+    run(): void;
+}
+/** Что просят показать. */
+export interface NotificationRequest {
+    /** По умолчанию `info`. */
+    readonly level?: NotificationLevel;
+    /**
+     * Ключ i18n сообщения. Голый ключ переводит словарь оболочки; свою строку плагин называет
+     * ключом с владельцем — `pluginMessageKey(pluginId, key)` — и она берётся из ЕГО словаря.
+     */
+    readonly messageKey: string;
+    readonly params?: Record<string, unknown>;
+    readonly action?: NotificationAction;
+    /** Подсказка отрисовке, сколько держать тост. Без значения решает отрисовка. */
+    readonly durationMs?: number;
+}
+/** Уведомление в очереди: запрос плюс выданный идентификатор, с проставленным уровнем. */
+export interface Notification extends NotificationRequest {
+    readonly id: string;
+    readonly level: NotificationLevel;
+}
+/** Ссылка на показанное уведомление — чтобы снять его до того, как истечёт время. */
+export interface NotificationHandle {
+    readonly id: string;
+    dismiss(): void;
+}
+/** Настройки одного уровня — всё, кроме самого уровня и сообщения. */
+export type NotificationOptions = Omit<NotificationRequest, 'messageKey' | 'level'>;
+export interface NotificationsService {
+    show(request: NotificationRequest): NotificationHandle;
+    info(messageKey: string, options?: NotificationOptions): NotificationHandle;
+    success(messageKey: string, options?: NotificationOptions): NotificationHandle;
+    warning(messageKey: string, options?: NotificationOptions): NotificationHandle;
+    error(messageKey: string, options?: NotificationOptions): NotificationHandle;
+    /**
+     * Очередь не показанных уведомлений в порядке поступления.
+     *
+     * Между изменениями возвращает **ту же** ссылку: снимок читает `useSyncExternalStore`,
+     * который на новом массиве при каждом вызове падает с «The result of getSnapshot should
+     * be cached».
+     */
+    pending(): readonly Notification[];
+    /** Снимает уведомление из очереди. Неизвестный идентификатор — не ошибка. */
+    dismiss(id: string): void;
+    /** Очередь изменилась: добавили или сняли. */
+    observe(cb: () => void): Disposable;
+}
+export declare const NotificationsServiceToken: import('../index.js').ServiceToken<NotificationsService>;

package/dist/services/plugin-settings.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Ключ настроек плагина каталога.
+ *
+ * Одна функция на всё приложение: адрес не должен разъехаться между тем, кто пишет настройку,
+ * и тем, кто рисует её форму. Сам вид службы настроек для плагина живёт в оболочке билдера.
+ *
+ * @module @reformer/builder-plugin-api/services/plugin-settings
+ */
+/** Ключ настроек плагина каталога. Одна функция на всё приложение: адрес не должен разъехаться. */
+export declare function pluginSettingsKey(pluginId: string): string;

package/dist/services/plugins-catalog.d.ts

@@ -0,0 +1,58 @@
+import { Capability } from '../primitives/capability.js';
+/** Состояние строки каталога: найден-выключен, работает, не грузится. */
+export type ManagedPluginState = 'disabled' | 'enabled' | 'failed';
+/** Плагин каталога в объёме, нужном тому, кто им распоряжается. */
+export interface ManagedPlugin {
+    readonly id: string;
+    readonly name: string;
+    readonly version?: string;
+    readonly state: ManagedPluginState;
+    /** Помечен «в разработке»: файлы наблюдаются, плагин перезагружается после правки. */
+    readonly dev: boolean;
+    /** Слой, из которого взят плагин: каталог проекта или установленное из npm. */
+    readonly layer?: 'project' | 'installed';
+    /** Почему `failed`. Текста достаточно: код разбора нужен спискам оболочки, а не отсюда. */
+    readonly problem?: {
+        readonly message: string;
+    };
+}
+export interface PluginsCatalogService {
+    /** Снимок списка. Живого списка здесь нет намеренно: подписка — дело того, кто рисует. */
+    list(): readonly ManagedPlugin[];
+    /** Загружает и активирует. Для упавшего это и есть «попробовать снова». */
+    enable(id: string): Promise<boolean>;
+    /** Снимает вклады, помнит решение человека. */
+    disable(id: string): void;
+    /** Снимает вклады, перечитывает файлы, поднимает заново. */
+    reload(id: string): Promise<boolean>;
+    /** Ставит или снимает пометку «в разработке». */
+    setDev(id: string, on: boolean): void;
+    /** Перечитывает каталог: так в списке появляется только что созданный плагин. */
+    refresh(): Promise<unknown>;
+    /**
+     * Ставит плагин из npm, спросив имя пакета у человека.
+     *
+     * Необязателен, и это названная деградация: сборка без установки (профиль без неё,
+     * окружение без OPFS) обязана работать, а тот, кто рисует список, — не показывать
+     * действие, которое ничего не сделает. Имя пакета спрашивает ОБОЛОЧКА: диалоги — её
+     * служба, и плагин не должен получать её ради одного поля ввода.
+     */
+    install?(): Promise<void>;
+    /** Убирает установленный плагин целиком. Плагина из каталога проекта не касается. */
+    uninstall?(id: string): Promise<void>;
+    /**
+     * Переключает установленный плагин на другую уже скачанную версию.
+     *
+     * Откат существует ради одного случая, зато обязательного: новая версия сломала работу.
+     * Прошлые версии остаются на диске, поэтому операция не ходит в сеть и работает без неё.
+     */
+    rollback?(id: string): Promise<void>;
+}
+/**
+ * Возможность «каталог плагинов». Привилегированная: право `plugins.manage`.
+ *
+ * Провайдер — оболочка. Версия `1.0.0` — исходная; растит её тот, кто меняет интерфейс.
+ */
+export declare const PluginsCatalogCapability: Capability<PluginsCatalogService>;
+/** Токен службы — ТОТ ЖЕ объект: возможность расширяет токен, второго реестра нет. */
+export declare const PluginsCatalogServiceToken: Capability<PluginsCatalogService>;