@kubohiroya/turbowarp-extension-data-editor 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,152 @@
-# Temporary Holding Version
+# turbowarp-extension-data-editor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TurboWarp拡張が扱う構造化データを、フォームや独自UIで編集するための実験的な共通API v1です。
+[共通基盤 #1](https://github.com/kubohiroya/turbowarp-extension-data-editor/issues/1) と
+[GUI 接続 #1](https://github.com/kubohiroya/scratch-gui/issues/1) に対応します。
+
+日本語の利用手順・API・GUI接続・公開・検証記録は[ドキュメント一覧](docs/README.md)へ集約しています。
+
+[公開エディター・日英案内](https://kubohiroya.github.io/turbowarp-extension-data-editor/) と
+[公開・検証の運用Issue #26](https://github.com/kubohiroya/turbowarp-extension-data-editor/issues/26) も本リポジトリが所有します。
+
+## 標準の JSON Schema エディター
+
+JSON/YAML を格納する文字列引数と JSON Schema を宣言すると、react-jsonschema-form がフォームを生成します。
+GUI の登録 API は `schema` を検出して標準エディターを選びます。本文 UI の実装は不要です。
+
+```js
+const unregister = Scratch.gui.blockEditors.register({
+  apiVersion: 1,
+  extensionId: 'story',
+  editorId: 'properties',
+  opcodes: ['story_scene'],
+  argument: 'PROPERTIES',
+  format: 'yaml', // Omit for JSON compatibility.
+  schema: {
+    type: 'object',
+    properties: {
+      label: {type: 'string', minLength: 1, title: '名前'},
+      duration: {type: 'number', minimum: 1, maximum: 60, title: '秒数'}
+    },
+    required: ['label', 'duration'],
+    additionalProperties: false
+  },
+  uiSchema: {'ui:order': ['label', 'duration']}
+});
+```
+
+`registerSchema()` も同じ標準エディターを明示的に登録できます。
+必須項目・型・範囲などの検証エラーがある間は保存ボタンを無効化し、保存時にも必ず再検証します。
+任意の非同期 `validateData(data, snapshot)` による業務検証は保存時に追加実行されます。
+スキーマの検証は AJV 8、描画は React 16.14 に対応する RJSF 5.24.13 を使用します。
+対応の基本は JSON Schema draft-07 とローカル参照です。外部参照の取得は行わず、解決できない参照は登録時に拒否します。
+`default` は下書きへ補完し、保存するまで元ブロックへ書き込みません。
+
+`format: 'json' | 'yaml'` を指定できます。省略時は従来どおり JSON です。
+YAML はホスト側の `yaml` 2.x で単一の YAML 1.2 core 文書を decode し、
+JSON と同じ Schema で検証した後、指定形式で encode します。
+文字列キーの mapping、sequence、有限数値・文字列・真偽値・null が対象です。
+重複キー、非文字列キー、独自 tag、非有限数値、循環 alias、複数文書、YAML 1.1 は拒否し、元の引数は変更しません。
+非循環 alias は制限付きで展開します。merge key の特別な展開は行いません。
+変更なしの保存はコメント・空白を含む元文字列を保持し、commit しません。
+変更がある保存はデータの意味を保持して再出力しますが、コメント・引用符・anchor・キー順の保持は保証しません。
+フォームで編集しない追加プロパティも、Schema が許可する限り保持します。
+GUIのwebpack 4接続では[互換配布物と設定API](docs/webpack4.md)を使い、RJSF/YAMLの変換を本パッケージ側で行います。
+
+## API とトランザクション
+
+ルートの `EditorRegistry` / `EditorSession` は React / Blockly に依存しません。
+`@kubohiroya/turbowarp-extension-data-editor/rjsf` の `createSchemaEditor()` が標準フォームを提供します。
+通常 DOM や独自 React UI の `mount()` を持つ定義も登録できます。
+`/rjsf` の `createBlockEditorService()` がSchema検出・登録/解除・通知を提供します。
+`/react` の `BlockEditorDialog` は保存/キャンセル・エラー・階層UIを提供し、ホストのModal・翻訳・テーマを注入します。
+CSSは `/react/styles.css` をホストのCSS Modules経由で読み込みます。
+
+開始時のスナップショットと独立した JSON の下書きを持ち、キャンセルでは変更を破棄します。
+保存は検証、引数の許可リスト、reporter 保護、競合確認を通し、ホストへ1回だけ変更を要求します。
+GUI ホストは画面と VM を同期し、保存を Undo/Redo 各1回にまとめます。失敗時の復元もホストの責務です。
+`session.reference` で対象の target / block を識別できます。本文の unmount は下書きとエラーを保持し、再マウントできます。
+解除済みビューからの更新を拒否し、ビューの購読を解放します。標準フォームのフィールド ID も各表示で分離します。
+詳しくは [API とホスト契約](docs/api.md) を参照してください。
+
+## TurboWarp 接続
+
+`/turbowarp` の `attachTurboWarpBlockEditors()` にホストのScratchBlocks / VM / workspace、
+登録サービスと画面コールバックを渡すと、アイコン装飾・セッション起動・VM同期・一括保存を接続します。
+`enabled` / `descendants` は省略時OFF、戻り値は `refresh()` / 冪等な `dispose()` です。
+GUIには起動時フラグ・ライフサイクル・Modal/翻訳/テーマの接続を残します。
+詳細は [TurboWarp アダプターAPI](docs/turbowarp-adapter.md) を参照してください。
+
+## 子孫をまとめる階層セッション
+
+[共通基盤 #2](https://github.com/kubohiroya/turbowarp-extension-data-editor/issues/2) の追加 API として、
+`EditorRegistry.openDescendants()` と `DescendantSession` を提供します。
+ホストが `descendant-editing-v1` capability と完全な subtree snapshot / 一括 commit を提供する場合だけ使用します。
+既存の API v1 の本文を再利用し、親子孫・複数枝の下書きと検証結果を保持して、全変更を1回でホストへ渡します。
+未登録の中間ノードを構造として保持し、非表示ノードも検証します。構造・値・登録の競合、上限超過、非同期処理中の無効化に対応します。
+
+上限は500ノード・深さ32。GUI は起動時固定・既定 OFF の `blockEditorDescendants` と基盤フラグで選択し、
+フラグ OFF／未対応ホストでは既存の単一編集を使う設計です。
+詳細と業務非依存サンプルは [階層セッションの契約](docs/descendants.md) を参照してください。
+実 GUI の探索・階層モーダル・一括 Undo/Redo・`.sb3` 結合確認は scratch-gui #2 での接続が必要です。
+
+## ローカル検証
+
+Node.js 22.18 以降と pnpm を使用します。
+
+```sh
+pnpm install
+pnpm typecheck
+pnpm test
+```
+
+`pnpm test` は型宣言を含むビルド後、コアと標準フォームのテストを実行します。
+パッケージは ESM です。ブラウザには ES2022 の組み込み API が必要です。
+標準フォームの React / ReactDOM peer は 16.14 / 17 / 18。GUI は既存の 16.14 を共有します。
+初回の実験版は `@kubohiroya/turbowarp-extension-data-editor@0.1.0` です。固定SchemaのSource/Form編集を追加する今回の配布版は `0.2.0` です。
+
+```sh
+npm install --save-exact @kubohiroya/turbowarp-extension-data-editor@0.2.0
+```
+
+配布物・改名時の互換性・公開手順は[パッケージ配布](docs/package-distribution.md)を参照してください。
+
+## GUI で試す
+
+`scratch-gui` は本パッケージを検証済みのnpm完全version、またはGitの完全SHAで固定参照します。通常のGUIビルドに共通リポジトリの隣接配置は不要です。
+[GUIの起動・制約・検証手順](docs/block-editor.md) に従ってください。
+既存の拡張アイコンをクリックすると、標準モーダルで下書きを編集できます。
+
+現在の GUI 適用範囲は、配置済みブロックの通常の text shadow に保存された JSON/YAML 文字列です。
+reporter、メニュー、独自 validator 付きフィールドは書き換えません。
+`.sb3` の実保存と標準 `project_url` 経路での再読込を確認済みです。OS のファイル選択による再読込、アイコンがないブロックへの追加表示、翻訳・全テーマは後続の確認項目です。
+
+## フラグとロールバック
+
+GUI の `src/lib/tw-feature-flags.js` で起動時固定の `blockEditorDialogs` を読み取り、既定 OFF とします。
+`?blockEditorDialogs=1` の場合だけ登録 API と UI 接続を初期化します。
+標準フォームは機能有効時の既定の描画方法であり、機能フラグ自体を既定 ON にしません。
+フラグを外して再読込すれば従来の操作へ戻せます。
+確定値は既存引数へ保存し、UI・下書き・関数・revision をプロジェクトデータへ追加しません。
+
+## webpack 4 / E2E
+
+[webpack 4配布物と設定API](docs/webpack4.md)、[GUI接続E2EとCIの実行手順](docs/block-editor-e2e.md)を参照。専用編集UIから互換ビルド・E2Eまで共通側で管理し、GUIには明示的なホスト接続とCI呼出しを残す。
+
+## Schemaの共通型と診断変換
+
+`@kubohiroya/turbowarp-extension-data-editor/schema`はDOM・React・RJSFをロードせずに利用できる入口です。Schema bundle、正本・生成物・参照用の役割、処理段階別の診断・結果、同期owner検証の型を公開します。
+
+`toValidationIssues()`は入力診断を既存の`ValidationIssue`へ変換し、JSON Pointerのpath・順序・件数を維持した凍結結果を返します。不正な診断やcompile/execution診断はTypeErrorで拒否します。既存RJSFのpathや保存時専用の非同期`validateData`の契約は変わりません。
+
+`compileSchemaBundle()`はdraft-07/2020-12と同梱resourceからオフラインの同期validatorを生成します。Schemaと入力を変更せず、構造化診断を返します。[pure検証API](docs/schema.md)を参照してください。同期owner合成と明示bundleのRJSF経路も追加済みです。既存公開入口・webpack4/build-info・CSS buildを維持しています。
+
+同期owner検証には`/schema`の`validateSchemaInput`を利用できます。明示bundleフォームは`/rjsf`の`createSchemaBundleEditor` / `registerSchemaBundle`で登録します。context providerは呼出しごとに時刻・設定を渡します。表示上の対応範囲と既存APIの扱いは[Schema基盤](docs/schema.md)を参照してください。
+
+現在のowner横断検証は**14契約・8 package**です。[Template分離後の再検証手順](docs/template-fixture-separation.ja.md#current-verification)で、Templateを含まないisolation indexと2つの検証commandを確認してください。段階2では、この14本番契約と新規予定の9固定契約を区別して計画します。旧16契約・9 packageの結果と当時の開始条件は[段階1の履歴](docs/schema-stage1.ja.md)として保持します。
+
+## Optional editing examples
+
+Repository examples are opt-in teaching code, not template blocks or additional package exports. See [the JSON/YAML document example](examples/document-properties.mjs) and [its guide](examples/README.ja.md). Each extension owns its actual data contract.
+
+Prepared source editing is an optional host capability. See [the source/form contract](docs/source-forms.ja.md) for fixed-schema bindings, atomic saves, compatibility, and rollback.

package/dist/build-info.json

@@ -0,0 +1,11 @@
+{
+  "name": "@kubohiroya/turbowarp-extension-data-editor",
+  "version": "0.2.0",
+  "repository": "https://github.com/kubohiroya/turbowarp-extension-data-editor",
+  "revision": "76fa1d50a3c188082ceef723ea018a9d8769ea6e",
+  "sourceState": "commit",
+  "sourceSha256": "912efc0438710958698527aa5c26a33b0b1c2da280f91d36b048f6f2389a48f0",
+  "capabilities": {
+    "preparedSource": 1
+  }
+}

package/dist/codec.d.ts

@@ -0,0 +1,6 @@
+import type { JsonValue } from './types.js';
+export type SourceFormat = 'json' | 'yaml';
+export declare function decodeSource(source: string, format: SourceFormat): JsonValue;
+export declare function encodeSource(data: JsonValue, format: SourceFormat): string;
+/** Ignore object key order when deciding whether saving would change the data. */
+export declare function sameData(left: JsonValue, right: JsonValue): boolean;

package/dist/codec.js

@@ -0,0 +1,57 @@
+import { parseDocument, stringify } from 'yaml';
+import { cloneJson } from './data.js';
+/** Convert YAML mappings without coercing non-string keys into JSON property names. */
+function jsonData(value, ancestors = new Set(), depth = 0) {
+    if (depth > 100)
+        throw new TypeError('YAML data exceeds the maximum depth.');
+    if (value === null || typeof value !== 'object')
+        return cloneJson(value);
+    if (ancestors.has(value))
+        throw new TypeError('YAML data must not contain cycles.');
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value))
+            return value.map(child => jsonData(child, ancestors, depth + 1));
+        if (value instanceof Map) {
+            return Object.fromEntries([...value.entries()].map(([key, child]) => {
+                if (typeof key !== 'string')
+                    throw new TypeError('YAML mapping keys must be strings.');
+                return [key, jsonData(child, ancestors, depth + 1)];
+            }));
+        }
+        throw new TypeError('Expected JSON-compatible YAML data.');
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+export function decodeSource(source, format) {
+    if (format === 'json')
+        return cloneJson(JSON.parse(source));
+    const doc = parseDocument(source, { version: '1.2', schema: 'core', uniqueKeys: true });
+    const problems = [...doc.errors, ...doc.warnings];
+    if (problems.length)
+        throw new TypeError(problems.map(problem => problem.message).join('\n'));
+    if (doc.directives.yaml.version !== '1.2')
+        throw new TypeError('Only YAML 1.2 is supported.');
+    return jsonData(doc.toJS({ mapAsMap: true, maxAliasCount: 100 }));
+}
+export function encodeSource(data, format) {
+    const value = cloneJson(data);
+    return format === 'json' ? JSON.stringify(value) : stringify(value, { version: '1.2' });
+}
+/** Ignore object key order when deciding whether saving would change the data. */
+export function sameData(left, right) {
+    if (left === right)
+        return true;
+    if (left === null || right === null || typeof left !== 'object' || typeof right !== 'object')
+        return false;
+    if (Array.isArray(left)) {
+        return Array.isArray(right) && left.length === right.length &&
+            left.every((value, index) => sameData(value, right[index]));
+    }
+    if (Array.isArray(right))
+        return false;
+    const keys = Object.keys(left);
+    return keys.length === Object.keys(right).length && keys.every(key => Object.hasOwn(right, key) && sameData(left[key], right[key]));
+}

package/dist/data.d.ts

@@ -0,0 +1,7 @@
+import type { BlockReference, BlockSnapshot, JsonValue, LiteralValue } from './types.js';
+export declare function isLiteral(value: unknown): value is LiteralValue;
+/** Reject values whose meaning would change during JSON persistence. */
+export declare function cloneJson<T extends JsonValue>(value: T): T;
+export declare function captureReference(reference: BlockReference): BlockReference;
+export declare function captureSnapshot(snapshot: BlockSnapshot, reference: BlockReference): BlockSnapshot;
+export declare function sameSnapshot(left: BlockSnapshot, right: BlockSnapshot): boolean;

package/dist/data.js

@@ -0,0 +1,76 @@
+export function isLiteral(value) {
+    return typeof value === 'string' || typeof value === 'boolean' ||
+        (typeof value === 'number' && Number.isFinite(value));
+}
+/** Reject values whose meaning would change during JSON persistence. */
+export function cloneJson(value) {
+    const ancestors = new Set();
+    const visit = (item, depth) => {
+        if (depth > 100)
+            throw new TypeError('JSON data exceeds the maximum depth.');
+        if (item === null || isLiteral(item))
+            return item;
+        if (typeof item !== 'object')
+            throw new TypeError('Expected JSON-compatible data.');
+        if (ancestors.has(item))
+            throw new TypeError('JSON data must not contain cycles.');
+        ancestors.add(item);
+        try {
+            if (Array.isArray(item))
+                return Array.from(item, child => visit(child, depth + 1));
+            const prototype = Object.getPrototypeOf(item);
+            if (prototype !== Object.prototype && prototype !== null) {
+                throw new TypeError('JSON objects must be plain objects.');
+            }
+            if (Object.getOwnPropertySymbols(item).length > 0) {
+                throw new TypeError('JSON objects must not have symbol properties.');
+            }
+            return Object.fromEntries(Object.entries(item).map(([key, child]) => [key, visit(child, depth + 1)]));
+        }
+        finally {
+            ancestors.delete(item);
+        }
+    };
+    return visit(value, 0);
+}
+export function captureReference(reference) {
+    if (!reference || typeof reference.targetId !== 'string' || !reference.targetId ||
+        typeof reference.blockId !== 'string' || !reference.blockId) {
+        throw new TypeError('A target ID and block ID are required.');
+    }
+    return Object.freeze({ targetId: reference.targetId, blockId: reference.blockId });
+}
+export function captureSnapshot(snapshot, reference) {
+    if (snapshot.targetId !== reference.targetId || snapshot.blockId !== reference.blockId ||
+        typeof snapshot.opcode !== 'string' || !snapshot.opcode ||
+        typeof snapshot.revision !== 'string' || !snapshot.revision ||
+        !snapshot.arguments || typeof snapshot.arguments !== 'object' ||
+        Array.isArray(snapshot.arguments)) {
+        throw new TypeError('The host returned an invalid block snapshot.');
+    }
+    const entries = Object.entries(snapshot.arguments).map(([name, slot]) => {
+        if (!slot || (slot.kind !== 'reporter' && slot.kind !== 'literal') ||
+            (slot.kind === 'literal' && !isLiteral(slot.value))) {
+            throw new TypeError(`Invalid argument slot: ${name}`);
+        }
+        const copy = slot.kind === 'reporter'
+            ? Object.freeze({ kind: 'reporter' })
+            : Object.freeze({ kind: 'literal', value: slot.value });
+        return [name, copy];
+    });
+    return Object.freeze({
+        ...captureReference(reference), opcode: snapshot.opcode, revision: snapshot.revision,
+        arguments: Object.freeze(Object.fromEntries(entries))
+    });
+}
+export function sameSnapshot(left, right) {
+    const names = Object.keys(left.arguments);
+    return left.targetId === right.targetId && left.blockId === right.blockId &&
+        left.opcode === right.opcode && left.revision === right.revision &&
+        names.length === Object.keys(right.arguments).length && names.every(name => {
+        const a = left.arguments[name];
+        const b = Object.hasOwn(right.arguments, name) ? right.arguments[name] : undefined;
+        return b !== undefined && a.kind === b.kind &&
+            (a.kind === 'reporter' || (b.kind === 'literal' && a.value === b.value));
+    });
+}

package/dist/descendant-types.d.ts

@@ -0,0 +1,89 @@
+import type { BlockEditorHost, BlockReference, BlockSnapshot, EditorDescriptor, EditorViewContext, LiteralArgumentChange, SaveResult, SessionStatus, ValidationIssue } from './types.js';
+export declare const DESCENDANT_EDITING_CAPABILITY: "descendant-editing-v1";
+export declare const DEFAULT_DESCENDANT_LIMITS: Readonly<{
+    maxDepth: 32;
+    maxNodes: 500;
+}>;
+export interface DescendantLimits {
+    readonly maxDepth?: number;
+    readonly maxNodes?: number;
+}
+/** Ordered statement inputs; each list includes its internal next chain, never reporters. */
+export interface StatementBranch {
+    readonly input: string;
+    readonly blockIds: readonly string[];
+}
+export interface SubtreeNodeSnapshot {
+    readonly block: BlockSnapshot;
+    readonly branches: readonly StatementBranch[];
+}
+export interface SubtreeSnapshot extends BlockReference {
+    /** Changes across project reloads and editing sessions, even when block IDs are reused. */
+    readonly generation: string;
+    /** The complete scope, including unregistered structural nodes. No truncation is allowed. */
+    readonly nodes: readonly SubtreeNodeSnapshot[];
+}
+export interface SubtreeArgumentChange extends LiteralArgumentChange {
+    readonly blockId: string;
+}
+export interface SubtreeCommitRequest {
+    readonly expected: SubtreeSnapshot;
+    readonly changes: readonly SubtreeArgumentChange[];
+    /** Check both this signal and expected at the actual write boundary. */
+    readonly signal: AbortSignal;
+}
+export interface DescendantEditorHost {
+    readonly capability: typeof DESCENDANT_EDITING_CAPABILITY;
+    readSubtree(reference: BlockReference): SubtreeSnapshot | null;
+    /** One atomic transaction and one Undo/Redo step; rejection leaves data and history unchanged. */
+    commitSubtree(request: SubtreeCommitRequest): void | Promise<void>;
+    /** Notify project/target invalidation promptly, including during pending validation/commit. */
+    subscribeInvalidation?(reference: BlockReference, listener: (reason?: unknown) => void): () => void;
+}
+export declare function supportsDescendantEditing(host: BlockEditorHost): host is BlockEditorHost & {
+    descendants: DescendantEditorHost;
+};
+export interface InputPathStep {
+    readonly blockId: string;
+    readonly input: string;
+    readonly index: number;
+}
+export interface DescendantNodeDescriptor {
+    readonly reference: BlockReference;
+    readonly opcode: string;
+    readonly inputPath: readonly InputPathStep[];
+    readonly editor?: EditorDescriptor;
+}
+/** Body-only access. Nodes have no independent save, cancel, dispose or host commit. */
+export interface DescendantNodeEditor extends EditorViewContext {
+    readonly reference: BlockReference;
+    mount(container: HTMLElement): () => void;
+}
+export interface DescendantValidationIssue extends ValidationIssue {
+    readonly reference: BlockReference;
+    readonly inputPath: readonly InputPathStep[];
+}
+export type DescendantSessionStatus = SessionStatus | 'invalidated';
+export interface DescendantSessionState {
+    readonly status: DescendantSessionStatus;
+    readonly canSave: boolean;
+    readonly issues: readonly DescendantValidationIssue[];
+    readonly error: unknown;
+}
+export type DescendantSaveResult = Exclude<SaveResult, {
+    status: 'invalid';
+}> | {
+    readonly status: 'invalid';
+    readonly issues: readonly DescendantValidationIssue[];
+} | {
+    readonly status: 'invalidated';
+};
+export declare class BlockEditorStructureError extends Error {
+    readonly code: 'invalid-structure' | 'cycle' | 'limit';
+    constructor(message: string, code: 'invalid-structure' | 'cycle' | 'limit');
+}
+export declare class DescendantNodeError extends Error {
+    readonly reference: BlockReference;
+    readonly inputPath: readonly InputPathStep[];
+    constructor(reference: BlockReference, inputPath: readonly InputPathStep[], cause: unknown);
+}

package/dist/descendant-types.js

@@ -0,0 +1,22 @@
+export const DESCENDANT_EDITING_CAPABILITY = 'descendant-editing-v1';
+export const DEFAULT_DESCENDANT_LIMITS = Object.freeze({ maxDepth: 32, maxNodes: 500 });
+export function supportsDescendantEditing(host) {
+    const port = host.descendants;
+    return (port === null || port === void 0 ? void 0 : port.capability) === DESCENDANT_EDITING_CAPABILITY &&
+        typeof port.readSubtree === 'function' && typeof port.commitSubtree === 'function';
+}
+export class BlockEditorStructureError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'BlockEditorStructureError';
+    }
+}
+export class DescendantNodeError extends Error {
+    constructor(reference, inputPath, cause) {
+        super(`Editor callback failed for block ${reference.blockId}.`, { cause });
+        this.reference = reference;
+        this.inputPath = inputPath;
+        this.name = 'DescendantNodeError';
+    }
+}

package/dist/descendants.d.ts

@@ -0,0 +1,21 @@
+import type { CapturedSubtree } from './subtree.js';
+import type { DescendantEditorHost, DescendantLimits, DescendantNodeDescriptor, DescendantNodeEditor, DescendantSaveResult, DescendantSessionState } from './descendant-types.js';
+import type { BlockReference, EditorDefinition } from './types.js';
+/** Aggregate draft/validation only. The negotiated host owns the atomic write. */
+export declare class DescendantSession {
+    #private;
+    /** Use EditorRegistry.openDescendants() to negotiate and capture the scope. */
+    constructor(captured: CapturedSubtree, host: DescendantEditorHost, lookup: (opcode: string) => EditorDefinition | undefined, subscribeRegistry: (listener: () => void) => () => void, limits: Required<DescendantLimits>);
+    get reference(): BlockReference;
+    get generation(): string;
+    getNodes(): readonly DescendantNodeDescriptor[];
+    getEditor(blockId: string): DescendantNodeEditor | undefined;
+    getState(): DescendantSessionState;
+    subscribe(listener: () => void): () => void;
+    save(): Promise<DescendantSaveResult>;
+    /** Validation may be cancelled; an already dispatched commit must finish atomically. */
+    cancel(): boolean;
+    dispose(): boolean;
+    /** The host must observe the abort signal before any deferred write. */
+    invalidate(reason?: unknown): boolean;
+}