@kubohiroya/turbowarp-structured-data 0.5.1 → 0.6.1

package/docs/index.html

@@ -9,8 +9,17 @@
     code{background:#f3f3f3;padding:.1em .3em;border-radius:.25em}
     pre{background:#f6f8fa;padding:1rem;overflow:auto;border-radius:.5rem}
   </style>
+<style id="block-reference-style">
+#extension-block-reference{max-width:72rem;margin:2rem auto;padding:1rem;line-height:1.6;overflow-wrap:anywhere}
+#extension-block-reference .block-reference-entry{display:block;scroll-margin-top:6rem;margin:2rem 0;padding:1rem;border:1px solid currentColor;border-radius:.5rem}
+#extension-block-reference .block-reference-table{overflow-x:auto}
+#extension-block-reference table{border-collapse:collapse;width:100%}
+#extension-block-reference th,#extension-block-reference td{text-align:left;vertical-align:top;border:1px solid currentColor;padding:.5rem}
+#extension-block-reference code{white-space:pre-wrap}
+#extension-block-reference a:focus-visible{outline:3px solid currentColor;outline-offset:3px}
+</style>
 </head>
-<body>
+<body><p lang="en" class="complete-block-reference-link"><a href="#extension-block-reference">Complete block reference (16 blocks)</a></p>
   <h1>Structured Data</h1>
   <p>Named structured data with safe JSON/YAML codecs and deterministic path operations.</p>
 
@@ -22,5 +31,30 @@
 
   <h2>Development</h2>
   <p>See the repository README and architecture documentation for build, test, release, and compatibility details.</p>
+<!-- BEGIN COMPLETE BLOCK REFERENCE -->
+<section lang="en" id="extension-block-reference" aria-labelledby="block-reference-title">
+<h2 id="block-reference-title">Structured Data: complete block reference</h2>
+<p>All 16 blocks are documented below, including compatibility blocks and blocks available through optional features. Select a block to read its behavior, arguments, default values, and menu choices. Each block has a permanent link.</p>
+<nav aria-label="Block reference"><ul><li><a href="#block-parseJson"><code>parse JSON [TEXT] as [NAME]</code></a></li>
+<li><a href="#block-parseYaml"><code>parse YAML [TEXT] as [NAME]</code></a></li>
+<li><a href="#block-toJson"><code>to JSON [NAME]</code></a></li>
+<li><a href="#block-toYaml"><code>to YAML [NAME]</code></a></li>
+<li><a href="#block-hasStructuredData"><code>structured data [NAME] exists?</code></a></li>
+<li><a href="#block-deleteStructuredData"><code>delete structured data [NAME]</code></a></li>
+<li><a href="#block-getJsonAtPath"><code>get JSON from [NAME] at path [PATH]</code></a></li>
+<li><a href="#block-hasPath"><code>structured data [NAME] has path [PATH]?</code></a></li>
+<li><a href="#block-setJsonAtPath"><code>set [NAME] at path [PATH] to JSON [VALUE]</code></a></li>
+<li><a href="#block-deleteAtPath"><code>delete path [PATH] from [NAME]</code></a></li>
+<li><a href="#block-keysAtPath"><code>keys in [NAME] at path [PATH]</code></a></li>
+<li><a href="#block-lengthAtPath"><code>length of array in [NAME] at path [PATH]</code></a></li>
+<li><a href="#block-forEachAtPath"><code>for each in [NAME] at path [PATH] max [MAX]</code></a></li>
+<li><a href="#block-currentKey"><code>current key</code></a></li>
+<li><a href="#block-currentIndex"><code>current index</code></a></li>
+<li><a href="#block-currentValueJson"><code>current value JSON</code></a></li>
+</ul></nav>
+<article id="block-parseJson" class="block-reference-entry"><h3><code>parse JSON [TEXT] as [NAME]</code></h3><p>Parse JSON text into the target-local structured data namespace.</p><p>Block type: COMMAND. Opcode: <code>parseJson</code>. <a href="#block-parseJson">Permanent link</a></p><div class="block-reference-table"><table><thead><tr><th>Argument</th><th>Type</th><th>Default value</th><th>Menu choices</th></tr></thead><tbody><tr><th scope="row"><code>TEXT</code></th><td>STRING</td><td><code>{&quot;name&quot;:&quot;TurboWarp&quot;}</code></td><td></td></tr><tr><th scope="row"><code>NAME</code></th><td>STRING</td><td><code>data</code></td><td></td></tr></tbody></table></div></article><article id="block-parseYaml" class="block-reference-entry"><h3><code>parse YAML [TEXT] as [NAME]</code></h3><p>Parse safe YAML text into the target-local structured data namespace.</p><p>Block type: COMMAND. Opcode: <code>parseYaml</code>. <a href="#block-parseYaml">Permanent link</a></p><div class="block-reference-table"><table><thead><tr><th>Argument</th><th>Type</th><th>Default value</th><th>Menu choices</th></tr></thead><tbody><tr><th scope="row"><code>TEXT</code></th><td>STRING</td><td><code>name: TurboWarp</code></td><td></td></tr><tr><th scope="row"><code>NAME</code></th><td>STRING</td><td><code>data</code></td><td></td></tr></tbody></table></div></article><article id="block-toJson" class="block-reference-entry"><h3><code>to JSON [NAME]</code></h3><p>Render named structured data as canonical JSON.</p><p>Block type: REPORTER. Opcode: <code>toJson</code>. <a href="#block-toJson">Permanent link</a></p><div class="block-reference-table"><table><thead><tr><th>Argument</th><th>Type</th><th>Default value</th><th>Menu choices</th></tr></thead><tbody><tr><th scope="row"><code>NAME</code></th><td>STRING</td><td><code>data</code></td><td></td></tr></tbody></table></div></article><article id="block-toYaml" class="block-reference-entry"><h3><code>to YAML [NAME]</code></h3><p>Render named structured data as deterministic YAML.</p><p>Block type: REPORTER. Opcode: <code>toYaml</code>. <a href="#block-toYaml">Permanent link</a></p><div class="block-reference-table"><table><thead><tr><th>Argument</th><th>Type</th><th>Default value</th><th>Menu choices</th></tr></thead><tbody><tr><th scope="row"><code>NAME</code></th><td>STRING</td><td><code>data</code></td><td></td></tr></tbody></table></div></article><article id="block-hasStructuredData" class="block-reference-entry"><h3><code>structured data [NAME] exists?</code></h3><p>Report whether the current target has named structured data.</p><p>Block type: BOOLEAN. Opcode: <code>hasStructuredData</code>. <a href="#block-hasStructuredData">Permanent link</a></p><div class="block-reference-table"><table><thead><tr><th>Argument</th><th>Type</th><th>Default value</th><th>Menu choices</th></tr></thead><tbody><tr><th scope="row"><code>NAME</code></th><td>STRING</td><td><code>data</code></td><td></td></tr></tbody></table></div></article><article id="block-deleteStructuredData" class="block-reference-entry"><h3><code>delete structured data [NAME]</code></h3><p>Delete named structured data from the current target.</p><p>Block type: COMMAND. Opcode: <code>deleteStructuredData</code>. <a href="#block-deleteStructuredData">Permanent link</a></p><div class="block-reference-table"><table><thead><tr><th>Argument</th><th>Type</th><th>Default value</th><th>Menu choices</th></tr></thead><tbody><tr><th scope="row"><code>NAME</code></th><td>STRING</td><td><code>data</code></td><td></td></tr></tbody></table></div></article><article id="block-getJsonAtPath" class="block-reference-entry"><h3><code>get JSON from [NAME] at path [PATH]</code></h3><p>Return a named value at a path as JSON.</p><p>Block type: REPORTER. Opcode: <code>getJsonAtPath</code>. <a href="#block-getJsonAtPath">Permanent link</a></p><div class="block-reference-table"><table><thead><tr><th>Argument</th><th>Type</th><th>Default value</th><th>Menu choices</th></tr></thead><tbody><tr><th scope="row"><code>NAME</code></th><td>STRING</td><td><code>data</code></td><td></td></tr><tr><th scope="row"><code>PATH</code></th><td>STRING</td><td><code>$.name</code></td><td></td></tr></tbody></table></div></article><article id="block-hasPath" class="block-reference-entry"><h3><code>structured data [NAME] has path [PATH]?</code></h3><p>Report whether a path exists in named structured data.</p><p>Block type: BOOLEAN. Opcode: <code>hasPath</code>. <a href="#block-hasPath">Permanent link</a></p><div class="block-reference-table"><table><thead><tr><th>Argument</th><th>Type</th><th>Default value</th><th>Menu choices</th></tr></thead><tbody><tr><th scope="row"><code>NAME</code></th><td>STRING</td><td><code>data</code></td><td></td></tr><tr><th scope="row"><code>PATH</code></th><td>STRING</td><td><code>$.name</code></td><td></td></tr></tbody></table></div></article><article id="block-setJsonAtPath" class="block-reference-entry"><h3><code>set [NAME] at path [PATH] to JSON [VALUE]</code></h3><p>Immutably update a named value and replace its binding.</p><p>Block type: COMMAND. Opcode: <code>setJsonAtPath</code>. <a href="#block-setJsonAtPath">Permanent link</a></p><div class="block-reference-table"><table><thead><tr><th>Argument</th><th>Type</th><th>Default value</th><th>Menu choices</th></tr></thead><tbody><tr><th scope="row"><code>NAME</code></th><td>STRING</td><td><code>data</code></td><td></td></tr><tr><th scope="row"><code>PATH</code></th><td>STRING</td><td><code>$.name</code></td><td></td></tr><tr><th scope="row"><code>VALUE</code></th><td>STRING</td><td><code>&quot;Scratch&quot;</code></td><td></td></tr></tbody></table></div></article><article id="block-deleteAtPath" class="block-reference-entry"><h3><code>delete path [PATH] from [NAME]</code></h3><p>Immutably delete a path and replace its named binding.</p><p>Block type: COMMAND. Opcode: <code>deleteAtPath</code>. <a href="#block-deleteAtPath">Permanent link</a></p><div class="block-reference-table"><table><thead><tr><th>Argument</th><th>Type</th><th>Default value</th><th>Menu choices</th></tr></thead><tbody><tr><th scope="row"><code>NAME</code></th><td>STRING</td><td><code>data</code></td><td></td></tr><tr><th scope="row"><code>PATH</code></th><td>STRING</td><td><code>$.name</code></td><td></td></tr></tbody></table></div></article><article id="block-keysAtPath" class="block-reference-entry"><h3><code>keys in [NAME] at path [PATH]</code></h3><p>Return sorted object keys as JSON.</p><p>Block type: REPORTER. Opcode: <code>keysAtPath</code>. <a href="#block-keysAtPath">Permanent link</a></p><div class="block-reference-table"><table><thead><tr><th>Argument</th><th>Type</th><th>Default value</th><th>Menu choices</th></tr></thead><tbody><tr><th scope="row"><code>NAME</code></th><td>STRING</td><td><code>data</code></td><td></td></tr><tr><th scope="row"><code>PATH</code></th><td>STRING</td><td><code>$</code></td><td></td></tr></tbody></table></div></article><article id="block-lengthAtPath" class="block-reference-entry"><h3><code>length of array in [NAME] at path [PATH]</code></h3><p>Return the array length.</p><p>Block type: REPORTER. Opcode: <code>lengthAtPath</code>. <a href="#block-lengthAtPath">Permanent link</a></p><div class="block-reference-table"><table><thead><tr><th>Argument</th><th>Type</th><th>Default value</th><th>Menu choices</th></tr></thead><tbody><tr><th scope="row"><code>NAME</code></th><td>STRING</td><td><code>data</code></td><td></td></tr><tr><th scope="row"><code>PATH</code></th><td>STRING</td><td><code>$</code></td><td></td></tr></tbody></table></div></article><article id="block-forEachAtPath" class="block-reference-entry"><h3><code>for each in [NAME] at path [PATH] max [MAX]</code></h3><p>Iterate named data deterministically with a static maximum.</p><p>Block type: LOOP. Opcode: <code>forEachAtPath</code>. <a href="#block-forEachAtPath">Permanent link</a></p><div class="block-reference-table"><table><thead><tr><th>Argument</th><th>Type</th><th>Default value</th><th>Menu choices</th></tr></thead><tbody><tr><th scope="row"><code>NAME</code></th><td>STRING</td><td><code>data</code></td><td></td></tr><tr><th scope="row"><code>PATH</code></th><td>STRING</td><td><code>$</code></td><td></td></tr><tr><th scope="row"><code>MAX</code></th><td>NUMBER</td><td><code>100</code></td><td></td></tr></tbody></table></div><!-- BEGIN FIXED INPUT HELP --><p id="fixed-input-forEachAtPath-MAX" class="fixed-input-editor">MVP機能を有効にした場合だけ、MAXを整数1〜1000で編集します。入力途中・空白・非finiteな新値は保存できません。NAMEとPATHは変更しません。 GUIのDialogsとFixedInputsは起動時の既定OFFです。両方を有効にして再読込すると固定フォームが使えます。未変更のraw値を保存し直さず、接続reporterは評価しません。</p><!-- END FIXED INPUT HELP --></article><article id="block-currentKey" class="block-reference-entry"><h3><code>current key</code></h3><p>Return the current object key or array index string.</p><p>Block type: REPORTER. Opcode: <code>currentKey</code>. <a href="#block-currentKey">Permanent link</a></p><p>This block has no arguments.</p></article><article id="block-currentIndex" class="block-reference-entry"><h3><code>current index</code></h3><p>Return the zero-based iteration number.</p><p>Block type: REPORTER. Opcode: <code>currentIndex</code>. <a href="#block-currentIndex">Permanent link</a></p><p>This block has no arguments.</p></article><article id="block-currentValueJson" class="block-reference-entry"><h3><code>current value JSON</code></h3><p>Return the current iteration value as JSON.</p><p>Block type: REPORTER. Opcode: <code>currentValueJson</code>. <a href="#block-currentValueJson">Permanent link</a></p><p>This block has no arguments.</p></article>
+<p><a href="https://github.com/kubohiroya/turbowarp-structured-data/blob/main/README.md">Repository guide and examples</a></p>
+</section>
+<!-- END COMPLETE BLOCK REFERENCE -->
 </body>
 </html>

package/docs/schemas/block-editor-fixed-inputs.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kubohiroya.github.io/turbowarp-structured-data/schemas/block-editor-fixed-inputs.schema.json",
+  "$defs": {
+    "forEachAtPath": {
+      "type": "object",
+      "properties": {
+        "MAX": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1000
+        }
+      },
+      "required": [
+        "MAX"
+      ],
+      "additionalProperties": true
+    }
+  }
+}

package/docs/source-forms.ja.md

@@ -0,0 +1,20 @@
+# 段階2 Source/Form編集
+
+この文書はローカル実装時の契約を示す。npm公開は実施しない。
+
+- 対象: parseJson.TEXT / parseYaml.TEXT / setJsonAtPath.VALUE
+- 契約: json-value
+- Schema正本: 共通エディター src/json-value.ts。Schema文書はcanonical-schema、bundleは正本参照とprovenanceを保持する。
+- owner受理条件: src/codecs.ts / core.ts の各ブロックと同じparse関数。JSON/YAML文書の256KiB、深さ64、ノード50000制限、YAML alias・重複キー・未知tag拒否を維持。setJsonAtPath.VALUEは従来のparseJson契約を維持。Named data名/path候補は段階4。
+
+UIはSourceとFormを切り替える。無変更・cancel・編集後の元の値への復帰は入力文字列をそのまま保持する。Formの部分編集でも未知キー・null・空文字・配列の順序と重複・未編集箇所の表記を維持する。既定値の暗黙補完、variant/formatの暗黙移行、runtime正規化後の値の書き戻しは行わない。不正なsourceもSourceとして開き修復できるが、ownerに拒否される候補は保存できない。
+
+利用条件は、GUI起動時に `blockEditorDialogs=1` と `blockEditorSourceForms=1` の両方を指定し、信頼した拡張をunsandboxedで読み込むこと。`Scratch.gui.blockEditors` はunsandboxed拡張APIにのみ提供される。既存のsandbox実行権限や拡張の既定の読み込み方法は変更しない。sandboxed実行では従来のブロックを使用し、編集capabilityがないためフォーム登録を省略する。
+
+登録入口はoptionalな `Scratch.gui.blockEditors.registerSourceEditor`。GUIの起動時固定 `blockEditorSourceForms` は既定OFF、既存 `blockEditorDialogs` が前提となる。旧GUIやcapabilityを持たないhostでは登録を行わず、既存ブロックのAPI・引数・実行挙動は維持する。`dispose()` またはruntime破棄で登録を解除する。既存のruntime処理を実行せず、pure parser/validatorで保存候補の同じsourceを検査する。複数入力のブロックは単一editor definitionとして一度に検査・commitする。
+
+依存: 共通エディターの新 `./schema` 型・json-value契約と新prepared save経路、およびGUIのcapabilityが必要。ローカル検証は独立cloneから新共通artifactへaliasする。遠隔配布用のpin・lockは最終共通artifactのSHA確定後に揃える。架空のSHAを記載しない。
+
+受け入れ基準: 全対象inputの登録、既存受理との互換、Source修復、不正保存の拒否、no-opでundoを作らないこと、部分編集でraw値を維持すること、runtime破棄時の解除、既存APIのテスト・型検査・buildを確認する。原文不変・部分編集・拒否は `tests/source-editor.test.ts` から実際の共通serviceと接続して検証する。
+
+ロールバック: 起動時 `blockEditorSourceForms` をOFFに戻してGUIを再起動する。登録capabilityを外すと新フォームは使用されず、既存のブロックと保存済みsourceは引き続き実行できる。Schema自体の編集・実行時の値からの動的Schema・値候補との接続は別工程。

package/docs/stage2-release-verification.ja.md

@@ -0,0 +1,28 @@
+# 段階2の安定版検証記録
+
+公開予定版: `@kubohiroya/turbowarp-structured-data@0.6.0`。JSON/YAML のTEXTとpath操作のVALUEを接続し、既存サイズ・深度・node・alias制限を維持します。
+
+| opcode | 入力 |
+| --- | --- |
+| parseJson | TEXT |
+| parseYaml | TEXT |
+| setJsonAtPath | VALUE |
+
+正本は共通 `src/json-value.ts` と既存 `src/codecs.ts` / `src/core.ts` のpure検証です。JSON/YAMLのroot型・配列・object・scalarを明示操作で編集します。runtimeの任意Schemaとの連動は追加しません。
+
+共通依存は `76fa1d50a3c188082ceef723ea018a9d8769ea6e`（`@kubohiroya/turbowarp-extension-data-editor` 0.2.0）へGitの完全SHAで固定しています。manifest・lock・build許可・fresh実解決を揃え、直接・AJV経由のfast-uriを3.1.8へ統一しています。古い共有aliasの実解決を安定版の検証として流用していません。
+
+`react-dom@18.3.1` は実際のRJSF registration回帰テストに必要なdev依存として追加しました。拡張のruntimeコードはGUIのoptional APIを使い、ReactDOMを拡張bundleへ追加しません。
+
+Node v22.23.3 / pnpm 11.11.0で、空の専用storeからscripts有効の `pnpm install --frozen-lockfile` を実施しました。Git prepareから得た共通packageにはsrcが含まれず、build-infoは上記SHAと一致します。
+
+- 全テスト 40件、型検査、全lint、build、文書/リポジトリ検査、pack検査が成功しました。
+- production auditはcritical/high/moderate/lowすべて0件です。
+- dist 2件は2回のbuildでSHA-256が一致し、異なるcheckout pathのfresh fixtureと作業cloneでも全件のbytesが一致しました。
+- Vite8を使う場合の生成region行にはpackage storeのpathが入るため、そのマーカー行だけを省きます。licenseコメントと実行コードは保持します。Vite7のrepoにはこの追加処理を適用しません。
+
+過去の段階2ローカル全体659件・実GUI5ケース（各8手順）は別の保存済み記録です。今回の数は当該repoのfresh full結果であり、繰り返し実行を合算していません。GitHub CIの結果はPRで別途確認します。
+
+GUIの起動時固定・既定OFFの `blockEditorSourceForms` と `blockEditorDialogs` の両方、および信頼した拡張のunsandboxed読込を必要とします。旧API、ブロックのopcode/入力、raw保存形式を保持し、無変更・Cancelでは元の入力を維持します。検査した候補だけを保存し、複数入力はatomicに保存します。Schema自体の編集・動的Schema・既存候補への新規項目追加はこの段階に含みません。
+
+ロールバックはflagをOFFにして再読込します。コードを戻す場合はconsumer→producer→共通の逆順でrevertし、manifest・lock・実解決を一体で戻します。以前の公開版 `@kubohiroya/turbowarp-structured-data@0.5.1` へ固定できます。保存形式を自動移行しません。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubohiroya/turbowarp-structured-data",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "Named structured data with JSON/YAML codecs and deterministic path operations for TurboWarp.",
   "author": "Hiroya Kubo <hiroya@cuc.ac.jp>",
   "license": "MPL-2.0",
@@ -27,6 +27,7 @@
     "dist/",
     "docs/",
     "src/",
+    "schemas/",
     "templates/",
     "README.md",
     "README.ja.md",
@@ -47,8 +48,8 @@
     "build": "vite build",
     "lint": "eslint src tests scripts vite.config.ts eslint.config.ts",
     "test": "vitest run",
-    "docs": "node scripts/generate-readme.ts",
-    "docs:check": "node scripts/generate-readme.ts --check",
+    "docs": "node scripts/generate-readme.ts && node scripts/generate-fixed-input-docs.mjs",
+    "docs:check": "node scripts/generate-readme.ts --check && node scripts/generate-fixed-input-docs.mjs --check",
     "template:readme": "node scripts/apply-readme-template.ts",
     "repo:check": "node scripts/check-repo.ts",
     "pack:check": "npm pack --dry-run --ignore-scripts",
@@ -57,21 +58,29 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.5",
-    "@kubohiroya/turbowarp-extension-manifest": "0.3.0",
-    "@kubohiroya/turbowarp-named-data": "0.1.0",
-    "@kubohiroya/vite-plugin-turbowarp-extension": "0.3.0",
+    "@kubohiroya/turbowarp-extension-manifest": "0.3.2",
+    "@kubohiroya/turbowarp-named-data": "0.3.1",
+    "@kubohiroya/vite-plugin-turbowarp-extension": "0.6.1",
     "@types/node": "^24.13.3",
     "eslint": "^9.39.5",
     "jiti": "^2.7.0",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.66.0",
     "vite": "^8.2.2",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.0",
+    "react-dom": "18.3.1"
   },
   "dependencies": {
-    "yaml": "^2.9.1"
+    "yaml": "^2.9.1",
+    "@kubohiroya/turbowarp-extension-data-editor": "0.2.1"
   },
   "peerDependencies": {
-    "@kubohiroya/turbowarp-named-data": ">=0.1.0 <1"
+    "@kubohiroya/turbowarp-named-data": "0.3.1"
+  },
+  "gitHead": "7429d0707e0c46099fa89d09f456a43a29919395",
+  "x-turbowarp-source": {
+    "revision": "7429d0707e0c46099fa89d09f456a43a29919395",
+    "revisionRole": "base-commit",
+    "sourceState": "local-release-overlay"
   }
 }

package/schemas/block-editor-fixed-inputs.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kubohiroya.github.io/turbowarp-structured-data/schemas/block-editor-fixed-inputs.schema.json",
+  "$defs": {
+    "forEachAtPath": {
+      "type": "object",
+      "properties": {
+        "MAX": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1000
+        }
+      },
+      "required": [
+        "MAX"
+      ],
+      "additionalProperties": true
+    }
+  }
+}

package/src/editor-schema.ts

@@ -0,0 +1,16 @@
+import type {SourceEditorOptions} from '@kubohiroya/turbowarp-extension-data-editor/schema';
+import {extensionConfig} from './config.js';
+import {sourceBinding} from './source-editor.js';
+import {jsonValueSchemaBundle} from '@kubohiroya/turbowarp-extension-data-editor/schema';
+import {parseJsonDocument, parseYamlDocument} from './codecs.js';
+import {parseJson} from './core.js';
+const definitions = [
+ {editorId: 'json-document-source', opcodes: ['parseJson'], bindings: [sourceBinding('TEXT', jsonValueSchemaBundle, parseJsonDocument)]},
+ {editorId: 'yaml-document-source', opcodes: ['parseYaml'], bindings: [sourceBinding('TEXT', jsonValueSchemaBundle, parseYamlDocument, parseYamlDocument, 'yaml')]},
+ {editorId: 'json-path-value-source', opcodes: ['setJsonAtPath'], bindings: [sourceBinding('VALUE', jsonValueSchemaBundle, parseJson)]}
+];
+
+export const sourceEditorDefinitions: readonly SourceEditorOptions[] = definitions.map(({editorId, opcodes, bindings}) => ({
+  apiVersion: 1, extensionId: extensionConfig.id, editorId, opcodes: opcodes.map(opcode => `${extensionConfig.id}_${opcode}`), bindings,
+  validationContext: () => ({consumerId: extensionConfig.id, nowMs: Date.now(), settings: null})
+}));

package/src/extension.ts

@@ -1,3 +1,6 @@
+import {fixedInputEditorDefinitions, registerFixedInputEditors} from './fixed-input-editors.js';
+import {sourceEditorDefinitions} from './editor-schema.js';
+import {registerSourceEditors} from './source-editor.js';
 import definitions from './block-definitions.json';
 import {
   bindNamedDataRegistryLifecycle,
@@ -72,6 +75,10 @@ const blockDefinitions = definitions.blocks as readonly BlockDefinition[];
 
 export class StructuredDataExtension implements TurboWarpExtension {
   private readonly enabled: boolean;
+  private disposed = false;
+  private readonly releaseRuntimeListeners: () => void;
+  private readonly unregisterSourceEditors: () => void;
+  private readonly unregisterFixedInputEditors: () => void;
   private registries = new WeakMap<object, Map<string, StructuredDataBinding>>();
   private iterationStacks = new WeakMap<object, ActiveIteration[]>();
   private nextRevision = 1;
@@ -85,6 +92,18 @@ export class StructuredDataExtension implements TurboWarpExtension {
     namedDataEnabled = isNamedDataRegistryMvpEnabled()
   ) {
     this.enabled = enabled;
+    this.unregisterSourceEditors = registerSourceEditors(Scratch, enabled ? sourceEditorDefinitions : []);
+    const runtime = Scratch.vm?.runtime;
+    const onDispose = () => {void this.dispose();};
+    const onStop = () => this.clearRuntimeState();
+    this.releaseRuntimeListeners = () => {
+      runtime?.off?.('RUNTIME_DISPOSED', onDispose);
+      runtime?.off?.('PROJECT_STOP_ALL', onStop);
+    };
+    let unregisterFixed = () => {};
+    try {
+      unregisterFixed = registerFixedInputEditors(Scratch, enabled ? fixedInputEditorDefinitions : []);
+      this.unregisterFixedInputEditors = unregisterFixed;
     if (namedDataEnabled) {
       this.namedDataProvider = new StructuredDataNamedDataProvider({
         get: (target, name) => this.registries.get(target)?.get(name)
@@ -100,12 +119,18 @@ export class StructuredDataExtension implements TurboWarpExtension {
           runtime,
           this.namedDataRegistry
         );
-        runtime.on?.('RUNTIME_DISPOSED', () => {
-          void this.dispose();
-        });
+        runtime.on?.('RUNTIME_DISPOSED', onDispose);
       }
     }
-    Scratch.vm?.runtime?.on?.('PROJECT_STOP_ALL', () => this.clearRuntimeState());
+    runtime?.on?.('PROJECT_STOP_ALL', onStop);
+    } catch (error) {
+      this.releaseRuntimeListeners();
+      unregisterFixed();
+      this.unregisterSourceEditors();
+      this.unbindNamedDataRegistryLifecycle?.();
+      void this.namedDataRegistration?.unregister().catch(() => {});
+      throw error;
+    }
   }
 
   public getNamedDataProvider(): StructuredDataNamedDataProvider | undefined {
@@ -117,6 +142,11 @@ export class StructuredDataExtension implements TurboWarpExtension {
   }
 
   public async dispose(): Promise<void> {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.releaseRuntimeListeners();
+    this.unregisterFixedInputEditors();
+    this.unregisterSourceEditors();
     await this.namedDataRegistration?.unregister();
     this.unbindNamedDataRegistryLifecycle?.();
   }

package/src/fixed-input-editors.ts

@@ -0,0 +1,67 @@
+import {parseFixedNumberInput} from '@kubohiroya/turbowarp-extension-data-editor';
+import type {FixedInputEditorOptions} from '@kubohiroya/turbowarp-extension-data-editor';
+import {extensionConfig} from './config.js';
+import {fixedInputSchemaBundle} from './fixed-input-schema.js';
+
+
+export const fixedInputEditorDefinitions: readonly FixedInputEditorOptions[] = [{
+  apiVersion: 1, extensionId: extensionConfig.id, editorId: 'forEachAtPath-fixed-inputs',
+  opcodes: [`${extensionConfig.id}_forEachAtPath`],
+  contractId: 'turbowarp-structured-data:forEachAtPath.MAX', contractRevision: 'fixed-inputs-v1',
+  bindings: [{argument: 'MAX', schemaBundle: fixedInputSchemaBundle,
+    control: {kind: 'number', label: 'MAX'},
+    read(value) {
+      if (typeof value !== 'string' && typeof value !== 'number') throw new TypeError('Expected a literal maximum.');
+      if (typeof value === 'string' && value.trim() === '') throw new TypeError('Blank maximum stays readonly.');
+      // Existing nonempty finite Number aliases may project; no-op saving retains the exact raw token.
+      const number = Number(value);
+      if (!Number.isFinite(number)) throw new TypeError('Maximum must be finite.');
+      return number;
+    },
+    encode(value) {
+      const parsed = parseFixedNumberInput(value);
+      if (parsed.kind !== 'valid') throw new TypeError('Expected a finite numeric token.');
+      return parsed.token;
+    },
+    validateCandidate(value) {
+      const parsed = parseFixedNumberInput(value);
+      return parsed.kind === 'valid' && Number.isInteger(parsed.value) && parsed.value >= 1 && parsed.value <= 1000 ? []
+        : [{path: '/inputs/MAX', message: 'Maximum must be an integer from 1 to 1000.'}];
+    }
+  }],
+  validationContext: () => ({consumerId: extensionConfig.id, nowMs: Date.now(), settings: null})
+}];
+
+interface RuntimeLifetime {
+  on?: (event: string, listener: () => void) => void;
+  off?: (event: string, listener: () => void) => void;
+}
+
+/** Register metadata only; the GUI startup capability owns editor activation. */
+export function registerFixedInputEditors(
+  scratch: unknown, definitions: readonly FixedInputEditorOptions[], runtimeOverride?: RuntimeLifetime
+): () => void {
+  const host = scratch as {gui?: {blockEditors?: {apiVersion?: number;
+    registerFixedInputEditor?: (options: FixedInputEditorOptions) => () => void}};
+    vm?: {runtime?: RuntimeLifetime}};
+  const api = host.gui?.blockEditors;
+  if (!definitions.length || api?.apiVersion !== 1 || typeof api.registerFixedInputEditor !== 'function') return () => {};
+  const runtime = runtimeOverride ?? host.vm?.runtime;
+  const removers: (() => void)[] = [];
+  let active = true;
+  const dispose = () => {
+    if (!active) return;
+    active = false;
+    runtime?.off?.('RUNTIME_DISPOSED', dispose);
+    for (const remove of removers.splice(0).reverse()) remove();
+  };
+  try {
+    for (const definition of definitions) {
+      const remove = api.registerFixedInputEditor.call(api, definition);
+      if (typeof remove !== 'function') throw new TypeError('Invalid fixed input registration disposer.');
+      removers.push(remove);
+    }
+    runtime?.on?.('RUNTIME_DISPOSED', dispose);
+  } catch (error) {dispose(); throw error;}
+  return dispose;
+}

package/src/fixed-input-schema.ts

@@ -0,0 +1,16 @@
+import type {SchemaBundle} from '@kubohiroya/turbowarp-extension-data-editor/schema';
+import document from '../schemas/block-editor-fixed-inputs.schema.json';
+
+const source = {repository: 'turbowarp-structured-data', path: 'schemas/block-editor-fixed-inputs.schema.json',
+  symbol: '#/$defs/forEachAtPath/properties/MAX'};
+
+/** The on-disk owner Schema is canonical; this is its single-field projection. */
+export const fixedInputSchemaBundle: SchemaBundle = {
+  identity: {ownerId: 'turbowarp-structured-data', contractId: 'forEachAtPath.MAX', revision: 'fixed-inputs-v1', variantId: 'default'},
+  dialect: '2020-12',
+  root: {retrievalUri: 'https://kubohiroya.github.io/turbowarp-structured-data/schemas/forEachAtPath-MAX.schema.json',
+    document: document.$defs.forEachAtPath.properties.MAX, artifact: {role: 'canonical-schema', source}},
+  resources: [],
+  provenance: {canonicalSources: [source, {repository: 'turbowarp-structured-data', path: 'src/core.ts', symbol: 'iterationEntries'}],
+    generatedFiles: [{repository: 'turbowarp-structured-data', path: 'docs/schemas/block-editor-fixed-inputs.schema.json'}], referenceSchemas: [], generationSources: [{repository: 'turbowarp-structured-data', path: 'scripts/generate-fixed-input-docs.mjs'}]}
+};

package/src/source-editor.ts

@@ -0,0 +1,57 @@
+import {compileSchemaBundle, validateSchemaInput} from '@kubohiroya/turbowarp-extension-data-editor/schema';
+import type {SchemaBundle, SchemaDocument, SchemaJsonValue, SourceBinding, SourceEditorOptions} from '@kubohiroya/turbowarp-extension-data-editor/schema';
+
+export function canonicalBundle(ownerId: string, contractId: string, document: SchemaDocument, ownerSource: {path: string; symbol: string}): SchemaBundle {
+  const path = `schemas/${contractId}.schema.json`;
+  const source = {repository: ownerId, path};
+  return {
+    identity: {ownerId, contractId, revision: 'source-forms-v1', variantId: 'default'},
+    dialect: '2020-12',
+    root: {retrievalUri: `https://kubohiroya.github.io/${ownerId}/schemas/${contractId}.schema.json`, document,
+      artifact: {role: 'canonical-schema', source}},
+    resources: [], provenance: {canonicalSources: [source, {repository: ownerId, ...ownerSource}], generatedFiles: [], referenceSchemas: [], generationSources: []}
+  };
+}
+
+export function sourceBinding(argument: string, bundle: SchemaBundle,
+  read: (source: string) => unknown, check: (source: string) => unknown = read,
+  format: 'json' | 'yaml' = 'json', uiSchema?: SourceBinding['variants'][number]['uiSchema']): SourceBinding {
+  const compiled = compileSchemaBundle(bundle);
+  return {
+    argument,
+    variants: [{variantId: 'default', format, schemaBundle: bundle, ...(uiSchema ? {uiSchema} : {})}],
+    decode(source) {return {source, format, variantId: 'default', data: read(source) as SchemaJsonValue};},
+    validateSource(source, context) {
+      if (compiled.kind !== 'compiled') return {source, result: {kind: 'schema-error', diagnostics: [{code: 'source-schema-invalid'}]}};
+      try {
+        const data = read(source) as SchemaJsonValue;
+        return {source, result: validateSchemaInput(compiled.validator, data, {context,
+          ownerValidate: () => {
+            try {check(source); return {kind: 'valid', issues: []};}
+            catch {return {kind: 'invalid', issues: [{dataPath: '', ruleId: 'source-owner-invalid'}]};}
+          }})};
+      } catch {return {source, result: {kind: 'invalid', diagnostics: [{code: 'source-decode-invalid'}]}};}
+    }
+  };
+}
+
+/** The optional capability keeps legacy hosts and the startup flag safely inactive. */
+export function registerSourceEditors(scratch: unknown, definitions: readonly SourceEditorOptions[]): () => void {
+  const host = scratch as {gui?: {blockEditors?: {apiVersion?: number; registerSourceEditor?: (options: SourceEditorOptions) => () => void}};
+    vm?: {runtime?: {on?: (event: string, listener: () => void) => void; off?: (event: string, listener: () => void) => void}}};
+  const api = host.gui?.blockEditors;
+  if (api?.apiVersion !== 1 || typeof api.registerSourceEditor !== 'function') return () => {};
+  const removers: (() => void)[] = [];
+  let active = true;
+  const dispose = () => {
+    if (!active) return;
+    active = false;
+    host.vm?.runtime?.off?.('RUNTIME_DISPOSED', dispose);
+    for (const remove of removers.splice(0).reverse()) remove();
+  };
+  try {
+    for (const definition of definitions) removers.push(api.registerSourceEditor.call(api, definition));
+    host.vm?.runtime?.on?.('RUNTIME_DISPOSED', dispose);
+  } catch (error) {dispose(); throw error;}
+  return dispose;
+}

package/templates/README.ja.md

@@ -181,3 +181,16 @@ release consistency checkでは、exact-version README／CDN例に加え、`docs
 
 third-party componentを含む場合は
 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)に記載します。
+
+## 固定引数の編集フォーム（S3-4）
+
+共通エディターの起動時フラグ `blockEditorFixedInputs` とDialogsがONのGUIでは、`forEachAtPath` の `MAX` だけを固定フォームとして登録します。旧GUI・フラグOFFでは追加登録を行いません。Schemaの正本は `schemas/block-editor-fixed-inputs.schema.json#/$defs/forEachAtPath/properties/MAX`、codecと登録は `src/fixed-input-editors.ts` です。既存raw値・未変更alias・未知enumは無操作保存で書き換えず、reporterを評価しません。明示変更だけを検査し、他の引数やブロック宣言、保存形式を変更しません。
+
+MAXは整数1〜1000です。新しい入力には共通の有限数値token規則も適用し、途中入力を保存しません。MVP flagがOFFなら登録せず、NAME/PATH・staticLiteral由来の接続可否を変更しません。
+
+登録はoptional API（apiVersion:1）に限定し、RUNTIME_DISPOSED/明示disposeで解除します。起動フラグOFF＋再読込で従来経路へ切り戻せます。依存を戻す場合はmanifest/lock/実解決を一組で復旧します。npm公開や後続段階の動的候補は含みません。
+
+Schemaが記述する契約の根拠は実getInfoの宣言と既存の純粋なruntime変換です。SchemaBundleのretrievalUriはこのローカル文書の識別子であり、URL配信済み・HTTP取得によるref解決を意味しません。Schemaは同梱文書だけでcompileします。
+既存MAXの非空finiteなNumber alias（例`001`・`+1`・`0x10`）はNumberによる表示投影だけを行い、無変更rawを保存し直しません。空白・非finite・投影不能値はreadonlyとし、0/defaultを補いません。新しい入力にはこれらaliasを許可せずNP-finite-new-input-v1を適用します。
+
+登録は拡張インスタンスの構築時に存在する任意の editor API を使用します。後からの API 追加や差し替えには自動追従しません。起動設定を変更した場合は GUI を再読み込みし、拡張インスタンスを再構築してください。

package/templates/README.md

@@ -196,3 +196,16 @@ site and `blockIconURI` remains a `data:image/svg+xml;base64,...` URI.
 
 Third-party components, when present, are listed in
 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
+
+## 固定引数の編集フォーム（S3-4）
+
+共通エディターの起動時フラグ `blockEditorFixedInputs` とDialogsがONのGUIでは、`forEachAtPath` の `MAX` だけを固定フォームとして登録します。旧GUI・フラグOFFでは追加登録を行いません。Schemaの正本は `schemas/block-editor-fixed-inputs.schema.json#/$defs/forEachAtPath/properties/MAX`、codecと登録は `src/fixed-input-editors.ts` です。既存raw値・未変更alias・未知enumは無操作保存で書き換えず、reporterを評価しません。明示変更だけを検査し、他の引数やブロック宣言、保存形式を変更しません。
+
+MAXは整数1〜1000です。新しい入力には共通の有限数値token規則も適用し、途中入力を保存しません。MVP flagがOFFなら登録せず、NAME/PATH・staticLiteral由来の接続可否を変更しません。
+
+登録はoptional API（apiVersion:1）に限定し、RUNTIME_DISPOSED/明示disposeで解除します。起動フラグOFF＋再読込で従来経路へ切り戻せます。依存を戻す場合はmanifest/lock/実解決を一組で復旧します。npm公開や後続段階の動的候補は含みません。
+
+Schemaが記述する契約の根拠は実getInfoの宣言と既存の純粋なruntime変換です。SchemaBundleのretrievalUriはこのローカル文書の識別子であり、URL配信済み・HTTP取得によるref解決を意味しません。Schemaは同梱文書だけでcompileします。
+既存MAXの非空finiteなNumber alias（例`001`・`+1`・`0x10`）はNumberによる表示投影だけを行い、無変更rawを保存し直しません。空白・非finite・投影不能値はreadonlyとし、0/defaultを補いません。新しい入力にはこれらaliasを許可せずNP-finite-new-input-v1を適用します。
+
+Registration uses the optional editor API available when the extension instance is constructed. Adding or replacing that API later is not followed automatically; reload the GUI and reconstruct the extension instance after changing the startup configuration.