@kubohiroya/turbowarp-structured-data 0.6.3 → 0.7.0

package/README.ja.md

@@ -65,6 +65,42 @@ arrayはindex昇順、objectはUnicodeコードポイント順で反復します
 
 `dist/extension-manifest.json` format version 3はtarget-local named reference、型付きpath、argument/result型、effect、error、IR v2 operationを宣言します。[architecture](docs/architecture.ja.md)、[JSON Schema](schemas/extension-manifest.schema.json)、[semantic parity fixture](tests/fixtures/semantic-parity.json)を参照してください。
 
+## 統合ビルド用module API
+
+このソースのbuildは、単体JSとは別に、統合用のESM入口`./bundle-module`と
+型宣言を`lib-module/`へ生成します。
+
+```ts
+import {bundleModuleMetadata, createExtension, type ScratchApi}
+  from '@kubohiroya/turbowarp-structured-data/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フラグや
+保存データの移行は導入しません。
+
 ## 開発
 
 ```bash

package/README.md

@@ -37,7 +37,7 @@ immediately return to metadata without schema identities.
 ## Installation
 
 ```bash
-pnpm add --save-exact @kubohiroya/turbowarp-structured-data@0.6.3
+pnpm add --save-exact @kubohiroya/turbowarp-structured-data@0.7.0
 ```
 
 ## Quick start
@@ -244,6 +244,48 @@ Return the current iteration value as JSON.
 
 `dist/extension-manifest.json` format version 3 declares the target-local named reference model, typed path segments, block argument/result types, effects, stable errors, and IR v2 operations. See [architecture](docs/architecture.md), the [JSON Schema](schemas/extension-manifest.schema.json), and [semantic parity fixtures](tests/fixtures/semantic-parity.json).
 
+## 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/turbowarp-structured-data/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
 
 ```bash
@@ -258,15 +300,15 @@ SPDX-License-Identifier: MPL-2.0
 
 Bundled third-party license terms 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.

package/dist/structured-data.js

@@ -7056,14 +7056,15 @@
   var LOOP_STATE = "structuredDataLoopState";
   var blockDefinitions = block_definitions_default.blocks;
   var StructuredDataExtension = class {
-  	constructor(enabled = isStructuredDataMvpEnabled(), namedDataEnabled = isNamedDataRegistryMvpEnabled()) {
+  	constructor(scratch, enabled = isStructuredDataMvpEnabled(), namedDataEnabled = isNamedDataRegistryMvpEnabled()) {
+  		this.scratch = scratch;
   		this.disposed = false;
   		this.registries = /* @__PURE__ */ new WeakMap();
   		this.iterationStacks = /* @__PURE__ */ new WeakMap();
   		this.nextRevision = 1;
   		this.enabled = enabled;
-  		this.unregisterSourceEditors = registerSourceEditors(Scratch, enabled ? sourceEditorDefinitions : []);
-  		const runtime = Scratch.vm?.runtime;
+  		this.unregisterSourceEditors = registerSourceEditors(this.scratch, enabled ? sourceEditorDefinitions : []);
+  		const runtime = this.scratch.vm?.runtime;
   		const onDispose = () => {
   			this.dispose();
   		};
@@ -7074,11 +7075,11 @@
   		};
   		let unregisterFixed = () => {};
   		try {
-  			unregisterFixed = registerFixedInputEditors(Scratch, enabled ? fixedInputEditorDefinitions : []);
+  			unregisterFixed = registerFixedInputEditors(this.scratch, enabled ? fixedInputEditorDefinitions : []);
   			this.unregisterFixedInputEditors = unregisterFixed;
   			if (namedDataEnabled) {
   				this.namedDataProvider = new StructuredDataNamedDataProvider({ get: (target, name) => this.registries.get(target)?.get(name) });
-  				const runtime = Scratch.vm?.runtime;
+  				const runtime = this.scratch.vm?.runtime;
   				if (runtime) {
   					this.namedDataRegistry = installNamedDataRegistry(runtime);
   					this.namedDataRegistration = this.namedDataRegistry.registerProvider(this.namedDataProvider, { lifetime: "persistent" });
@@ -7114,17 +7115,17 @@
   	getInfo() {
   		return {
   			id: extensionConfig.id,
-  			name: Scratch.translate(block_definitions_default.extensionName),
+  			name: this.scratch.translate(block_definitions_default.extensionName),
   			docsURI: extensionConfig.docsURI,
   			blockIconURI: extensionConfig.blockIconURI,
   			blocks: this.enabled ? blockDefinitions.map((block) => this.toScratchBlock(block)) : []
   		};
   	}
   	parseJson(args, util) {
-  		this.store(util.target, args.NAME, parseJsonDocument(Scratch.Cast.toString(args.TEXT)), "json");
+  		this.store(util.target, args.NAME, parseJsonDocument(this.scratch.Cast.toString(args.TEXT)), "json");
   	}
   	parseYaml(args, util) {
-  		this.store(util.target, args.NAME, parseYamlDocument(Scratch.Cast.toString(args.TEXT)), "yaml");
+  		this.store(util.target, args.NAME, parseYamlDocument(this.scratch.Cast.toString(args.TEXT)), "yaml");
   	}
   	toJson(args, util) {
   		return renderJsonDocument(this.requireData(util.target, args.NAME));
@@ -7148,7 +7149,7 @@
   	}
   	setJsonAtPath(args, util) {
   		const name = this.name(args.NAME);
-  		const updated = setAtPath(this.requireDataByName(util.target, name), this.path(args.PATH), parseJson(Scratch.Cast.toString(args.VALUE)));
+  		const updated = setAtPath(this.requireDataByName(util.target, name), this.path(args.PATH), parseJson(this.scratch.Cast.toString(args.VALUE)));
   		this.setBinding(util.target, name, updated);
   	}
   	deleteAtPath(args, util) {
@@ -7167,7 +7168,7 @@
   		const stack = this.stackFor(util.thread);
   		if (!state) {
   			state = {
-  				entries: iterationEntries(this.requireData(util.target, args.NAME), this.path(args.PATH), Scratch.Cast.toNumber(args.MAX)),
+  				entries: iterationEntries(this.requireData(util.target, args.NAME), this.path(args.PATH), this.scratch.Cast.toNumber(args.MAX)),
   				cursor: 0,
   				active: false
   			};
@@ -7229,7 +7230,7 @@
   		this.nextRevision += 1;
   	}
   	name(value) {
-  		const name = Scratch.Cast.toString(value).trim();
+  		const name = this.scratch.Cast.toString(value).trim();
   		if (name.length === 0) throw new StructuredDataError("INVALID_NAME", "Structured data name cannot be empty.");
   		return name;
   	}
@@ -7250,7 +7251,7 @@
   		return stack;
   	}
   	path(value) {
-  		return parsePath(Scratch.Cast.toString(value));
+  		return parsePath(this.scratch.Cast.toString(value));
   	}
   	clearRuntimeState() {
   		this.namedDataProvider?.clearSession();
@@ -7261,16 +7262,25 @@
   	toScratchBlock(block) {
   		return {
   			opcode: block.opcode,
-  			blockType: Scratch.BlockType[block.blockType],
-  			text: Scratch.translate(block.text),
+  			blockType: this.scratch.BlockType[block.blockType],
+  			text: this.scratch.translate(block.text),
   			arguments: Object.fromEntries(Object.entries(block.arguments).map(([name, argument]) => [name, {
-  				type: Scratch.ArgumentType[argument.type],
+  				type: this.scratch.ArgumentType[argument.type],
   				defaultValue: argument.defaultValue
   			}]))
   		};
   	}
   };
+  Object.freeze({
+  	formatVersion: 1,
+  	id: extensionConfig.id,
+  	unsandboxed: extensionConfig.unsandboxed ? "required" : "not-needed"
+  });
+  /** The caller supplies the member host and owns registration and lifetime. */
+  function createExtension(scratch) {
+  	return new StructuredDataExtension(scratch);
+  }
   if (extensionConfig.unsandboxed && !Scratch.extensions.unsandboxed) throw new Error(`${extensionConfig.name} must run unsandboxed.`);
-  Scratch.extensions.register(new StructuredDataExtension());
+  Scratch.extensions.register(createExtension(Scratch));
 
 })(Scratch);

package/docs/assets/github-mark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path d="M10.226 17.284c-2.965-.36-5.054-2.493-5.054-5.256 0-1.123.404-2.336 1.078-3.144-.292-.741-.247-2.314.09-2.965.898-.112 2.111.36 2.83 1.01.853-.269 1.752-.404 2.853-.404 1.1 0 1.999.135 2.807.382.696-.629 1.932-1.1 2.83-.988.315.606.36 2.179.067 2.942.72.854 1.101 2 1.101 3.167 0 2.763-2.089 4.852-5.098 5.234.763.494 1.28 1.572 1.28 2.807v2.336c0 .674.561 1.056 1.235.786 4.066-1.55 7.255-5.615 7.255-10.646C23.5 6.188 18.334 1 11.978 1 5.62 1 .5 6.188.5 12.545c0 4.986 3.167 9.12 7.435 10.669.606.225 1.19-.18 1.19-.786V20.63a2.9 2.9 0 0 1-1.078.224c-1.483 0-2.359-.808-2.987-2.313-.247-.607-.517-.966-1.034-1.033-.27-.023-.359-.135-.359-.27 0-.27.45-.471.898-.471.652 0 1.213.404 1.797 1.235.45.651.921.943 1.483.943.561 0 .92-.202 1.437-.719.382-.381.674-.718.944-.943"/></svg>