@kubohiroya/turbowarp-extension-data-editor 0.1.0 → 0.2.1

package/README.md

@@ -6,6 +6,9 @@ TurboWarp拡張が扱う構造化データを、フォームや独自UIで編集
 
 日本語の利用手順・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 がフォームを生成します。
@@ -100,23 +103,22 @@ 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` です。
+初回の実験版は `@kubohiroya/turbowarp-extension-data-editor@0.1.0` です。固定SchemaのSource/Form編集は `0.2.0` で追加しました。今回の配布版 `0.2.1` は、既定OFFの固定入力契約・標準field transaction・固定フォームとGUI接続も含みます。
 
 ```sh
-npm install --save-exact @kubohiroya/turbowarp-extension-data-editor@0.1.0
+npm install --save-exact @kubohiroya/turbowarp-extension-data-editor@0.2.1
 ```
 
 配布物・改名時の互換性・公開手順は[パッケージ配布](docs/package-distribution.md)を参照してください。
 
 ## GUI で試す
 
-`scratch-gui` はnpmに公開した本パッケージを固定versionで参照します。通常のGUIビルドに共通リポジトリの隣接配置は不要です。
+`scratch-gui` は本パッケージを検証済みのnpm完全version、またはGitの完全SHAで固定参照します。通常のGUIビルドに共通リポジトリの隣接配置は不要です。
 [GUIの起動・制約・検証手順](docs/block-editor.md) に従ってください。
 既存の拡張アイコンをクリックすると、標準モーダルで下書きを編集できます。
 
-現在の GUI 適用範囲は、配置済みブロックの通常の text shadow に保存された JSON/YAML 文字列です。
-reporter、メニュー、独自 validator 付きフィールドは書き換えません。
-`.sb3` の実保存と標準 `project_url` 経路での再読込を確認済みです。OS のファイル選択による再読込、アイコンがないブロックへの追加表示、翻訳・全テーマは後続の確認項目です。
+既存のSOURCE経路は、配置済みブロックの通常の text shadow に保存された JSON/YAML 文字列を扱います。この経路でreporter、メニュー、独自validator付きfieldを書き換えません。固定入力経路は対応hostと明示opt-inで静的menu・数値・色を扱い、reporterや動的menuを評価・置換しません。
+`.sb3` の保存、`project_url` とOSのファイル選択による再読込、日英表示とテーマの検証手順・実行範囲は[GUI接続E2E](docs/block-editor-e2e.md)と[固定入力の契約](docs/fixed-input-contracts.md)を参照してください。
 
 ## フラグとロールバック
 
@@ -129,3 +131,25 @@ GUI の `src/lib/tw-feature-flags.js` で起動時固定の `blockEditorDialogs`
 ## 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)を参照してください。
+
+既存SOURCE契約の導入時に採取した横断検証記録は**14契約・8 package**です。[Template分離後の再検証手順](docs/template-fixture-separation.ja.md#current-verification)で、Templateを含まないisolation indexと2つの検証commandを確認してください。この導入時記録では14本番契約と9固定契約を区別しています。固定入力の実装・GUI接続は末尾の契約節を参照してください。旧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.
+
+## 固定入力とGUI接続（S3-1〜S3-3）
+
+固定入力の型・Schema検査・同期prepared契約を追加しています。`createBlockEditorService({fixedInputs: true})`の明示時だけ新しい登録APIを提供し、対応hostがない場合は開けません。lower-level hostの`enableFixedInputs: true`で標準fieldの読取・原子的保存を利用できます。固定フォームとGUIの既定OFFフラグ接続も含みます。各拡張は正本Schema・codec・登録を所有します。[固定入力の契約](docs/fixed-input-contracts.md)を参照してください。配布物には元Git SHAと版更新を含むworking-tree release overlayの区分を記録しています。

package/dist/build-info.json

@@ -1,6 +1,11 @@
 {
   "name": "@kubohiroya/turbowarp-extension-data-editor",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "repository": "https://github.com/kubohiroya/turbowarp-extension-data-editor",
-  "revision": "9e041e5278a1ea70146a76c10732d1401955a12a"
+  "revision": "485f0e550e622235624b5e9176820161aeeba252",
+  "sourceState": "working-tree",
+  "sourceSha256": "175674eaaffce60dd9ebcf4c31f0f02a3bbd9dc6b8659ab3101ea6d8bceeea2f",
+  "capabilities": {
+    "preparedSource": 1
+  }
 }

package/dist/descendants.js

@@ -143,9 +143,15 @@ export class DescendantSession {
         __classPrivateFieldGet(this, _DescendantSession_instances, "m", _DescendantSession_notify).call(this);
         try {
             __classPrivateFieldGet(this, _DescendantSession_instances, "m", _DescendantSession_assertSaving).call(this);
+            const prepared = new Map();
             for (const record of __classPrivateFieldGet(this, _DescendantSession_records, "f").values()) {
                 try {
-                    const issues = await abortable(record.definition.validate(cloneJson(record.draft), record.snapshot), __classPrivateFieldGet(this, _DescendantSession_abort, "f").signal);
+                    const result = isPreparedEditor(record.definition)
+                        ? capturePreparedSave(record.definition, cloneJson(record.draft), record.snapshot) : undefined;
+                    if (result)
+                        prepared.set(record.snapshot.blockId, result);
+                    const issues = result ? (result.kind === 'invalid' ? result.issues : [])
+                        : await abortable(record.definition.validate(cloneJson(record.draft), record.snapshot), __classPrivateFieldGet(this, _DescendantSession_abort, "f").signal);
                     __classPrivateFieldGet(this, _DescendantSession_instances, "m", _DescendantSession_assertSaving).call(this);
                     record.issues = copyIssues(issues);
                 }
@@ -161,7 +167,9 @@ export class DescendantSession {
             const destinations = new Set();
             for (const record of __classPrivateFieldGet(this, _DescendantSession_records, "f").values()) {
                 try {
-                    const patch = record.definition.createPatch(cloneJson(record.draft), record.snapshot);
+                    const result = prepared.get(record.snapshot.blockId);
+                    const patch = (result === null || result === void 0 ? void 0 : result.kind) === 'ready' ? result.changes
+                        : record.definition.createPatch(cloneJson(record.draft), record.snapshot);
                     __classPrivateFieldGet(this, _DescendantSession_instances, "m", _DescendantSession_assertSaving).call(this);
                     if (!Array.isArray(patch))
                         throw new TypeError('createPatch() must return an array.');
@@ -334,3 +342,4 @@ _DescendantSession_snapshot = new WeakMap(), _DescendantSession_host = new WeakM
     __classPrivateFieldGet(this, _DescendantSession_detach, "f").clear();
     __classPrivateFieldGet(this, _DescendantSession_listeners, "f").clear();
 };
+import { isPreparedEditor, capturePreparedSave } from './prepared-save.js';

package/dist/fixed-input-branches.d.ts

@@ -0,0 +1,12 @@
+import type { FixedBlockSnapshot, FixedInputBranchCase, FixedInputBranchRule, FixedInputBranchState, FixedInputDeclaration, FixedInputDependency } from './fixed-input-types.js';
+import type { ArgumentSlot, LiteralArgumentChange, ValidationIssue } from './types.js';
+/** Capture finite JSON policy once; callbacks and getters are never part of host authority. */
+export declare function captureFixedBranchRules(value: unknown, dependencies: readonly FixedInputDependency[], readOnlyArguments: readonly string[]): readonly FixedInputBranchRule[];
+export interface ResolvedFixedBranch extends FixedInputBranchState {
+    readonly rule: FixedInputBranchRule;
+    readonly selected?: FixedInputBranchCase;
+}
+/** Resolve only captured literal metadata. Reporters and unavailable fields are never evaluated. */
+export declare function resolveFixedBranches(declaration: FixedInputDeclaration, snapshot: FixedBlockSnapshot, arguments_?: Readonly<Record<string, ArgumentSlot>>): readonly ResolvedFixedBranch[];
+/** Shared session/host gate. Schema and owner validation remain the prepared factory's responsibility. */
+export declare function validateFixedBranchChanges(declaration: FixedInputDeclaration, snapshot: FixedBlockSnapshot, changes: readonly LiteralArgumentChange[]): readonly ValidationIssue[];

package/dist/fixed-input-branches.js

@@ -0,0 +1,180 @@
+import { snapshotJson } from './schema-json.js';
+const fail = () => { throw new TypeError('Invalid fixed branch declaration.'); };
+const names = (value) => {
+    if (!Array.isArray(value) || !value.length || value.some(item => typeof item !== 'string' || !item) ||
+        new Set(value).size !== value.length)
+        return fail();
+    return Object.freeze(value);
+};
+const object = (value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return fail();
+    return value;
+};
+const normalize = (value, rule) => {
+    var _a, _b;
+    const text = ((_a = rule.normalize) === null || _a === void 0 ? void 0 : _a.trim) ? value.trim() : value;
+    return ((_b = rule.normalize) === null || _b === void 0 ? void 0 : _b.lowercase) ? text.toLowerCase() : text;
+};
+/** Capture finite JSON policy once; callbacks and getters are never part of host authority. */
+export function captureFixedBranchRules(value, dependencies, readOnlyArguments) {
+    if (value === undefined)
+        return Object.freeze([]);
+    const captured = snapshotJson(value);
+    if (!Array.isArray(captured))
+        return fail();
+    const selectors = new Set();
+    const occupied = new Set();
+    const result = [];
+    for (const item of captured) {
+        const rule = object(item);
+        if (typeof rule.selector !== 'string' || selectors.has(rule.selector))
+            return fail();
+        const group = dependencies.find(dependency => dependency.selector === rule.selector);
+        if (!group)
+            return fail();
+        for (const argument of [group.selector, ...group.dependents]) {
+            if (occupied.has(argument) || dependencies.some(other => other !== group &&
+                (other.selector === argument || other.dependents.includes(argument))))
+                return fail();
+            occupied.add(argument);
+        }
+        selectors.add(rule.selector);
+        let normalization;
+        if (rule.normalize !== undefined) {
+            const input = object(rule.normalize);
+            if (Object.keys(input).some(key => key !== 'trim' && key !== 'lowercase') ||
+                Object.values(input).some(value => typeof value !== 'boolean'))
+                return fail();
+            normalization = Object.freeze({ ...input });
+        }
+        const shell = { selector: rule.selector, cases: [], ...(normalization ? { normalize: normalization } : {}) };
+        if (!Array.isArray(rule.cases) || !rule.cases.length)
+            return fail();
+        const values = new Set();
+        const cases = [];
+        for (const input of rule.cases) {
+            const branch = object(input);
+            const caseValues = names(branch.values);
+            const normalized = caseValues.map(value => normalize(value, shell));
+            if (normalized.some(value => !value || values.has(value)))
+                return fail();
+            for (const value of normalized)
+                values.add(value);
+            if (new Set(normalized).size !== normalized.length)
+                return fail();
+            if (!Array.isArray(branch.activeDependents))
+                return fail();
+            const active = branch.activeDependents.length ? names(branch.activeDependents) : Object.freeze([]);
+            if (active.some(argument => !group.dependents.includes(argument)))
+                return fail();
+            const requirements = [];
+            if (branch.requireOnSelectorChange !== undefined) {
+                if (!Array.isArray(branch.requireOnSelectorChange))
+                    return fail();
+                const required = new Set();
+                for (const input of branch.requireOnSelectorChange) {
+                    const requirement = object(input);
+                    if (typeof requirement.argument !== 'string' || !readOnlyArguments.includes(requirement.argument) ||
+                        required.has(requirement.argument) || (requirement.rule !== 'literal' && requirement.rule !== 'nonempty-string'))
+                        return fail();
+                    required.add(requirement.argument);
+                    requirements.push(Object.freeze({ argument: requirement.argument, rule: requirement.rule }));
+                }
+            }
+            cases.push(Object.freeze({ values: caseValues, activeDependents: active,
+                ...(branch.requireOnSelectorChange === undefined ? {} : { requireOnSelectorChange: Object.freeze(requirements) }) }));
+        }
+        result.push(Object.freeze({ ...shell, cases: Object.freeze(cases) }));
+    }
+    return Object.freeze(result);
+}
+/** Resolve only captured literal metadata. Reporters and unavailable fields are never evaluated. */
+export function resolveFixedBranches(declaration, snapshot, arguments_ = snapshot.arguments) {
+    var _a;
+    return Object.freeze(((_a = declaration.branchRules) !== null && _a !== void 0 ? _a : []).map(rule => {
+        const metadata = snapshot.fixedContext.inputs[rule.selector];
+        const slot = arguments_[rule.selector];
+        let status;
+        if (!metadata || metadata.source === 'missing')
+            status = 'missing';
+        else if (metadata.source === 'reporter' || (slot === null || slot === void 0 ? void 0 : slot.kind) === 'reporter')
+            status = 'reporter';
+        else if ((metadata.source !== 'field' && metadata.source !== 'shadow') || metadata.role !== 'editable')
+            status = 'unsupported';
+        else if ((slot === null || slot === void 0 ? void 0 : slot.kind) !== 'literal' || typeof slot.value !== 'string')
+            status = 'unknown';
+        else {
+            const value = normalize(slot.value, rule);
+            const selected = rule.cases.find(branch => branch.values.some(item => normalize(item, rule) === value));
+            if (selected)
+                return Object.freeze({ selector: rule.selector, rule, selected,
+                    status: slot.value === selected.values[0] ? 'known' : 'alias', value: selected.values[0] });
+            status = 'unknown';
+        }
+        return Object.freeze({ selector: rule.selector, rule, status });
+    }));
+}
+const writableLiteral = (snapshot, arguments_, name) => {
+    var _a;
+    const metadata = snapshot.fixedContext.inputs[name];
+    return ((_a = arguments_[name]) === null || _a === void 0 ? void 0 : _a.kind) === 'literal' && (metadata === null || metadata === void 0 ? void 0 : metadata.role) === 'editable' &&
+        (metadata.source === 'field' || metadata.source === 'shadow');
+};
+const diagnostic = (declaration, code, argument) => Object.freeze({
+    message: `Fixed branch validation failed: ${code}; contract=${JSON.stringify(declaration.contractId)}.`,
+    path: `/${argument.replace(/~/g, '~0').replace(/\//g, '~1')}`
+});
+/** Shared session/host gate. Schema and owner validation remain the prepared factory's responsibility. */
+export function validateFixedBranchChanges(declaration, snapshot, changes) {
+    var _a;
+    const issues = [];
+    const finalArguments = { ...snapshot.arguments };
+    const changed = new Set();
+    const seen = new Set();
+    for (const change of changes) {
+        if (seen.has(change.argument) || !['string', 'number', 'boolean'].includes(typeof change.value) || !declaration.editableArguments.includes(change.argument) ||
+            !writableLiteral(snapshot, snapshot.arguments, change.argument)) {
+            issues.push(diagnostic(declaration, 'disallowed-change', change.argument));
+            continue;
+        }
+        seen.add(change.argument);
+        const original = snapshot.arguments[change.argument];
+        if ((original === null || original === void 0 ? void 0 : original.kind) === 'literal' && Object.is(original.value, change.value))
+            continue;
+        changed.add(change.argument);
+        Object.defineProperty(finalArguments, change.argument, { value: { kind: 'literal', value: change.value }, enumerable: true, configurable: true });
+    }
+    const resolved = resolveFixedBranches(declaration, snapshot, finalArguments);
+    for (const group of declaration.dependencies) {
+        if (![group.selector, ...group.dependents].some(name => changed.has(name)))
+            continue;
+        const branch = resolved.find(item => item.selector === group.selector);
+        if (!(branch === null || branch === void 0 ? void 0 : branch.selected)) {
+            issues.push(diagnostic(declaration, branch ? 'selector-unavailable' : 'fixed-dependency-validation-unavailable', group.selector));
+            continue;
+        }
+        for (const argument of group.dependents) {
+            if (changed.has(argument) && !branch.selected.activeDependents.includes(argument)) {
+                issues.push(diagnostic(declaration, 'inactive-change', argument));
+            }
+        }
+        if (!changed.has(group.selector))
+            continue;
+        for (const argument of branch.selected.activeDependents) {
+            if (!writableLiteral(snapshot, finalArguments, argument))
+                issues.push(diagnostic(declaration, 'dependency-unverifiable', argument));
+        }
+        for (const requirement of (_a = branch.selected.requireOnSelectorChange) !== null && _a !== void 0 ? _a : []) {
+            const metadata = snapshot.fixedContext.inputs[requirement.argument];
+            const slot = finalArguments[requirement.argument];
+            if (!metadata || metadata.role !== 'readonly' || (metadata.source !== 'field' && metadata.source !== 'shadow') || (slot === null || slot === void 0 ? void 0 : slot.kind) !== 'literal') {
+                issues.push(diagnostic(declaration, 'dependency-unverifiable', requirement.argument));
+            }
+            else if (requirement.rule === 'nonempty-string' && (typeof slot.value !== 'string' || !slot.value.trim())) {
+                issues.push(diagnostic(declaration, 'dependency-invalid', requirement.argument));
+            }
+        }
+    }
+    return Object.freeze(issues);
+}

package/dist/fixed-input-editor.d.ts

@@ -0,0 +1,39 @@
+import type { FixedBlockSnapshot, FixedInputBranchRule, FixedInputControl, FixedInputDeclaration, FixedInputEditorDefinition, FixedPreparedSave } from './fixed-input-types.js';
+import type { SchemaBundle, SchemaValidationContext } from './schema-types.js';
+import type { EditorDefinition, JsonObject, JsonValue, LiteralValue, ValidationIssue } from './types.js';
+export interface FixedInputBinding<C = null> {
+    readonly argument: string;
+    readonly schemaBundle: SchemaBundle;
+    readonly control?: FixedInputControl;
+    /** Produce a JSON editing projection. Throw to retain the raw literal as readonly. */
+    read(value: LiteralValue): JsonValue;
+    /** Construct the exact literal candidate once. A numeric buffer supplies its validated string token, which must be returned unchanged. Neither this nor validation may be asynchronous. */
+    encode(value: JsonValue, context: SchemaValidationContext<C>): LiteralValue;
+    /** Check the exact candidate. Messages from this callback are never rendered verbatim. */
+    validateCandidate(candidate: LiteralValue, context: SchemaValidationContext<C>, snapshot: FixedBlockSnapshot): readonly ValidationIssue[];
+}
+export interface FixedInputBranchPolicy<C = null> extends Omit<FixedInputBranchRule, 'cases'> {
+    readonly cases: readonly (FixedInputBranchRule['cases'][number] & {
+        readonly bindings?: readonly FixedInputBinding<C>[];
+    })[];
+}
+export interface FixedInputEditorOptions<C = null> {
+    readonly apiVersion: 1;
+    readonly extensionId: string;
+    readonly editorId: string;
+    readonly opcodes: readonly string[];
+    readonly contractId: string;
+    readonly contractRevision: string;
+    readonly readOnlyArguments?: readonly string[];
+    readonly dependencies?: FixedInputDeclaration['dependencies'];
+    readonly branchPolicies?: readonly FixedInputBranchPolicy<C>[];
+    readonly bindings: readonly FixedInputBinding<C>[];
+    readonly validationContext: () => SchemaValidationContext<C>;
+}
+/** Capture exactly the callbacks and declaration values subsequently registered. */
+export declare function captureFixedInputEditorDefinition<C = null>(value: FixedInputEditorDefinition<C>): FixedInputEditorDefinition<C>;
+export declare function isFixedInputEditor(definition: EditorDefinition): definition is FixedInputEditorDefinition<unknown>;
+/** Capture a synchronous callback result without invoking getters, iterators, or toJSON. */
+export declare function captureFixedPreparedSave<C = null>(definition: FixedInputEditorDefinition<C>, draft: JsonObject, snapshot: FixedBlockSnapshot): FixedPreparedSave<C>;
+/** Fixed inputs are additive: legacy callbacks cannot accidentally save their drafts. */
+export declare function createFixedInputEditor<C = null>(options: FixedInputEditorOptions<C>): FixedInputEditorDefinition<C>;