@kubohiroya/turbowarp-asset-cache 0.1.0

package/dist/extension-manifest.json

@@ -0,0 +1,420 @@
+{
+  "formatVersion": 2,
+  "id": "kubohiroyaassetcache",
+  "blocks": [
+    {
+      "opcode": "assetErrorLabel",
+      "blockType": "REPORTER",
+      "arguments": [],
+      "resultType": "string",
+      "effect": "pure",
+      "immutable": true,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "assetErrorType",
+      "blockType": "REPORTER",
+      "arguments": [],
+      "resultType": "string",
+      "effect": "pure",
+      "immutable": true,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "deleteAllCachedAssets",
+      "blockType": "COMMAND",
+      "arguments": [],
+      "resultType": "void",
+      "effect": "storage-write",
+      "immutable": false,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "deleteAllMemoryAssets",
+      "blockType": "COMMAND",
+      "arguments": [],
+      "resultType": "void",
+      "effect": "control",
+      "immutable": false,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "deleteCachedAsset",
+      "blockType": "COMMAND",
+      "arguments": [
+        {
+          "id": "NAME",
+          "type": "STRING"
+        }
+      ],
+      "resultType": "void",
+      "effect": "storage-write",
+      "immutable": false,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "deleteMemoryAsset",
+      "blockType": "COMMAND",
+      "arguments": [
+        {
+          "id": "NAME",
+          "type": "STRING"
+        }
+      ],
+      "resultType": "void",
+      "effect": "control",
+      "immutable": false,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "finishAllActorSequences",
+      "blockType": "COMMAND",
+      "arguments": [],
+      "resultType": "void",
+      "effect": "control",
+      "immutable": false,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "getAssetMimeType",
+      "blockType": "REPORTER",
+      "arguments": [
+        {
+          "id": "NAME",
+          "type": "STRING"
+        }
+      ],
+      "resultType": "string",
+      "effect": "pure",
+      "immutable": true,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "getVersion",
+      "blockType": "REPORTER",
+      "arguments": [],
+      "resultType": "string",
+      "effect": "pure",
+      "immutable": true,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "isLoaded",
+      "blockType": "BOOLEAN",
+      "arguments": [
+        {
+          "id": "NAME",
+          "type": "STRING"
+        }
+      ],
+      "resultType": "boolean",
+      "effect": "pure",
+      "immutable": true,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "loadAsset",
+      "blockType": "COMMAND",
+      "arguments": [
+        {
+          "id": "NAME",
+          "type": "STRING"
+        },
+        {
+          "id": "URL",
+          "type": "STRING"
+        }
+      ],
+      "resultType": "void",
+      "effect": "control",
+      "immutable": false,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "playSound",
+      "blockType": "COMMAND",
+      "arguments": [
+        {
+          "id": "NAME",
+          "type": "STRING"
+        }
+      ],
+      "resultType": "void",
+      "effect": "control",
+      "immutable": false,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "playSoundUntilDone",
+      "blockType": "COMMAND",
+      "arguments": [
+        {
+          "id": "NAME",
+          "type": "STRING"
+        }
+      ],
+      "resultType": "void",
+      "effect": "control",
+      "immutable": false,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "registerAsset",
+      "blockType": "COMMAND",
+      "arguments": [
+        {
+          "id": "NAME",
+          "type": "STRING"
+        },
+        {
+          "id": "RESOURCE_ID",
+          "type": "STRING"
+        }
+      ],
+      "resultType": "void",
+      "effect": "control",
+      "immutable": false,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "setSpriteSkin",
+      "blockType": "COMMAND",
+      "arguments": [
+        {
+          "id": "NAME",
+          "type": "STRING"
+        },
+        {
+          "id": "SPRITE",
+          "type": "STRING"
+        }
+      ],
+      "resultType": "void",
+      "effect": "control",
+      "immutable": false,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "setStageSkin",
+      "blockType": "COMMAND",
+      "arguments": [
+        {
+          "id": "NAME",
+          "type": "STRING"
+        }
+      ],
+      "resultType": "void",
+      "effect": "control",
+      "immutable": false,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "setTextStyle",
+      "blockType": "COMMAND",
+      "arguments": [
+        {
+          "id": "NAME",
+          "type": "STRING"
+        },
+        {
+          "id": "PROPERTY",
+          "type": "STRING"
+        },
+        {
+          "id": "VALUE",
+          "type": "STRING"
+        }
+      ],
+      "resultType": "void",
+      "effect": "control",
+      "immutable": false,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "setTextValue",
+      "blockType": "COMMAND",
+      "arguments": [
+        {
+          "id": "NAME",
+          "type": "STRING"
+        },
+        {
+          "id": "VALUE",
+          "type": "STRING"
+        }
+      ],
+      "resultType": "void",
+      "effect": "control",
+      "immutable": false,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "setThisSpriteSkin",
+      "blockType": "COMMAND",
+      "arguments": [
+        {
+          "id": "NAME",
+          "type": "STRING"
+        }
+      ],
+      "resultType": "void",
+      "effect": "control",
+      "immutable": false,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "startActorLoop",
+      "blockType": "COMMAND",
+      "arguments": [
+        {
+          "id": "ACTOR",
+          "type": "STRING"
+        },
+        {
+          "id": "ASSETS",
+          "type": "STRING"
+        },
+        {
+          "id": "DURATIONS",
+          "type": "STRING"
+        }
+      ],
+      "resultType": "void",
+      "effect": "control",
+      "immutable": false,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "startActorSequence",
+      "blockType": "COMMAND",
+      "arguments": [
+        {
+          "id": "ACTOR",
+          "type": "STRING"
+        },
+        {
+          "id": "ASSETS",
+          "type": "STRING"
+        },
+        {
+          "id": "DURATIONS",
+          "type": "STRING"
+        }
+      ],
+      "resultType": "void",
+      "effect": "control",
+      "immutable": false,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "stopActorAnimation",
+      "blockType": "COMMAND",
+      "arguments": [
+        {
+          "id": "ACTOR",
+          "type": "STRING"
+        }
+      ],
+      "resultType": "void",
+      "effect": "control",
+      "immutable": false,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "stopAllSounds",
+      "blockType": "COMMAND",
+      "arguments": [],
+      "resultType": "void",
+      "effect": "control",
+      "immutable": false,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    },
+    {
+      "opcode": "stopSound",
+      "blockType": "COMMAND",
+      "arguments": [
+        {
+          "id": "NAME",
+          "type": "STRING"
+        }
+      ],
+      "resultType": "void",
+      "effect": "control",
+      "immutable": false,
+      "errors": [],
+      "server": {
+        "supported": false
+      }
+    }
+  ],
+  "menus": []
+}

package/dist/types/animation.d.ts

@@ -0,0 +1,41 @@
+import { AssetManagerExtension } from './extension.js';
+import { type AssetManagerFeatureFlags } from './feature-flags.js';
+type BlockArgs = Record<string, unknown>;
+/**
+ * Asset Cache with actor-level background asset animation.
+ *
+ * ACTOR is resolved from a clone-local actorName variable before falling back
+ * to the existing named-sprite behaviour of setSpriteSkin.
+ * ASSETS and DURATIONS are comma-separated strings. ASSETS contains registered
+ * image or audio asset names. Each duration is the interval before the next
+ * action, and a zero groups those adjacent actions. Loop has one interval per
+ * action; sequence omits the final interval. COSTUMES remains accepted as a
+ * compatibility alias for projects saved with the earlier block.
+ */
+export declare class AnimatedAssetManagerExtension extends AssetManagerExtension {
+    private readonly actorAnimations;
+    private animationGeneration;
+    constructor(featureFlags?: AssetManagerFeatureFlags);
+    setThisSpriteSkin(args: BlockArgs, util: ScratchBlockUtility): Promise<void>;
+    setSpriteSkin(args: BlockArgs, util?: ScratchBlockUtility): Promise<void>;
+    startActorLoop(args: BlockArgs, util?: ScratchBlockUtility): void;
+    startActorSequence(args: BlockArgs, util?: ScratchBlockUtility): void;
+    stopActorAnimation(args: BlockArgs, util?: ScratchBlockUtility): void;
+    finishAllActorSequences(): Promise<void>;
+    deleteAllMemoryAssets(): void;
+    private getAnimationAssetsInput;
+    private requireActorName;
+    private actorNameOf;
+    private resolveActorTarget;
+    private parseAnimation;
+    private startActorAnimation;
+    private createAnimationAction;
+    private showCurrentStep;
+    private getCurrentBatch;
+    private advance;
+    private isCurrent;
+    private stopActor;
+    private stopTarget;
+    private stopAllActorAnimations;
+}
+export {};

package/dist/types/asset-cache-error.d.ts

@@ -0,0 +1,28 @@
+export declare const ASSET_MANAGER_ERROR_CODES: readonly ["INVALID_ASSET_NAME", "ASSET_NOT_REGISTERED", "ASSET_TYPE_MISMATCH", "ASSET_TYPE_CHANGE", "SPRITE_NOT_FOUND", "SPRITE_NAME_AMBIGUOUS", "SOURCE_ASSET_NOT_FOUND", "RESOURCE_ID_INVALID", "DEPENDENCY_MISSING", "STYLE_PROPERTY_INVALID", "STYLE_VALUE_INVALID", "PLAYBACK_FAILED", "ANIMATION_FAILED", "REPLACEMENT_FAILED"];
+export type AssetManagerErrorCode = typeof ASSET_MANAGER_ERROR_CODES[number];
+export interface AssetManagerErrorContext {
+    operation: string;
+    assetName?: string | undefined;
+    resourceId?: string | undefined;
+    actorName?: string | undefined;
+    expectedKind?: string | undefined;
+    actualKind?: string | undefined;
+    hint?: string | undefined;
+    candidates?: string[] | undefined;
+    cause?: unknown;
+}
+export declare class AssetManagerError extends Error {
+    readonly code: AssetManagerErrorCode;
+    readonly operation: string;
+    readonly assetName: string | undefined;
+    readonly resourceId: string | undefined;
+    readonly actorName: string | undefined;
+    readonly expectedKind: string | undefined;
+    readonly actualKind: string | undefined;
+    readonly hint: string | undefined;
+    readonly candidates: readonly string[];
+    constructor(code: AssetManagerErrorCode, message: string, context: AssetManagerErrorContext);
+}
+export declare function suggestNames(value: unknown, choices: Iterable<string>, limit?: number): string[];
+export declare function suggestionHint(candidates: readonly string[]): string | undefined;
+export declare function errorMessage(error: unknown): string;

package/dist/types/audio-voice.d.ts

@@ -0,0 +1,9 @@
+export interface AssetManagerAudioVoice {
+    readonly ended: Promise<void>;
+    setGain(value: number): void;
+    stop(): void;
+}
+export interface AssetManagerAudioVoiceOptions {
+    readonly gain?: number;
+}
+export declare function normalizeAudioVoiceGain(value: unknown, label?: string): number;

package/dist/types/binary-bundle-store.d.ts

@@ -0,0 +1,93 @@
+import { type BinaryStorageBackendPolicy, type OpfsBinaryObjectStoreOptions } from './binary-object-store.js';
+export interface BinaryBundleKeyInput {
+    readonly namespace: unknown;
+    readonly name: unknown;
+    readonly integrity: unknown;
+}
+export interface BinaryBundleFileInput {
+    readonly path: unknown;
+    readonly size: unknown;
+    readonly integrity: unknown;
+    readonly bytes: ArrayBuffer | Uint8Array;
+}
+export interface BinaryBundlePutInput extends BinaryBundleKeyInput {
+    readonly files: ReadonlyArray<BinaryBundleFileInput>;
+}
+export interface BinaryBundleOperationOptions {
+    readonly signal?: AbortSignal;
+}
+export interface BinaryBundleFileRegistration {
+    readonly path: string;
+    readonly size: number;
+    readonly integrity: string;
+}
+export interface BinaryBundleRegistration {
+    readonly namespace: string;
+    readonly name: string;
+    readonly integrity: string;
+    readonly files: ReadonlyArray<BinaryBundleFileRegistration>;
+    readonly totalBytes: number;
+}
+export interface BinaryBundleFileResult extends BinaryBundleFileRegistration {
+    readonly bytes: Uint8Array;
+}
+export interface BinaryBundleResult {
+    readonly namespace: string;
+    readonly name: string;
+    readonly integrity: string;
+    readonly files: ReadonlyArray<BinaryBundleFileResult>;
+    readonly totalBytes: number;
+}
+export interface BinaryBundleStoreOptions {
+    readonly indexedDB?: IDBFactory;
+    readonly subtleCrypto?: SubtleCrypto;
+    readonly databaseName?: string;
+    readonly now?: () => number;
+    readonly maxFilesPerBundle?: number;
+    readonly maxBundleBytes?: number;
+    readonly maxStoredBundles?: number;
+    readonly maxStoreBytes?: number;
+    readonly ttlMs?: number;
+    readonly backendPolicy?: BinaryStorageBackendPolicy;
+    readonly opfs?: OpfsBinaryObjectStoreOptions;
+    readonly opfsMetadataDatabaseName?: string;
+    readonly recoveryBatchSize?: number;
+}
+export interface BinaryBundleBackendWarning {
+    readonly code: 'ASSET_BINARY_BACKEND_FALLBACK';
+    readonly causeCode: string;
+}
+export interface BinaryBundleBackendStatus {
+    readonly policy: BinaryStorageBackendPolicy;
+    readonly selected: 'pending' | 'indexeddb' | 'opfs';
+    readonly warning?: BinaryBundleBackendWarning;
+}
+export interface BinaryBundleStoreStats {
+    readonly backend: 'indexeddb' | 'opfs';
+    readonly bundles: number;
+    readonly logicalBytes: number;
+    readonly physicalObjectBytes: number;
+    readonly stagingBytes: number;
+    readonly orphanBytes: number;
+    readonly pendingDeletionBytes: number;
+}
+export interface BinaryBundlePruneResult {
+    readonly removedBundles: number;
+    readonly removedBytes: number;
+}
+export interface BinaryBundleStore {
+    put(input: BinaryBundlePutInput, options?: BinaryBundleOperationOptions): Promise<BinaryBundleRegistration>;
+    get(input: BinaryBundleKeyInput, options?: BinaryBundleOperationOptions): Promise<BinaryBundleResult>;
+    delete(input: BinaryBundleKeyInput, options?: BinaryBundleOperationOptions): Promise<void>;
+    touch(input: BinaryBundleKeyInput, options?: BinaryBundleOperationOptions): Promise<void>;
+    getStats(): Promise<BinaryBundleStoreStats>;
+    prune(): Promise<BinaryBundlePruneResult>;
+    clear(): Promise<BinaryBundlePruneResult>;
+    getBackendStatus(): BinaryBundleBackendStatus;
+    release(): Promise<void>;
+}
+/**
+ * Create a binary bundle store whose backend is selected once, before its first operation.
+ * IndexedDB remains the default so existing consumers keep the previous behavior.
+ */
+export declare function createBinaryBundleStore(options?: BinaryBundleStoreOptions): BinaryBundleStore;

package/dist/types/binary-object-store.d.ts

@@ -0,0 +1,56 @@
+export type BinaryStorageBackendPolicy = 'indexeddb' | 'opfs-prefer' | 'opfs-required';
+export interface BinaryObjectDescriptor {
+    readonly key: string;
+    readonly size: number;
+    readonly integrity: string;
+    readonly contentType?: string;
+}
+export interface BinaryObjectResult extends BinaryObjectDescriptor {
+    readonly bytes: Uint8Array;
+}
+export interface BinaryObjectOperationOptions {
+    readonly signal?: AbortSignal;
+}
+export interface BinaryObjectStoreStats {
+    readonly physicalObjectBytes: number;
+    readonly stagingBytes: number;
+    readonly orphanBytes: number;
+    readonly pendingDeletionBytes: number;
+}
+export interface BinaryObjectStatsOptions extends BinaryObjectOperationOptions {
+    readonly referencedKeys?: ReadonlySet<string>;
+    readonly pendingDeletionKeys?: ReadonlySet<string>;
+}
+export interface BinaryObjectStore {
+    readonly kind: 'indexeddb' | 'opfs';
+    put(descriptor: BinaryObjectDescriptor, source: ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>, options?: BinaryObjectOperationOptions): Promise<void>;
+    get(descriptor: BinaryObjectDescriptor, options?: BinaryObjectOperationOptions): Promise<BinaryObjectResult>;
+    delete(key: string, options?: BinaryObjectOperationOptions): Promise<void>;
+    listOrphans?(options?: {
+        readonly limit?: number;
+        readonly signal?: AbortSignal;
+    }): AsyncIterable<string>;
+    cleanupStaging?(options?: {
+        readonly limit?: number;
+        readonly createdBefore?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<number>;
+    getStats?(options?: BinaryObjectStatsOptions): Promise<BinaryObjectStoreStats>;
+    release(): Promise<void>;
+}
+export interface OpfsStorageManager {
+    getDirectory(): Promise<FileSystemDirectoryHandle>;
+}
+export interface OpfsBinaryObjectStoreOptions {
+    readonly rootDirectory?: FileSystemDirectoryHandle;
+    readonly storage?: OpfsStorageManager;
+    readonly subtleCrypto?: SubtleCrypto;
+}
+export interface IndexedDBBinaryObjectStoreOptions {
+    readonly indexedDB?: IDBFactory;
+    readonly databaseName?: string;
+    readonly subtleCrypto?: SubtleCrypto;
+}
+export declare function createOpfsBinaryObjectStore(options?: OpfsBinaryObjectStoreOptions): BinaryObjectStore;
+/** IndexedDB adapter for consumers that want the object contract without OPFS. */
+export declare function createIndexedDBBinaryObjectStore(options?: IndexedDBBinaryObjectStoreOptions): BinaryObjectStore;