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

package/dist/services/preview.d.ts

@@ -0,0 +1,163 @@
+import { Capability } from '../primitives/capability.js';
+import { Disposable } from '../primitives/disposable.js';
+import { ExtensionPoint } from '../primitives/extension-point.js';
+import { ResourceId } from '../primitives/resource.js';
+import { TextRange } from './diagnostics/types.js';
+import { NodeId } from '../workspace/model/provider.js';
+import { DocumentRef } from './validation/types.js';
+/**
+ * Что поверхность умеет. Каждый признак отвечает на вопрос, который обязаны задать ДО
+ * монтирования: правило выбора ранжирует по ним поверхности и сверяет их с правами источника.
+ */
+export interface PreviewCapabilities {
+    /** Можно ли трогать форму: вводить значения, нажимать кнопки. */
+    readonly interactive: boolean;
+    /** Выбор узла кликом. */
+    readonly hitTest: boolean;
+    /** Принимает ли дроп с палитры. */
+    readonly dragSource: boolean;
+    /** Исполняет ли код документа. Только по этому признаку работает запрет по источнику. */
+    readonly executesCode: boolean;
+    /** Тот же realm, что у оболочки. Исполняющая поверхность обязана отвечать `true`. */
+    readonly sameRealm: boolean;
+}
+/** На чём споткнулись. */
+export type PreviewProblemPhase = 
+/** Документ не разобрался в схему формы. */
+'schema'
+/** Импорт не привязался. */
+ | 'resolve'
+/** Движок транспиляции отказался. */
+ | 'transpile'
+/** Модуль исполнился и бросил. */
+ | 'evaluate'
+/** Сборка формы или отрисовка. */
+ | 'render';
+/**
+ * Сбой превью — данные, а не исключение.
+ *
+ * `resource` и `range` — адрес для службы диагностик: по ним находка становится подчёркиванием
+ * в редакторе того файла, где чинить. Оба необязательны: сбой без файла относится к документу.
+ */
+export interface PreviewProblem {
+    readonly file: string;
+    readonly phase: PreviewProblemPhase;
+    readonly message: string;
+    readonly resource?: ResourceId;
+    readonly range?: TextRange;
+}
+/** Значения модели формы. Форма приходит из схемы, и сузить её нечем. */
+export type PreviewValues = Record<string, unknown>;
+/** Мок-данные формы: значения модели и значения источников. Авторский артефакт. */
+export interface PreviewMock {
+    readonly model: Record<string, unknown>;
+    readonly dataSources: Record<string, unknown>;
+}
+/**
+ * Собранная форма в объёме, нужном наблюдателю (панели модели): модель и реестр. Шире — значит
+ * дать наблюдателю пересобирать форму, а этим занята поверхность.
+ */
+export interface PreviewFormHandle {
+    readonly model: unknown;
+    readonly registry?: unknown;
+}
+/**
+ * Что поверхность получает на монтирование.
+ *
+ * Схема — метод, а не поле: документ правят, пока превью открыто, и поверхность обязана читать
+ * то, что есть СЕЙЧАС. `null` — документ не разобрался; это законное состояние, а не ошибка.
+ */
+export interface PreviewContext {
+    readonly doc: DocumentRef;
+    /**
+     * Модель документа, как её разобрал провайдер (`doc.providerId`), либо `null`. Ссылка
+     * стабильна, пока документ не менялся. Форму знает поверхность и сужает её сама.
+     */
+    schema(): unknown;
+    onDidChangeSchema(cb: () => void): Disposable;
+    /** Выделенные узлы — те же адреса, которыми оперирует редактор документа. */
+    selection(): readonly NodeId[];
+    onDidChangeSelection(cb: () => void): Disposable;
+    /** Обратная связь хит-теста: поверхность сообщает, куда ткнули. */
+    select(ids: readonly NodeId[]): void;
+    /** Мок-данные или `null`, если автор их не задавал (тогда поверхность синтезирует свои). */
+    mock(): PreviewMock | null;
+    /** Что человек успел ввести в прежнюю сборку этой формы; `undefined` — не начинали. */
+    values(): PreviewValues | undefined;
+    /**
+     * Отдать значения на хранение: перед пересборкой формы и при размонтировании. Не позовёт
+     * поверхность — потеряет набранное человеком, и никто, кроме него, этого не заметит.
+     */
+    keepValues(values: PreviewValues): void;
+    /** Отдать собранную форму наблюдателям; `null` — формы сейчас нет. Необязателен. */
+    publishForm?(form: PreviewFormHandle | null): void;
+    /** Куда уходят находки сборки. Список от одного `source` ЗАМЕЩАЕТСЯ целиком. */
+    report(source: string, problems: readonly PreviewProblem[]): void;
+}
+/** Поверхность превью — вклад в точку {@link PreviewSurfacePoint}. */
+export interface PreviewSurface {
+    /** Уникален среди поверхностей: он же имя источника диагностик. */
+    readonly id: string;
+    /**
+     * Берётся ли поверхность за такой документ. Синхронная и дешёвая, решает по адресу, виду
+     * и провайдеру модели — содержимого здесь нет, выбор не должен стоить разбора текста.
+     */
+    applies(doc: DocumentRef): boolean;
+    readonly capabilities: PreviewCapabilities;
+    mount(host: HTMLElement, ctx: PreviewContext): Disposable;
+    /**
+     * Имя для человека, УЖЕ переведённое. Функция, а не ключ: словарь принадлежит внёсшему
+     * плагину, а спрашивает имя чужой (живой вид редактора). Нет — показывают `id`.
+     */
+    title?(): string;
+}
+/** Точка расширения поверхностей превью. Заполняется только вкладами. */
+export declare const PreviewSurfacePoint: ExtensionPoint<PreviewSurface>;
+/**
+ * Что живой вид даёт поверхности: схему из МОДЕЛИ редактора (буфер перерисовывается с задержкой,
+ * пока печатают), выделение и обратную связь хит-теста. Остальное достраивает провайдер.
+ */
+export interface LiveSurfaceContext {
+    /** Разобранная модель документа; `null` — не разбирается. Ссылка обязана быть стабильной. */
+    schema(): unknown;
+    onDidChangeSchema(cb: () => void): Disposable;
+    selection(): readonly NodeId[];
+    onDidChangeSelection(cb: () => void): Disposable;
+    select(ids: readonly NodeId[]): void;
+}
+/** Чем нарисован документ — в объёме, которым живой вид принимает решения. */
+export interface LiveSurfaceInfo {
+    readonly id: string;
+    /** Уже переведённое имя. */
+    readonly title: string;
+    readonly hitTest: boolean;
+    readonly sameRealm: boolean;
+    readonly executesCode: boolean;
+    /** Уже переведённая причина, по которой выбрана не самая способная поверхность. */
+    readonly notice: string | null;
+}
+/**
+ * Живой вид: выбрать поверхность для документа по общему правилу и смонтировать её.
+ *
+ * Одно правило на всех, кто показывает документ, — поэтому «чем нарисована эта форма» имеет
+ * один ответ, где бы её ни показывали, а введённые значения и находки не раздваиваются.
+ */
+export interface PreviewLiveService {
+    /** Есть ли кому рисовать вовсе. */
+    available(): boolean;
+    /** Чем будет нарисован документ; `null` — показывать нечем. */
+    chosen(documentId: ResourceId): LiveSurfaceInfo | null;
+    /** Смонтировать поверхность в элемент; `null` — не за что было взяться. */
+    mount(documentId: ResourceId, element: HTMLElement, ctx: LiveSurfaceContext): Disposable | null;
+    /** Состав поверхностей для этого документа изменился. */
+    onDidChange(documentId: ResourceId, cb: () => void): Disposable;
+    /** Форма, которую опубликовала смонтированная поверхность; `null` — формы нет. */
+    formOf(documentId: ResourceId): PreviewFormHandle | null;
+    /** Опубликованная форма документа сменилась. */
+    onDidChangeForm(documentId: ResourceId, cb: () => void): Disposable;
+}
+/**
+ * Живой вид превью. Провайдер — плагин превью (`reformer.preview`), потребители — редакторы
+ * любых стеков. Необязателен у каждого потребителя: превью выключаемо.
+ */
+export declare const PreviewLiveCapability: Capability<PreviewLiveService>;

package/dist/services/prompt.d.ts

@@ -0,0 +1,111 @@
+import { Disposable } from '../primitives/disposable.js';
+/** Проверка введённого значения: ключ сообщения об ошибке или `null`, если всё хорошо. */
+export type PromptValidator = (value: string) => string | null;
+/** Общая часть запроса: заголовок и необязательное пояснение — ключами i18n. */
+export interface PromptRequestBase {
+    /** Ключ i18n заголовка. */
+    readonly titleKey: string;
+    /** Ключ i18n пояснения под заголовком. */
+    readonly descriptionKey?: string;
+    /** Параметры подстановки для заголовка и пояснения (имя файла, число записей). */
+    readonly params?: Readonly<Record<string, unknown>>;
+    /**
+     * Чей это словарь. Тот же приём, что у заголовков команд в палитре: ключ сам по себе
+     * не говорит, где его искать, и без владельца запрос плагина показывал бы маркер промаха.
+     */
+    readonly pluginId?: string;
+}
+/** Запрос строки. */
+export interface PromptInputRequest extends PromptRequestBase {
+    readonly kind: 'input';
+    /** Начальное значение поля. */
+    readonly value?: string;
+    /** Ключ i18n подписи поля — для скринридера и для метки над полем. */
+    readonly labelKey?: string;
+    /** Ключ i18n подписи кнопки подтверждения; без него оболочка возьмёт свою. */
+    readonly confirmKey?: string;
+    /** Ключ i18n подписи кнопки отмены; без него оболочка возьмёт свою. */
+    readonly cancelKey?: string;
+    /**
+     * Что выделить при открытии.
+     *
+     * `stem` — имя без расширения: переименовывая `schema.json`, человек меняет `schema`,
+     * и выделять точку с расширением значило бы заставлять его каждый раз их дописывать.
+     */
+    readonly select?: 'all' | 'stem';
+    readonly validate?: PromptValidator;
+}
+/** Запрос подтверждения. */
+export interface PromptConfirmRequest extends PromptRequestBase {
+    readonly kind: 'confirm';
+    readonly confirmKey?: string;
+    readonly cancelKey?: string;
+    /** Опасное действие: оболочка покажет подтверждение красным. */
+    readonly tone?: 'default' | 'danger';
+}
+/** Пункт выбора из списка. */
+export interface PromptPickItem {
+    /** Уникален в пределах запроса; его и возвращает {@link PromptService.pick}. */
+    readonly id: string;
+    /** Готовая строка: пункты — данные, а не сообщения. */
+    readonly label: string;
+    /** Пояснение справа: дата, раздел. Участвует в поиске — как пояснение пункта палитры. */
+    readonly description?: string;
+}
+/** Выбор из списка. */
+export interface PromptPickRequest extends PromptRequestBase {
+    readonly kind: 'pick';
+    /**
+     * Пункты в порядке показа. Порядок — решение спрашивающего (у недавних это свежесть):
+     * поиск его не пересчитывает, пока пункты совпадают с запросом одинаково.
+     */
+    readonly items: readonly PromptPickItem[];
+    /** Ключ i18n подсказки в поле поиска. */
+    readonly placeholderKey?: string;
+    /** Ключ i18n текста для пустого списка; без него оболочка возьмёт свой. */
+    readonly emptyKey?: string;
+    /**
+     * Кнопка «убрать» на каждом пункте — «Remove from Recently Opened» из VS Code.
+     *
+     * Зовёт её оболочка, и окно при этом остаётся открытым: человек чистит список, а не выбирает.
+     * Пункт исчезает сразу, не дожидаясь `run`: ответ хранилища ничего не меняет в том, что
+     * человек уже увидел. Отказ `run` уходит в консоль.
+     */
+    readonly remove?: {
+        /** Ключ i18n подписи кнопки — для скринридера и всплывающей подсказки. */
+        readonly labelKey: string;
+        run(id: string): void | Promise<void>;
+    };
+}
+export type PromptRequest = PromptInputRequest | PromptConfirmRequest | PromptPickRequest;
+/** Запрос, ждущий ответа: то, что оболочка сейчас рисует. */
+export type PendingPrompt = PromptRequest & {
+    /** Выдаётся службой; годится React-ключом и адресом ответа. */
+    readonly id: string;
+};
+/** Ответ на запрос: строка либо согласие; отмена — всегда `null`. */
+export type PromptAnswer = string | boolean | null;
+export interface PromptService {
+    /** Спрашивает строку. `null` — отменили. */
+    input(request: Omit<PromptInputRequest, 'kind'>): Promise<string | null>;
+    /** Спрашивает согласие. Отмена — `false`: несделанное действие и есть отказ. */
+    confirm(request: Omit<PromptConfirmRequest, 'kind'>): Promise<boolean>;
+    /** Спрашивает выбор из списка. Ответ — `id` пункта; отмена — `null`. */
+    pick(request: Omit<PromptPickRequest, 'kind'>): Promise<string | null>;
+    /**
+     * Текущий запрос или `null`. Ссылка стабильна между изменениями — условие
+     * `useSyncExternalStore`.
+     */
+    current(): PendingPrompt | null;
+    /**
+     * Отвечает на текущий запрос. Отвечает ОБОЛОЧКА, а не спрашивающий.
+     *
+     * Идентификатор обязателен: между отрисовкой и нажатием запрос мог смениться (команда
+     * отменила его, плагин выключили), и ответ «да» ушёл бы не тому вопросу.
+     */
+    resolve(id: string, answer: PromptAnswer): void;
+    /** Снимает все ожидающие запросы отменой: закрытие проекта, выключение плагина. */
+    cancelAll(): void;
+    observe(cb: () => void): Disposable;
+}
+export declare const PromptServiceToken: import('../index.js').ServiceToken<PromptService>;

package/dist/services/resource-clipboard.d.ts

@@ -0,0 +1,28 @@
+import { Disposable } from '../primitives/disposable.js';
+import { ResourceId } from '../primitives/resource.js';
+/**
+ * Что сделали с записями.
+ *
+ * Различать обязательно: копия оставляет оригинал на месте, перенос — нет. Сейчас вставка
+ * умеет только копирование, но вид хранится с самого начала, потому что добавить его позже
+ * означало бы, что уже написанные вклады меню знают о буфере не всё.
+ */
+export type ClipboardMode = 'copy' | 'cut';
+/** Снимок буфера. Ссылка стабильна между изменениями — условие `useSyncExternalStore`. */
+export interface ClipboardState {
+    readonly mode: ClipboardMode;
+    readonly items: readonly ResourceId[];
+}
+export interface ResourceClipboardService {
+    /** Кладёт записи в буфер, заменяя предыдущее содержимое. Пустой список очищает буфер. */
+    copy(items: readonly ResourceId[]): void;
+    /** То же, но с пометкой «вырезано»: вставка обязана перенести, а не скопировать. */
+    cut(items: readonly ResourceId[]): void;
+    clear(): void;
+    /** Содержимое буфера; пустой список — буфер пуст. */
+    get(): ClipboardState;
+    /** Сколько записей лежит в буфере. Нужен предикатам применимости — им хватает числа. */
+    size(): number;
+    observe(cb: () => void): Disposable;
+}
+export declare const ResourceClipboardServiceToken: import('../index.js').ServiceToken<ResourceClipboardService>;

package/dist/services/selection.d.ts

@@ -0,0 +1,46 @@
+import { Disposable } from '../primitives/disposable.js';
+import { ResourceId } from '../primitives/resource.js';
+import { NodeId } from '../workspace/model/provider.js';
+/**
+ * Общий канал выделения.
+ *
+ * Читающая и пишущая половины намеренно НЕ разведены (в отличие от документа и ручки правки
+ * в моделях): выделение — не правка, право выбрать узел есть у всех, кто узел показывает,
+ * и разделение здесь означало бы, что превью надо выдавать отдельную привилегию на то,
+ * что оно и так делает своим кликом.
+ */
+export interface SelectionService {
+    /**
+     * Выделение ресурса; пустой список, если никто ничего не выбирал.
+     *
+     * Между изменениями возвращает ТУ ЖЕ ссылку. Это не экономия: снимок читает
+     * `useSyncExternalStore`, который сравнивает по ссылке и падает с «The result of
+     * getSnapshot should be cached» на новом массиве при каждом вызове. Та же дисциплина,
+     * что у службы диагностик и у реестра вкладов.
+     */
+    get(resource: ResourceId): readonly NodeId[];
+    /**
+     * Записывает выделение ресурса целиком.
+     *
+     * Замещение, а не добавление: писать сюда будут стороны, каждая из которых знает своё
+     * состояние полностью, и «добавить один узел» означало бы, что снятие выделения нельзя
+     * выразить вовсе. Пустой список — законная запись со смыслом «ничего не выбрано».
+     *
+     * Совпадающее по содержимому значение НЕ порождает уведомления: обе стороны пишут сюда
+     * своё состояние на каждое движение, и эхо чужой записи обязано затухать само, иначе
+     * два подписчика, отражающих выделение друг друга, крутились бы вечно.
+     */
+    set(resource: ResourceId, ids: readonly NodeId[]): void;
+    /** Выделение ресурса изменилось. Полезная нагрузка — какого именно. */
+    onDidChange(cb: (resource: ResourceId) => void): Disposable;
+    /**
+     * Забывает выделение ресурса.
+     *
+     * Отличается от `set(resource, [])` только намерением и потому существует отдельно:
+     * пустой список — это «человек снял выделение» (о нём сообщают), а `forget` — «ресурса
+     * больше нет в работе». Уведомление он тоже шлёт: подписчик, держащий копию, обязан
+     * узнать, что копия больше ничего не отражает.
+     */
+    forget(resource: ResourceId): void;
+}
+export declare const SelectionServiceToken: import('../index.js').ServiceToken<SelectionService>;

package/dist/services/settings.d.ts

@@ -0,0 +1,44 @@
+import { Disposable } from '../primitives/disposable.js';
+/** Куда пишется значение. Читается всегда из обеих: `workspace` перекрывает `user`. */
+export type SettingsScope = 'user' | 'workspace';
+/** То, что видит плагин. */
+export interface SettingsService {
+    /**
+     * Действующее значение: `workspace` → `user` → умолчание вклада → `undefined`.
+     *
+     * Тип не проверяется в рантайме: в хранилище лежит то, что туда положили прошлые версии
+     * приложения. Потребитель, для которого чужое значение опасно, обязан его провалидировать —
+     * так делает служба темы.
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Записывает значение. Без `scope` область берётся из префикса ключа
+     * ({@link scopeForKey}); явный `scope` позволяет перекрыть глобальную настройку
+     * в рабочей области — ради этого слои и существуют.
+     *
+     * `value === undefined` снимает запись именно этой области, и значение проваливается
+     * на слой ниже. Без этого «workspace перекрывает user» было бы дверью в одну сторону:
+     * перекрыть можно, вернуться к глобальному значению нельзя.
+     *
+     * Кэш и подписчики обновляются сразу, до того как хранилище подтвердит запись, — иначе
+     * переключатель в интерфейсе ждал бы IndexedDB. Если запись отказала, кэш откатывается,
+     * подписчики уведомляются повторно, а отказ пробрасывается вызывающему.
+     */
+    set<T>(key: string, value: T, scope?: SettingsScope): Promise<void>;
+    /**
+     * Уведомление о смене **действующего** значения ключа.
+     *
+     * Запись, перекрытая более сильной областью, уведомления не вызывает: подписчик реагирует
+     * на то, что вернёт `get`, а перерисовка ради того же самого значения — просто трата кадра.
+     */
+    onDidChange(cb: (key: string) => void): Disposable;
+    /**
+     * Объявляет умолчание вклада. `dispose()` снимает его — вместе с плагином.
+     *
+     * Повторное объявление того же ключа — ошибка, а не замена: два умолчания на один ключ
+     * означают, что действующее значение зависит от порядка активации плагинов, а он ничего
+     * не значит.
+     */
+    registerDefault<T>(key: string, value: T): Disposable;
+}
+export declare const SettingsServiceToken: import('../index.js').ServiceToken<SettingsService>;

package/dist/services/theme.d.ts

@@ -0,0 +1,15 @@
+import { Disposable } from '../primitives/disposable.js';
+/** Тема, которая реально применена. Третьего состояния у оболочки нет. */
+export type ThemeKind = 'light' | 'dark';
+/** Что выбрал пользователь. `system` — «следуй за системой», а не «светлая». */
+export type ThemePreference = ThemeKind | 'system';
+export interface ThemeService {
+    /** Применённая тема: то, что сейчас на корневом элементе. */
+    readonly theme: ThemeKind;
+    /** Выбор пользователя. `system` означает «действующая тема берётся у системы». */
+    readonly preference: ThemePreference;
+    /** Записывает выбор в настройки; тема применяется сразу, не дожидаясь хранилища. */
+    setPreference(preference: ThemePreference): Promise<void>;
+    onDidChange(cb: (theme: ThemeKind) => void): Disposable;
+}
+export declare const ThemeServiceToken: import('../index.js').ServiceToken<ThemeService>;

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

@@ -0,0 +1,98 @@
+import { ResourceId, ResourceRef } from '../../primitives/resource.js';
+import { Diagnostic } from '../diagnostics/types.js';
+import { DocumentKind } from '../../workspace/document.js';
+/**
+ * То, что валидатор знает о документе, ещё ничего не прочитав.
+ *
+ * Все поля — из уже открытого документа (`Document` присваивается сюда структурно). Методов
+ * здесь нет намеренно: {@link ValidatorContribution.applies} обязан отвечать по адресу и виду,
+ * а не по содержимому — иначе выбор валидаторов стоил бы разбора текста на каждой правке,
+ * причём каждому кандидату своего.
+ */
+export interface DocumentRef {
+    readonly id: ResourceId;
+    readonly ref: ResourceRef;
+    readonly kind: DocumentKind;
+    /**
+     * Провайдер модели, который взялся за документ (`DocumentModelProvider.id`); есть только
+     * у `kind: 'model'`.
+     *
+     * Без него «чей это документ» узнавалось по медиатипу, а `.json` бывает схемой ЛЮБОГО
+     * стека: валидатор и поверхность превью одного стека брались бы за документы другого.
+     * Провайдер же отвечает на этот вопрос пробой содержимого ещё при открытии — дёшево и один
+     * раз, и здесь его ответ только читают.
+     */
+    readonly providerId?: string;
+}
+/**
+ * Что валидатору дают на проход.
+ *
+ * `text()` и `model()` — методы, а не поля: контекст переживает один проход, но проход бывает
+ * отложенным (дорогой уровень), и читать состояние надо в момент чтения, а не в момент сборки
+ * контекста.
+ */
+export interface ValidateContext {
+    readonly doc: DocumentRef;
+    /** Текст буфера — ровно то, что видит человек и что уйдёт в файл при сохранении. */
+    text(): string;
+    /**
+     * Модель документа, **согласованная с буфером**, либо `undefined`.
+     *
+     * `undefined` означает одно из трёх: документ текстовый (провайдера модели нет), буфер
+     * не разобрался (расхождение), или модель есть, но она устарела. Все три случая для
+     * валидатора одинаковы: доверять можно только тексту, и если ему нужна структура — он
+     * разбирает текст сам и сам отвечает за ошибку разбора.
+     *
+     * Отдавать УСТАРЕВШУЮ модель было бы хуже, чем не отдавать ничего: диагностика указывала бы
+     * на узлы, которых в тексте перед человеком уже нет.
+     */
+    model(): unknown;
+}
+/**
+ * Вклад валидатора.
+ *
+ * Оба метода необязательны, но хотя бы один обязан быть — вклад без обоих просто ничего
+ * не делает, и оркестратор его молча пропускает.
+ */
+export interface ValidatorContribution {
+    /**
+     * Уникален среди валидаторов: он же — имя источника в службе диагностик, по которому
+     * замещаются прошлые находки.
+     */
+    readonly id: string;
+    /** Берётся ли этот валидатор за такой документ. Синхронный и дешёвый — см. {@link DocumentRef}. */
+    applies(doc: DocumentRef): boolean;
+    /**
+     * Быстрая проверка. **СИНХРОННАЯ** — на ней стоит гейт ассистента.
+     *
+     * Возвращает полный список своих находок: не «что изменилось», а «что я вижу сейчас».
+     * Пустой массив — законный ответ «чисто», и именно он снимает исправленную ошибку.
+     */
+    validate?(ctx: ValidateContext): readonly Diagnostic[];
+    /**
+     * Дорогая проверка: запускается с задержкой, отменяется следующей правкой, результат
+     * вливается отдельным источником.
+     *
+     * Обязана уважать `signal`: оркестратор отменённый результат **отбросит**, но работу,
+     * которую валидатор продолжает делать в отменённом проходе, за него никто не остановит.
+     */
+    validateAsync?(ctx: ValidateContext, signal: AbortSignal): Promise<readonly Diagnostic[]>;
+}
+/**
+ * Точка расширения валидаторов.
+ *
+ * Заполняется только плагинами: разбор и проверка содержимого — предметное знание, и в Host
+ * оно означало бы, что второй формат придётся вносить правкой ядра.
+ */
+export declare const ValidatorPoint: import('../../internal.js').ExtensionPoint<ValidatorContribution>;
+/**
+ * Суффикс источника дорогого уровня.
+ *
+ * Видимый, а не скрытый: имя источника попадает в интерфейс и в лог, и «почему у меня два
+ * источника от одного валидатора» должно читаться из самого имени.
+ */
+export declare const ASYNC_SOURCE_SUFFIX = "#async";
+/** Имя источника быстрого уровня — сам идентификатор валидатора. */
+export declare function fastSource(validatorId: string): string;
+/** Имя источника дорогого уровня — идентификатор плюс {@link ASYNC_SOURCE_SUFFIX}. */
+export declare function asyncSource(validatorId: string): string;

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

@@ -0,0 +1,84 @@
+import { Capability } from '../primitives/capability.js';
+import { Disposable } from '../primitives/disposable.js';
+import { ResourceId, ResourceRef } from '../primitives/resource.js';
+export interface WorkspaceFilesService {
+    /**
+     * Каталог, в котором лежит ресурс. Для ресурса в корне источника — сам корень.
+     *
+     * Нужен каждому, чьё состояние принадлежит КАТАЛОГУ, а не файлу: у превью значения формы
+     * и находки сборки общие на форму и её сайдкары.
+     */
+    parentOf(id: ResourceId): ResourceId;
+    /** Адрес внутри каталога: `resolve(dir, 'validation.ts')`. Сегменты приписываются по одному. */
+    resolve(dir: ResourceId, ...segments: readonly string[]): ResourceId;
+    /**
+     * Адрес по пути ОТ КОРНЯ ИСТОЧНИКА, в котором лежит опорный ресурс.
+     *
+     * Нужен импортам и ссылкам вида `src/forms/credit`: они записаны от корня проекта,
+     * а опорой служит любой ресурс того же источника.
+     */
+    fromRoot(anchor: ResourceId, path: string): ResourceId;
+    /**
+     * Корень открытого проекта или `null`, если проекта нет.
+     *
+     * Отдельный вопрос, а не «parentOf до упора»: корень знает рабочая область, и подниматься
+     * к нему перебором значило бы гадать, где остановиться.
+     */
+    projectRoot(): ResourceId | null;
+    /**
+     * Есть ли такой ресурс. Отказ источника — это `false`, а не исключение: спрашивают об этом,
+     * чтобы не затереть чужой файл, и «не знаю» здесь хуже, чем «нет».
+     */
+    exists(id: ResourceId): Promise<boolean>;
+    /** Один уровень каталога. Отказ листинга — пустой список: «здесь ничего не нашлось». */
+    list(dir: ResourceId): Promise<readonly ResourceRef[]>;
+    /** Текст ресурса из рабочей копии; `null` — нет проекта, нет ресурса или он не читается текстом. */
+    readText(id: ResourceId): Promise<string | null>;
+    /**
+     * Примет ли ИСТОЧНИК этого ресурса запись. Без проекта — `false`.
+     *
+     * Не то же, что «есть ли право у плагина»: право одно на всех и выражено самой дверью
+     * записи. Это вопрос к источнику — каталог мог быть открыт только на чтение, — и задают
+     * его ДО работы: генерация обязана сказать «сюда писать нельзя» до первого напечатанного
+     * файла, а не после половины.
+     */
+    canWrite(id: ResourceId): boolean;
+    /**
+     * Разрешает ли ИСТОЧНИК этого ресурса исполнять его код. Без проекта — `false`.
+     *
+     * Близнец {@link canWrite} и по той же причине вопрос к источнику, а не к плагину: сайдкары
+     * формы — это код, и придёт он оттуда же, откуда схема. Задают его поверхности превью,
+     * которые компилируют и исполняют файлы рабочей копии; `false` для них — отказ, а не повод
+     * исполнять «на всякий случай».
+     */
+    executesCode(id: ResourceId): boolean;
+    /**
+     * Перечитать каталог: в нём появились или исчезли записи мимо интерфейса.
+     *
+     * Дерево проекта читает уровни ЛЕНИВО и помнит прочитанное, поэтому каталог, созданный
+     * записью плагина, сам в нём не появится. Это не «сбросить кэш на всякий случай»: зовёт
+     * это тот, кто ТОЛЬКО ЧТО записал, и знает, куда именно.
+     */
+    refresh(dir: ResourceId): Promise<void>;
+    /**
+     * ТЕКСТ ресурсов рабочей копии изменился или они исчезли.
+     *
+     * В `changed` — только такие адреса: «загрузился» и «сохранился» текста не меняют, и тот,
+     * кто держит находки по этим файлам, стёр бы их на каждое сохранение. Подписка переживает
+     * смену проекта: служба существует с запуска, а проект открывают и закрывают.
+     */
+    onDidChange(cb: (changed: readonly ResourceId[]) => void): Disposable;
+}
+/**
+ * Возможность «записи рабочей области».
+ *
+ * Провайдер — оболочка (`./host-capabilities`): рабочая область существует с запуска и
+ * отвечает без проекта — `null`, `false`, пустым списком, — как и служба документов рядом.
+ *
+ * Версия `1.1.0`: к исходной добавлены {@link WorkspaceFilesService.executesCode} и
+ * {@link WorkspaceFilesService.onDidChange} — ими поверхности превью перестали зависеть от порта,
+ * который собирала оболочка. Растит её тот, кто интерфейс меняет.
+ */
+export declare const WorkspaceFilesCapability: Capability<WorkspaceFilesService>;
+/** Токен службы — ТОТ ЖЕ объект: возможность расширяет токен, второго реестра нет. */
+export declare const WorkspaceFilesServiceToken: Capability<WorkspaceFilesService>;

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

@@ -0,0 +1,41 @@
+import { Capability } from '../primitives/capability.js';
+import { ResourceId } from '../primitives/resource.js';
+/**
+ * Итог пакетной операции: что получилось и что нет.
+ *
+ * Пакетные операции НЕ всё-или-ничего: удаление десяти файлов, где один занят чужим
+ * процессом, обязано удалить девять и назвать десятый. Откатить уже удалённое всё равно
+ * нечем, а отказ целиком заставил бы человека повторять то, что уже сделано.
+ */
+export interface WorkspaceBatchResult {
+    readonly done: readonly ResourceId[];
+    readonly failed: readonly {
+        readonly id: ResourceId;
+        readonly error: unknown;
+    }[];
+}
+export interface WorkspaceResourcesService {
+    /**
+     * Умеет ли движок выбрать каталог вообще.
+     *
+     * Ответ не меняется за время жизни вкладки: это про браузер (File System Access),
+     * а не про состояние. Спрашивают его, чтобы не показывать кнопку, которая ничего не делает.
+     */
+    canOpenProject(): boolean;
+    /** Показывает человеку выбор каталога и открывает проект. `false` — не выбрали. */
+    openProject(): Promise<boolean>;
+    createFile(dir: ResourceId, name: string, text?: string): Promise<ResourceId>;
+    createDirectory(dir: ResourceId, name: string): Promise<ResourceId>;
+    rename(id: ResourceId, name: string): Promise<ResourceId>;
+    move(id: ResourceId, dir: ResourceId): Promise<ResourceId>;
+    remove(ids: readonly ResourceId[]): Promise<WorkspaceBatchResult>;
+    copy(ids: readonly ResourceId[], dir: ResourceId): Promise<WorkspaceBatchResult>;
+}
+/**
+ * Возможность «правка записей проекта».
+ *
+ * Провайдер — оболочка. Версия `1.0.0` — исходная; растит её тот, кто меняет интерфейс.
+ */
+export declare const WorkspaceResourcesCapability: Capability<WorkspaceResourcesService>;
+/** Токен службы — ТОТ ЖЕ объект: возможность расширяет токен, второго реестра нет. */
+export declare const WorkspaceResourcesServiceToken: Capability<WorkspaceResourcesService>;