@kubohiroya/turbowarp-structured-data 0.6.2 → 0.7.0

package/src/structured-provider.ts

@@ -1,4 +1,5 @@
 import {renderJsonDocument, renderYamlDocument} from './codecs.js';
+import {isNamedDataSchemaRefEnabled} from './config.js';
 import type {JsonValue} from './core.js';
 import {
   NamedDataError,
@@ -6,6 +7,7 @@ import {
   type NamedDataMetadata,
   type NamedDataProvider,
   type NamedDataReference,
+  type NamedDataSchemaRef,
   type NamedDataRepresentation,
   type NamedDataResolveContext
 } from '@kubohiroya/turbowarp-named-data/composition';
@@ -17,6 +19,7 @@ export interface StructuredDataBinding {
   value: JsonValue;
   revision: number;
   nativeRepresentation: 'json' | 'yaml';
+  schemaRef?: NamedDataSchemaRef;
 }
 
 export interface StructuredDataBindingStore {
@@ -31,7 +34,8 @@ export class StructuredDataNamedDataProvider implements NamedDataProvider {
 
   public constructor(
     private readonly store: StructuredDataBindingStore,
-    private readonly maxBodyBytes = STRUCTURED_BODY_MAX_BYTES
+    private readonly maxBodyBytes = STRUCTURED_BODY_MAX_BYTES,
+    private readonly schemaRefEnabled = isNamedDataSchemaRefEnabled()
   ) {}
 
   public canResolve(
@@ -57,7 +61,8 @@ export class StructuredDataNamedDataProvider implements NamedDataProvider {
       resolved.nativeRepresentation,
       representation,
       resolved.bytes.byteLength,
-      resolved.revision
+      resolved.revision,
+      resolved.schemaRef
     );
   }
 
@@ -76,7 +81,8 @@ export class StructuredDataNamedDataProvider implements NamedDataProvider {
         resolved.nativeRepresentation,
         representation,
         resolved.bytes.byteLength,
-        resolved.revision
+        resolved.revision,
+        resolved.schemaRef
       ),
       body: resolved.bytes,
       release: () => {
@@ -100,7 +106,12 @@ export class StructuredDataNamedDataProvider implements NamedDataProvider {
     reference: NamedDataReference,
     representation: NamedDataRepresentation,
     context: NamedDataResolveContext
-  ): {bytes: Uint8Array; revision: number; nativeRepresentation: 'json' | 'yaml'} {
+  ): {
+    bytes: Uint8Array;
+    revision: number;
+    nativeRepresentation: 'json' | 'yaml';
+    schemaRef?: NamedDataSchemaRef;
+  } {
     if (this.released) {
       throw new NamedDataError('NAMED_DATA_PROVIDER_RELEASED', 'The structured provider was released.');
     }
@@ -113,6 +124,23 @@ export class StructuredDataNamedDataProvider implements NamedDataProvider {
         `Structured data does not exist: ${reference.name}`
       );
     }
+    const requestedSchemaRef = reference.schemaRef;
+    if (requestedSchemaRef !== undefined && !this.schemaRefEnabled) {
+      throw new NamedDataError(
+        'NAMED_DATA_SCHEMA_UNRESOLVED',
+        'Schema reference resolution is disabled.'
+      );
+    }
+    if (
+      requestedSchemaRef !== undefined &&
+      (binding.schemaRef?.id !== requestedSchemaRef.id ||
+        binding.schemaRef?.version !== requestedSchemaRef.version)
+    ) {
+      throw new NamedDataError(
+        'NAMED_DATA_SCHEMA_VERSION_MISMATCH',
+        'Binding schemaRef does not match the requested reference.'
+      );
+    }
     const text = this.render(binding.value, representation);
     const bytes = new TextEncoder().encode(text);
     if (bytes.byteLength > this.maxBodyBytes) {
@@ -125,7 +153,8 @@ export class StructuredDataNamedDataProvider implements NamedDataProvider {
     return {
       bytes,
       revision: binding.revision,
-      nativeRepresentation: binding.nativeRepresentation
+      nativeRepresentation: binding.nativeRepresentation,
+      ...(requestedSchemaRef === undefined ? {} : {schemaRef: binding.schemaRef})
     };
   }
 
@@ -164,7 +193,8 @@ export class StructuredDataNamedDataProvider implements NamedDataProvider {
     nativeRepresentation: 'json' | 'yaml',
     representation: NamedDataRepresentation,
     byteLength: number,
-    revision: number
+    revision: number,
+    schemaRef?: NamedDataSchemaRef
   ): NamedDataMetadata {
     return {
       reference: {...reference},
@@ -176,7 +206,8 @@ export class StructuredDataNamedDataProvider implements NamedDataProvider {
           : 'application/yaml; charset=utf-8',
       byteLength,
       revision: String(revision),
-      replayable: true
+      replayable: true,
+      ...(schemaRef === undefined ? {} : {schemaRef})
     };
   }
 

package/templates/README.ja.md

@@ -144,6 +144,42 @@ renderer境界、`release()`／`releaseAll()`を説明します。
 
 extension IDまたはopcode変更時はschema-aware migrationを説明し、保存済み識別子が変わった場合にJavaScriptだけの差替えを案内しません。
 
+## 統合ビルド用module API
+
+このソースのbuildは、単体JSとは別に、統合用のESM入口`./bundle-module`と
+型宣言を`lib-module/`へ生成します。
+
+```ts
+import {bundleModuleMetadata, createExtension, type ScratchApi}
+  from '@kubohiroya/<package>/bundle-module';
+
+export function createMember(memberScratch: ScratchApi) {
+  return createExtension(memberScratch);
+}
+```
+
+import時はglobal Scratch / window / documentを参照せず、拡張の生成・登録を行いません。
+明示的なcreateExtension(memberScratch)ごとに新しいinstanceを返し、後から実行する
+ブロック・編集用補助処理・lifecycle callbackも同じhostを使います。factoryは
+Scratch.extensions.registerを呼びません。単体entryも同じfactoryを使い、登録は1回です。
+
+凍結されたbundleModuleMetadataはformatVersion: 1、元のid、unsandboxed条件を
+宣言します。統合hostが生成前に検査し、登録とdisposeを管理します。ID・opcode・
+保存データ形式を変更しません。
+
+既存のSTRUCTURED_DATA_MVP・NAMED_DATA_REGISTRY_MVP・Schema参照の起動フラグと既定値を維持します。生成時の任意の編集登録・named-data初期化には注入hostを使います。dispose()をawaitして、このinstanceの登録とlistenerを解除します。StructuredDataExtensionを直接newする内部コードでは、hostを先頭に渡し、その後に従来の任意の機能フラグ引数を渡します。
+
+yaml等のruntime依存とそのsubpathは外部importのまま保持します。既存の小さな編集用
+純粋ヘルパーだけを含め、production consumerには編集packageやGUIエンジンを要求しません。
+公開型は既存tsconfigと同じES2022の型ライブラリを使い、生成JSはES2020を対象とします。
+既存exportsを維持して./bundle-moduleを追加し、templateへのruntime依存は追加しません。
+
+pnpm run build:moduleで生成し、pnpm run check:moduleは実tarballをproduction依存だけの
+consumerへinstallしてhost分離・単体版との動作一致・公開型・編集エンジンの非混入を検査します。
+sb3-toolchain側の統合buildは[sb3-toolchain #65](https://github.com/kubohiroya/sb3-toolchain/issues/65)の後続です。
+切戻しはこのmodule入口を選択せず従来のclassic distを読み込みます。新しいruntimeフラグや
+保存データの移行は導入しません。
+
 ## 開発
 
 `engines`のNode.jsと、`packageManager`に宣言したpnpmを使用します。

package/templates/README.md

@@ -154,6 +154,48 @@ for example `TurboWarp-Asset-Manager`, `TurboWarp-Runtime-Expression`, and
 Document schema-aware migrations when an extension ID or opcode changes. Never
 instruct users to replace JavaScript alone when stored identifiers have changed.
 
+## Integrated-build module API
+
+Building this source also produces a `./bundle-module` ESM entry and declarations
+in `lib-module/`. This entry is separate from the standalone JavaScript file.
+
+```ts
+import {bundleModuleMetadata, createExtension, type ScratchApi}
+  from '@kubohiroya/<package>/bundle-module';
+
+export function createMember(memberScratch: ScratchApi) {
+  return createExtension(memberScratch);
+}
+```
+
+Importing the entry does not access global Scratch / window / document or create
+and register an extension. Each explicit createExtension(memberScratch) call
+returns a fresh instance bound to that host, including deferred block execution,
+editor helpers and lifecycle callbacks. The factory does not call
+Scratch.extensions.register; the standalone entry uses the same factory and
+registers exactly once.
+
+The frozen bundleModuleMetadata declares formatVersion: 1, the original id and
+unsandboxed requirement. An integrated host validates these before creation and
+owns registration and disposal. Existing IDs, opcodes and saved data stay unchanged.
+
+The existing STRUCTURED_DATA_MVP, NAMED_DATA_REGISTRY_MVP and Schema reference startup flags retain their defaults. Creation performs the existing optional editor and named-data initialization against the injected host. Call and await dispose() to release the instance registrations and listeners. Internal callers constructing StructuredDataExtension directly now pass the host first, followed by the existing optional feature arguments.
+
+Runtime dependencies (including yaml and their subpaths) remain external imports.
+Only the existing small, pure development-time editor helpers are included, so
+production consumers need no editor package or GUI engine. Public types use the
+same ES2022 libraries as the project tsconfig; generated JavaScript targets ES2020.
+The package retains its existing exports and adds ./bundle-module; no template
+runtime dependency is required.
+
+pnpm run build:module builds this entry; pnpm run check:module packs and installs
+the actual package with production dependencies only, checks host isolation,
+standalone parity and public types, and rejects editor-engine dependency leaks.
+The integrated sb3-toolchain build remains a later step in
+[sb3-toolchain #65](https://github.com/kubohiroya/sb3-toolchain/issues/65).
+To roll back, continue loading the existing classic dist artifact without selecting
+this module entry. No runtime flag or saved-data migration is introduced.
+
 ## Development
 
 Use Node.js `<minimum version>` and the pnpm version declared by
@@ -197,15 +239,15 @@ 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）
+## Fixed-input editor form (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を評価しません。明示変更だけを検査し、他の引数やブロック宣言、保存形式を変更しません。
+When the shared editor's startup flag `blockEditorFixedInputs` and Dialogs are both on in the GUI, the extension registers a fixed form for `forEachAtPath`'s `MAX` input only. Older GUIs, or a GUI with the flag off, get no extra registration. The canonical Schema is `schemas/block-editor-fixed-inputs.schema.json#/$defs/forEachAtPath/properties/MAX`; the codec and registration live in `src/fixed-input-editors.ts`. Saving without changes never rewrites existing raw values, unchanged aliases, or unknown enum values, and connected reporters are never evaluated. Only explicit changes are validated; other arguments, block declarations, and the saved format are unchanged.
 
-MAXは整数1〜1000です。新しい入力には共通の有限数値token規則も適用し、途中入力を保存しません。MVP flagがOFFなら登録せず、NAME/PATH・staticLiteral由来の接続可否を変更しません。
+`MAX` is an integer from 1 to 1000. New input also follows the shared finite-number token rule, and partial input is not saved. When the MVP flag is off nothing is registered, and whether `NAME`/`PATH` accept connected reporters (derived from `staticLiteral`) does not change.
 
-登録はoptional API（apiVersion:1）に限定し、RUNTIME_DISPOSED/明示disposeで解除します。起動フラグOFF＋再読込で従来経路へ切り戻せます。依存を戻す場合はmanifest/lock/実解決を一組で復旧します。npm公開や後続段階の動的候補は含みません。
+Registration is limited to the optional API (`apiVersion: 1`) and is released on `RUNTIME_DISPOSED` or an explicit dispose. Turning the startup flag off and reloading restores the previous behavior. When rolling back the dependency, restore the manifest, lockfile, and actual resolution together. This stage does not include an npm release or dynamic candidates from later stages.
 
-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を適用します。
+The contract the Schema describes is grounded in the actual `getInfo` declarations and the existing pure runtime conversions. The SchemaBundle `retrievalUri` identifies this local document; it does not mean the Schema is served from that URL or that `$ref` is resolved over HTTP. The Schema compiles from the bundled documents only.
+Existing non-empty finite Number aliases for `MAX` (for example `001`, `+1`, or `0x10`) are only projected through `Number` for display; unchanged raw values are not saved again. Blank, non-finite, or unprojectable values are read-only, and no `0` or default is substituted. New input does not accept these aliases and follows 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.