@kubohiroya/turbowarp-asset-cache 0.6.0 → 0.6.1

package/README.ja.md

@@ -54,6 +54,11 @@ Standalone拡張機能を使います。
 importし、registryを内部に閉じたまま、パレットへAsset Cacheのblockを追加したくない場合はComposition APIを
 使います。
 
+独立したプレビューVMでは、`createAssetManagerComposition.supportsRuntimeIsolation === true`を確認し、
+`createAssetManagerComposition(undefined, {runtime: previewVm.runtime})`で描画とイベント購読の所有先を指定します。
+省略時は従来どおり拡張機能のホストruntimeを使います。終了時の`releaseAll()`は、そのcompositionが所有する
+`STOP_FOR_TARGET`購読も解除します。同じcompositionへ再登録すると必要な購読を再開します。
+
 ## 動作条件と安全性
 
 standaloneでの利用には、TurboWarp Desktop、またはunsandboxedなカスタム拡張機能を読み込める他の
@@ -83,14 +88,14 @@ SVG入力は既定で拒否します。remote binaryのcache entryは、保存
 versionを付けたnpm packageにも、同じレビュー済みビルドが入っています。
 
 ```bash
-pnpm add --save-exact @kubohiroya/turbowarp-asset-cache@0.6.0
+pnpm add --save-exact @kubohiroya/turbowarp-asset-cache@0.6.1
 ```
 
 `node_modules/@kubohiroya/turbowarp-asset-cache/dist/asset-cache.js`を読み込むか、version固定の
 CDN URLを使います。
 
 ```text
-https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-cache@0.6.0/dist/asset-cache.js
+https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-cache@0.6.1/dist/asset-cache.js
 ```
 
 ## クイックスタート

package/README.md

@@ -66,13 +66,13 @@ The built JavaScript file is committed to this repository so users do not need t
 The versioned npm package contains the same reviewed build:
 
 ```bash
-pnpm add --save-exact @kubohiroya/turbowarp-asset-cache@0.6.0
+pnpm add --save-exact @kubohiroya/turbowarp-asset-cache@0.6.1
 ```
 
 Load `node_modules/@kubohiroya/turbowarp-asset-cache/dist/asset-cache.js`, or use the version-pinned CDN URL:
 
 ```text
-https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-cache@0.6.0/dist/asset-cache.js
+https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-cache@0.6.1/dist/asset-cache.js
 ```
 
 ## Quick Start

package/dist/asset-cache.js

@@ -2341,9 +2341,9 @@ function validateProjectAssetAddress(runtime, assetName, resourceIdentifier) {
 	}
 }
 var AssetManagerExtension = class {
-	constructor(featureFlags = FEATURE_FLAGS) {
-		_defineProperty(this, "runtime", Scratch.vm.runtime);
-		_defineProperty(this, "renderer", this.runtime.renderer);
+	constructor(featureFlags = FEATURE_FLAGS, runtime = Scratch.vm.runtime) {
+		_defineProperty(this, "runtime", void 0);
+		_defineProperty(this, "renderer", void 0);
 		_defineProperty(this, "externalAssets", /* @__PURE__ */ new Map());
 		_defineProperty(this, "costumeAssets", /* @__PURE__ */ new Map());
 		_defineProperty(this, "soundAssets", /* @__PURE__ */ new Map());
@@ -2393,6 +2393,12 @@ var AssetManagerExtension = class {
 			this.unbindNamedDataRegistryLifecycle = void 0;
 		});
 		_defineProperty(this, "fixedEditors", fixedInputRegistration(Scratch));
+		_defineProperty(this, "listeningForTargetStops", false);
+		_defineProperty(this, "releaseStoppedTarget", (target) => {
+			if (target && !this.runtime.targets.includes(target)) this.displayedAssets.delete(target.id);
+		});
+		this.runtime = runtime;
+		this.renderer = runtime.renderer;
 		this.featureFlags = Object.freeze({ ...featureFlags });
 		if (this.featureFlags.NAMED_ASSET_BODY_PROVIDER) {
 			this.namedBodyProviderValue = this.createNamedBodyProvider();
@@ -2401,9 +2407,19 @@ var AssetManagerExtension = class {
 			this.unbindNamedDataRegistryLifecycle = bindNamedDataRegistryLifecycle(this.runtime, registry);
 			this.startListeningForNamedBodyLifecycle();
 		}
-		this.runtime.on?.("STOP_FOR_TARGET", (target) => {
-			if (target && !this.runtime.targets.includes(target)) this.displayedAssets.delete(target.id);
-		});
+		this.ensureRuntimeListeners();
+	}
+	/** A reusable composition reattaches its own listener when registering new assets. */
+	ensureRuntimeListeners() {
+		if (this.listeningForTargetStops || !this.runtime.on) return;
+		this.runtime.on("STOP_FOR_TARGET", this.releaseStoppedTarget);
+		this.listeningForTargetStops = true;
+	}
+	/** Release only this instance's subscription, leaving other runtime owners untouched. */
+	releaseRuntimeListeners() {
+		if (!this.listeningForTargetStops || !this.runtime.off) return;
+		this.runtime.off("STOP_FOR_TARGET", this.releaseStoppedTarget);
+		this.listeningForTargetStops = false;
 	}
 	setLoadingBackdrop(args) {
 		this.loadingBackdropName = normalizeName(args.NAME);

package/dist/composition.js

@@ -2293,8 +2293,8 @@ function validateProjectAssetAddress(runtime, assetName, resourceIdentifier) {
 	}
 }
 var AssetManagerExtension = class {
-	runtime = Scratch.vm.runtime;
-	renderer = this.runtime.renderer;
+	runtime;
+	renderer;
 	externalAssets = /* @__PURE__ */ new Map();
 	costumeAssets = /* @__PURE__ */ new Map();
 	soundAssets = /* @__PURE__ */ new Map();
@@ -2344,7 +2344,13 @@ var AssetManagerExtension = class {
 		this.unbindNamedDataRegistryLifecycle = void 0;
 	};
 	fixedEditors = fixedInputRegistration(Scratch);
-	constructor(featureFlags = FEATURE_FLAGS) {
+	listeningForTargetStops = false;
+	releaseStoppedTarget = (target) => {
+		if (target && !this.runtime.targets.includes(target)) this.displayedAssets.delete(target.id);
+	};
+	constructor(featureFlags = FEATURE_FLAGS, runtime = Scratch.vm.runtime) {
+		this.runtime = runtime;
+		this.renderer = runtime.renderer;
 		this.featureFlags = Object.freeze({ ...featureFlags });
 		if (this.featureFlags.NAMED_ASSET_BODY_PROVIDER) {
 			this.namedBodyProviderValue = this.createNamedBodyProvider();
@@ -2353,9 +2359,19 @@ var AssetManagerExtension = class {
 			this.unbindNamedDataRegistryLifecycle = bindNamedDataRegistryLifecycle(this.runtime, registry);
 			this.startListeningForNamedBodyLifecycle();
 		}
-		this.runtime.on?.("STOP_FOR_TARGET", (target) => {
-			if (target && !this.runtime.targets.includes(target)) this.displayedAssets.delete(target.id);
-		});
+		this.ensureRuntimeListeners();
+	}
+	/** A reusable composition reattaches its own listener when registering new assets. */
+	ensureRuntimeListeners() {
+		if (this.listeningForTargetStops || !this.runtime.on) return;
+		this.runtime.on("STOP_FOR_TARGET", this.releaseStoppedTarget);
+		this.listeningForTargetStops = true;
+	}
+	/** Release only this instance's subscription, leaving other runtime owners untouched. */
+	releaseRuntimeListeners() {
+		if (!this.listeningForTargetStops || !this.runtime.off) return;
+		this.runtime.off("STOP_FOR_TARGET", this.releaseStoppedTarget);
+		this.listeningForTargetStops = false;
 	}
 	setLoadingBackdrop(args) {
 		this.loadingBackdropName = normalizeName(args.NAME);
@@ -8732,7 +8748,10 @@ async function createSessionBinaryBacking(inputValue, optionValue = {}, operatio
 //#region src/composition.ts
 function createAssetManagerComposition(featureFlags, options = {}) {
 	if (!options || typeof options !== "object" || Array.isArray(options)) throw new TypeError("Asset Cache composition options must be an object.");
-	const extension = featureFlags ? new AssetManagerExtension(featureFlags) : new AssetManagerExtension();
+	const runtimeInput = options.runtime === void 0 ? Scratch.vm.runtime : options.runtime;
+	if (options.runtime !== void 0 && (!runtimeInput || typeof runtimeInput !== "object" || !Array.isArray(runtimeInput.targets) || !runtimeInput.renderer || typeof runtimeInput.renderer !== "object")) throw new TypeError("Asset Cache composition runtime must provide targets and renderer.");
+	const runtime = runtimeInput;
+	const extension = new AssetManagerExtension(featureFlags, runtime);
 	const ownedNames = /* @__PURE__ */ new Map();
 	let literalNameSequence = 0;
 	let verifiedRemoteCache = null;
@@ -9012,7 +9031,6 @@ function createAssetManagerComposition(featureFlags, options = {}) {
 		previous?.resource.release();
 		return resource;
 	}
-	const runtime = Scratch.vm.runtime;
 	let listeningForDOMImageLifecycle = false;
 	const releaseStoppedTargetDOMImageResources = (target) => {
 		if (target && !runtime.targets.includes(target)) releaseDOMImageResourcesForOwner(target.id);
@@ -9036,6 +9054,7 @@ function createAssetManagerComposition(featureFlags, options = {}) {
 	return Object.freeze({
 		async registerProjectAsset(input) {
 			if (!input || typeof input !== "object" || Array.isArray(input)) throw new TypeError("Project asset registration input must be an object.");
+			extension.ensureRuntimeListeners();
 			const hasLocator = Object.hasOwn(input, "locator");
 			if (hasLocator === Object.hasOwn(input, "resourceId")) throw new TypeError("Provide exactly one project asset locator or resourceId.");
 			const claimed = claimName(input.name, input.nameMode ?? (hasLocator ? "literal" : "trimmed"));
@@ -9045,6 +9064,7 @@ function createAssetManagerComposition(featureFlags, options = {}) {
 			}));
 		},
 		async registerEmbeddedAsset(input) {
+			extension.ensureRuntimeListeners();
 			if (!input || typeof input !== "object" || Array.isArray(input)) throw new TypeError("Embedded asset registration input must be an object.");
 			const claimed = claimName(input.name, input.nameMode ?? "trimmed");
 			return trackRegistration(claimed, extension.registerEmbeddedAsset({
@@ -9057,9 +9077,13 @@ function createAssetManagerComposition(featureFlags, options = {}) {
 		},
 		releaseAsset,
 		releaseAll() {
-			releaseAllDOMImageResources();
-			audioGeneration++;
 			const errors = [];
+			try {
+				releaseAllDOMImageResources();
+			} catch (error) {
+				errors.push(error);
+			}
+			audioGeneration++;
 			for (const playback of audioPlaybacks) try {
 				playback.dispose();
 			} catch (error) {
@@ -9070,6 +9094,11 @@ function createAssetManagerComposition(featureFlags, options = {}) {
 			} catch (error) {
 				errors.push(error);
 			}
+			try {
+				extension.releaseRuntimeListeners();
+			} catch (error) {
+				errors.push(error);
+			}
 			if (errors.length > 0) throw new AggregateError(errors, "Failed to release assets");
 		},
 		isRegistered(name) {
@@ -9101,7 +9130,7 @@ function createAssetManagerComposition(featureFlags, options = {}) {
 		applyToTarget(name, target) {
 			return extension.setThisSpriteSkin({ NAME: ownedName(name)?.internal ?? name }, {
 				target,
-				runtime: Scratch.vm.runtime
+				runtime
 			});
 		},
 		playSound(name, options = {}) {
@@ -9187,5 +9216,7 @@ function createAssetManagerComposition(featureFlags, options = {}) {
 		}
 	});
 }
+createAssetManagerComposition.supportsRuntimeIsolation = true;
+Object.defineProperty(createAssetManagerComposition, "supportsRuntimeIsolation", { writable: false });
 //#endregion
 export { NAMED_ASSET_BODY_NAMESPACE, NamedAssetBodyError, createAssetManagerComposition, createBinaryBundleStore, createIndexedDBBinaryObjectStore, createOpfsBinaryObjectStore, createSessionBinaryBacking, createVerifiedRemoteBinaryCache, createVerifiedRemoteCacheDatabaseName };

package/dist/types/composition.d.ts

@@ -65,7 +65,20 @@ export interface DOMImageResourceBindingOptions {
     readonly attribute?: 'href' | 'src';
     readonly owner?: AssetManagerCompositionTarget;
 }
+/** Public runtime boundary; rendering and asset capabilities are checked when used. */
+export interface AssetManagerCompositionRuntime {
+    readonly renderer: object;
+    readonly targets: readonly object[];
+    readonly storage?: unknown;
+    readonly stageWidth?: number;
+    on?(eventName: string, listener: (target?: AssetManagerCompositionTarget) => void): unknown;
+    off?(eventName: string, listener: (target?: AssetManagerCompositionTarget) => void): unknown;
+    requestRedraw?(): unknown;
+    getOpcodeFunction?(opcode: string): unknown;
+}
 export interface AssetManagerCompositionOptions {
+    /** Explicit owner for independent preview/player runtimes; defaults to the extension host. */
+    readonly runtime?: AssetManagerCompositionRuntime;
     readonly verifiedRemoteCache?: VerifiedRemoteBinaryCacheOptions;
     readonly binaryBundleStore?: BinaryBundleStoreOptions;
     readonly sessionBinaryBacking?: SessionBinaryBackingOptions;
@@ -112,3 +125,6 @@ export interface AssetManagerComposition {
     createSessionBinaryBacking(input: SessionBinaryBackingInput, options?: BinaryBundleOperationOptions): Promise<SessionBinaryBacking>;
 }
 export declare function createAssetManagerComposition(featureFlags?: AssetManagerFeatureFlags, options?: AssetManagerCompositionOptions): AssetManagerComposition;
+export declare namespace createAssetManagerComposition {
+    var supportsRuntimeIsolation: true;
+}

package/dist/types/extension.d.ts

@@ -124,7 +124,13 @@ export declare class AssetManagerExtension {
     private readonly releaseNamedBodySnapshotsForLifecycle;
     private readonly unregisterNamedBodyProviderForRuntimeDispose;
     private readonly fixedEditors;
-    constructor(featureFlags?: AssetManagerFeatureFlags);
+    private listeningForTargetStops;
+    private readonly releaseStoppedTarget;
+    constructor(featureFlags?: AssetManagerFeatureFlags, runtime?: TurboWarpRuntime);
+    /** A reusable composition reattaches its own listener when registering new assets. */
+    ensureRuntimeListeners(): void;
+    /** Release only this instance's subscription, leaving other runtime owners untouched. */
+    releaseRuntimeListeners(): void;
     setLoadingBackdrop(args: BlockArgs): void;
     setLoadingCostumes(args: BlockArgs): void;
     prepareLoadingAssets(args: BlockArgs, util: ScratchBlockUtility): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubohiroya/turbowarp-asset-cache",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "A browser-local image, audio, and runtime-text asset cache for TurboWarp projects.",
   "author": {
     "name": "Hiroya Kubo",