@waica/engine 0.11.0 → 0.13.0

package/dist/index.d.ts

@@ -1,5 +1,9 @@
 export { Game } from './game.js';
-export type { GameOptions, GameResolution, SpawnPrefabOptions, UpdateFn, ParamOverrides, } from './game.js';
+export type { GameOptions, GameResolution, SceneCatalog, SpawnPrefabOptions, UpdateFn, ParamOverrides, } from './game.js';
+export { AudioSubsystem } from './audio/audio-subsystem.js';
+export type { AudioSubsystemOptions } from './audio/audio-subsystem.js';
+export type { AudioBackend, AudioResource, BackendPlayHandle, BackendPlayOptions } from './audio/backend.js';
+export type { AudioChannelState, AudioPlayOptions, LiveSoundInfo, SoundHandle } from './audio/types.js';
 export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
 export type { AnimationFacingProvider, DirectionalAnimation, DirectionalFallback, ResolvedDirectionalClip, } from './animation/directional.js';
 export { isYSortParticipant, ySortZ } from './render-sort.js';
@@ -25,7 +29,7 @@ export type { PointerCamera, PointerDeps, PointerPick, PointerResolution } from
 export { RUNTIME_BRIDGE_CAPABILITIES, RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';
 export type { RuntimeBridge, RuntimeBridgeActivation, RuntimeControlRequest, RuntimeControlResult, RuntimeMetadata, RuntimeMode, } from './runtime-bridge.js';
 export { RUNTIME_PROJECTION_LIMITS } from './runtime-inspection.js';
-export type { ProjectedValue, ProjectionIssue, ProjectionMarker, ProjectionMarkerKind, RuntimeComponentSnapshot, RuntimeEntitySnapshot, RuntimeSnapshot, RuntimeSnapshotFilters, RuntimeTransformSnapshot, } from './runtime-inspection.js';
+export type { ProjectedValue, ProjectionIssue, ProjectionMarker, ProjectionMarkerKind, RuntimeComponentSnapshot, RuntimeEntitySnapshot, RuntimeSnapshot, RuntimeSnapshotAudio, RuntimeSnapshotFilters, RuntimeTransformSnapshot, } from './runtime-inspection.js';
 export type { ArchetypeArt, ArchetypeManifest, BrowserArchetypeManifest, EntityTemplate, } from './archetype.js';
 export { Stats } from './stats.js';
 export type { StatValue } from './stats.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { Game } from './game.js';
+export { AudioSubsystem } from './audio/audio-subsystem.js';
 export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
 export { isYSortParticipant, ySortZ } from './render-sort.js';
 export { projectIsometric, screenInputToLogical, unprojectIsometric } from './projection.js';

package/dist/runtime-bridge.d.ts

@@ -11,7 +11,7 @@ export type RuntimeMode = 'paused' | 'real-time';
  * doesn't distinguish an engine that silently no-ops an unknown operation
  * from one that runs it.
  */
-export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click'];
+export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene'];
 export interface RuntimeMetadata {
     bridgeVersion: typeof RUNTIME_BRIDGE_PROTOCOL_VERSION;
     engineVersion: string;
@@ -33,6 +33,9 @@ export type RuntimeControlRequest = {
     operation: 'click';
     x: number;
     y: number;
+} | {
+    operation: 'scene';
+    scene: string;
 };
 export interface RuntimeControlResult extends RuntimeMetadata {
     heldActions: string[];
@@ -40,8 +43,9 @@ export interface RuntimeControlResult extends RuntimeMetadata {
 export declare class RuntimeBridgeOperationError extends Error {
     readonly code: 'runtime-invalid-state' | 'runtime-operation-failed';
     readonly availableActions?: string[] | undefined;
+    readonly availableScenes?: string[] | undefined;
     readonly stage: 'control';
-    constructor(code: 'runtime-invalid-state' | 'runtime-operation-failed', message: string, availableActions?: string[] | undefined);
+    constructor(code: 'runtime-invalid-state' | 'runtime-operation-failed', message: string, availableActions?: string[] | undefined, availableScenes?: string[] | undefined);
 }
 /** Engine-owned capability registered only in an MCP-activated page. */
 export interface RuntimeBridge {
@@ -66,6 +70,9 @@ export interface RuntimeBridgeHost {
     heldActions(): string[];
     inspect(metadata: RuntimeMetadata, filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
     click(x: number, y: number): void;
+    /** Resolves `name` through the registered catalog and loads it. */
+    loadScene(name: string): boolean;
+    availableScenes(): string[];
 }
 export declare class EngineRuntimeBridge implements RuntimeBridge {
     readonly surface: HTMLCanvasElement;

package/dist/runtime-bridge.js

@@ -10,15 +10,17 @@ export const RUNTIME_BRIDGE_SYMBOL = Symbol.for('@waica/runtime-bridge/v1');
  * doesn't distinguish an engine that silently no-ops an unknown operation
  * from one that runs it.
  */
-export const RUNTIME_BRIDGE_CAPABILITIES = ['click'];
+export const RUNTIME_BRIDGE_CAPABILITIES = ['click', 'scene'];
 export class RuntimeBridgeOperationError extends Error {
     code;
     availableActions;
+    availableScenes;
     stage = 'control';
-    constructor(code, message, availableActions) {
+    constructor(code, message, availableActions, availableScenes) {
         super(message);
         this.code = code;
         this.availableActions = availableActions;
+        this.availableScenes = availableScenes;
         this.name = 'RuntimeBridgeOperationError';
     }
 }
@@ -106,6 +108,13 @@ export class EngineRuntimeBridge {
                 this.host.click(request.x, request.y);
                 break;
             }
+            case 'scene': {
+                if (!this.host.loadScene(request.scene)) {
+                    const available = this.host.availableScenes();
+                    throw new RuntimeBridgeOperationError('runtime-operation-failed', `Unknown scene "${request.scene}". Available scenes: ${available.join(', ') || '(none)'}.`, undefined, available);
+                }
+                break;
+            }
             default: {
                 const unsupported = request;
                 throw new RuntimeBridgeOperationError('runtime-operation-failed', `Unsupported runtime control operation "${unsupported.operation}".`);

package/dist/runtime-inspection.d.ts

@@ -1,3 +1,4 @@
+import type { AudioChannelState, LiveSoundInfo } from './audio/types.js';
 import type { Game } from './game.js';
 import type { RuntimeMetadata } from './runtime-bridge.js';
 import type { StatValue } from './stats.js';
@@ -48,10 +49,29 @@ export interface RuntimeEntitySnapshot {
     transform: RuntimeTransformSnapshot;
     components: RuntimeComponentSnapshot[];
 }
+/**
+ * The mixer's state (CA-15): `master` and every channel's volume/mute,
+ * sorted by name, plus `playing` — `game.audio.liveSounds()` verbatim,
+ * already sorted (by uri then channel). Despite the name, `playing` is not
+ * "every currently-audible sound": per `liveSounds()`'s own docstring it
+ * also carries a loop retained before the autoplay unlock, a sound still
+ * loading, and even one about to fail to load (gone a tick later). Emitted
+ * unconditionally, like every other snapshot section —
+ * `[DEVIATION 2026-09-08]` in the spec: no section of RuntimeSnapshot is
+ * filterable today, so audio does not invent the first one.
+ */
+export interface RuntimeSnapshotAudio {
+    master: number;
+    channels: Record<string, AudioChannelState>;
+    playing: LiveSoundInfo[];
+}
 export interface RuntimeSnapshot extends RuntimeMetadata {
     stats: Record<string, StatValue>;
+    /** The live scene's name (its catalog key), or null with no scene loaded. */
+    scene: string | null;
     entities: RuntimeEntitySnapshot[];
     projectionIssues: ProjectionIssue[];
+    audio: RuntimeSnapshotAudio;
 }
 export declare const RUNTIME_PROJECTION_LIMITS: {
     readonly depth: 5;
@@ -66,6 +86,7 @@ export declare class RuntimeInspector {
     private nextId;
     constructor(game: Game);
     snapshot(metadata: RuntimeMetadata, filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
+    private audioSnapshot;
     private capSnapshot;
     private idFor;
 }

package/dist/runtime-inspection.js

@@ -234,10 +234,23 @@ export class RuntimeInspector {
         return this.capSnapshot({
             ...metadata,
             stats: Object.fromEntries([...this.game.stats.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))),
+            scene: this.game.sceneName,
             entities,
             projectionIssues,
+            audio: this.audioSnapshot(),
         });
     }
+    audioSnapshot() {
+        const channels = {};
+        for (const name of this.game.audio.channels().sort()) {
+            channels[name] = this.game.audio.channelState(name);
+        }
+        return {
+            master: this.game.audio.master,
+            channels,
+            playing: this.game.audio.liveSounds(),
+        };
+    }
     capSnapshot(snapshot) {
         if (utf8Bytes(JSON.stringify(snapshot)) <= RUNTIME_PROJECTION_LIMITS.snapshotBytes) {
             return snapshot;

package/dist/scene.d.ts

@@ -88,5 +88,9 @@ export declare function resolveProps(props: Record<string, unknown> | undefined,
 export declare function resolveEntityComponents(entity: SceneEntityJson, prefabs?: Record<string, PrefabJson>): SceneComponentJson[];
 /** Instantiates a scene entity into the game. */
 export declare function spawnFromJson(game: Game, json: SceneEntityJson, registry: SceneRegistry): Entity;
-/** Loads a full scene into the game. */
+/**
+ * Loads a full scene into the game, replacing whatever scene is already
+ * live (Game.unloadScene() first) — see ADR 0011. A Game shows one scene
+ * at a time.
+ */
 export declare function loadScene(game: Game, scene: SceneJson, registry: SceneRegistry): void;

package/dist/scene.js

@@ -79,8 +79,14 @@ export function spawnFromJson(game, json, registry) {
     }
     return entity;
 }
-/** Loads a full scene into the game. */
+/**
+ * Loads a full scene into the game, replacing whatever scene is already
+ * live (Game.unloadScene() first) — see ADR 0011. A Game shows one scene
+ * at a time.
+ */
 export function loadScene(game, scene, registry) {
+    if (game.registry)
+        game.unloadScene();
     game.registry = registry;
     game.setSceneRender(scene.render);
     for (const entityJson of scene.entities)
@@ -89,6 +95,7 @@ export function loadScene(game, scene, registry) {
     game.setSceneCamera(scene.camera);
     if (registry.ui)
         game.ui.defineAll(registry.ui);
+    // Scene-scoped: Game.unloadScene() unmounts these along with the entities.
     for (const name of scene.ui ?? [])
-        game.ui.show(name);
+        game.ui.show(name, { scope: 'scene' });
 }

package/dist/ui.d.ts

@@ -27,7 +27,7 @@ export declare class GameUi {
     defineAll(pieces: Record<string, string>): void;
     /** Piece names available to show (defined via the registry or define()). */
     names(): string[];
-    show(name: string): void;
+    show(name: string, options?: ShowOptions): void;
     hide(name: string): void;
     toggle(name: string): void;
     isVisible(name: string): boolean;
@@ -41,7 +41,18 @@ export declare class GameUi {
     setActive(active: boolean): void;
     /** Unmounts every piece and removes the overlay (Game.dispose). */
     dispose(): void;
+    /**
+     * Unmounts every scene-scoped piece: the ones `loadScene` showed from the
+     * outgoing scene's `ui` list, plus any shown with `{ scope: 'scene' }`.
+     * A piece the host showed with no scope is untouched. The definition
+     * catalog (sources) always survives — Game.unloadScene.
+     */
+    unloadScene(): void;
     private mount;
     private mountOverlay;
     private sync;
 }
+export interface ShowOptions {
+    /** 'scene': unmounted by Game.unloadScene() along with the rest of the scene. */
+    scope?: 'scene';
+}

package/dist/ui.js

@@ -35,10 +35,19 @@ export class GameUi {
     names() {
         return [...this.sources.keys()];
     }
-    show(name) {
+    show(name, options = {}) {
+        const mounted = this.pieces.has(name);
         const piece = this.mount(name);
-        if (piece)
+        if (piece) {
             piece.visible = true;
+            // Scope belongs to whoever mounts the piece, and a later show never
+            // changes it. Otherwise a scene whose `ui` list happens to name a piece
+            // the host already mounted would quietly take ownership of it and
+            // destroy it on the next unload — a session-scoped HUD dying with a
+            // map it merely shares a name with.
+            if (!mounted)
+                piece.scope = options.scope;
+        }
         this.sync();
     }
     hide(name) {
@@ -81,6 +90,23 @@ export class GameUi {
         this.overlay?.remove();
         this.overlay = undefined;
     }
+    /**
+     * Unmounts every scene-scoped piece: the ones `loadScene` showed from the
+     * outgoing scene's `ui` list, plus any shown with `{ scope: 'scene' }`.
+     * A piece the host showed with no scope is untouched. The definition
+     * catalog (sources) always survives — Game.unloadScene.
+     */
+    unloadScene() {
+        for (const [name, piece] of this.pieces) {
+            if (piece.scope !== 'scene')
+                continue;
+            for (const off of piece.unsubs)
+                off();
+            piece.shell.remove();
+            this.pieces.delete(name);
+        }
+        this.sync();
+    }
     mount(name) {
         const existing = this.pieces.get(name);
         if (existing)
@@ -100,7 +126,13 @@ export class GameUi {
         root.style.display = 'contents';
         root.innerHTML = html;
         shadow.append(root);
-        const piece = { shell, root, visible: false, unsubs: bindStats(root, this.stats) };
+        const piece = {
+            shell,
+            root,
+            visible: false,
+            scope: undefined,
+            unsubs: bindStats(root, this.stats),
+        };
         this.mountOverlay().append(shell);
         this.pieces.set(name, piece);
         return piece;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/engine",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",