@kubohiroya/turbowarp-structured-data 0.6.3 → 0.7.1

package/lib-module/src/codecs.d.ts

@@ -0,0 +1,10 @@
+import { type JsonValue } from './core.js';
+export declare const PARSE_LIMITS: {
+    readonly maxInputBytes: number;
+    readonly maxDepth: 64;
+    readonly maxNodes: 50000;
+};
+export declare function parseJsonDocument(source: string): JsonValue;
+export declare function parseYamlDocument(source: string): JsonValue;
+export declare function renderJsonDocument(value: JsonValue): string;
+export declare function renderYamlDocument(value: JsonValue): string;

package/lib-module/src/config.d.ts

@@ -0,0 +1,25 @@
+export declare const STRUCTURED_DATA_MVP_DEFAULT = false;
+export declare const NAMED_DATA_REGISTRY_MVP_DEFAULT = false;
+export declare const NAMED_DATA_SCHEMA_REF_DEFAULT = false;
+export declare function isNamedDataSchemaRefEnabled(source?: {
+    __TW_NAMED_DATA_FEATURE_FLAGS__?: {
+        NAMED_DATA_SCHEMA_REF?: unknown;
+    };
+}): boolean;
+export declare function isStructuredDataMvpEnabled(source?: {
+    STRUCTURED_DATA_MVP?: unknown;
+}): boolean;
+export declare function isNamedDataRegistryMvpEnabled(source?: {
+    NAMED_DATA_REGISTRY_MVP?: unknown;
+}): boolean;
+export declare const extensionConfig: {
+    readonly id: "kubohiroyastructureddata";
+    readonly slug: "structured-data";
+    readonly name: "Structured Data";
+    readonly description: "Named structured data with JSON/YAML codecs for TurboWarp and server compilation.";
+    readonly author: "Hiroya Kubo";
+    readonly license: "MPL-2.0";
+    readonly unsandboxed: true;
+    readonly docsURI: "https://kubohiroya.github.io/turbowarp-structured-data/";
+    readonly blockIconURI: "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0OCA0OCI+PHJlY3QgeD0iNCIgeT0iOCIgd2lkdGg9IjQwIiBoZWlnaHQ9IjMyIiByeD0iNiIgZmlsbD0iIzhBNTVENyIvPjxwYXRoIGQ9Ik0xOSAxNWMtMyAwLTIgNy01IDkgMyAyIDIgOSA1IDkiIGZpbGw9Im5vbmUiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIzIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz48cGF0aCBkPSJNMjkgMTVjMyAwIDIgNyA1IDktMyAyLTIgOS01IDkiIGZpbGw9Im5vbmUiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIzIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz48Y2lyY2xlIGN4PSIyNCIgY3k9IjI0IiByPSIyLjIiIGZpbGw9IiNmZmYiLz48L3N2Zz4=";
+};

package/lib-module/src/core.d.ts

@@ -0,0 +1,34 @@
+export declare const STRUCTURED_DATA_ERROR_CODES: readonly ["INVALID_JSON", "INVALID_YAML", "INVALID_NAME", "DATA_NOT_FOUND", "INVALID_PATH", "PATH_NOT_FOUND", "TYPE_MISMATCH", "INDEX_OUT_OF_RANGE", "ITERATION_LIMIT_EXCEEDED", "ITERATION_CONTEXT_REQUIRED", "PARSE_LIMIT_EXCEEDED"];
+export type StructuredDataErrorCode = (typeof STRUCTURED_DATA_ERROR_CODES)[number];
+export type JsonPrimitive = null | boolean | number | string;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type PathSegment = {
+    kind: 'key';
+    value: string;
+} | {
+    kind: 'index';
+    value: number;
+};
+export declare class StructuredDataError extends Error {
+    readonly code: StructuredDataErrorCode;
+    constructor(code: StructuredDataErrorCode, message: string);
+}
+export declare function parseJson(text: unknown): JsonValue;
+export declare function isValidJson(text: unknown): boolean;
+export declare function normalizeJson(text: unknown): string;
+export declare function stringifyJson(value: JsonValue): string;
+export declare function parsePath(input: unknown): PathSegment[];
+export declare function getAtPath(root: JsonValue, segments: readonly PathSegment[]): JsonValue;
+export declare function hasAtPath(root: JsonValue, segments: readonly PathSegment[]): boolean;
+export declare function setAtPath(root: JsonValue, segments: readonly PathSegment[], replacement: JsonValue): JsonValue;
+export declare function deleteAtPath(root: JsonValue, segments: readonly PathSegment[]): JsonValue;
+export declare function keysAtPath(root: JsonValue, segments: readonly PathSegment[]): string[];
+export declare function lengthAtPath(root: JsonValue, segments: readonly PathSegment[]): number;
+export interface IterationEntry {
+    key: string;
+    value: JsonValue;
+}
+export declare function iterationEntries(root: JsonValue, segments: readonly PathSegment[], maximum: number): IterationEntry[];
+export declare function compareUnicodeCodePoints(left: string, right: string): number;

package/lib-module/src/editor-schema.d.ts

@@ -0,0 +1,2 @@
+import type { SourceEditorOptions } from '@kubohiroya/turbowarp-extension-data-editor/schema';
+export declare const sourceEditorDefinitions: readonly SourceEditorOptions[];

package/lib-module/src/extension.d.ts

@@ -0,0 +1,74 @@
+import type { ScratchApi, TurboWarpExtension, ScratchBlockUtility } from './runtime-api.js';
+import { type NamedDataRegistryService } from '@kubohiroya/turbowarp-named-data/composition';
+import { StructuredDataNamedDataProvider } from './structured-provider.js';
+interface NamedPathArguments {
+    NAME: unknown;
+    PATH: unknown;
+}
+export declare class StructuredDataExtension implements TurboWarpExtension {
+    private readonly scratch;
+    private readonly enabled;
+    private disposed;
+    private readonly releaseRuntimeListeners;
+    private readonly unregisterSourceEditors;
+    private readonly unregisterFixedInputEditors;
+    private registries;
+    private iterationStacks;
+    private nextRevision;
+    private readonly namedDataProvider?;
+    private readonly namedDataRegistry?;
+    private readonly namedDataRegistration?;
+    private readonly unbindNamedDataRegistryLifecycle?;
+    constructor(scratch: ScratchApi, enabled?: boolean, namedDataEnabled?: boolean);
+    getNamedDataProvider(): StructuredDataNamedDataProvider | undefined;
+    getNamedDataRegistry(): NamedDataRegistryService | undefined;
+    dispose(): Promise<void>;
+    getInfo(): Record<string, unknown>;
+    parseJson(args: {
+        TEXT: unknown;
+        NAME: unknown;
+    }, util: ScratchBlockUtility): void;
+    parseYaml(args: {
+        TEXT: unknown;
+        NAME: unknown;
+    }, util: ScratchBlockUtility): void;
+    toJson(args: {
+        NAME: unknown;
+    }, util: ScratchBlockUtility): string;
+    toYaml(args: {
+        NAME: unknown;
+    }, util: ScratchBlockUtility): string;
+    hasStructuredData(args: {
+        NAME: unknown;
+    }, util: ScratchBlockUtility): boolean;
+    deleteStructuredData(args: {
+        NAME: unknown;
+    }, util: ScratchBlockUtility): void;
+    getJsonAtPath(args: NamedPathArguments, util: ScratchBlockUtility): string;
+    hasPath(args: NamedPathArguments, util: ScratchBlockUtility): boolean;
+    setJsonAtPath(args: NamedPathArguments & {
+        VALUE: unknown;
+    }, util: ScratchBlockUtility): void;
+    deleteAtPath(args: NamedPathArguments, util: ScratchBlockUtility): void;
+    keysAtPath(args: NamedPathArguments, util: ScratchBlockUtility): string;
+    lengthAtPath(args: NamedPathArguments, util: ScratchBlockUtility): number;
+    forEachAtPath(args: NamedPathArguments & {
+        MAX: unknown;
+    }, util: ScratchBlockUtility): void;
+    currentKey(_args: Record<string, never>, util: ScratchBlockUtility): string;
+    currentIndex(_args: Record<string, never>, util: ScratchBlockUtility): number;
+    currentValueJson(_args: Record<string, never>, util: ScratchBlockUtility): string;
+    private store;
+    private requireData;
+    private requireDataByName;
+    private registryFor;
+    private setBinding;
+    private name;
+    private dataNotFound;
+    private currentIteration;
+    private stackFor;
+    private path;
+    private clearRuntimeState;
+    private toScratchBlock;
+}
+export {};

package/lib-module/src/fixed-input-editors.d.ts

@@ -0,0 +1,9 @@
+import type { FixedInputEditorOptions } from '@kubohiroya/turbowarp-extension-data-editor';
+export declare const fixedInputEditorDefinitions: readonly FixedInputEditorOptions[];
+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 declare function registerFixedInputEditors(scratch: unknown, definitions: readonly FixedInputEditorOptions[], runtimeOverride?: RuntimeLifetime): () => void;
+export {};

package/lib-module/src/fixed-input-schema.d.ts

@@ -0,0 +1,3 @@
+import type { SchemaBundle } from '@kubohiroya/turbowarp-extension-data-editor/schema';
+/** The on-disk owner Schema is canonical; this is its single-field projection. */
+export declare const fixedInputSchemaBundle: SchemaBundle;

package/lib-module/src/runtime-api.d.ts

@@ -0,0 +1,41 @@
+export interface TurboWarpExtension {
+    getInfo(): Record<string, unknown>;
+}
+export interface ScratchTranslate {
+    (text: string): string;
+    (message: {
+        default: string;
+        description?: string;
+    }, placeholders?: Record<string, string | number>): string;
+}
+export interface ScratchBlockUtility {
+    thread: object;
+    target: object;
+    stackFrame: Record<string, unknown>;
+    startBranch(branchNumber: number, isLoop: boolean): void;
+}
+export interface ScratchApi {
+    extensions: {
+        unsandboxed: boolean;
+        register(extension: TurboWarpExtension): void;
+    };
+    BlockType: Record<'COMMAND' | 'REPORTER' | 'BOOLEAN' | 'HAT' | 'LOOP', string>;
+    ArgumentType: Record<'STRING' | 'NUMBER' | 'BOOLEAN', string>;
+    Cast: {
+        toString(value: unknown): string;
+        toNumber(value: unknown): number;
+        toBoolean(value: unknown): boolean;
+    };
+    translate: ScratchTranslate;
+    vm?: {
+        runtime?: {
+            on(event: string, listener: () => void): void;
+            off?(event: string, listener: () => void): void;
+        };
+    };
+}
+export interface ExtensionModuleMetadata {
+    readonly formatVersion: 1;
+    readonly id: string;
+    readonly unsandboxed: 'required' | 'optional' | 'not-needed';
+}

package/lib-module/src/source-editor.d.ts

@@ -0,0 +1,8 @@
+import type { SchemaBundle, SchemaDocument, SourceBinding, SourceEditorOptions } from '@kubohiroya/turbowarp-extension-data-editor/schema';
+export declare function canonicalBundle(ownerId: string, contractId: string, document: SchemaDocument, ownerSource: {
+    path: string;
+    symbol: string;
+}): SchemaBundle;
+export declare function sourceBinding(argument: string, bundle: SchemaBundle, read: (source: string) => unknown, check?: (source: string) => unknown, format?: 'json' | 'yaml', uiSchema?: SourceBinding['variants'][number]['uiSchema']): SourceBinding;
+/** The optional capability keeps legacy hosts and the startup flag safely inactive. */
+export declare function registerSourceEditors(scratch: unknown, definitions: readonly SourceEditorOptions[]): () => void;

package/lib-module/src/structured-provider.d.ts

@@ -0,0 +1,33 @@
+import type { JsonValue } from './core.js';
+import { type NamedDataBody, type NamedDataMetadata, type NamedDataProvider, type NamedDataReference, type NamedDataSchemaRef, type NamedDataRepresentation, type NamedDataResolveContext } from '@kubohiroya/turbowarp-named-data/composition';
+export declare const STRUCTURED_DATA_NAMESPACE = "structured";
+export declare const STRUCTURED_BODY_MAX_BYTES: number;
+export interface StructuredDataBinding {
+    value: JsonValue;
+    revision: number;
+    nativeRepresentation: 'json' | 'yaml';
+    schemaRef?: NamedDataSchemaRef;
+}
+export interface StructuredDataBindingStore {
+    get(target: object, name: string): StructuredDataBinding | undefined;
+}
+export declare class StructuredDataNamedDataProvider implements NamedDataProvider {
+    private readonly store;
+    private readonly maxBodyBytes;
+    private readonly schemaRefEnabled;
+    readonly namespace = "structured";
+    readonly kind: "structured";
+    private readonly openBodies;
+    private released;
+    constructor(store: StructuredDataBindingStore, maxBodyBytes?: number, schemaRefEnabled?: boolean);
+    canResolve(reference: NamedDataReference, representation: NamedDataRepresentation): boolean;
+    stat(reference: NamedDataReference, representation: NamedDataRepresentation, context: NamedDataResolveContext): NamedDataMetadata;
+    openBody(reference: NamedDataReference, representation: NamedDataRepresentation, context: NamedDataResolveContext): NamedDataBody;
+    release(): void;
+    clearSession(): void;
+    private resolve;
+    private validateReference;
+    private render;
+    private metadata;
+    private throwIfAborted;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubohiroya/turbowarp-structured-data",
-  "version": "0.6.3",
+  "version": "0.7.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",
@@ -33,7 +33,9 @@
     "README.ja.md",
     "THIRD_PARTY_NOTICES.md",
     "LICENSE",
-    "lib-editor/"
+    "lib-editor/",
+    "lib-module/",
+    "assets/block-icon.svg"
   ],
   "publishConfig": {
     "access": "public",
@@ -46,17 +48,19 @@
   "scripts": {
     "dev": "vite build --watch",
     "typecheck": "tsc --noEmit",
-    "build": "vite build && pnpm run build:editor",
-    "lint": "eslint src tests scripts vite.config.ts vite.editor.config.ts eslint.config.ts",
+    "build": "vite build && pnpm run build:editor && pnpm run build:module",
+    "lint": "eslint src tests scripts vite.config.ts vite.editor.config.ts eslint.config.ts vite.module.config.ts",
     "test": "vitest run",
     "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",
-    "check": "pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run docs:check && pnpm run check:dist && pnpm run repo:check && pnpm run pack:check",
+    "check": "pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run docs:check && pnpm run check:dist && pnpm run check:module && pnpm run repo:check && pnpm run pack:check",
     "check:dist": "pnpm run build && node scripts/check-dist.ts",
-    "build:editor": "tsc -p tsconfig.editor.json && vite build --config vite.editor.config.ts"
+    "build:editor": "tsc -p tsconfig.editor.json && vite build --config vite.editor.config.ts",
+    "build:module": "tsc -p tsconfig.module.json && vite build --config vite.module.config.ts",
+    "check:module": "node scripts/check-bundle-module.ts"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.5",
@@ -80,9 +84,9 @@
   "peerDependencies": {
     "@kubohiroya/turbowarp-named-data": ">=0.4.0 <1"
   },
-  "gitHead": "870ebcaa4071e0eacb4d36a6d9e98734e51f2361",
+  "gitHead": "0cd886abf134b9833f29e7f5119adec70d0e3185",
   "x-turbowarp-source": {
-    "revision": "870ebcaa4071e0eacb4d36a6d9e98734e51f2361",
+    "revision": "0cd886abf134b9833f29e7f5119adec70d0e3185",
     "revisionRole": "base-commit",
     "sourceState": "local-release-overlay"
   },
@@ -91,6 +95,10 @@
     "./editor-metadata": {
       "types": "./lib-editor/src/editor-metadata.d.ts",
       "import": "./lib-editor/src/editor-metadata.js"
+    },
+    "./bundle-module": {
+      "types": "./lib-module/src/bundle-module.d.ts",
+      "import": "./lib-module/src/bundle-module.js"
     }
   }
 }

package/src/bundle-module.ts

@@ -0,0 +1,23 @@
+import {extensionConfig} from './config.js';
+import {StructuredDataExtension} from './extension.js';
+import type {ExtensionModuleMetadata, ScratchApi} from './runtime-api.js';
+
+export type {
+  TurboWarpExtension,
+  ScratchTranslate,
+  ScratchBlockUtility,
+  ScratchApi,
+  ExtensionModuleMetadata
+} from './runtime-api.js';
+
+/** Static contract: importing this entry never creates or registers an extension. */
+export const bundleModuleMetadata: ExtensionModuleMetadata = Object.freeze({
+  formatVersion: 1,
+  id: extensionConfig.id,
+  unsandboxed: extensionConfig.unsandboxed ? 'required' : 'not-needed'
+});
+
+/** The caller supplies the member host and owns registration and lifetime. */
+export function createExtension(scratch: ScratchApi): StructuredDataExtension {
+  return new StructuredDataExtension(scratch);
+}

package/src/config.ts

@@ -38,5 +38,5 @@ export const extensionConfig = {
   unsandboxed: true,
   docsURI: 'https://kubohiroya.github.io/turbowarp-structured-data/',
   blockIconURI:
-    'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0OCA0OCI+PHJlY3QgeD0iNCIgeT0iOCIgd2lkdGg9IjE4IiBoZWlnaHQ9IjE0IiByeD0iMyIgZmlsbD0iIzRDOTdGRiIvPjxyZWN0IHg9IjI2IiB5PSI4IiB3aWR0aD0iMTgiIGhlaWdodD0iMTQiIHJ4PSIzIiBmaWxsPSIjNTlDMDU5Ii8+PHJlY3QgeD0iMTUiIHk9IjI2IiB3aWR0aD0iMTgiIGhlaWdodD0iMTQiIHJ4PSIzIiBmaWxsPSIjRkZBQjE5Ii8+PC9zdmc+'
+    'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0OCA0OCI+PHJlY3QgeD0iNCIgeT0iOCIgd2lkdGg9IjQwIiBoZWlnaHQ9IjMyIiByeD0iNiIgZmlsbD0iIzhBNTVENyIvPjxwYXRoIGQ9Ik0xOSAxNWMtMyAwLTIgNy01IDkgMyAyIDIgOSA1IDkiIGZpbGw9Im5vbmUiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIzIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz48cGF0aCBkPSJNMjkgMTVjMyAwIDIgNyA1IDktMyAyLTIgOS01IDkiIGZpbGw9Im5vbmUiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIzIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz48Y2lyY2xlIGN4PSIyNCIgY3k9IjI0IiByPSIyLjIiIGZpbGw9IiNmZmYiLz48L3N2Zz4='
 } as const;

package/src/extension.ts

@@ -1,7 +1,8 @@
+import type {ScratchApi, TurboWarpExtension, ScratchBlockUtility} from './runtime-api.js';
 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 definitions from './block-definitions.json' with {type: 'json'};
 import {
   bindNamedDataRegistryLifecycle,
   installNamedDataRegistry,
@@ -88,12 +89,13 @@ export class StructuredDataExtension implements TurboWarpExtension {
   private readonly unbindNamedDataRegistryLifecycle?: () => void;
 
   public constructor(
+    private readonly scratch: ScratchApi,
     enabled = isStructuredDataMvpEnabled(),
     namedDataEnabled = isNamedDataRegistryMvpEnabled()
   ) {
     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 = () => {void this.dispose();};
     const onStop = () => this.clearRuntimeState();
     this.releaseRuntimeListeners = () => {
@@ -102,13 +104,13 @@ export class StructuredDataExtension implements TurboWarpExtension {
     };
     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(
@@ -154,7 +156,7 @@ export class StructuredDataExtension implements TurboWarpExtension {
   public getInfo(): Record<string, unknown> {
     return {
       id: extensionConfig.id,
-      name: Scratch.translate(definitions.extensionName),
+      name: this.scratch.translate(definitions.extensionName),
       docsURI: extensionConfig.docsURI,
       blockIconURI: extensionConfig.blockIconURI,
       blocks: this.enabled ? blockDefinitions.map((block) => this.toScratchBlock(block)) : []
@@ -165,7 +167,7 @@ export class StructuredDataExtension implements TurboWarpExtension {
     this.store(
       util.target,
       args.NAME,
-      parseJsonDocument(Scratch.Cast.toString(args.TEXT)),
+      parseJsonDocument(this.scratch.Cast.toString(args.TEXT)),
       'json'
     );
   }
@@ -174,7 +176,7 @@ export class StructuredDataExtension implements TurboWarpExtension {
     this.store(
       util.target,
       args.NAME,
-      parseYamlDocument(Scratch.Cast.toString(args.TEXT)),
+      parseYamlDocument(this.scratch.Cast.toString(args.TEXT)),
       'yaml'
     );
   }
@@ -215,7 +217,7 @@ export class StructuredDataExtension implements TurboWarpExtension {
     const updated = setAtPath(
       this.requireDataByName(util.target, name),
       this.path(args.PATH),
-      parseJsonValue(Scratch.Cast.toString(args.VALUE))
+      parseJsonValue(this.scratch.Cast.toString(args.VALUE))
     );
     this.setBinding(util.target, name, updated);
   }
@@ -251,7 +253,7 @@ export class StructuredDataExtension implements TurboWarpExtension {
         entries: iterationEntries(
           this.requireData(util.target, args.NAME),
           this.path(args.PATH),
-          Scratch.Cast.toNumber(args.MAX)
+          this.scratch.Cast.toNumber(args.MAX)
         ),
         cursor: 0,
         active: false
@@ -333,7 +335,7 @@ export class StructuredDataExtension implements TurboWarpExtension {
   }
 
   private name(value: unknown): string {
-    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.');
     }
@@ -365,7 +367,7 @@ export class StructuredDataExtension implements TurboWarpExtension {
   }
 
   private path(value: unknown) {
-    return parsePath(Scratch.Cast.toString(value));
+    return parsePath(this.scratch.Cast.toString(value));
   }
 
   private clearRuntimeState(): void {
@@ -378,12 +380,12 @@ export class StructuredDataExtension implements TurboWarpExtension {
   private toScratchBlock(block: BlockDefinition): Record<string, unknown> {
     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], defaultValue: argument.defaultValue}
+          {type: this.scratch.ArgumentType[argument.type], defaultValue: argument.defaultValue}
         ])
       )
     };

package/src/globals.d.ts

@@ -1,38 +1,9 @@
-interface TurboWarpExtension {
-  getInfo(): Record<string, unknown>;
-}
-
-interface ScratchTranslate {
-  (text: string): string;
-  (message: {default: string; description?: string}, placeholders?: Record<string, string | number>): string;
-}
+import type * as Runtime from './runtime-api.js';
 
-interface ScratchBlockUtility {
-  thread: object;
-  target: object;
-  stackFrame: Record<string, unknown>;
-  startBranch(branchNumber: number, isLoop: boolean): void;
+declare global {
+  type TurboWarpExtension = Runtime.TurboWarpExtension;
+  type ScratchTranslate = Runtime.ScratchTranslate;
+  type ScratchBlockUtility = Runtime.ScratchBlockUtility;
+  type ScratchApi = Runtime.ScratchApi;
+  const Scratch: ScratchApi;
 }
-
-interface ScratchApi {
-  extensions: {
-    unsandboxed: boolean;
-    register(extension: TurboWarpExtension): void;
-  };
-  BlockType: Record<'COMMAND' | 'REPORTER' | 'BOOLEAN' | 'HAT' | 'LOOP', string>;
-  ArgumentType: Record<'STRING' | 'NUMBER' | 'BOOLEAN', string>;
-  Cast: {
-    toString(value: unknown): string;
-    toNumber(value: unknown): number;
-    toBoolean(value: unknown): boolean;
-  };
-  translate: ScratchTranslate;
-  vm?: {
-    runtime?: {
-      on(event: string, listener: () => void): void;
-      off?(event: string, listener: () => void): void;
-    };
-  };
-}
-
-declare const Scratch: ScratchApi;

package/src/index.ts

@@ -1,8 +1,8 @@
 import {extensionConfig} from './config.js';
-import {StructuredDataExtension} from './extension.js';
+import {createExtension} from './bundle-module.js';
 
 if (extensionConfig.unsandboxed && !Scratch.extensions.unsandboxed) {
   throw new Error(`${extensionConfig.name} must run unsandboxed.`);
 }
 
-Scratch.extensions.register(new StructuredDataExtension());
+Scratch.extensions.register(createExtension(Scratch));

package/src/runtime-api.ts

@@ -0,0 +1,43 @@
+export interface TurboWarpExtension {
+  getInfo(): Record<string, unknown>;
+}
+
+export interface ScratchTranslate {
+  (text: string): string;
+  (message: {default: string; description?: string}, placeholders?: Record<string, string | number>): string;
+}
+
+export interface ScratchBlockUtility {
+  thread: object;
+  target: object;
+  stackFrame: Record<string, unknown>;
+  startBranch(branchNumber: number, isLoop: boolean): void;
+}
+
+export interface ScratchApi {
+  extensions: {
+    unsandboxed: boolean;
+    register(extension: TurboWarpExtension): void;
+  };
+  BlockType: Record<'COMMAND' | 'REPORTER' | 'BOOLEAN' | 'HAT' | 'LOOP', string>;
+  ArgumentType: Record<'STRING' | 'NUMBER' | 'BOOLEAN', string>;
+  Cast: {
+    toString(value: unknown): string;
+    toNumber(value: unknown): number;
+    toBoolean(value: unknown): boolean;
+  };
+  translate: ScratchTranslate;
+  vm?: {
+    runtime?: {
+      on(event: string, listener: () => void): void;
+      off?(event: string, listener: () => void): void;
+    };
+  };
+}
+
+
+export interface ExtensionModuleMetadata {
+  readonly formatVersion: 1;
+  readonly id: string;
+  readonly unsandboxed: 'required' | 'optional' | 'not-needed';
+}

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を使用します。