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

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

@@ -0,0 +1,228 @@
+import { ComponentType } from 'react';
+import { Disposable } from '../../primitives/disposable.js';
+import { WhenContext } from '../../primitives/when-context.js';
+/**
+ * Корневые меню, объявленные Host.
+ *
+ * Набор фиксирован по тому же доводу, что и набор слотов оболочки: состав шапки — часть
+ * идентичности приложения, а не следствие того, какие плагины включены. Добавление корня —
+ * правка Host, и пусть будет заметной.
+ *
+ * Плагин при этом не заперт: он вправе внести СВОЁ корневое меню ({@link MenuRootContribution}),
+ * но встанет оно в зону между `file` и `help` — см. {@link sortMenuRoots}.
+ *
+ * ## Почему только «Файл» и «Справка»
+ *
+ * «Правка» и «Вид» были и убраны. Обе состояли из действий, у которых уже есть более короткий
+ * путь: правка узлов — из сочетаний клавиш и контекстного меню на самом узле, а панели, тема
+ * и палитра — из рейла и `mod+shift+p`. Меню, дублирующее то, что рядом на экране, стоит
+ * не «ничего», а лишний уровень в шапке и лишнее место, где состав приложения надо повторить.
+ * Сами действия никуда не делись: команды на месте, сочетания работают, палитра их находит.
+ */
+export type MenuRootId = 'file' | 'help';
+/** Корневые меню Host. Порядок показа задаёт {@link sortMenuRoots}, а не этот список. */
+export declare const MENU_ROOT_IDS: readonly MenuRootId[];
+/**
+ * Контекстные меню, объявленные Host, — корни, у которых нет места в шапке.
+ *
+ * Они перечислены здесь по той же причине, что и корни шапки: набор поверхностей приложения
+ * не должен зависеть от того, какие плагины включены. Но показывает их не {@link buildMenuBar},
+ * а сама поверхность — дерево ресурсов строит своё меню через {@link buildMenu} в момент
+ * щелчка, потому что до щелчка у контекстного меню нет цели, а без цели половина его пунктов
+ * не имеет смысла.
+ *
+ * - `resource/context` — щелчок правой кнопкой по строке дерева ресурсов (или мимо строк).
+ * - `editor/title` — ряд действий справа в строке вкладок: то, что относится к ОТКРЫТОМУ
+ *   документу, а не к приложению. Пункт со значком становится кнопкой, пункт без значка
+ *   уходит под «…» — так же, как это устроено в редакторах, откуда пришла привычка.
+ */
+export type ContextMenuId = 'resource/context' | 'editor/title';
+/** Контекстные корни Host. Известны {@link unknownMenuPaths}, поэтому вклад в них — не промах. */
+export declare const CONTEXT_MENU_IDS: readonly ContextMenuId[];
+/**
+ * Адрес места в дереве меню: корень (`file`) или подменю (`file/recent`).
+ *
+ * Строка, а не объединение: пути подменю заводят плагины, и перечислить их Host не может.
+ * Промах по несуществующему пути не рисуется — найти его умеет {@link unknownMenuPaths}.
+ */
+export type MenuPath = string;
+/** Общее у всего, что вносится ВНУТРЬ меню. */
+interface MenuPlacement {
+    /** Куда: корневое меню или подменю. */
+    readonly menu: MenuPath;
+    /**
+     * Группа внутри меню. Группы сортируются по имени, поэтому соглашение — числовой префикс:
+     * `1_new`, `2_open`. Отсутствие означает безымянную группу, и она идёт первой.
+     */
+    readonly group?: string;
+    /** Порядок внутри группы; меньше — раньше. Без значения берётся `order` вклада. */
+    readonly order?: number;
+    /**
+     * Показывать ли сейчас. Отсутствие означает «всегда».
+     *
+     * `when` скрывает, а недоступность гасит: первое — про принадлежность контексту (пункты
+     * редактора схемы не нужны на markdown), второе — про «сейчас нечего отменять». Скрывать
+     * второе значило бы, что меню меняет высоту под курсором.
+     */
+    readonly when?: (ctx: WhenContext, target: MenuTarget) => boolean;
+    /**
+     * Доступен ли пункт ПРИ ЭТОЙ ЦЕЛИ. Отсутствие означает «доступен».
+     *
+     * ## Зачем он, если недоступность уже считает реестр команд
+     *
+     * `CommandRegistry.isEnabled` отвечает на вопрос «есть ли чему сработать» по
+     * {@link WhenContext}, и цели щелчка там нет и быть не может: контекст применимости
+     * одинаков для палитры, клавиш и меню, а цель существует только в момент щелчка. Поэтому
+     * «сгенерировать можно в папку, но не в файл» через `enabled` невыразимо — команда не
+     * знает, по чему щёлкнули, и в палитре этот вопрос не имеет смысла вовсе.
+     *
+     * ## Почему не `when`
+     *
+     * `when` СКРЫВАЕТ, и для «применимо не к каждой строке дерева» это чаще всего правильно:
+     * «Переименовать» на пустом месте панели — пункт не про эту цель, и его там нет. Но там,
+     * где пункт про цель ОДНОГО РОДА (создание — про каталоги), исчезновение на файле читается
+     * как пропажа возможности: человек видел «Сгенерировать» на папке, щёлкнул по файлу — и
+     * пункта нет, а почему — меню не сказало. Серый пункт говорит это сам.
+     *
+     * Предикат обязан быть чистым и дешёвым — его зовут на каждую сборку меню. Бросок означает
+     * «недоступен»: запускать действие, условие которого неизвестно, хуже, чем не запускать.
+     */
+    readonly enabledWhen?: (ctx: WhenContext, target: MenuTarget) => boolean;
+    /**
+     * Сигнал «мой ответ изменился»: подписка, по которой поверхность пересчитывает меню.
+     *
+     * Нужен вкладу, чьи `when` и `toggled` зависят от состояния, о котором поверхность
+     * не знает вовсе. Пример, ради которого поле и появилось: кнопка markdown меняет значок
+     * вместе с режимом показа, а режим живёт в плагине — меню перерисовывать не с чего,
+     * и кнопка оставалась прежней, хотя документ уже показан иначе.
+     *
+     * Это ровно то же решение, что у вклада декорации ресурса (`./decorations`), и по той же
+     * причине: контекст применимости отвечает на вопрос «что происходит в приложении», а не
+     * «что происходит внутри плагина», и класть туда чужое состояние значило бы вносить
+     * предметное знание в платформу.
+     */
+    readonly onDidChange?: (cb: () => void) => Disposable;
+}
+/**
+ * То, ПО ЧЕМУ вызвали меню: строка дерева, узел канваса, вкладка. Для шапки — `undefined`.
+ *
+ * Непрозрачна для этого модуля намеренно. Меню — платформенная проекция реестра команд,
+ * и знать, что бывает строкой дерева, оно не вправе: сегодня контекстное меню открывают
+ * над ресурсом, завтра над узлом схемы, и перечислить это здесь значило бы менять модель
+ * меню на каждый новый вид поверхности. Типизированную форму цели объявляет тот, кто меню
+ * вызывает (для дерева — `./resource-menu`), и он же сужает `unknown` для своих вкладов.
+ *
+ * Отсюда и то, почему цель приходит ОТДЕЛЬНО от {@link WhenContext}: тот отвечает на вопрос
+ * «что происходит в приложении» и одинаков для палитры, клавиш и меню, а цель существует
+ * только в момент щелчка и только у контекстного вызова.
+ */
+export type MenuTarget = unknown;
+/** Пункт меню: ссылка на команду и ничего больше. */
+export interface MenuItemContribution extends MenuPlacement {
+    readonly kind: 'item';
+    /** Идентификатор команды. Нет такой команды — пункта не будет. */
+    readonly command: string;
+    /** Аргументы команды. Уходят в `execute` как есть. */
+    readonly args?: unknown;
+    /**
+     * Аргументы, вычисляемые по цели щелчка. Заданы — {@link MenuItemContribution.args}
+     * не используется вовсе.
+     *
+     * Отдельным полем, а не «`args` может быть функцией»: аргументы команды — произвольное
+     * значение, и различать «функция как аргумент» от «функция, считающая аргумент» по типу
+     * означало бы запретить первое молча.
+     */
+    readonly argsOf?: (target: MenuTarget) => unknown;
+    /**
+     * Ключ заголовка, если он должен отличаться от заголовка команды. Разрешается словарём
+     * того, кто внёс ПУНКТ, — в отличие от заголовка команды, который принадлежит её владельцу.
+     *
+     * По умолчанию отсутствует, и берётся заголовок команды: одно действие — одно имя
+     * в палитре, в меню и у ассистента.
+     */
+    readonly titleKey?: string;
+    /**
+     * Состояние переключателя: галочка или точка радио. Отсутствие означает обычный пункт.
+     *
+     * Предикат, а не значение: состояние вычисляется на том же контексте, что и видимость,
+     * и держать его копию рядом означало бы иметь два ответа на один вопрос.
+     */
+    readonly toggled?: (ctx: WhenContext, target: MenuTarget) => boolean;
+    /**
+     * Значок — для поверхностей, где пункт рисуется КНОПКОЙ, а не строкой списка
+     * (`editor/title`). В списке он не показывается: ряд подписей со значками у одних
+     * пунктов и без значков у других читается хуже, чем ряд одних подписей.
+     *
+     * Отсутствие значка на кнопочной поверхности — не ошибка: такой пункт уходит под «…»,
+     * где у него есть место для подписи.
+     */
+    readonly icon?: ComponentType;
+}
+/**
+ * Подменю: заголовок в одном месте, содержимое — по собственному адресу.
+ *
+ * `submenu` — это путь, по которому в него вносят пункты. Заводит его тот, кто вносит
+ * заголовок, но наполнять может кто угодно: адрес и есть точка расширения.
+ */
+export interface MenuSubmenuContribution extends MenuPlacement {
+    readonly kind: 'submenu';
+    /** Адрес содержимого, например `file/recent`. */
+    readonly submenu: MenuPath;
+    /** Ключ заголовка в словаре внёсшего. */
+    readonly titleKey: string;
+}
+/**
+ * Группа пунктов, состав которой известен только в рантайме: открытые панели, недавние
+ * проекты, шаблоны форм.
+ *
+ * Функция, а не список, потому что перечислить это заранее нельзя; зовётся при каждом
+ * пересчёте меню и обязана быть чистой и дешёвой — та же дисциплина, что у `when` панели.
+ */
+export interface MenuDynamicContribution extends MenuPlacement {
+    readonly kind: 'dynamic';
+    readonly items: (ctx: WhenContext, target: MenuTarget) => readonly MenuDynamicItem[];
+}
+/** Пункт динамической группы. Готовая строка вместо ключа — имена файлов не переводятся. */
+export interface MenuDynamicItem {
+    /** Уникален в пределах группы: служит React-ключом. */
+    readonly id: string;
+    readonly command: string;
+    readonly args?: unknown;
+    /** Готовый заголовок. Указан вместе с `titleKey` — выигрывает он. */
+    readonly title?: string;
+    /** Ключ заголовка в словаре внёсшего группу. */
+    readonly titleKey?: string;
+    /** Галочка. Значение, а не предикат: контекст группе уже дали. */
+    readonly toggled?: boolean;
+}
+/**
+ * Собственное корневое меню плагина.
+ *
+ * Встать перед «Файлом» или после «Справки» оно не может — см. {@link sortMenuRoots}: порядок
+ * корней держится зонами, а не сквозным числом, потому что числа со временем нарушают все.
+ */
+export interface MenuRootContribution {
+    readonly kind: 'root';
+    /** Путь корня, по которому в него вносят пункты. Совпадение с корнем Host — отказ. */
+    readonly id: MenuPath;
+    readonly titleKey: string;
+    /** Порядок среди корней ПЛАГИНОВ. Без значения берётся `order` вклада. */
+    readonly order?: number;
+}
+/** Всё, что можно внести в точку расширения меню. */
+export type MenuContribution = MenuItemContribution | MenuSubmenuContribution | MenuDynamicContribution | MenuRootContribution;
+/**
+ * Точка расширения меню.
+ *
+ * Заполняется вкладами плагинов. Проекции платформенных реестров (список панелей, справка)
+ * вкладами НЕ являются — они приходят в {@link MenuBuildOptions.entries} от самой оболочки
+ * через {@link hostMenuEntry}: у корневого реестра метода `contribute` нет вовсе, и «вклад,
+ * внесённый Host» невыразим по построению.
+ *
+ * Недавние проекты сюда не относятся, хотя список тоже платформенный: подменю `file/recent`
+ * вносит плагин файлов — тем же порядком, что и «Открыть папку…». Решение «показать проекты
+ * в «Файле» и открывать их вот этой командой» предметное, а данные и глагол «открыть
+ * по записи» плагин получает портом.
+ */
+export declare const MenuPoint: import('../../internal.js').ExtensionPoint<MenuContribution>;
+export {};

package/dist/ui/menu/palette.d.ts

@@ -0,0 +1,36 @@
+import { WhenContext } from '../../primitives/when-context.js';
+/**
+ * Пункт палитры.
+ *
+ * `titleKey` **либо** `title`: первое — для того, что переводится, второе — для динамических
+ * данных. Указаны оба — выигрывает `title`: готовая строка уже содержит то, что человек
+ * ожидает увидеть, а ключ рядом с ней означает, что вносящий не решил, и молча предпочесть
+ * перевод значило бы показать не тот текст.
+ */
+export interface PaletteItem {
+    /** Уникален в пределах палитры. Служит React-ключом и адресом при слиянии. */
+    readonly id: string;
+    /** Ключ i18n — либо он… */
+    readonly titleKey?: string;
+    /** …либо готовая строка для динамических данных (имя файла). */
+    readonly title?: string;
+    /** Пояснение справа: путь, раздел, сочетание клавиш. Участвует в поиске. */
+    readonly detail?: string;
+    readonly run: () => unknown | Promise<unknown>;
+    /** Меньше — выше. По умолчанию `0`. */
+    readonly order?: number;
+}
+/**
+ * Поставщик динамических пунктов.
+ *
+ * `provide` получает запрос и контекст и вправе отвечать асинхронно. Отмены в сигнатуре нет
+ * намеренно: поставщик не обязан уметь прерываться, а устаревший ответ отбрасывает вызывающий
+ * (см. {@link createPaletteQueryRunner}). Требовать `AbortSignal` от каждого поставщика значило
+ * бы усложнить простой случай ради того, что и так решается на стороне палитры.
+ */
+export interface PaletteItemProvider {
+    readonly id: string;
+    provide(query: string, ctx: WhenContext): PaletteItem[] | Promise<PaletteItem[]>;
+}
+/** Точка расширения динамических пунктов палитры. */
+export declare const PaletteItemsPoint: import('../../internal.js').ExtensionPoint<PaletteItemProvider>;

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

@@ -0,0 +1,45 @@
+import { ResourceId, ResourceRef } from '../../primitives/resource.js';
+import { WhenContext } from '../../primitives/when-context.js';
+import { ContextMenuId, MenuTarget } from './menu.js';
+/** Адрес контекстного меню дерева: в него вносят пункты те, кому есть что предложить. */
+export declare const RESOURCE_CONTEXT_MENU: ContextMenuId;
+/** По чему щёлкнули в дереве. */
+export interface ResourceMenuTarget {
+    /**
+     * Строка, по которой щёлкнули. `null` — щелчок по пустому месту панели, и это законный
+     * случай: «Новый файл…» там осмысленен, «Переименовать» — нет.
+     */
+    readonly ref: ResourceRef | null;
+    /** Каталог, ВНУТРЬ которого действуют пункты создания. Считается по правилу модуля. */
+    readonly dir: ResourceId;
+    /**
+     * К чему пункт применится: набор, если щёлкнули по его строке, иначе одна строка.
+     * Считает дерево (`actionTargets` в `./resource-tree`) — это его состояние, а не меню.
+     */
+    readonly selection: readonly ResourceRef[];
+    /** Корень показа: им вклад отличает «щёлкнули по проекту» от «щёлкнули по файлу». */
+    readonly rootId: ResourceId;
+}
+/**
+ * Сужает непрозрачную цель модели меню до цели дерева; `null` — меню открыли не над деревом.
+ *
+ * Проверка структурная, а не `instanceof`: цель проходит через модель меню как `unknown`,
+ * и вклад плагина обязан уметь получить `null`, если его пункт по ошибке внесли в чужое меню.
+ */
+export declare function asResourceTarget(target: MenuTarget): ResourceMenuTarget | null;
+/**
+ * Предикат видимости пункта по цели щелчка.
+ *
+ * Обёртка ради одного: без неё каждый вклад начинался бы с приведения `unknown` и проверки
+ * на `null`, то есть с трёх строк, которые все напишут по-разному.
+ */
+export declare function whenResource(predicate: (target: ResourceMenuTarget, ctx: WhenContext) => boolean): (ctx: WhenContext, target: MenuTarget) => boolean;
+/**
+ * Аргументы команды по цели щелчка.
+ *
+ * `undefined` для чужой цели — команда получит его вместо адресов и откажется сама, что
+ * честнее выдуманного аргумента.
+ */
+export declare function argsOfResource<T>(compute: (target: ResourceMenuTarget) => T): (target: MenuTarget) => T | undefined;
+/** Адреса выделенных ресурсов — самая частая форма аргументов команд дерева. */
+export declare function selectedIds(target: ResourceMenuTarget): readonly ResourceId[];

package/dist/ui/slots.d.ts

@@ -0,0 +1,113 @@
+import { ComponentType } from 'react';
+import { WhenContext } from '../primitives/when-context.js';
+/**
+ * Область оболочки, в которую можно внести панель.
+ *
+ * - `rail.left` — вертикальные вкладки слева: переключатель левой панели и мелкие кнопки;
+ * - `panel.left` / `panel.right` / `panel.bottom` — доки вокруг центра;
+ * - `toolbar` / `statusbar` — горизонтальные полосы сверху и снизу;
+ * - `editor.main` — центр.
+ *
+ * Вкладки документов Host держит сам: вкладка — это открытый ресурс, а открытые ресурсы
+ * принадлежат Workspace, поэтому слота под них нет.
+ */
+export type SlotId = 'rail.left' | 'panel.left' | 'panel.right' | 'panel.bottom' | 'toolbar' | 'statusbar' | 'editor.main';
+/** Все слоты в порядке обхода. Нужен диагностике и тестам, а не раскладке. */
+export declare const SLOT_IDS: readonly SlotId[];
+/** Проверка непрозрачной строки (настройки, диагностика) на принадлежность набору слотов. */
+export declare function isSlotId(value: unknown): value is SlotId;
+/**
+ * Панель — единица содержимого слота.
+ *
+ * `titleKey`, а не готовая строка: панель регистрируется один раз при активации плагина,
+ * а локаль меняется потом, и переведённый в момент регистрации заголовок остался бы
+ * на языке, который был активен тогда. Ключ разрешается в пространстве имён внёсшего
+ * плагина — см. panelTitle в ./panels.
+ */
+export interface PanelContribution {
+    /**
+     * Идентификатор панели. Приходит в `Body` как `panelId` и служит адресом в настройках
+     * (какая вкладка дока активна).
+     *
+     * Уникальность в пределах точки расширения им **не** гарантируется: реестр проверяет
+     * только явный `meta.id` вклада. Поэтому React-ключом служит идентификатор вклада,
+     * а не этот.
+     */
+    readonly id: string;
+    readonly slot: SlotId;
+    /** Ключ i18n заголовка — в пространстве имён плагина, внёсшего панель. */
+    readonly titleKey: string;
+    /** Значок для рейла и шапки дока. Без него рейл покажет первые буквы заголовка. */
+    readonly icon?: ComponentType;
+    readonly Body: ComponentType<{
+        panelId: string;
+    }>;
+    /**
+     * Показывать ли панель сейчас. Отсутствие предиката означает «всегда».
+     *
+     * Предикат обязан быть чистым и быстрым: он вычисляется на каждое изменение
+     * {@link WhenContext} для каждой панели каждого слота.
+     */
+    readonly when?: (ctx: WhenContext) => boolean;
+    /**
+     * Порядок внутри слота; меньше — раньше. Без значения берётся `order` вклада.
+     *
+     * Два источника порядка — не дублирование: `order` вклада принадлежит регистрации
+     * (им плагин расставляет свои вклады между собой), а этот — самой панели, и он
+     * переживает перерегистрацию.
+     */
+    readonly order?: number;
+    /**
+     * Где стоит вкладка панели на рейле: в основной группе или прижатой к низу.
+     *
+     * Не то же, что {@link PanelContribution.order}. Порядок расставляет панели ВНУТРИ
+     * группы; эта пара говорит, к какому краю рейла панель принадлежит. Выразить прижатие
+     * к низу через большой порядок нельзя: «последняя в списке» и «у нижнего края»
+     * совпадают только пока рейл заполнен целиком.
+     *
+     * Нижняя группа — для того, что человек зовёт, а не просматривает: помощь, ассистент,
+     * настройки. Их место на краю постоянно, поэтому рука находит их не глядя, сколько бы
+     * панелей ни добавили сверху.
+     */
+    readonly railPlacement?: 'top' | 'bottom';
+    /**
+     * Значок на вкладке панели: число находок, точка «есть новое» и подобное.
+     *
+     * КОМПОНЕНТ, а не число: панель сама знает, на что подписаться и как часто это меняется,
+     * а оболочка не должна ни того ни другого. Верни он число — оболочке пришлось бы
+     * перевычислять его на каждый свой кадр либо завести отдельный канал уведомлений
+     * ради одной цифры.
+     *
+     * Значок — единственное, что видно у панели в свёрнутом доке, и ради него свёрнутое
+     * состояние и существует: полоса вкладок остаётся, чтобы ошибку было видно, не разворачивая.
+     */
+    readonly Badge?: ComponentType<{
+        panelId: string;
+    }>;
+    /**
+     * Действия панели — то, что стоит в шапке дока справа от заголовка.
+     *
+     * КОМПОНЕНТ по той же причине, что {@link PanelContribution.Badge}: доступность действия
+     * зависит от состояния, которое знает панель («перечитать» имеет смысл всегда, «сохранить»
+     * — только когда есть что), а оболочка ни этого состояния, ни поводов перерисоваться
+     * не имеет.
+     *
+     * Почему не в теле панели: кнопка, стоящая первой строкой содержимого, уезжает вместе
+     * с ним при прокрутке и занимает высоту у списка — а шапка дока уже нарисована и пуста
+     * справа. Тело панели — про содержимое; постоянные действия над ним — про шапку.
+     *
+     * Рисуется только там, где шапка есть, — в левом и правом доках. У нижнего её нет вовсе:
+     * его роль играет полоса вкладок.
+     */
+    readonly Actions?: ComponentType<{
+        panelId: string;
+    }>;
+}
+/**
+ * Точка расширения панелей.
+ *
+ * Заполняется только через `PluginContext.extensions`: у корневого реестра метода
+ * `contribute` нет вовсе, поэтому «панель, внесённая самим Host» невыразима, и вопрос
+ * «откуда здесь эта панель» всегда имеет ответ.
+ */
+export declare const PanelPoint: import('../internal.js').ExtensionPoint<PanelContribution>;

package/dist/ui/useActiveDocument.d.ts

@@ -0,0 +1,5 @@
+import { ResourceId } from '../primitives/resource.js';
+import { DocumentsService } from '../services/documents.js';
+/** Служба документов в объёме хука: снимок и уведомление. */
+export type ActiveDocumentSource = Pick<DocumentsService, 'activeResource' | 'onDidChange'>;
+export declare function useActiveDocument(documents: ActiveDocumentSource): ResourceId | null;

package/dist/ui/useLocale.d.ts

@@ -0,0 +1,9 @@
+import { PluginI18n } from '../services/i18n.js';
+/**
+ * Текущая локаль — как повод перерисоваться, а не как значение.
+ *
+ * `t()` читается прямо из сервиса, но результат меняется при смене локали, а сервис
+ * не является React-состоянием. Этот хук и есть недостающая связь: он ничего не переводит,
+ * он делает перевод реактивным.
+ */
+export declare function useLocale(i18n: Pick<PluginI18n, 'locale' | 'onDidChangeLocale'>): string;

package/dist/ui/useTranslate.d.ts

@@ -0,0 +1,4 @@
+import { PluginI18n } from '../services/i18n.js';
+/** Перевод: ключ и параметры сообщения. Совпадает по форме с `PluginI18n.t`. */
+export type Translate = (key: string, params?: Record<string, unknown>) => string;
+export declare function useTranslate(i18n: Pick<PluginI18n, 'locale' | 't' | 'onDidChangeLocale'>): Translate;

package/dist/workspace/document.d.ts

@@ -0,0 +1,42 @@
+import { Disposable } from '../primitives/disposable.js';
+import { ResourceId, ResourceRef } from '../primitives/resource.js';
+/**
+ * Вид документа — дискриминант союза `TextDocument | ModelDocument`.
+ *
+ * Он объявлен ЗДЕСЬ, а не в `model/`, потому что документ без провайдера модели должен
+ * оставаться текстовым, ничем себя для этого не оборачивая: «остаётся текстовым» —
+ * это и есть определение `TextDocument`, и обёртка вокруг него означала бы две ссылки
+ * на один документ, из которых свежая только одна.
+ *
+ * Сам буфер о видах не знает: фабрика документа в оболочке всегда делает `'text'`, а `'model'`
+ * появляется у документа, которому провайдер модели дал вторую истину (`model/model-document.ts`).
+ */
+export type DocumentKind = 'text' | 'model';
+/** Открытый ресурс: вкладка. Живёт, пока открыт, — в отличие от ресурса, который живёт в источнике. */
+export interface Document {
+    /**
+     * Различает два вида документа. Поле, а не метод: оно не меняется за жизнь документа,
+     * и сужение союза обязано работать без вызова.
+     */
+    readonly kind: DocumentKind;
+    readonly id: ResourceId;
+    /** Ссылка на ресурс: путь, вид, медиатип. Стабильна на всё время жизни документа. */
+    readonly ref: ResourceRef;
+    /**
+     * Текущий текст буфера — то, что уйдёт в файл при сохранении.
+     *
+     * Метод, а не поле: буфер меняется, а `useSyncExternalStore` подписывается на
+     * {@link Document.onDidChangeContent} и читает снимок — поле заставило бы держать
+     * ссылку на документ и следить за мутацией самому.
+     */
+    getText(): string;
+    /** Расходится ли буфер с BASE — тем, что отдал источник. */
+    isDirty(): boolean;
+    /**
+     * Буфер сменился: правкой через Workspace, откатом или слиянием.
+     *
+     * Обработчик обязан быть дешёвым: уведомление синхронно относительно смены буфера,
+     * и тяжёлую работу (разбор, валидацию, перерисовку) планирует себе сам подписчик.
+     */
+    onDidChangeContent(cb: (text: string) => void): Disposable;
+}

package/dist/workspace/model/editor-view-states.d.ts

@@ -0,0 +1,29 @@
+import { Capability } from '../../primitives/capability.js';
+import { ResourceId } from '../../primitives/resource.js';
+/** Вид хранилища для ОДНОГО редактора: ровно то, чем пользуется его тело. */
+export interface EditorViewStateSlice {
+    /** Запоминает снимок. Повторная запись того же значения — дело вызывающего. */
+    record(id: ResourceId, state: unknown): void;
+    /** Последний записанный снимок или `undefined`. Разбирает его читающий. */
+    peek(id: ResourceId): unknown;
+    /** Забывает снимок этого документа у ЭТОГО редактора. */
+    forget(id: ResourceId): void;
+}
+export interface EditorViewStates {
+    /**
+     * Вид на хранилище от лица редактора `editorId`.
+     *
+     * `editorId` — идентификатор ВКЛАДА редактора (`EditorContribution.id`), а не плагина:
+     * плагин вправе внести два редактора, и снимки у них разные.
+     */
+    forEditor(editorId: string): EditorViewStateSlice;
+}
+/**
+ * Возможность «снимки вида редакторов».
+ *
+ * Провайдер — оболочка (`services/host-capabilities`), а не редактор: хранилище делят
+ * ВСЕ редакторы, и принадлежать оно не может ни одному из них. Версия `1.0.0` — исходная.
+ */
+export declare const EditorViewStatesCapability: Capability<EditorViewStates>;
+/** Токен службы — ТОТ ЖЕ объект: возможность расширяет токен, второго реестра нет. */
+export declare const EditorViewStatesToken: Capability<EditorViewStates>;

package/dist/workspace/model/model-document.d.ts

@@ -0,0 +1,86 @@
+import { Disposable } from '../../primitives/disposable.js';
+import { Document } from '../document.js';
+import { ApplyResult, EditOp, NodeId } from './provider.js';
+/** Согласован ли буфер с моделью. `diverged` — буфер не разбирается, модель прежняя. */
+export type DocumentSyncState = 'synced' | 'diverged';
+/** Отказ разбора: чей и почему. */
+export interface ParseFailure {
+    readonly providerId: string;
+    /** Сообщение провайдера: годится для диагностики и для лога, не для интерфейса. */
+    readonly message: string;
+    /** Исходная ошибка: у разбора с позициями в ней лежит смещение. */
+    readonly error?: unknown;
+}
+/** Что вызвало смену состояния модельного документа. */
+export type ModelChangeReason = 'apply' | 'parse' | 'undo' | 'redo' | 'selection';
+export interface ModelChange<M> {
+    readonly model: M;
+    readonly selection: readonly NodeId[];
+    readonly syncState: DocumentSyncState;
+    readonly reason: ModelChangeReason;
+}
+/**
+ * Документ с моделью. Наследует `Document` целиком: для текстового редактора модельный документ
+ * ничем не отличается от обычного, и это осознанно.
+ */
+export interface ModelDocument<M = unknown> extends Document {
+    readonly kind: 'model';
+    /** Чей разбор. По нему плагин стека узнаёт СВОЙ документ и сужает модель. */
+    readonly providerId: string;
+    /** Последняя валидная модель. В расхождении — та, что была до поломки буфера. */
+    getModel(): M;
+    getSyncState(): DocumentSyncState;
+    /** `undefined`, когда согласовано. */
+    getParseFailure(): ParseFailure | undefined;
+    /** Выделение — часть модели правки: операция переносит его на `focus`, оно входит в снимок отмены. */
+    getSelection(): readonly NodeId[];
+    /** Ложь в расхождении: структурные редакторы там только на чтение. */
+    isStructurallyEditable(): boolean;
+    onDidChangeModel(cb: (change: ModelChange<M>) => void): Disposable;
+}
+/** Отказ применить операцию. Не исключение: оба случая — нормальные состояния, а не аварии. */
+export type ApplyRejection = 
+/** Буфер не разбирается: правка модели затёрла бы работу пользователя при перерисовке. */
+{
+    readonly status: 'rejected';
+    readonly reason: 'diverged';
+    readonly failure: ParseFailure;
+}
+/** Провайдер не смог применить операцию: неизвестный тип, исчезнувшая цель, битые параметры. */
+ | {
+    readonly status: 'rejected';
+    readonly reason: 'provider-error';
+    readonly error: unknown;
+};
+export type ApplyOutcome<M> = ({
+    readonly status: 'applied';
+} & ApplyResult<M>) | ApplyRejection;
+export interface ApplyOptions {
+    /** Ключ схлопывания в истории, обычно `свойство@узел`. */
+    readonly mergeKey?: string;
+}
+/**
+ * Ручки управления модельным документом — пишущее лицо.
+ *
+ * Разведено с {@link ModelDocument} так же, как документ и его владелец: читать может любой,
+ * а править — только через ручку, мимо истории и перерисовки буфера не пройти. Времени жизни
+ * здесь нет (`dispose`): ручкой владеет тот, кто открыл документ, то есть оболочка.
+ */
+export interface ModelDocumentHandle<M> {
+    readonly document: ModelDocument<M>;
+    /** Применяет операцию: история, перенос выделения на `focus`, перерисовка буфера. */
+    apply(op: EditOp, options?: ApplyOptions): ApplyOutcome<M>;
+    setSelection(selection: readonly NodeId[]): void;
+    /** `false`, если отменять нечего или документ в расхождении. */
+    undo(): boolean;
+    redo(): boolean;
+    /** Ответит ли {@link undo} согласием; расхождение учтено здесь же. */
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /** Явная граница схлопывания: конец хода ассистента, уход фокуса с поля. */
+    breakUndoMerge(): void;
+    /** Выполняет отложенную перерисовку буфера и дожидается записи. */
+    flush(): Promise<void>;
+    /** Ждёт ли документ перерисовки буфера, отложенной из-за фокуса. */
+    hasPendingSync(): boolean;
+}