@kubohiroya/turbowarp-asset-cache 0.2.1 → 0.3.0

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

@@ -0,0 +1,5 @@
+export declare function createAudioAmplifier(audio: HTMLAudioElement): {
+    setGain(value: number): void;
+    resume(): Promise<void>;
+    dispose: () => void;
+};

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

@@ -0,0 +1,46 @@
+export type AssetManagerAudioSource = Readonly<{
+    asset: unknown;
+    url?: never;
+}> | Readonly<{
+    url: string;
+    asset?: never;
+}>;
+export interface AssetManagerAudioFadeOptions {
+    readonly fadeIn?: number;
+    readonly fadeOut?: number;
+}
+export interface AssetManagerAudioStopOptions {
+    readonly fadeOut?: number;
+    readonly signal?: AbortSignal;
+}
+export interface AssetManagerAudioPlaybackOptions extends AssetManagerAudioFadeOptions {
+    readonly gain?: number;
+    readonly muted?: boolean;
+    readonly playbackRate?: number;
+}
+export interface AssetManagerAudioPlayOptions extends AssetManagerAudioFadeOptions {
+    readonly gain?: number;
+    readonly restart?: boolean;
+    readonly loop?: boolean;
+    readonly signal?: AbortSignal;
+}
+export interface AssetManagerAudioPlayback {
+    readonly ended: Promise<void>;
+    readonly currentTime: number;
+    readonly paused: boolean;
+    readonly loop: boolean;
+    readonly gain: number;
+    readonly muted: boolean;
+    readonly playbackRate: number;
+    play(options?: AssetManagerAudioPlayOptions): Promise<void>;
+    pause(): void;
+    stop(options?: AssetManagerAudioStopOptions): void | Promise<void>;
+    seek(seconds: number, signal?: AbortSignal): Promise<void>;
+    setGain(value: number): void | Promise<void>;
+    setMuted(value: boolean): void;
+    setPlaybackRate(value: number): void;
+    dispose(): void;
+}
+export declare function validateAudioPlaybackOptions(options: AssetManagerAudioPlaybackOptions): void;
+/** One reusable native element; the caller owns source resolution and resource release. */
+export declare function createBrowserAudioPlayback(audio: HTMLAudioElement, options: AssetManagerAudioPlaybackOptions, release: () => void, playbackError: (cause: unknown) => Error): AssetManagerAudioPlayback;

package/dist/types/composition.d.ts

@@ -7,6 +7,8 @@ import { type NamedAssetBodyProvider } from './named-body-provider.js';
 export { type AssetManagerAudioVoice, type AssetManagerAudioVoiceOptions } from './audio-voice.js';
 import { type AssetManagerAudioVoice, type AssetManagerAudioVoiceOptions } from './audio-voice.js';
 export { type DOMImageResource } from './dom-image-resource.js';
+export type { AssetManagerAudioSource, AssetManagerAudioPlayback, AssetManagerAudioPlaybackOptions, AssetManagerAudioPlayOptions, AssetManagerAudioFadeOptions, AssetManagerAudioStopOptions } from './audio-playback.js';
+import type { AssetManagerAudioSource, AssetManagerAudioPlayback, AssetManagerAudioPlaybackOptions } from './audio-playback.js';
 export { NAMED_ASSET_BODY_NAMESPACE, NamedAssetBodyError, type NamedAssetBodyErrorCode, type NamedAssetBodyMetadata, type NamedAssetBodyOpenOptions, type NamedAssetBodyProvider, type NamedAssetBodyReference, type NamedAssetBodySnapshot } from './named-body-provider.js';
 export { createBinaryBundleStore, type BinaryBundleBackendStatus, type BinaryBundleBackendWarning, type BinaryBundleFileInput, type BinaryBundleFileRegistration, type BinaryBundleFileResult, type BinaryBundleKeyInput, type BinaryBundleOperationOptions, type BinaryBundlePruneResult, type BinaryBundlePutInput, type BinaryBundleRegistration, type BinaryBundleResult, type BinaryBundleStore, type BinaryBundleStoreStats, type BinaryBundleStoreOptions } from './binary-bundle-store.js';
 export { createIndexedDBBinaryObjectStore, createOpfsBinaryObjectStore, type BinaryObjectDescriptor, type BinaryObjectOperationOptions, type BinaryObjectResult, type BinaryObjectStore, type BinaryObjectStoreStats, type BinaryObjectStatsOptions, type BinaryStorageBackendPolicy, type IndexedDBBinaryObjectStoreOptions, type OpfsBinaryObjectStoreOptions, type OpfsStorageManager } from './binary-object-store.js';
@@ -87,6 +89,7 @@ export interface AssetManagerComposition {
         untilDone?: boolean;
     }>): Promise<void>;
     createAudioVoice(name: unknown, options?: AssetManagerAudioVoiceOptions): Promise<AssetManagerAudioVoice>;
+    createAudioPlayback(source: AssetManagerAudioSource, options?: AssetManagerAudioPlaybackOptions): Promise<AssetManagerAudioPlayback>;
     stopSound(name: unknown): void;
     stopAllSounds(): void;
     resolveVerifiedRemoteBinary(input: VerifiedRemoteBinaryInput, options: VerifiedRemoteBinaryResolveOptions): Promise<VerifiedRemoteBinaryResult>;

package/dist/types/extension.d.ts

@@ -1,3 +1,4 @@
+import { type AssetManagerAudioSource, type AssetManagerAudioPlayback, type AssetManagerAudioPlaybackOptions } from './audio-playback.js';
 import { AssetManagerError } from './asset-cache-error.js';
 import { type AssetManagerFeatureFlags } from './feature-flags.js';
 import { type DOMImageResource } from './dom-image-resource.js';
@@ -91,6 +92,7 @@ export declare class AssetManagerExtension {
     private readonly textAssets;
     private readonly assetRegistry;
     private readonly displayedAssets;
+    private readonly explicitAudio;
     private readonly playingAudio;
     private readonly audioVoiceStops;
     private readonly registrationVersions;
@@ -121,6 +123,7 @@ export declare class AssetManagerExtension {
     private readonly releaseDOMImageResourcesForRuntimeDispose;
     private readonly releaseNamedBodySnapshotsForLifecycle;
     private readonly unregisterNamedBodyProviderForRuntimeDispose;
+    private readonly fixedEditors;
     constructor(featureFlags?: AssetManagerFeatureFlags);
     setLoadingBackdrop(args: BlockArgs): void;
     setLoadingCostumes(args: BlockArgs): void;
@@ -138,6 +141,8 @@ export declare class AssetManagerExtension {
         color3: string;
         blocks: Record<string, unknown>[];
     };
+    /** Release only this optional editor registration; runtime data remains unchanged. */
+    dispose(): void;
     /**
      * Exposes the stock extension registry through a host-neutral DOM image
      * resource contract for other unsandboxed extensions.
@@ -169,6 +174,8 @@ export declare class AssetManagerExtension {
     playSound(args: BlockArgs): Promise<void>;
     playSoundUntilDone(args: BlockArgs): Promise<void>;
     createAudioVoice(value: unknown, options?: AssetManagerAudioVoiceOptions): Promise<AssetManagerAudioVoice>;
+    createAudioPlayback(source: AssetManagerAudioSource, options?: AssetManagerAudioPlaybackOptions, onDispose?: () => void): Promise<AssetManagerAudioPlayback>;
+    private prepareBrowserAudio;
     stopSound(args: BlockArgs): void;
     stopAllSounds(): void;
     getAssetMimeType(args: BlockArgs): string;

package/dist/types/fixed-input-editors.d.ts

@@ -0,0 +1,10 @@
+import type { FixedInputBinding, FixedInputEditorOptions } from '@kubohiroya/turbowarp-extension-data-editor';
+import { type TextStyleProperty } from './text-style.js';
+/** New edits preserve the candidate token; existing aliases are display projections only. */
+export declare function styleBinding(property: TextStyleProperty): FixedInputBinding;
+export declare const fixedInputEditors: readonly FixedInputEditorOptions[];
+/** Per-instance, idempotent registration. Legacy hosts never acquire the fixed capability. */
+export declare function fixedInputRegistration(scratch: unknown): {
+    ensure(opcodes: readonly string[]): void;
+    dispose: () => void;
+};

package/dist/types/fixed-input-schema.d.ts

@@ -0,0 +1,46 @@
+import type { SchemaBundle, SchemaDocument } from '@kubohiroya/turbowarp-extension-data-editor/schema';
+/** Canonical owner schema fragments; no network resources or runtime providers. */
+export declare function fixedInputBundle(fragment: string, schema: SchemaDocument): SchemaBundle;
+export declare const fixedSchemas: {
+    setTextStyle: {
+        type: string;
+        properties: {
+            PROPERTY: {
+                type: string;
+                enum: string[];
+            };
+            VALUE: {
+                type: string;
+            };
+        };
+        additionalProperties: boolean;
+    };
+    animation: {
+        type: string;
+        enum: string[];
+    };
+    font: {
+        type: string;
+    };
+    color: {
+        type: string;
+        pattern: string;
+    };
+    width: {
+        type: string;
+        $comment: string;
+    };
+    align: {
+        type: string;
+        enum: string[];
+    };
+    loadingCostumeAt: {
+        type: string;
+        properties: {
+            INDEX: {
+                type: string;
+            };
+        };
+        additionalProperties: boolean;
+    };
+};

package/docs/audio-playback.md

@@ -0,0 +1,49 @@
+# 音声instanceの共通controller
+
+追跡: [Issue #6](https://github.com/kubohiroya/turbowarp-asset-cache/issues/6)。開発中の追加APIで、既存公開版に同名APIがあることを示す文書ではありません。
+
+`createAudioPlayback({asset: 'Music'}, {gain: 0.7, muted: false, playbackRate: 1, fadeIn: 0.5, fadeOut: 1.5})` は、停止状態の独立したinstanceを返します。`asset` と `url` のどちらか一つが必須です。直接URLは認証情報を含まないHTTP(S)に限定し、anonymous CORSで読み込みます。別originのサーバーにはAccess-Control-Allow-Originが必要です。これは後からsetGainで増幅する場合も必要となる[Web AudioのCORS仕様](https://webaudio.github.io/web-audio-api/#MediaElementAudioSourceNode-security)に従います。準備だけではnative `play()` を呼びません。有効化フラグは不要です。
+
+```js
+const playback = await assets.createAudioPlayback({asset: 'Music'}, {gain: 0.7, fadeIn: 0.5, fadeOut: 1.5});
+try {
+  await playback.play({restart: true, loop: true, gain: 1.5, fadeIn: 0.5, fadeOut: 1.5, signal});
+  playback.pause();
+  await playback.seek(1.5, signal);
+  await playback.setGain(2);
+  playback.setMuted(false);
+  playback.setPlaybackRate(1.5);
+  await playback.play({signal});
+  await playback.stop({fadeOut: 0.5});
+} finally {
+  playback.dispose();
+}
+```
+
+- `play` はnative再生の開始まで待ちます。`restart` は先頭へ戻す指定（既定false）、`loop` を省略すると直前の設定を保ちます。
+- `ended` は現在の再生の終了待ちPromiseです。`play` ごとに更新されるため、`await playback.play(); await playback.ended;` の順で使います。自然終了・pause・stop・置換・disposeで待機を完了し、再生失敗やAbortSignalによる中断はrejectします。
+- `pause` は位置を保持します。`stop({fadeOut, signal})` は再生中ならフェードアウト完了まで待ち、ループを解除して先頭へ戻します。0秒・一時停止中・未再生なら即時停止です。いずれもinstanceと素材を保持し、再利用できます。フェードを使うstopはPromiseをawaitしてください。
+- `seek` は必要ならmetadataを最大10秒待ちます。負の秒、有限でない秒、長さを超える秒を拒否します。待機中のabort/disposeでもlistenerとtimerを回収します。
+- gainは0以上の有限数（既定1）、mutedは真偽値、playbackRateは0.25〜4です。音量などは同じ素材の別instanceへ影響しません。gain=0で無音、1で原音、2で2倍です。playのgain省略時は現在値を保持します。100%超の増幅には共有AudioContextとinstanceごとのGainNodeを使い、native volumeは減衰とフェードに使います。極端なgainはWeb Audioのfloat表現上限内で出力します。増幅後のsetGainはAudioContextの再開を待つ場合があるためawaitしてください。
+- `dispose` は冪等です。sourceを外してnative音声と増幅nodeを解放し、最後の増幅instanceでは共有AudioContextもcloseします。所有するObject URLを一度だけrevokeします。直接HTTP(S) URLをrevokeすることはありません。
+
+`createAudioVoice` と外部ファイルの `playSound` も同じnative controllerへ委譲します。voiceの `ended` / `setGain` / `stop` の契約は維持します。プロジェクト素材の旧 `playSound` はScratch SoundBankの互換adapterとして残します。
+
+明示的に準備したcontrollerは旧 `stopSound(asset)` の停止範囲に含めません。ID単位の所有者はcontrollerの `pause` / `stop` / `dispose` を使ってください。`releaseAsset` は該当素材のinstanceを回収し、compositionの `releaseAll` は直接URLも含めて所有するinstanceを回収します。別compositionのinstanceは対象にしません。全体停止の `stopAllSounds` は従来どおり全音声を停止します。
+
+autoplay拒否は `PLAYBACK_FAILED` の `cause` にブラウザの `NotAllowedError` を保持します。アプリはこの原因をDSL側の診断へ変換できます。ポリシーを回避する起動フラグやURLスイッチは追加しません。
+
+切り戻しはconsumerを先に旧APIへ戻し、依存版を前版へ固定して行います。旧consumerのvoice APIは変更不要です。
+
+
+## フェード
+
+`fadeIn` / `fadeOut` は0以上の有限な秒数で、既定は0です。準備時に設定し、`play` の同名optionでその再生を上書きできます。再生開始はnative play成功までを待ち、フェードイン完了までは待ちません。`ended` はフェードインを含む再生全体の自然終了を待ちます。
+
+フェードは実時間で線形に変化します。設定gainと音量倍率を分離するため、`gain` と `setGain` はフェード中も元の設定音量を扱います。短い素材で開始と終了のフェードが重なる場合は小さい倍率を使います。
+
+非ループは残りのmedia時間を現在の再生速度で換算し、終了前のfadeOutへ追従します。seek・rate変更・duration確定でも再計算します。長さが不明なら自動の終了予測はできないため、明示的なstopを使います。ループの各周回ではfadeOutを行いません。
+
+`stop` の秒数省略時はその再生のfadeOutを使い、現在の音量倍率から0へ下げます。完了後はgainを保持して再利用できます。stop中の自然終了は待機を完了し、native errorは失敗を返します。新しいplay・pause・disposeは古いフェードとstop待機をキャンセルし、timerを残しません。stopのAbortSignalはフェードを中断して即時停止し、呼び出しをAbortErrorでrejectします。
+
+sceneや素材の解放に使うdisposeはフェードを待たず即時に解放します。旧createAudioVoiceのstopとBGM crossfadeの既存契約は変えません。

package/docs/fixed-input-editors.ja.md

@@ -0,0 +1,20 @@
+# 固定入力エディターの契約
+
+対応GUIの起動時に`blockEditorDialogs=1&blockEditorFixedInputs=1`を指定し、再読込した場合だけ登録する。既定OFFで、旧GUIやCLIに固定登録APIがなければ何もしない。公開するブロック・引数・既定値・`docsURI`・既存データ形式は変更しない。
+
+| ブロック | 対象 | UIと保存 |
+|---|---|---|
+| `setTextStyle` | `PROPERTY` / `VALUE` | PROPERTYの固定5選択とVALUEの有限分岐。animation/alignは選択、fontは自由入力、colorは色、widthは数値文字列。VALUEは常にSTRINGで空文字reset可能 |
+| `loadingCostumeAt` | `INDEX` | 数値UI。新入力は有限の数値表記。小数・負数を許容し、既存runtimeの切捨て・下限補正・循環を維持。非表示の互換ブロック |
+
+Schemaの正本は`schemas/block-editor-fixed-inputs.schema.json`。`getInfo()`と`src/text-style.ts`の`normalizeTextStyleProperty` / `normalizeTextStyleValue`、`src/extension.ts`の`loadingCostumeAt`がruntime契約の正本であり、棚卸しやUI候補だけを受け入れ根拠にしない。新Schemaは登録用の各fragmentに投影し、ネットワークSchema参照を行わない。NP-finite-new-input-v1の対象はINDEXであり、STRINGであるVALUE.widthへ一律適用しない。widthのSchemaはSTRING構造を確認し、CPの正の有限値/resetをpure normalizerで意味検証する。STRINGの数値UIとprogrammatic候補はともに`0x10`・`+20`等を既存runtimeと同じく受け入れる。JSON数値文法のbuffer検査はINDEX等のnumber型投影に限定し、widthと区別する。
+
+既存alias（`typing`、短縮色、大小文字、旧数値表記）は表示投影だけでは書き換えない。PROPERTYの修復・変更時は最終branchで必要なVALUEを検査し、不適合なら修正/resetまで全patchを拒否する。selectorがreporter・欠落・非対応ならVALUEは読取専用。reporterを評価・置換しない。未知literal selectorは既知値へ修復可能で、未変更なら未知rawも保持する。NAMEや素材registry、font候補providerには触れない。
+
+同じ画面で分岐を切り替えてもdraftを保持し、保存失敗後も保持する。取消・dispose・project/target/登録の失効では共通sessionが破棄する。再openは現在のrawから開始し、旧draftを復活させない。登録はgetInfoに存在するopcodeだけを対象とし、同じinstance/APIへの重複登録を行わず、API置換・部分失敗・runtime終了・disposeでcleanupする。
+
+共通依存はGit commit `485f0e550e622235624b5e9176820161aeeba252`に固定する。開発用の型とpure数値parserを使い、登録はhostの`registerFixedInputEditor`へoptionsを渡す。既存composition APIにGUI/React実行依存を追加しない。runtime同梱JSと公開入口の型が外部common参照を要求しないことをbuildとpack consumerで確認する。
+
+`tests/fixed-input-editors.test.ts`でCP-asset-cacheのBC01〜05/14全6fixture、全5branchのruntime比較、空文字reset、有限数値と精度表記、旧raw保持、登録とcleanupを検証する。Asset Managerは別ownerであり、この結果を流用して合格とはしない。文書入口は`docs/index.html`と`docs/ja/index.html`の各固定アンカーから到達でき、Markdown再生成ではこれらの静的HTML説明を削除しない。
+
+切戻しは固定フラグをOFFにして再読込する。依存を戻す場合はmanifest・lock・実解決を一組で戻す。既存raw値やsb3の移行は不要。今回の作業はローカルのみで、commit・push・PR・merge・Pages公開・npm公開・Issue操作は含まない。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubohiroya/turbowarp-asset-cache",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "A browser-local image, audio, and runtime-text asset cache for TurboWarp projects.",
   "author": "Hiroya Kubo <hiroya@cuc.ac.jp>",
   "type": "module",
@@ -22,8 +22,11 @@
   },
   "files": [
     "dist/",
+    "schemas/",
+    "docs/fixed-input-editors.ja.md",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "docs/audio-playback.md"
   ],
   "unpkg": "./dist/asset-cache.js",
   "jsdelivr": "./dist/asset-cache.js",
@@ -60,9 +63,10 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.5",
-    "@kubohiroya/turbowarp-extension-manifest": "0.3.0",
-    "@kubohiroya/turbowarp-named-data": "0.1.0",
-    "@kubohiroya/vite-plugin-turbowarp-extension": "0.4.0",
+    "@kubohiroya/turbowarp-extension-data-editor": "0.2.1",
+    "@kubohiroya/turbowarp-extension-manifest": "0.3.2",
+    "@kubohiroya/turbowarp-named-data": "0.3.1",
+    "@kubohiroya/vite-plugin-turbowarp-extension": "0.6.1",
     "@types/node": "^22.20.1",
     "@xmldom/xmldom": "0.9.11",
     "eslint": "^9.39.5",
@@ -73,7 +77,7 @@
     "vitest": "^4.1.10"
   },
   "peerDependencies": {
-    "@kubohiroya/turbowarp-named-data": ">=0.1.0 <1"
+    "@kubohiroya/turbowarp-named-data": "0.3.1"
   },
   "keywords": [
     "turbowarp",

package/schemas/block-editor-fixed-inputs.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kubohiroya.github.io/turbowarp-asset-cache/schemas/block-editor-fixed-inputs.schema.json",
+  "$defs": {
+    "setTextStyle": {
+      "type": "object",
+      "properties": {
+        "PROPERTY": {"type": "string", "enum": ["animation", "font", "color", "width", "align"]},
+        "VALUE": {"type": "string"}
+      },
+      "additionalProperties": false
+    },
+    "animation": {"type": "string", "enum": ["", "none", "type", "rainbow", "zoom", "shake"]},
+    "font": {"type": "string"},
+    "color": {"type": "string", "pattern": "^(?:|#[0-9a-fA-F]{3}|#[0-9a-fA-F]{6})$"},
+    "width": {"type": "string", "$comment": "Empty/trimmed empty resets; otherwise normalizeTextStyleValue requires Number(value) finite and positive. Preserve the existing STRING grammar, including hexadecimal and leading plus."},
+    "align": {"type": "string", "enum": ["", "left", "center", "right"]},
+    "loadingCostumeAt": {
+      "type": "object",
+      "properties": {"INDEX": {"type": "number"}},
+      "additionalProperties": false
+    }
+  }
+}