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

package/docs/schema.md

@@ -0,0 +1,43 @@
+# 固定Schemaのpure検証API
+
+`@kubohiroya/turbowarp-extension-data-editor/schema`はDOM・React・RJSFをimportせず、同梱resourceだけで同期検証する。既存の登録API・GUIフラグ・保存データは変更しない。
+
+`compileSchemaBundle(bundle)`は`compiled`、`schema-error`、`execution-error`を区別する。成功した`validator.validate(data, {consumerId})`は`valid`、`invalid`、`execution-error`を返す。入力診断は`toValidationIssues()`で従来の表示用型へ変換できる。
+
+bundleは`identity`・`dialect`・`root`・`resources`・`provenance`を持つ。方言は`draft-07`または`2020-12`を必ず指定する。各resourceの`retrievalUri`はfragmentなしの絶対URI。HTTP形式でもネットワークへアクセスせず、URNも使える。`$id`・相対/絶対ref・再帰refをローカルで解決し、実効IDが異なる場所と衝突するbundleは拒否する。bundleごとのAjv instanceで同じIDの異版を隔離する。
+
+artifactの`canonical-schema`は`canonicalSources`、`generated-schema`は`generatedFiles`と`generatedFrom`へ対応させる。参照用Schemaと生成処理はcompile入力にしない。正本・生成物・参照用・生成処理の同一repository/path/symbolを重複分類しない。metadataにあるファイル・URLを探索して読み込む機能はない。
+
+Schemaと入力を専用snapshotへコピーして検証する。coercion・default補完・追加property削除を行わず、frozen入力も扱う。privateなSchema snapshot内でURI/方言の同義識別子を正規化するが、所有側のSchema・rawデータ・正本や生成物を書き換えない。JSONの有限数・文字列・真偽値・null・密な配列・plain objectを受け付ける。循環、class instance、accessor、非JSON値を拒否し、getter・toJSON・入力iteratorを実行しない。
+
+snapshotは最大100,000訪問値・深さ128に制限し、超過は`limit-exceeded`の実行診断とする。制限のためにデータを切り捨てて成功扱いにはしない。Schemaの非同期検証は受け付けない。標準formatは直接依存のajv-formatsにあるものを使い、未知formatを黙って無視しない。
+
+診断は固定codeとscope、必要なresource URI・JSON Pointer・keywordを持つ。required/additionalPropertiesは問題の子項目へPointerを付け、URI fragmentをschemaPathへ分解する。raw値・Ajvのparams・例外本文をコピーしない。未知ref・Schema不正とengine実行失敗を混同しない。
+
+同期owner合成とRJSFの明示経路はS1-3で追加済み。owner形式adapterと配布はS1-4で追加し、16契約をS1-5で横断確認した。既存フォームへ自動接続しない。新入口の利用を外すことで従来の経路へ戻せる。
+
+実装根拠: [Ajvの方言](https://ajv.js.org/json-schema.html)、[Schema登録と隔離](https://ajv.js.org/guide/managing-schemas.html)。
+
+## S1-3: 同期owner検証と明示フォーム
+
+`validateSchemaInput(compiled, data, {context, ownerValidate?})` はcontextを先に検査し、構造検証に成功したときだけ同期ownerを1回呼ぶ。`context`にはconsumerId、有限のnowMs、JSON互換settingsが必要。候補とcontextの保護snapshotを渡し、入力を正規化値へ置換しない。Promise/thenableはasync-owner-unsupported、例外はowner-validation-failed、不正な結果はowner-result-invalid。不正contextはowner-context-invalid。拒否Promiseも処理して未処理rejectionを残さない。
+
+`/rjsf`の`createSchemaBundleEditor`と`registerSchemaBundle`は、従来optionsのschemaの代わりにschemaBundle、呼出しごとの`validationContext: () => context`、任意のownerValidateを受ける。構造・同期owner検証はlive/save/未mount保存で共通。legacy validateDataはこの検証が成功した後、保存時だけ実行する。新経路のreadはdefaultを補わず、既存createSchemaEditorのdefault初期化は維持する。
+
+`SchemaBundleEditorOptions`の型引数を省略した場合は`null`設定を使う。`SchemaValidationContext` / `SyncOwnerValidator`と同じ既定であり、options変数にも`settings: null`を指定できる。設定を使う場合は明示型またはfactoryの推論を使う。public型の検査は省略・inline・明示型と不正設定の負例を含む。
+
+RJSF v5用には正本を変えないprivateな表示Schemaを作る。閉じたresource graphのID/anchor/refを解決し、wrapper内のfragment pointerへ展開する。private表示側で不要になったID宣言を除くが、正本・検証制約は変更しない。検証の正本は常に元bundleのengineで、RJSFへextraErrorsを渡す。JSON Pointerの特殊キーを保持し、共通field-errorsのARIA表示・訂正・解除へ接続する。
+
+2020-12 prefixItems、dynamic/recursive ref、RJSFが展開を終了できないobject再帰は、フォーム登録時に明示的に拒否する。配列items経由の再帰と両方言の同梱refは合成フォームで確認する。これらの表示制限はheadless engineの受理範囲を狭めない。現行14本番契約の実フォームと段階2で新規予定の9固定契約は、段階2の具体計画で区別して検証する。旧16契約には撤去したTemplateサンプル2件が含まれる。[現行の再検証手順](template-fixture-separation.ja.md#current-verification)に従い、Templateの旧入口を検証対象にしない。
+
+この工程は拡張へのeditor登録、GUI依存更新、binding、候補UIを追加しない。新APIを呼ばない既存利用者の挙動は維持する。
+
+## S1-4pの配布
+
+段階1中はnpmへ未公開のAPIを既存の0.1.0公開版と取り違えないよう、ownerの追加pure型依存を検証済みGit commitへ固定する。Git依存のprepareで既存buildを実行し、dist/JS/型/CSS/webpack4/build-infoを生成する。ローカルfile:/tmp依存は公開manifestへ残さない。npm publishや既存GUI依存の変更はこの作業に含めない。
+
+既存hostがBlockEditorRegistrationAPI/BlockEditorServiceを実装する場合、新しいregisterSchemaBundleは任意のcapabilityとして追加する。既存の3 memberだけを持つobjectも代入できる。createBlockEditorServiceの戻り値ではSchemaBundleBlockEditorRegistrationAPIとしてこのcapabilityを保証し、外部hostでは存在を確認して利用する。ownerのGit依存はpureファイルだけでなく./rjsfの修正版宣言も照合する。固定するcommitと実解決の対応は公開時の検証記録に残す。
+
+ownerのvalidate*Sourceは元source/未正規化データと診断を分けて返す。形式不正・未知variantで生のparser例外を診断へ混ぜない。Camera系は既存readerと同じtrim/BOM・ROSのtrim後サイズ条件を維持するが、返すsourceは原文を保持する。lib-editor/schemasのemit copyは配布用生成物であり、bundleのartifact.roleは元のSchema正本/TypeBox・Spec生成物の由来を表す。
+
+旧SchemaEditorOptions.schema経路は既存format/error/defaultの互換性とprovenance不在を考慮し、従来のRJSF validatorを継続する。明示bundleだけをpure engineへ接続し、それぞれlive/save/未mountで同じ判定を使う。webpack4 helperには新しい/schemaの事前build入口も追加し、既存4入口とCSS aliasを保つ。

package/docs/source-forms.ja.md

@@ -0,0 +1,19 @@
+# 固定Schemaを使うSource/Form編集
+
+既存の`register`・`registerSchema`・`registerSchemaBundle`は変更しない。追加の`registerSourceEditor`は、ホスト提供APIでは任意、`createBlockEditorService()`の返す`SourceBlockEditorRegistrationAPI`では必須となる。既存の`SchemaBundleBlockEditorRegistrationAPI`を実装するホストに新メソッドを要求しない。公開入口は従来の8つを維持する。
+
+型と汎用有限JSON契約`jsonValueSchemaBundle`は`./schema`から取得する。この入口はDOM・Reactを必要としない。`PreparedEditorDefinition`と`PreparedSave`は`.`・`./rjsf`、UIを含む`createSourceEditor`は`./rjsf`から取得する。拡張側は型とpure owner adapterだけを参照し、React/RJSFを重複同梱しない。汎用JSON Schemaの正本は`src/json-value.ts`の`jsonValueSchema`であり、JSONファイルの生成物を正本と呼ばない。
+
+`SourceEditorOptions`は固定した`bindings`と、保存のたびに新しい検証contextを返す`validationContext`を受け取る。各bindingは引数名、固定variant一覧、必要なら空scene等を明示するsourceOnlyVariants、`decode`と`validateSource`を持つ。`decode(source)`は`SourceDocument`を返し、その`source`に原文のraw文字列、`data`に編集表示用の値、`format`と`variantId`に形式と固定variantの識別子を保持する。`validateSource(source, context)`は`SourceValidation`を返し、その`source`に検証した候補文字列、`result`に検証結果を保持する。opcodeは`extensionId_opcode`の完全修飾名とする。複数のbindingを一つのeditorに束ねれば、一回のSaveで全候補を検証し、単一transactionとして保存する。
+
+追加経路は`prepareSave`で候補を一回だけ生成し、同一文字列をowner検証とcommitへ渡す。診断やcallback出力はgetter・iteratorを実行せずJSON snapshotし、不正値や非同期結果を拒否する。contextは保存試行ごとに一回取得してfreezeする。単一sessionとDescendantSessionの両方がこの経路を使う。旧`validate/createPatch`経路にprepared定義を渡すと安全に拒否する。prepared単一sessionの登録解除・再登録は保存を失効させる。既存legacy sessionの登録解除後の挙動は変更しない。
+
+追加UIにはSourceとForm、明示的な形式・固定variant選択による新規作成を用意する。Formは実在するJSON値を有限のReactツリーとして描画する。既存RJSFの描画・default初期化には変更を加えず、新経路ではroot scalar/array、任意キー、再帰、prefixItemsを扱うためRJSFのSchema変換制約を引き継がない。Schemaのkeywordを削除せず、正本の両方言・resource/ref/anchorを共通engineで検証する。表示用コピーだけを同じURI registryで解決する。閉じたenum/const unionは選択UI、互換なraw値を許すenum候補は`ui:enum`で提示する。外部候補一覧や新しいenum項目の登録は後続工程であり、この追加UIには含めない。
+
+無変更・編集後の差戻し・Cancelは原文とUndo履歴を保持する。JSON range/YAML ASTで未編集箇所を保持し、既定値、const、minItemsによるデータ補完を行わない。ownerが受理したJSONのBOMや前後のtrim whitespaceを保持し、厳密なJSON codec自体の文法は拡張しない。YAMLの空配列等をJSONと誤認するownerには単一document markerを付けてYAMLを維持する。Formからの暗黙variant変更は拒否する。
+
+安全に保持できないalias/anchor/tag自体の編集、コメントを消す部分置換などは保存を拒否し、`Discard form edits`で原文Sourceへ戻れる。非有限数に変換されるJSON数値は共通の有限JSON契約で扱えない。既存runtimeのparserは変更せず、旧GUIやflag OFFでは従来の実行を維持する。これらを無条件なForm対応済みとは数えない。
+
+GUIの`blockEditorSourceForms`は起動時固定・既定OFFで、`blockEditorDialogs=1`も必要。OFFで新capabilityを公開せず、従来の登録APIを維持する。ロールバックはflag OFFで再読込し、必要ならconsumer→producer→共通の順で差分と依存を戻す。raw形式を自動移行しないため逆変換は不要。
+
+開発時のローカルtarballはnpm公開を行わず検証できる。公開可能な配布の受け入れ条件はmanifest・lock・実解決・build-info/capabilityの一致である。作業コピーのHEADだけを実装済みのGit artifactと呼ばない。build-infoの`sourceState: working-tree`と`sourceSha256`で未commit実装を区別し、公開Git pinへの置換は別の承認・検証条件とする。

package/docs/stage-2-publication.ja.md

@@ -0,0 +1,35 @@
+# 段階2の公開Git配布
+
+管理: https://github.com/kubohiroya/turbowarp-extension-data-editor/issues/31
+
+`feat/schema/stage2-source-forms` → `main`。Sourceを正本とする固定Schema編集とprepared-source-v1保存を追加する。GUIは起動時固定の`blockEditorSourceForms`既定OFFと`blockEditorDialogs`を必要とする。既存API、8公開入口、CSS、rawの無変更保存を維持する。
+
+先行ローカル検証は共通212ケース、全体の関連659ケースと実GUI5代表×8手順。再実行を加算していない。共通ローカルartifact SHA-256は`f3f66138902e4fb869540029460f800492ae0a23d29aacdd90eaf6d2b0766672`、sourceSha256は`aef366417f026ececbcb718f8001f3b5dddc5e34a2fdb3bc69d5390ce2e9118e`。このartifactは未commit基準d910ed0…であり公開Gitから再生成するartifactとは区別する。
+
+公開順序: 共通 → Scene Graph / Camera Source → consumerとGUI。公開Git SHAは各consumer manifest・lock・実解決・build-infoへ揃える。npm公開を必要としない。
+
+受け入れ基準: ./schemaのpure型、prepared公開型、旧型の互換、単一/子孫session、同じ候補の検査/commit、複数引数atomic、登録失効を維持する。GUIの数値入力・enum/ref/anchor表示とraw保持を確認する。無効なYAML alias/tagやコメントを消す置換はFormで拒否しSourceへ明示的に戻す。
+
+ロールバック: sourceForms OFFで再読込。必要ならconsumer→producer→共通の逆依存順でrevertし、manifest・lock・実解決を一体で戻す。rawの自動移行は行わない。merge・npm公開・Pages手動再公開は本工程に含めない。
+
+公開Git artifactの検証結果とCI URLはPR本文および集約記録へ追記する。履歴のローカル検証は置換しない。
+
+## 0.2.0のリリース追補
+
+2026-10-18、日本時間。ユーザーは段階2全体のcommit・push・PR・merge・npm公開を承認した。新規API追加に合わせ共通を0.2.0へminor更新する。文書レビューのdecode説明訂正を含む。先行0.1.0 Git/file artifactと過去659件の記録は採取時点の履歴として保持する。
+
+安定版build段階ではfresh frozen install、全commonテスト、CI/site/infrastructure、typecheck、8公開入口・CSS・packを検証する。最終merge SHAからpackした同一tarballをnpmへ公開し、registry integrityとbuild-infoを照合する。producer/consumerは最終共通Git SHAへpin・lock・allowBuilds・実解決を揃える。GUIの起動時固定・既定OFFを維持する。
+
+公開後の問題には、フラグOFFと逆依存順のrevertで対応する。公開済み版を削除せず、修正は新しいversionで公開する。
+
+## 公開直前の依存audit追補
+
+共通0.2.0はまだnpm未公開の時点で、direct fast-uri3.1.0に8high/1moderateのadvisoryを確認した。対象packageはfast-uriだけである。間接AJVで既に使っている3.1.8へ直接依存も固定し、lockの全fast-uri edgeを3.1.8へ統一する。Schemaの正本・owner・既存API・保存形式は変更しない。
+
+0.2.0の公開前修正として別PRでmainへ統合し、後続pinには修正後の最終SHAを使う。旧4818a4dの検証は履歴として保持し、最終配布の証拠と区別する。fresh install後にaudit、Schema/ref/診断/Source/Form/8入口を含む全common検証、packを確認する。一次資料: https://github.com/advisories/GHSA-qw65-cvwx-89v3 および保存した9件のaudit JSON。
+
+## 最終GUI/site固定の追補
+
+共通配布artifactはsecurity修正を含むGit `76fa1d50a3c188082ceef723ea018a9d8769ea6e`、GUIは `1caa902a51ec3338b9b30372174f71d04044ecd8` へ固定する。site/source.jsonのGUI/coreをこの対応へ更新する。siteのmain revisionと共通配布のcore revisionは役割が異なるため、siteだけの追補でconsumerのcore pinを循環更新しない。source/package/build入力がcore76faから不変であることを確認する。
+
+最終production GUIの実依存34edgeがlockと一致し、62block-editorテスト・既存addon33テスト・全6browserentryのproduction buildが成功。共通所有のChromium E2E6件もこのGUI/coreの組合せで成功した。npm公開とowner代表Source/Form確認の最終結果は集約記録へ保存する。既定OFFは維持する。

package/docs/template-fixture-separation.ja.md

@@ -0,0 +1,43 @@
+# Template用途依存からの試験分離
+
+owner横断検証は14契約・8packageです。Templateの旧2サンプルは対象外にしました。JSON/YAML編集の任意サンプルはexamples/document-properties.mjs、対応する実serviceの試験はtest/generic-document.test.mjsで所有します。Templateやその公開APIをimportしません。
+
+例には任意のtext/enabledと追加キーを使用します。required/defaultや業務条件はありません。新たなpackage exportや標準ブロックは追加せず、examplesはnpm配布APIにしません。登録は呼出側が明示的に行います。
+
+旧16契約・9packageという過去結果は変更しません。旧2入力とprovenanceはtest/fixtures/schema-stage1/historyへ保持しました。共通src・8公開入口・依存pin/lock・CSS/buildは変更しません。
+
+`docs/schema-stage1-contracts.json`は旧16契約の採取結果として保持します。現行の件数の正本は実行する`scripts/verify-schema-stage1.mjs`であり、Templateのない8packageのisolation indexを渡して検証します。今回の結果・依存照合はTemplate側のローカル集約記録に保存し、過去結果を上書きしません。
+
+<a id="current-verification"></a>
+
+## 現行の再検証手順（14契約・8package）
+
+対象は共通エディタと7つの実拡張packageです。Templateの`./editor-schema`は撤去済みで、共通依存も持ちません。Templateをこの手順のownerやindexに含めないでください。Template自体のhello/build/manifestはTemplate側で別に検証します。
+
+まず各ownerの採用commit・依存pin/lock・実解決を確認し、その版のbuild生成物を用意します。共通repoの`scripts/verify-schema-package.mjs`を各owner checkoutをcwdとして実行し、pure入口に必要なruntime依存だけを引数で指定します。共通自身の入口は`/schema`、7拡張の入口は`/editor-schema`です。新たな公開・install・依存更新を暗黙に行う手順ではありません。既存の検証済みartifactを使う場合も、その採取時のSHA・hash・実解決を確認します。
+
+検証成功ログの`isolated:`に出力されたディレクトリを、次の**8 keyだけ**へ対応付けて`isolation-index.json`を作成します。値は例示なので、実際のsource-free package検証先の絶対パスへ置き換えてください。
+
+```json
+{
+  "editor": "/path/to/isolated-editor",
+  "aframe": "/path/to/isolated-aframe",
+  "scene-graph": "/path/to/isolated-scene-graph",
+  "3d-scene-runtime": "/path/to/isolated-3d-scene-runtime",
+  "camera-source": "/path/to/isolated-camera-source",
+  "camera-calibration": "/path/to/isolated-camera-calibration",
+  "realtime-motion-capture": "/path/to/isolated-realtime-motion-capture",
+  "time-space-sync": "/path/to/isolated-time-space-sync"
+}
+```
+
+共通repoをcwdとして、同じindexで両方を実行します。
+
+```sh
+node scripts/verify-schema-stage1.mjs /path/to/isolation-index.json
+node scripts/verify-schema-dependencies.mjs /path/to/isolation-index.json
+```
+
+前者は`contracts: 14`・`packageCount: 8`と各契約の成功を確認します。後者はScene Graph→Runtime、Camera Source→Calibration/Motionの実bundle一致と、7consumerの共通pureファイル一致を確認します。失敗したownerをindexから落として成功扱いにせず、依存pin・lock・実解決・生成物を確認してください。
+
+この14契約は現行の本番owner契約です。共通examplesのJSON/YAML試験やTemplateのhello試験を本番契約へ足しません。段階2で新設予定の9固定契約は未実装の別計画で、現行検証が成功しても追加9件の実装済みを意味しません。旧16契約・9packageの再現にはその時点の旧commit/artifactを使い、ここに新Templateを混ぜません。過去の採取結果・手順は履歴として保持します。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubohiroya/turbowarp-extension-data-editor",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Custom editor sessions and UI for structured data handled by TurboWarp extensions",
   "type": "module",
   "sideEffects": [
@@ -37,7 +37,11 @@
     "./webpack4": {
       "require": "./webpack4.cjs"
     },
-    "./build-info": "./dist/build-info.json"
+    "./build-info": "./dist/build-info.json",
+    "./schema": {
+      "types": "./dist/schema.d.ts",
+      "import": "./dist/schema.js"
+    }
   },
   "files": [
     "dist",
@@ -54,9 +58,11 @@
     "build": "tsc --project tsconfig.json && node scripts/copy-react-css.mjs && node scripts/build-webpack4.mjs && node scripts/write-build-info.mjs",
     "test": "pnpm build && node --test test/*.test.mjs",
     "test:e2e:block-editor": "playwright test --config test/e2e/turbowarp/playwright.config.cjs",
+    "test:e2e:fixed-inputs": "E2E_FIXED_INPUTS=1 playwright test --config test/e2e/turbowarp/playwright.config.cjs --project=chromium-project-url fixed-inputs.spec.cjs",
     "test:e2e:infrastructure": "node --test test/e2e/turbowarp/infrastructure.test.cjs",
     "test:e2e:native": "E2E_NATIVE=1 pnpm test:e2e:block-editor",
-    "prepack": "npm run build"
+    "prepack": "npm run build",
+    "prepare": "npm run build"
   },
   "devDependencies": {
     "@playwright/test": "1.64.1",
@@ -73,6 +79,9 @@
     "@rjsf/core": "5.24.13",
     "@rjsf/utils": "5.24.13",
     "@rjsf/validator-ajv8": "5.24.13",
+    "ajv": "8.20.0",
+    "ajv-formats": "2.1.1",
+    "fast-uri": "3.1.8",
     "yaml": "^2.9.1"
   },
   "peerDependencies": {
@@ -89,5 +98,11 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "gitHead": "485f0e550e622235624b5e9176820161aeeba252",
+  "x-turbowarp-source": {
+    "revision": "485f0e550e622235624b5e9176820161aeeba252",
+    "revisionRole": "base-commit",
+    "sourceState": "working-tree-release-overlay"
   }
 }

package/webpack4.cjs

@@ -6,7 +6,7 @@ const withBlockEditorWebpack4 = (config, {hostRoot}) => {
     if (Array.isArray(config)) return config.map(item => withBlockEditorWebpack4(item, {hostRoot}));
     const prefix = '@kubohiroya/turbowarp-extension-data-editor';
     const alias = {...config.resolve?.alias};
-    for (const entry of ['index', 'rjsf', 'react', 'turbowarp']) {
+    for (const entry of ['index', 'rjsf', 'react', 'turbowarp', 'schema']) {
         alias[`${prefix}${entry === 'index' ? '' : `/${entry}`}$`] = path.join(__dirname, 'dist/webpack4', `${entry}.js`);
     }
     alias[`${prefix}/react/styles.css$`] = path.join(__dirname, 'dist/react.css');

package/dist/webpack4/shared-CQB3NG2A.js

@@ -1 +0,0 @@
-//# sourceMappingURL=shared-CQB3NG2A.js.map