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

package/dist/plugin/manifest.d.ts

@@ -0,0 +1,320 @@
+import { CapabilityDeclaration, CapabilityRequirement } from '../primitives/capability.js';
+import { PluginPermission } from './permissions.js';
+/** Имя файла манифеста внутри каталога плагина. */
+export declare const PLUGIN_MANIFEST_FILE = "manifest.json";
+/**
+ * Версия API плагинов, которую даёт эта сборка оболочки.
+ *
+ * Константа, а не мажор числом: с ней `apiVersion: "^1.2"` наконец значит то, что написано, —
+ * прежний разбор доставал из диапазона первое число и не отличал `^1` от `1.5`. Растить её
+ * обязан тот, кто меняет `@reformer/builder-plugin-api`: минор — на добавление имени, мажор — на удаление или смену
+ * смысла. Политики совместимости между мажорами как не было, так и нет (plugin-and-shell.md).
+ */
+export declare const BUILDER_API_VERSION = "1.0.0";
+/**
+ * Откуда плагин взялся. Разбор манифеста спрашивают об этом ЗАРАНЕЕ, а не выводят потом.
+ *
+ * Две поставки различаются не «происхождением вообще», а двумя проверками, которые нельзя
+ * сделать одинаковыми. У плагина ПРОЕКТА идентификатор обязан совпасть с именем каталога —
+ * каталог единственное, что видно до чтения манифеста, — и точка входа обязана быть, иначе
+ * грузить нечего. У ВСТРОЕННОГО каталога нет вовсе (он лежит в бандле оболочки, а имя его
+ * папки — `ai` против идентификатора `reformer.ai`), и точки входа тоже нет: его код уже
+ * здесь. Зато у него есть то, чего не бывает у плагина проекта, — способ доставки
+ * ({@link BuiltinDelivery}).
+ */
+export type PluginSource = {
+    readonly kind: 'builtin';
+} | {
+    readonly kind: 'project';
+    readonly dir: string;
+};
+/**
+ * Как встроенный плагин приезжает в браузер.
+ *
+ * Деление про СБОРКУ, а не про поведение: оба набора встают до первой отрисовки. Смысл в том,
+ * что иначе код всех плагинов лежит внутри entry одним файлом, а отдельный файл даёт только
+ * динамический импорт (`manualChunks` измерен и отвергнут — см. `vite.config.ts`).
+ *
+ * `reason` заполняется у СТАТИЧЕСКИХ и только у них: ленивость — умолчание, объяснять надо
+ * отступление от него. Живёт причина здесь, а не комментарием у записи состава, потому что
+ * относится к плагину, а не к карте: карта может смениться, а довод останется тем же.
+ */
+export interface BuiltinDelivery {
+    readonly loading: 'eager' | 'lazy';
+    /** Почему этот плагин не может приехать своим файлом. Обязателен при `eager`. */
+    readonly reason?: string;
+}
+/**
+ * Общее у манифестов обеих поставок.
+ *
+ * `name` и `version` необязательны в файле и получают умолчания: они нужны списку плагинов,
+ * а не механике, и требовать их значило бы отвергать рабочий плагин из-за подписи. `id`
+ * и `apiVersion` умолчаний не имеют — у них нет осмысленного «по умолчанию».
+ */
+export interface PluginManifestBase {
+    readonly id: string;
+    readonly name: string;
+    readonly version: string;
+    /** Диапазон API, объявленный плагином, как он написан в файле: `^1`, `1.2`, `~1.0.0`. */
+    readonly apiVersion: string;
+    /** Вклады, объявленные ДЕКЛАРАТИВНО — то есть видимые до того, как плагин включён. */
+    readonly contributes?: PluginContributes;
+    /**
+     * Возможности, которые плагин ДАЁТ другим: `[{ "id": "reformer.kit.catalog", "version": "1.0.0" }]`.
+     *
+     * Объявление, а не регистрация: слот в реестре служб плагин занимает сам, в `activate`.
+     * Расхождение между объявленным и занятым ловит рантайм (`./registry`) — иначе резолвер
+     * верил бы манифесту, а реестр молчал бы, и «возможность есть» означало бы «написано,
+     * что есть».
+     */
+    readonly provides?: readonly CapabilityDeclaration[];
+    /**
+     * Возможности, которые плагину НУЖНЫ, — двумя списками.
+     *
+     * Деление на обязательные и необязательные не косметическое, оно про разные исходы.
+     * Невыполненное ОБЯЗАТЕЛЬНОЕ требование — отказ включения ДО того, как исполнится код
+     * плагина (`./catalog`, `requires-unsatisfied`): плагин, которому нечем работать, не должен
+     * получать шанс упасть на середине `activate` и оставить половину вкладов.
+     * Невыполненное НЕОБЯЗАТЕЛЬНОЕ — названная деградация, ровно по принципу «необязательный
+     * член контракта = названная деградация, а не поломка»: плагин включается и работает
+     * без этой возможности, спрашивая её через `ctx.capabilities.get`.
+     */
+    readonly requires?: PluginRequirements;
+    /**
+     * Права, которые плагин просит: `["workspace.save"]`.
+     *
+     * Не декорация и не намерение — ключ к привилегированной службе. Оболочка отдаёт такую
+     * службу только тому, кто её здесь назвал И кому человек это подтвердил; не назвавший
+     * получает `undefined` на месте объекта. Поэтому список закрыт ({@link PluginPermission}):
+     * право, за которым не стоит запертой двери, было бы ровно тем ложным ощущением границы,
+     * из-за которого поля `permissions` не было до появления первой такой двери.
+     */
+    readonly permissions?: readonly PluginPermission[];
+    /**
+     * Совместимость с ПРИЛОЖЕНИЕМ: `{ "builder": ">=2.1" }`.
+     *
+     * Отдельная ось от {@link PluginManifestBase.apiVersion}, а не её уточнение. `apiVersion`
+     * отвечает «какие имена доступны плагину» — это версия контракта; `compatibility.builder`
+     * отвечает «какое приложение их подаёт». Расходятся они по построению: контракт растёт,
+     * когда меняется поверхность плагина, а билдер выпускается по своим причинам, и плагину
+     * бывает нужно сказать «мне нужна сборка, где это уже чинено», не требуя нового контракта.
+     *
+     * Поля не было, пока у оболочки не появилось своей версии в рантайме: проверять его было
+     * нечем, а объявление, которое ничего не принуждает, — то же ложное ощущение границы,
+     * из-за которого до первой запертой службы не было `permissions`. Теперь несовпадение —
+     * отказ загрузки (`builder-version`), а у того, кто своей версии не знает (CLI автора
+     * плагина), проверяется форма диапазона.
+     */
+    readonly compatibility?: PluginCompatibility;
+}
+/** Совместимость с приложением. Один член; растёт вместе с тем, у чего появится версия. */
+export interface PluginCompatibility {
+    /** Диапазон версий билдера: `^2`, `>=2.1`, `~2.1.0`. */
+    readonly builder: string;
+}
+/** Манифест плагина каталога проекта: у него есть каталог и точка входа. */
+export interface ProjectPluginManifest extends PluginManifestBase {
+    readonly source: {
+        readonly kind: 'project';
+        readonly dir: string;
+    };
+    /** Точка входа ВНУТРИ каталога плагина, нормализованная: `main.js`, `dist/main.js`. */
+    readonly main: string;
+    /**
+     * Своя таблица стилей. Отсутствие поля — рекомендуемый путь: плагин пользуется классами
+     * оболочки и токенами кита и выглядит родным бесплатно.
+     */
+    readonly styles?: PluginStyles;
+}
+/**
+ * Манифест встроенного плагина: точки входа нет, зато объявлен способ доставки.
+ *
+ * Своей таблицы стилей у встроенного не бывает и быть не может: его CSS собирается вместе
+ * с оболочкой, и изолировать его было бы нечего и не от чего.
+ */
+export interface BuiltinPluginManifest extends PluginManifestBase {
+    readonly source: {
+        readonly kind: 'builtin';
+    };
+    readonly builtin: BuiltinDelivery;
+}
+/**
+ * Манифест исходников плагина: то, что лежит в репозитории автора ДО сборки.
+ *
+ * Не поставка — оболочка такого манифеста не видит, — поэтому и не вариант {@link PluginManifest}.
+ * Форма та же, что у плагина каталога, без одного: каталога ещё нет, и `source` описывать нечему.
+ * `main` указывает на исходник (`src/main.ts`); собранный манифест получит `main.js`.
+ * Разбор — `parsePluginSourceManifest`.
+ */
+export interface PluginSourceManifest extends PluginManifestBase {
+    readonly main: string;
+    readonly styles?: PluginStyles;
+}
+/**
+ * Разобранный манифест — одной из двух поставок.
+ *
+ * Объединение размечено {@link PluginSource}, а не двумя необязательными полями: «точка входа
+ * есть, но у встроенного её не бывает» пришлось бы проверять в загрузчике на каждом обращении,
+ * и отсутствие `main` у того, кого грузят из каталога, стало бы не ошибкой разбора,
+ * а исключением где-то посередине загрузки.
+ */
+export type PluginManifest = ProjectPluginManifest | BuiltinPluginManifest;
+/** Требования плагина. Оба списка есть всегда — пустые, если в манифесте их не написали. */
+export interface PluginRequirements {
+    readonly required: readonly CapabilityRequirement[];
+    readonly optional: readonly CapabilityRequirement[];
+}
+/**
+ * Декларативные вклады манифеста — то есть видимые ДО того, как плагин включён.
+ *
+ * Клавиши попали сюда по проверяемой причине, а не «для симметрии с VS Code»: сочетание,
+ * объявленное КОДОМ, появляется в приложении только после активации плагина. Значит до
+ * включения таблица клавиш о нём не знает, и переназначить его нельзя — а человеку это нужно
+ * ровно тогда, когда новый плагин занял привычную ему клавишу.
+ *
+ * Словари попали сюда по причине жёстче: без них плагину каталога негде взять СВОЙ текст
+ * вовсе. Заголовок команды разрешается словарём её владельца (`primitives/command`, поле
+ * `titleKey`), сервиса i18n в `PluginContext` нет и не будет (вклад в словарь не снимается
+ * вместе с плагином, значит его подпиской быть не может), а словари встроенных вносит
+ * композиция — кодом, которого у внешнего плагина не существует. Итог без этого поля:
+ * КАЖДАЯ команда плагина каталога показана в палитре и меню маркером промаха
+ * `⟦mycode.command.format⟧`.
+ */
+export interface PluginContributes {
+    readonly keybindings?: readonly DeclaredKeybinding[];
+    /**
+     * Словари: локаль → путь к JSON внутри каталога плагина, например
+     * `{ "ru": "locales/ru.json", "en": "locales/en.json" }`.
+     *
+     * Путь, а не сам словарь. Манифесты читаются у ВСЕХ найденных плагинов на каждом обходе
+     * каталога, включая выключенные, и встроенный текст превратил бы обход в чтение всех
+     * переводов всех плагинов проекта. Файл читается один раз и только у того, кого включили
+     * (`./loader`).
+     */
+    readonly messages?: Readonly<Record<string, string>>;
+}
+/**
+ * Сочетание, объявленное в манифесте.
+ *
+ * `command` — строка, и плагин вправе назвать команду, которой сейчас нет: она появится
+ * при активации. Правило без команды просто не срабатывает — это обычное состояние
+ * выключенного плагина, а не поломка.
+ */
+export interface DeclaredKeybinding {
+    readonly command: string;
+    /** Сочетание или аккорд: `mod+alt+i`, `mod+k mod+i`. */
+    readonly key: string;
+    /** Условие применимости; синтаксис — `primitives/when-expr`. */
+    readonly when?: string;
+    /** Аргументы вызова: у клавиши их нет, поэтому объявить их можно только здесь. */
+    readonly args?: unknown;
+    readonly allowInEditable?: boolean;
+}
+/**
+ * Объявление своей таблицы стилей.
+ *
+ * `isolation` необязателен и умеет ровно одно значение. Поле существует не ради выбора,
+ * а ради читаемости манифеста: `"isolation": "scoped"` рядом с файлом говорит автору плагина,
+ * что его CSS ограничат, — и он не будет искать причину, почему `body { margin: 0 }`
+ * не подействовал на весь документ. Второго значения нет и не планируется: неизолированный
+ * чужой CSS перекрашивает оболочку, и это не режим, а поломка.
+ */
+export interface PluginStyles {
+    /** Путь к CSS ВНУТРИ каталога плагина, нормализованный. */
+    readonly file: string;
+    readonly isolation: 'scoped';
+}
+/**
+ * Почему плагин не работает. Код — для интерфейса и тестов, `message` — для человека.
+ *
+ * Набор плоский и общий на весь путь «нашли → разобрали → загрузили → включили», потому что
+ * показывается он в одном месте — строке списка плагинов, — и различать там «отказ разбора»
+ * от «отказа загрузки» человеку незачем: ему нужно знать, что чинить.
+ */
+export type PluginProblemCode = 
+/** В каталоге плагина нет `manifest.json`. */
+'manifest-missing'
+/** Манифест не читается или не разбирается как JSON. */
+ | 'manifest-unreadable'
+/** Манифест разобран, но поле отсутствует или не того вида. */
+ | 'manifest-invalid'
+/** `id` в манифесте не совпадает с именем каталога. */
+ | 'id-mismatch'
+/** `apiVersion` не покрывает версию оболочки: плагин написан против другой. */
+ | 'api-version'
+/**
+ * `compatibility.builder` не покрывает версию ПРИЛОЖЕНИЯ.
+ *
+ * Отдельный код, а не `api-version`: контракт может совпадать полностью, и чинится это
+ * иначе — обновлением билдера, а не переписыванием плагина под другой контракт.
+ */
+ | 'builder-version'
+/**
+ * Обязательное требование `requires.required` не выполнено ничем из доступного.
+ *
+ * Проверяется ДО загрузки кода (`./catalog`), поэтому плагин не получает шанса упасть
+ * на середине `activate`. Строка в списке плагинов остаётся — с этой причиной, как
+ * у `styles-invalid` и `messages-invalid`.
+ */
+ | 'requires-unsatisfied'
+/**
+ * Плагин объявил в `provides` возможность, которую к концу `activate` не зарегистрировал.
+ *
+ * Отдельный код, а не `activate-failed`: `activate` тут как раз НЕ бросал. Отличать их
+ * нужно тому, кто чинит плагин, — это ошибка в самом плагине, а не в его окружении.
+ */
+ | 'provides-unregistered'
+/** Файла точки входа нет среди файлов плагина. */
+ | 'entry-missing'
+/** В каталоге плагина слишком много файлов — это не плагин, а чужое дерево. */
+ | 'too-many-files'
+/** Источник не разрешает исполнять свой код (`capabilities.executesCode`). */
+ | 'source-forbids-code'
+/** Транспиляция, линковка или исполнение модуля отказали. */
+ | 'code-failed'
+/** Точка входа экспортировала не плагин. */
+ | 'not-a-plugin'
+/** Идентификатор уже занят другим плагином — встроенным или соседним по каталогу. */
+ | 'id-taken'
+/** `activate` бросил. Плагин выключен и показан — автоповтора нет. */
+ | 'activate-failed'
+/** Объявленная таблица стилей не разбирается или не изолируется (см. `./styles`). */
+ | 'styles-invalid'
+/** Объявленный файл словаря не читается или это не плоский объект «ключ → строка». */
+ | 'messages-invalid'
+/**
+ * Право, объявленное манифестом, человек не подтвердил.
+ *
+ * Проверяется ДО загрузки кода, как и требования: плагин, которому откажут в его главной
+ * службе, не должен исполниться наполовину. Отказ не гасит строку в списке — он её объясняет.
+ */
+ | 'permissions-denied';
+/** Отказ как данные. Исключением он не бывает нигде: испорченный каталог — не авария. */
+export interface PluginProblem {
+    readonly code: PluginProblemCode;
+    readonly message: string;
+    /** Файл, к которому отнесён отказ, если он известен. Путь внутри каталога плагина. */
+    readonly file?: string;
+    /** Исходное исключение — для консоли, не для показа. */
+    readonly cause?: unknown;
+}
+/**
+ * Манифест той поставки, которую назвали разбору.
+ *
+ * Нужен затем, чтобы загрузчик каталога получал манифест С точкой входа, а не объединение,
+ * у которого её может не быть: спросив разбор про каталог проекта, он спросил про плагин,
+ * у которого `main` есть по определению, и проверять это второй раз ему незачем.
+ */
+export type ManifestOf<S extends PluginSource> = Extract<PluginManifest, {
+    readonly source: {
+        readonly kind: S['kind'];
+    };
+}>;
+/** Результат разбора: либо манифест, либо причина, по которой его нет. */
+export type ManifestParseResult<M extends PluginManifestBase = PluginManifest> = {
+    readonly ok: true;
+    readonly manifest: M;
+} | {
+    readonly ok: false;
+    readonly problem: PluginProblem;
+};

package/dist/plugin/messages-bundle.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Файл словаря плагина: `locales/ru.json` и соседи.
+ *
+ * Один разбор на загрузчик оболочки и `reformer-plugin validate` — по той же причине, что
+ * и разбор манифеста.
+ *
+ * @module @reformer/builder-plugin-api/plugin/messages-bundle
+ */
+/**
+ * Разбирает файл словаря: плоский объект «ключ → строка», и ничего больше.
+ *
+ * Вложенные объекты не разворачиваются сознательно: ключ у нас и так составной
+ * (`command.format`), и второй способ записать тот же ключ дал бы словарь, в котором промах
+ * ищется в двух местах. Отказ возвращается ПРИЧИНОЙ, а не готовой проблемой: файл и локаль
+ * знает только вызывающий, и собирать сообщение дважды незачем.
+ */
+export declare function parseMessagesBundle(text: string): {
+    ok: true;
+    bundle: Readonly<Record<string, string>>;
+} | {
+    ok: false;
+    reason: string;
+    cause?: unknown;
+};

package/dist/plugin/permissions.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Права плагина: что он объявляет в манифесте и что человек ему подтверждает.
+ *
+ * ## Почему поле появилось только сейчас
+ *
+ * «`permissions` не вводим» — решение, записанное в `plugin-and-shell.md` и действовавшее до
+ * этого модуля. Довод был не в том, что права не нужны, а в том, что **поле, которое ничего
+ * не принуждает, создаёт ложное ощущение границы**: объявленное намерение, которое никто
+ * не проверяет, хуже честного «включённый плагин может всё».
+ *
+ * Принуждение появилось вместе с первой привилегированной службой. Реестр служб отдаёт её
+ * только тому, кому право подтверждено, и отказ — не совет, а отсутствие объекта. Поэтому
+ * список здесь **закрытый и растёт ровно по одному имени на одну такую службу**: право,
+ * за которым не стоит запертой двери, — это снова то самое ложное ощущение.
+ *
+ * ## Что право НЕ значит
+ *
+ * Оно не про безопасность исполнения: плагин работает в том же realm, что оболочка, и код,
+ * который человек включил, может дотянуться до чего угодно своими руками. Граница здесь одна,
+ * и она названа в `plugin-and-shell.md`: плагин включается ЯВНО. Права сужают не возможности
+ * кода, а поверхность платформы — то, что оболочка подаёт ему сама, по адресу из контракта.
+ *
+ * @module @reformer/builder-plugin-api/plugin/permissions
+ */
+/**
+ * Все права, которые оболочка умеет принуждать.
+ *
+ * - **`workspace.save`** — вынести написанное НАРУЖУ, в источник проекта. Единственная
+ *   операция с таким свойством: все остальные пути записи упираются в рабочую копию, и до
+ *   источника мимо сохранения не дотянуться физически. Отсюда и первое право: дверь ровно
+ *   одна, охранять её дешевле, чем объяснять, почему её нет.
+ * - **`workspace.resources`** — менять записи проекта: создать, переименовать, перенести,
+ *   удалить, скопировать, открыть другой каталог. То же свойство, что у сохранения: действие
+ *   выходит за пределы рабочей копии, и отменить его нашими силами нельзя. Право заведено
+ *   вместе со службой `reformer.workspace.resources`, а не «на будущее»: до неё эти операции
+ *   существовали только портом композиции, то есть для внешнего плагина их не было вовсе,
+ *   и запирать было нечего.
+ * - **`plugins.manage`** — распоряжаться ОСТАЛЬНЫМИ плагинами: включать, выключать,
+ *   перезагружать, ставить из npm. Самое сильное из трёх, и это надо называть вслух:
+ *   включить плагин значит исполнить чужой код, то есть обладатель права решает за человека
+ *   то, что человек привык решать сам. Отдельным правом оно и заведено — чтобы вопрос
+ *   задавался отдельно и заметно, а не приезжал довеском к работе с файлами.
+ */
+export declare const PLUGIN_PERMISSIONS: readonly ["workspace.save", "workspace.resources", "plugins.manage"];
+/** Право плагина — имя из {@link PLUGIN_PERMISSIONS}. */
+export type PluginPermission = (typeof PLUGIN_PERMISSIONS)[number];
+/** Знает ли оболочка такое право. Разбор манифеста отвергает незнакомые, а не игнорирует. */
+export declare function isPluginPermission(value: string): value is PluginPermission;

package/dist/plugin/plugin-exports.d.ts

@@ -0,0 +1,10 @@
+import { Plugin } from './types.js';
+/**
+ * Достаёт плагин из экспортов точки входа.
+ *
+ * Две формы, потому что их две в жизни: `module.exports = definePlugin(...)` у собранного
+ * `main.js` и `export default definePlugin(...)` у `main.ts`, который транспилируется
+ * в `exports.default`. Требовать одну из них значило бы отвергать половину рабочих плагинов
+ * ради формальности.
+ */
+export declare function pluginFromExports(exports: unknown): Plugin | undefined;

package/dist/plugin/runtime-modules.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Спецификаторы, которые оболочка подставляет исполняемому коду плагина СВОИМИ объектами.
+ *
+ * Это обещание рантайма, а не пожелание: сборка плагина обязана держать каждый из них ВНЕШНИМ.
+ * Вложи сборщик в `main.js` свою копию React или ядра форм — плагин получит второй экземпляр,
+ * и поломка будет тихой: два дерева хуков, `instanceof Signal`, всегда отвечающий `false`,
+ * вклады в чужой пустой реестр.
+ *
+ * Список — данные пакета, а не константа сборщика, по той же причине, что разбор манифеста:
+ * читают его двое. Оболочка регистрирует ровно эти модули (и тестом сверяет свой реестр
+ * с этим списком), инструменты автора плагина — выносят их из сборки. Разойдись два списка,
+ * и плагин, собранный «правильно», падал бы на спецификаторе, которого нет в реестре.
+ *
+ * Подпути перечислены поимённо: реестр резолвит ТОЧНЫМ совпадением, и `@reformer/cdk` не
+ * покрывает `@reformer/cdk/form-array`. Сборщику при этом годится и префикс — всё, что начинается
+ * с `@reformer/`, защищено оболочкой целиком и подменить его плагин не может.
+ *
+ * @module @reformer/builder-plugin-api/plugin/runtime-modules
+ */
+export declare const PLUGIN_RUNTIME_MODULES: readonly string[];

package/dist/plugin/storage.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Изолированное хранилище плагина и его секреты.
+ *
+ * Два разных API, потому что у них разные умолчания по времени жизни: обычные данные плагин
+ * кладёт, чтобы они пережили перезагрузку страницы, а секрет — чтобы он **не** пережил её,
+ * пока не сказано обратное.
+ *
+ * ## `localStorage` не используется нигде
+ *
+ * В v1 в `localStorage` лежит ключ AI-провайдера — это ровно та ошибка, которую здесь
+ * не повторяем: `localStorage` синхронный (то есть блокирует поток на каждом обращении),
+ * общий на весь источник (то есть без пространств имён) и доступен любому скрипту на странице
+ * без единого рубежа. Постоянное хранилище — IndexedDB, и оно приходит сюда бэкендом.
+ *
+ * ## Почему бэкенд внедряется, а не импортируется
+ *
+ * Слой IndexedDB — соседняя работа (`host/workspace/storage/`). Если бы этот модуль импортировал
+ * его напрямую, изолированное хранилище нельзя было бы проверить без базы, а тест пространств
+ * имён превратился бы в тест IDB. Поэтому здесь объявлен минимальный контракт
+ * {@link PluginStorageBackend}, зеркалящий поверхность хранилища плюс пространство имён,
+ * и есть его памятная реализация {@link createMemoryStorageBackend}. Настоящий бэкенд подключает
+ * композиция, ничего в этом файле не меняя.
+ *
+ * ## Пространство имён — идентификатор плагина
+ *
+ * Честная оговорка из контракта: пока весь код на странице наш, изоляция пространств — гигиена,
+ * а не граница безопасности. Дотянуться до чужого пространства можно, и рантайм этому помешать
+ * не в состоянии. Ценность в другом: секрет не протечёт в будущий плагин по недосмотру, а XSS
+ * в одном месте не достанет ключ из другого. Подделать пространство плагин при этом не может:
+ * `pluginId` связывается в момент создания хранилища рантаймом — тем же приёмом, что
+ * `ExtensionRegistry.forPlugin`.
+ *
+ * Здесь ОБЪЯВЛЕНИЕ обоих хранилищ: их получает плагин полями контекста. Бэкенд и сборка
+ * (`createPluginStorage`, `createSecretStorage`) живут в оболочке билдера — она же связывает
+ * пространство имён с идентификатором плагина, и подделать его плагину нечем.
+ *
+ * @module @reformer/builder-plugin-api/plugin/storage
+ */
+/** Данные плагина. Переживают перезагрузку страницы — если бэкенд постоянный. */
+export interface PluginStorage {
+    /**
+     * Значение по ключу или `undefined`.
+     *
+     * `T` — обещание вызывающего, а не проверка: бэкенд хранит то, что положили, и после
+     * перезагрузки страницы там может лежать значение прежней версии плагина. Прочитанное
+     * проверяет тот, кто читает.
+     */
+    get<T>(key: string): Promise<T | undefined>;
+    /** Значение обязано быть структурно клонируемым: бэкенд — IndexedDB, а не JSON. */
+    set<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** Только ключи своего пространства имён. */
+    keys(): Promise<readonly string[]>;
+}
+/**
+ * Секреты плагина: токены, ключи провайдеров.
+ *
+ * Умолчание — память сессии. Это решение, а не недоделка: секрет, который переживает
+ * перезагрузку, обязан быть положен туда сознательным `persist`, потому что цена ошибки
+ * несимметрична — забытый в памяти секрет стоит одного повторного ввода, забытый на диске
+ * живёт до тех пор, пока о нём не вспомнят.
+ */
+export interface SecretStorage {
+    get(key: string): Promise<string | undefined>;
+    /** По умолчанию — только память сессии. `persist` пишет в изолированное пространство. */
+    set(key: string, value: string, opts?: {
+        persist?: boolean;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+}