@forgeax/engine-audio 0.1.2

package/dist/components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../src/components.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,WAAW;;;;;;;EAOtB,CAAC;AAEH,eAAO,MAAM,aAAa,8DAAuC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { AUDIO_ERROR_HINTS, type AudioClipAsset, AudioError, type AudioErrorCode, type AudioErrorDetail, } from '@forgeax/engine-types';
+export { audioContribution } from './assets/audio-decoder';
+export type { AudioListenerPose, AudioPlayOptions, AudioState } from './audio-backend';
+export { AUDIO_ENGINE_RESOURCE_KEY, type AudioBackend, type BusName, } from './audio-backend';
+export { type AudioIntent, type AudioIntentBackendOptions, audioIntentErrorState, createAudioIntentBackend, } from './audio-intent';
+export { audioTickSystem, createClipResolver, detectEdge, detectRemovedEntities, type EdgeAction, listenerPoseFromWorldMatrix, } from './audio-tick-system';
+export { AudioListener, AudioSource } from './components';
+export { AUDIO_TICK_SYSTEM_NAME, audioPlugin } from './plugin-factory';
+export { audioBackendPlugin } from './plugin-service';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,EACL,iBAAiB,EACjB,KAAK,cAAc,EACnB,UAAU,EACV,KAAK,cAAc,EACnB,KAAK,gBAAgB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,EACL,yBAAyB,EACzB,KAAK,YAAY,EACjB,KAAK,OAAO,GACb,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,yBAAyB,EAC9B,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,UAAU,EACV,qBAAqB,EACrB,KAAK,UAAU,EACf,2BAA2B,GAC5B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.mjs

@@ -0,0 +1,266 @@
+import { ok, err } from '@forgeax/engine-types';
+export { AUDIO_ERROR_HINTS, AudioError } from '@forgeax/engine-types';
+import { defineComponent, Update } from '@forgeax/engine-ecs';
+import { PROPAGATE_TRANSFORMS_SYSTEM, Transform } from '@forgeax/engine-scene';
+
+// src/index.ts
+var audioContribution = {
+  kind: { kind: "audio" },
+  consumer: "AudioBackend",
+  decoder: {
+    async decode({ envelope, artifacts }) {
+      const payload = envelope.payload;
+      if (payload !== null && typeof payload === "object") {
+        const source = payload;
+        let bytes = source.bytes instanceof Uint8Array ? source.bytes : Array.isArray(source.bytes) ? Uint8Array.from(source.bytes) : void 0;
+        const body = envelope.artifacts.body ?? envelope.artifacts.source;
+        if (body !== void 0) {
+          const bodyBytes = await artifacts.read(body);
+          if (!bodyBytes.ok) return bodyBytes;
+          bytes = bodyBytes.value;
+        }
+        if (source.kind === "audio" && typeof source.mediaType === "string" && source.mediaType.startsWith("audio/") && bytes !== void 0 && bytes.byteLength > 0) {
+          return ok({
+            kind: "audio",
+            sourceKey: typeof source.sourceKey === "string" && source.sourceKey.length > 0 ? source.sourceKey : envelope.guid,
+            mediaType: source.mediaType,
+            bytes
+          });
+        }
+      }
+      return err({
+        code: "asset-package-invalid",
+        expected: "an audio payload with non-empty source bytes and audio mediaType",
+        hint: "recook the audio source with a browser-supported media type",
+        detail: { guid: envelope.guid, reason: "audio owner validation failed" }
+      });
+    }
+  }
+};
+
+// src/audio-backend.ts
+var AUDIO_ENGINE_RESOURCE_KEY = "AudioEngine";
+
+// src/audio-intent.ts
+function sameBytes(left, right) {
+  if (left.byteLength !== right.byteLength) return false;
+  for (let index = 0; index < left.byteLength; index += 1) {
+    if (left[index] !== right[index]) return false;
+  }
+  return true;
+}
+var DISCONNECTED_AUDIO_STATE = {
+  contextState: "suspended",
+  activeSourceCount: 0,
+  lastError: null
+};
+function createAudioIntentBackend(options) {
+  const publishedSources = /* @__PURE__ */ new Map();
+  let destroyed = false;
+  const emit = (intent) => {
+    if (!destroyed || intent.kind === "destroy") options.emit(intent);
+  };
+  const backend = {
+    play(entityId, clip, playOptions) {
+      const publishedBytes = publishedSources.get(clip.sourceKey);
+      const publishBytes = publishedBytes === void 0 || !sameBytes(publishedBytes, clip.bytes);
+      if (publishBytes) publishedSources.set(clip.sourceKey, clip.bytes.slice());
+      emit({
+        kind: "play",
+        entityId,
+        sourceKey: clip.sourceKey,
+        ...publishBytes ? { bytes: clip.bytes } : {},
+        options: playOptions
+      });
+    },
+    stop: (entityId) => emit({ kind: "stop", entityId }),
+    setVolume: (entityId, volume) => emit({ kind: "set-volume", entityId, volume }),
+    setBusVolume: (bus, volume) => {
+      const intent = { kind: "set-bus-volume", bus, volume };
+      emit(intent);
+    },
+    setBusMute: (bus, muted) => {
+      const intent = { kind: "set-bus-mute", bus, muted };
+      emit(intent);
+    },
+    setListenerPose: (pose) => {
+      const intent = { kind: "set-listener-pose", pose };
+      emit(intent);
+    },
+    getState: () => options.state?.() ?? DISCONNECTED_AUDIO_STATE,
+    getActiveSourceCount: () => (options.state?.() ?? DISCONNECTED_AUDIO_STATE).activeSourceCount,
+    destroy() {
+      if (destroyed) return;
+      const intent = { kind: "destroy" };
+      emit(intent);
+      destroyed = true;
+      publishedSources.clear();
+    }
+  };
+  return backend;
+}
+function audioIntentErrorState(error) {
+  return { contextState: "suspended", activeSourceCount: 0, lastError: error };
+}
+var AudioSource = defineComponent("AudioSource", {
+  clip: { type: "shared<AudioClipAsset>" },
+  playing: { type: "bool", default: false },
+  loop: { type: "bool", default: false },
+  volume: { type: "f32", default: 1 },
+  spatialBlend: { type: "f32", default: 0 },
+  bus: { type: "string", default: "sfx" }
+});
+var AudioListener = defineComponent("AudioListener", {});
+
+// src/audio-tick-system.ts
+function listenerPoseFromWorldMatrix(world) {
+  const forwardLength = Math.hypot(world[8] ?? 0, world[9] ?? 0, world[10] ?? 0) || 1;
+  const upLength = Math.hypot(world[4] ?? 0, world[5] ?? 0, world[6] ?? 0) || 1;
+  return {
+    positionX: world[12] ?? 0,
+    positionY: world[13] ?? 0,
+    positionZ: world[14] ?? 0,
+    forwardX: -(world[8] ?? 0) / forwardLength,
+    forwardY: -(world[9] ?? 0) / forwardLength,
+    forwardZ: -(world[10] ?? 0) / forwardLength,
+    upX: (world[4] ?? 0) / upLength,
+    upY: (world[5] ?? 0) / upLength,
+    upZ: (world[6] ?? 0) / upLength
+  };
+}
+function detectEdge(previous, current) {
+  if (!previous && current) return "play-start";
+  if (previous && !current) return "play-stop";
+  return "none";
+}
+function detectRemovedEntities(previous, current) {
+  const currentSet = new Set(current);
+  return previous.filter((entity) => !currentSet.has(entity));
+}
+var states = /* @__PURE__ */ new WeakMap();
+function stateFor(backend) {
+  const existing = states.get(backend);
+  if (existing !== void 0) return existing;
+  const created = {
+    playing: /* @__PURE__ */ new Map(),
+    previousEntities: /* @__PURE__ */ new Set(),
+    volumes: /* @__PURE__ */ new Map()
+  };
+  states.set(backend, created);
+  return created;
+}
+function createClipResolver(world) {
+  return (clipHandle) => {
+    const resolved = world.sharedRefs.resolve(
+      clipHandle
+    );
+    return resolved.ok && resolved.value.kind === "audio" ? resolved.value : void 0;
+  };
+}
+function audioTickSystem(world, backend) {
+  const state = stateFor(backend);
+  const resolveClip = createClipResolver(world);
+  const currentEntities = [];
+  const query = world.query({ read: [AudioSource] });
+  if (!query.ok) return;
+  for (const queryRow of query.value) {
+    const entity = queryRow.entity;
+    const source = queryRow.get(AudioSource);
+    const playing = source.playing === true;
+    const previous = state.playing.get(entity) ?? false;
+    const edge = detectEdge(previous, playing);
+    if (edge === "play-start") {
+      const clip = resolveClip(source.clip);
+      if (clip === void 0) {
+        state.playing.set(entity, false);
+      } else {
+        const options = {
+          loop: source.loop === true,
+          volume: typeof source.volume === "number" ? source.volume : 1,
+          spatialBlend: typeof source.spatialBlend === "number" ? source.spatialBlend : 0,
+          bus: typeof source.bus === "string" ? source.bus : "sfx"
+        };
+        backend.play(entity, clip, options);
+        state.playing.set(entity, true);
+        state.volumes.set(entity, options.volume);
+      }
+    } else {
+      state.playing.set(entity, playing);
+      if (edge === "play-stop") {
+        backend.stop(entity);
+      } else if (playing && typeof source.volume === "number" && state.volumes.get(entity) !== source.volume) {
+        backend.setVolume(entity, source.volume);
+        state.volumes.set(entity, source.volume);
+      }
+    }
+    currentEntities.push(entity);
+  }
+  for (const entity of detectRemovedEntities([...state.previousEntities], currentEntities)) {
+    if (state.playing.get(entity) === true) {
+      backend.stop(entity);
+    }
+    state.playing.delete(entity);
+    state.volumes.delete(entity);
+  }
+  state.previousEntities.clear();
+  for (const entity of currentEntities) state.previousEntities.add(entity);
+}
+var AUDIO_TICK_SYSTEM_NAME = "audio-tick";
+function audioPlugin() {
+  return {
+    name: "audio",
+    inject: ["world", "audio"],
+    apply(ctx) {
+      const world = ctx.world;
+      const backend = ctx.audio;
+      if (backend === void 0) throw new Error("Cordis activated audio without its provider");
+      ctx.effect(() => {
+        world.insertResource(AUDIO_ENGINE_RESOURCE_KEY, backend);
+        return () => {
+          world.removeResource(AUDIO_ENGINE_RESOURCE_KEY);
+        };
+      }, "audio/resource");
+      ctx.effect(() => {
+        world.addSystem(Update, {
+          name: AUDIO_TICK_SYSTEM_NAME,
+          queries: [],
+          fn: () => audioTickSystem(world, backend)
+        }).unwrap();
+        return () => world.removeSystem(Update, AUDIO_TICK_SYSTEM_NAME);
+      }, "audio/tick");
+      ctx.effect(() => {
+        world.addSystem(Update, {
+          name: "audio-listener-sync",
+          after: [PROPAGATE_TRANSFORMS_SYSTEM],
+          queries: [],
+          fn: () => {
+            const listeners = world.query({ read: [Transform], with: [AudioListener] });
+            if (!listeners.ok) return;
+            for (const row of listeners.value) {
+              const transform = row.get(Transform);
+              const pose = listenerPoseFromWorldMatrix(transform.world);
+              backend.setListenerPose(pose);
+              break;
+            }
+          }
+        }).unwrap();
+        return () => world.removeSystem(Update, "audio-listener-sync");
+      }, "audio/listener-sync");
+    }
+  };
+}
+
+// src/plugin-service.ts
+function audioBackendPlugin(backend) {
+  return {
+    name: "audio-backend",
+    provide: "audio",
+    apply(ctx) {
+      ctx.provide("audio", backend);
+    }
+  };
+}
+
+export { AUDIO_ENGINE_RESOURCE_KEY, AUDIO_TICK_SYSTEM_NAME, AudioListener, AudioSource, audioBackendPlugin, audioContribution, audioIntentErrorState, audioPlugin, audioTickSystem, createAudioIntentBackend, createClipResolver, detectEdge, detectRemovedEntities, listenerPoseFromWorldMatrix };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/assets/audio-decoder.ts","../src/audio-backend.ts","../src/audio-intent.ts","../src/components.ts","../src/audio-tick-system.ts","../src/plugin-factory.ts","../src/plugin-service.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["import {\n  type AssetDecoderContribution,\n  type AssetKind,\n  type AudioClipAsset,\n  err,\n  ok,\n} from '@forgeax/engine-types';\n\nexport const audioContribution: AssetDecoderContribution<AudioClipAsset, 'audio'> = {\n  kind: { kind: 'audio' } as AssetKind<AudioClipAsset, 'audio'>,\n  consumer: 'AudioBackend',\n  decoder: {\n    async decode({ envelope, artifacts }) {\n      const payload = envelope.payload as unknown;\n      if (payload !== null && typeof payload === 'object') {\n        const source = payload as Record<string, unknown>;\n        let bytes =\n          source.bytes instanceof Uint8Array\n            ? source.bytes\n            : Array.isArray(source.bytes)\n              ? Uint8Array.from(source.bytes as number[])\n              : undefined;\n        const body = envelope.artifacts.body ?? envelope.artifacts.source;\n        if (body !== undefined) {\n          const bodyBytes = await artifacts.read(body);\n          if (!bodyBytes.ok) return bodyBytes;\n          bytes = bodyBytes.value;\n        }\n        if (\n          source.kind === 'audio' &&\n          typeof source.mediaType === 'string' &&\n          source.mediaType.startsWith('audio/') &&\n          bytes !== undefined &&\n          bytes.byteLength > 0\n        ) {\n          return ok({\n            kind: 'audio',\n            sourceKey:\n              typeof source.sourceKey === 'string' && source.sourceKey.length > 0\n                ? source.sourceKey\n                : envelope.guid,\n            mediaType: source.mediaType as `audio/${string}`,\n            bytes,\n          });\n        }\n      }\n      return err({\n        code: 'asset-package-invalid',\n        expected: 'an audio payload with non-empty source bytes and audio mediaType',\n        hint: 'recook the audio source with a browser-supported media type',\n        detail: { guid: envelope.guid, reason: 'audio owner validation failed' },\n      });\n    },\n  },\n};\n","// @forgeax/engine-audio -- AudioBackend protocol interface (feat-20260527-audio-system M1 / w8)\n//\n// Decision anchors:\n// - plan-strategy D-1 (dual-package split: interface in engine-audio, impl in engine-audio-webaudio)\n// - plan-strategy D-5 (fixed two-bus topology: SFX + Music -> Master; bus name literal union)\n// - requirements S-5 (dual bus mixing hierarchy) + S-9 (AudioEngine Resource)\n// - requirements S-7 (entity despawn cleanup: stop + disconnect)\n// - charter P4 (consistent abstraction: structurally parallel to InputBackend)\n\nimport type { AudioClipAsset, AudioError } from '@forgeax/engine-types';\n\nexport type BusName = 'sfx' | 'music';\n\nexport const AUDIO_ENGINE_RESOURCE_KEY = 'AudioEngine' as const;\n\nexport interface AudioPlayOptions {\n  readonly loop: boolean;\n  readonly volume: number;\n  readonly spatialBlend: number;\n  readonly bus: BusName;\n}\n\nexport interface AudioListenerPose {\n  readonly positionX: number;\n  readonly positionY: number;\n  readonly positionZ: number;\n  readonly forwardX: number;\n  readonly forwardY: number;\n  readonly forwardZ: number;\n  readonly upX: number;\n  readonly upY: number;\n  readonly upZ: number;\n}\n\nexport interface AudioState {\n  readonly contextState: 'running' | 'suspended' | 'closed';\n  readonly activeSourceCount: number;\n  readonly lastError: AudioError | null;\n}\n\nexport interface AudioBackend {\n  play(entityId: number, clip: AudioClipAsset, opts: AudioPlayOptions): void;\n  stop(entityId: number): void;\n  setVolume(entityId: number, volume: number): void;\n  setBusVolume(busName: BusName, volume: number): void;\n  setBusMute(busName: BusName, muted: boolean): void;\n  setListenerPose(pose: AudioListenerPose): void;\n  getState(): AudioState;\n  getActiveSourceCount(): number;\n  destroy(): void;\n}\n","import type { AudioClipAsset, AudioError } from '@forgeax/engine-types';\nimport type {\n  AudioBackend,\n  AudioListenerPose,\n  AudioPlayOptions,\n  AudioState,\n  BusName,\n} from './audio-backend';\n\nexport type AudioIntent =\n  | {\n      readonly kind: 'play';\n      readonly entityId: number;\n      readonly sourceKey: string;\n      readonly bytes?: Uint8Array;\n      readonly options: AudioPlayOptions;\n    }\n  | { readonly kind: 'stop'; readonly entityId: number }\n  | { readonly kind: 'set-volume'; readonly entityId: number; readonly volume: number }\n  | { readonly kind: 'set-bus-volume'; readonly bus: BusName; readonly volume: number }\n  | { readonly kind: 'set-bus-mute'; readonly bus: BusName; readonly muted: boolean }\n  | { readonly kind: 'set-listener-pose'; readonly pose: AudioListenerPose }\n  | { readonly kind: 'destroy' };\n\nfunction sameBytes(left: Uint8Array, right: Uint8Array): boolean {\n  if (left.byteLength !== right.byteLength) return false;\n  for (let index = 0; index < left.byteLength; index += 1) {\n    if (left[index] !== right[index]) return false;\n  }\n  return true;\n}\n\nexport interface AudioIntentBackendOptions {\n  readonly emit: (intent: AudioIntent) => void;\n  readonly state?: () => AudioState;\n}\n\nconst DISCONNECTED_AUDIO_STATE: AudioState = {\n  contextState: 'suspended',\n  activeSourceCount: 0,\n  lastError: null,\n};\n\nexport function createAudioIntentBackend(options: AudioIntentBackendOptions): AudioBackend {\n  const publishedSources = new Map<string, Uint8Array>();\n  let destroyed = false;\n  const emit = (intent: AudioIntent): void => {\n    if (!destroyed || intent.kind === 'destroy') options.emit(intent);\n  };\n  const backend: AudioBackend = {\n    play(entityId: number, clip: AudioClipAsset, playOptions: AudioPlayOptions): void {\n      const publishedBytes = publishedSources.get(clip.sourceKey);\n      const publishBytes = publishedBytes === undefined || !sameBytes(publishedBytes, clip.bytes);\n      if (publishBytes) publishedSources.set(clip.sourceKey, clip.bytes.slice());\n      emit({\n        kind: 'play',\n        entityId,\n        sourceKey: clip.sourceKey,\n        ...(publishBytes ? { bytes: clip.bytes } : {}),\n        options: playOptions,\n      });\n    },\n    stop: (entityId) => emit({ kind: 'stop', entityId }),\n    setVolume: (entityId, volume) => emit({ kind: 'set-volume', entityId, volume }),\n    setBusVolume: (bus, volume) => {\n      const intent = { kind: 'set-bus-volume', bus, volume } as const;\n      emit(intent);\n    },\n    setBusMute: (bus, muted) => {\n      const intent = { kind: 'set-bus-mute', bus, muted } as const;\n      emit(intent);\n    },\n    setListenerPose: (pose) => {\n      const intent = { kind: 'set-listener-pose', pose } as const;\n      emit(intent);\n    },\n    getState: () => options.state?.() ?? DISCONNECTED_AUDIO_STATE,\n    getActiveSourceCount: () => (options.state?.() ?? DISCONNECTED_AUDIO_STATE).activeSourceCount,\n    destroy(): void {\n      if (destroyed) return;\n      const intent = { kind: 'destroy' } as const;\n      emit(intent);\n      destroyed = true;\n      publishedSources.clear();\n    },\n  };\n  return backend;\n}\n\nexport function audioIntentErrorState(error: AudioError): AudioState {\n  return { contextState: 'suspended', activeSourceCount: 0, lastError: error };\n}\n","// @forgeax/engine-audio -- AudioSource + AudioListener ECS components (feat-20260527-audio-system M1 / w9)\n//\n// Decision anchors:\n// - requirements S-3 (AudioSource single-component surface, 6 fields)\n// - requirements S-4 (AudioListener independent marker component)\n// - plan-strategy D-4 (edge-detection tick system; AudioSource.playing drives play/stop edges)\n// - plan-strategy D-5 (AudioSource.bus defaults to 'sfx'; BusName is 'sfx' | 'music')\n// - plan-strategy section 3.1 (6-field AudioSource + marker AudioListener)\n// - charter P1 (progressive disclosure: 3-symbol core surface)\n// - charter P4 (consistent abstraction: same defineComponent pattern as Transform/Camera)\n\nimport { defineComponent } from '@forgeax/engine-ecs';\n\nexport const AudioSource = defineComponent('AudioSource', {\n  clip: { type: 'shared<AudioClipAsset>' },\n  playing: { type: 'bool', default: false },\n  loop: { type: 'bool', default: false },\n  volume: { type: 'f32', default: 1.0 },\n  spatialBlend: { type: 'f32', default: 0 },\n  bus: { type: 'string', default: 'sfx' },\n});\n\nexport const AudioListener = defineComponent('AudioListener', {});\n","import type { World } from '@forgeax/engine-ecs';\nimport type { AudioClipAsset } from '@forgeax/engine-types';\nimport type { AudioBackend, AudioPlayOptions, BusName } from './audio-backend';\nimport { AudioSource } from './components';\n\nexport function listenerPoseFromWorldMatrix(world: Float32Array) {\n  const forwardLength = Math.hypot(world[8] ?? 0, world[9] ?? 0, world[10] ?? 0) || 1;\n  const upLength = Math.hypot(world[4] ?? 0, world[5] ?? 0, world[6] ?? 0) || 1;\n  return {\n    positionX: world[12] ?? 0,\n    positionY: world[13] ?? 0,\n    positionZ: world[14] ?? 0,\n    forwardX: -(world[8] ?? 0) / forwardLength,\n    forwardY: -(world[9] ?? 0) / forwardLength,\n    forwardZ: -(world[10] ?? 0) / forwardLength,\n    upX: (world[4] ?? 0) / upLength,\n    upY: (world[5] ?? 0) / upLength,\n    upZ: (world[6] ?? 0) / upLength,\n  };\n}\n\nexport type EdgeAction = ReturnType<typeof detectEdge>;\n\nexport function detectEdge(previous: boolean, current: boolean) {\n  if (!previous && current) return 'play-start';\n  if (previous && !current) return 'play-stop';\n  return 'none';\n}\n\nexport function detectRemovedEntities(\n  previous: readonly number[],\n  current: readonly number[],\n): number[] {\n  const currentSet = new Set(current);\n  return previous.filter((entity) => !currentSet.has(entity));\n}\n\ninterface TickState {\n  playing: Map<number, boolean>;\n  previousEntities: Set<number>;\n  volumes: Map<number, number>;\n}\n\nconst states = new WeakMap<AudioBackend, TickState>();\n\nfunction stateFor(backend: AudioBackend): TickState {\n  const existing = states.get(backend);\n  if (existing !== undefined) return existing;\n  const created: TickState = {\n    playing: new Map(),\n    previousEntities: new Set(),\n    volumes: new Map(),\n  };\n  states.set(backend, created);\n  return created;\n}\n\nexport function createClipResolver(\n  world: World,\n): (clipHandle: number) => AudioClipAsset | undefined {\n  return (clipHandle) => {\n    const resolved = world.sharedRefs.resolve<string, AudioClipAsset>(\n      clipHandle as unknown as Parameters<typeof world.sharedRefs.resolve>[0],\n    );\n    return resolved.ok && resolved.value.kind === 'audio' ? resolved.value : undefined;\n  };\n}\n\nexport function audioTickSystem(world: World, backend: AudioBackend): void {\n  const state = stateFor(backend);\n  const resolveClip = createClipResolver(world);\n  const currentEntities: number[] = [];\n  const query = world.query({ read: [AudioSource] });\n  if (!query.ok) return;\n  for (const queryRow of query.value) {\n    const entity = queryRow.entity as number;\n    const source = queryRow.get(AudioSource);\n    const playing = source.playing === true;\n    const previous = state.playing.get(entity) ?? false;\n    const edge = detectEdge(previous, playing);\n    if (edge === 'play-start') {\n      const clip = resolveClip(source.clip as number);\n      if (clip === undefined) {\n        state.playing.set(entity, false);\n      } else {\n        const options: AudioPlayOptions = {\n          loop: source.loop === true,\n          volume: typeof source.volume === 'number' ? source.volume : 1,\n          spatialBlend: typeof source.spatialBlend === 'number' ? source.spatialBlend : 0,\n          bus: (typeof source.bus === 'string' ? source.bus : 'sfx') as BusName,\n        };\n        backend.play(entity, clip, options);\n        state.playing.set(entity, true);\n        state.volumes.set(entity, options.volume);\n      }\n    } else {\n      state.playing.set(entity, playing);\n      if (edge === 'play-stop') {\n        backend.stop(entity);\n      } else if (\n        playing &&\n        typeof source.volume === 'number' &&\n        state.volumes.get(entity) !== source.volume\n      ) {\n        backend.setVolume(entity, source.volume);\n        state.volumes.set(entity, source.volume);\n      }\n    }\n    currentEntities.push(entity);\n  }\n  for (const entity of detectRemovedEntities([...state.previousEntities], currentEntities)) {\n    if (state.playing.get(entity) === true) {\n      backend.stop(entity);\n    }\n    state.playing.delete(entity);\n    state.volumes.delete(entity);\n  }\n  state.previousEntities.clear();\n  for (const entity of currentEntities) state.previousEntities.add(entity);\n}\n","import { Update } from '@forgeax/engine-ecs';\nimport type { Plugin } from '@forgeax/engine-plugin';\nimport { PROPAGATE_TRANSFORMS_SYSTEM, Transform } from '@forgeax/engine-scene';\nimport { AUDIO_ENGINE_RESOURCE_KEY } from './audio-backend';\nimport { audioTickSystem, listenerPoseFromWorldMatrix } from './audio-tick-system';\nimport { AudioListener } from './components';\n\nexport const AUDIO_TICK_SYSTEM_NAME = 'audio-tick' as const;\n\nexport function audioPlugin(): Plugin {\n  return {\n    name: 'audio',\n    inject: ['world', 'audio'],\n    apply(ctx) {\n      const world = ctx.world;\n      const backend = ctx.audio;\n      if (backend === undefined) throw new Error('Cordis activated audio without its provider');\n      ctx.effect(() => {\n        world.insertResource(AUDIO_ENGINE_RESOURCE_KEY, backend);\n        return () => {\n          world.removeResource(AUDIO_ENGINE_RESOURCE_KEY);\n        };\n      }, 'audio/resource');\n      ctx.effect(() => {\n        world\n          .addSystem(Update, {\n            name: AUDIO_TICK_SYSTEM_NAME,\n            queries: [],\n            fn: () => audioTickSystem(world, backend),\n          })\n          .unwrap();\n        return () => world.removeSystem(Update, AUDIO_TICK_SYSTEM_NAME);\n      }, 'audio/tick');\n      ctx.effect(() => {\n        world\n          .addSystem(Update, {\n            name: 'audio-listener-sync',\n            after: [PROPAGATE_TRANSFORMS_SYSTEM],\n            queries: [],\n            fn: () => {\n              const listeners = world.query({ read: [Transform], with: [AudioListener] });\n              if (!listeners.ok) return;\n              for (const row of listeners.value) {\n                const transform = row.get(Transform);\n                const pose = listenerPoseFromWorldMatrix(transform.world);\n                backend.setListenerPose(pose);\n                break;\n              }\n            },\n          })\n          .unwrap();\n        return () => world.removeSystem(Update, 'audio-listener-sync');\n      }, 'audio/listener-sync');\n    },\n  };\n}\n","import type { Plugin } from '@forgeax/engine-plugin';\n\nimport type { AudioBackend } from './audio-backend';\n\ndeclare module '@forgeax/engine-plugin' {\n  interface EngineContextServices {\n    audio?: AudioBackend;\n  }\n}\n\nexport function audioBackendPlugin(backend: AudioBackend): Plugin {\n  return {\n    name: 'audio-backend',\n    provide: 'audio',\n    apply(ctx) {\n      ctx.provide('audio', backend);\n    },\n  };\n}\n"]}

package/dist/plugin-factory.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from '@forgeax/engine-plugin';
+export declare const AUDIO_TICK_SYSTEM_NAME: "audio-tick";
+export declare function audioPlugin(): Plugin;
+//# sourceMappingURL=plugin-factory.d.ts.map

package/dist/plugin-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-factory.d.ts","sourceRoot":"","sources":["../src/plugin-factory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAMrD,eAAO,MAAM,sBAAsB,EAAG,YAAqB,CAAC;AAE5D,wBAAgB,WAAW,IAAI,MAAM,CA8CpC"}

package/dist/plugin-service.d.ts

@@ -0,0 +1,9 @@
+import type { Plugin } from '@forgeax/engine-plugin';
+import type { AudioBackend } from './audio-backend';
+declare module '@forgeax/engine-plugin' {
+    interface EngineContextServices {
+        audio?: AudioBackend;
+    }
+}
+export declare function audioBackendPlugin(backend: AudioBackend): Plugin;
+//# sourceMappingURL=plugin-service.d.ts.map

package/dist/plugin-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-service.d.ts","sourceRoot":"","sources":["../src/plugin-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAErD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,OAAO,QAAQ,wBAAwB,CAAC;IACtC,UAAU,qBAAqB;QAC7B,KAAK,CAAC,EAAE,YAAY,CAAC;KACtB;CACF;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAQhE"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@forgeax/engine-audio",
+  "version": "0.1.2",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Realm-neutral ForgeaX audio: ECS components, tick/plugin, backend protocol, POD clips, and closed Host intent transport.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-ecs": "0.1.2",
+    "@forgeax/engine-math": "0.1.2",
+    "@forgeax/engine-plugin": "0.1.2",
+    "@forgeax/engine-scene": "0.1.2",
+    "@forgeax/engine-types": "0.1.2"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": false,
+        "reason": "runtime tick and intent producer are covered by package build/tests; no standalone player bundle is emitted"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "realm-neutral package has no canvas; frame impact is measured by consuming apps"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "intent production is linear in changed sources; end-to-end cost is measured by the multithreaded execution app"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "no package-level binary gate; test surface coverage runs as part of pnpm test:unit + tsc -b"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package; this is a production MVP per plan-strategy D-1 (dual-package split)"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc -b"
+  }
+}

package/src/__tests__/asset-decoder.unit.test.ts

@@ -0,0 +1,26 @@
+import { World } from '@forgeax/engine-ecs';
+import type { AudioClipAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { audioContribution } from '../assets/audio-decoder';
+import { createClipResolver } from '../audio-tick-system';
+
+describe('audio asset consumer boundary', () => {
+  it('exposes the realm-neutral audio owner contribution', () => {
+    expect(audioContribution.kind.kind).toBe('audio');
+    expect(audioContribution.consumer).toBe('AudioBackend');
+  });
+  it('resolves a durable audio payload without a registry or host object', () => {
+    const clip: AudioClipAsset = {
+      kind: 'audio',
+      sourceKey: '019e2cc6-0c86-79da-aa76-b0984c86d45c',
+      mediaType: 'audio/ogg',
+      bytes: new Uint8Array([1, 2, 3]),
+    };
+    const world = new World();
+    const handle = world.internSharedRef('AudioClipAsset', clip);
+    const resolver = createClipResolver(world);
+
+    expect(resolver(handle)).toBe(clip);
+    expect(resolver(0)).toBeUndefined();
+  });
+});

package/src/__tests__/audio-edge-action-owner.test-d.ts

@@ -0,0 +1,25 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { detectEdge, type EdgeAction } from '../audio-tick-system.js';
+import type { EdgeAction as PublicEdgeAction } from '../index.js';
+
+describe('audio edge action owner', () => {
+  it('derives the public action from the executable edge detector', () => {
+    expectTypeOf<EdgeAction>().toEqualTypeOf<ReturnType<typeof detectEdge>>();
+    expectTypeOf<ReturnType<typeof detectEdge>>().toEqualTypeOf<
+      'none' | 'play-start' | 'play-stop'
+    >();
+    expectTypeOf<PublicEdgeAction>().toEqualTypeOf<EdgeAction>();
+
+    expect(detectEdge(false, false)).toBe('none');
+    expect(detectEdge(false, true)).toBe('play-start');
+    expect(detectEdge(true, false)).toBe('play-stop');
+    expect(detectEdge(true, true)).toBe('none');
+
+    const acceptsAction = (value: EdgeAction): EdgeAction => value;
+    acceptsAction('none');
+    acceptsAction('play-start');
+    acceptsAction('play-stop');
+    // @ts-expect-error Unknown edge actions remain outside the executable vocabulary.
+    acceptsAction('unknown');
+  });
+});

package/src/__tests__/audio-intent.unit.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createAudioIntentBackend, listenerPoseFromWorldMatrix } from '../index';
+
+const PLAY_OPTIONS = {
+  loop: false,
+  volume: 0.75,
+  spatialBlend: 0.5,
+  bus: 'sfx' as const,
+};
+
+describe('AudioIntent producer', () => {
+  it('publishes source bytes once and reuses sourceKey afterwards', () => {
+    const emit = vi.fn();
+    const backend = createAudioIntentBackend({ emit });
+    const clip = {
+      kind: 'audio' as const,
+      sourceKey: 'laser',
+      mediaType: 'audio/ogg' as const,
+      bytes: new Uint8Array([1, 2, 3]),
+    };
+
+    backend.play(1, clip, PLAY_OPTIONS);
+    backend.play(2, clip, PLAY_OPTIONS);
+
+    expect(emit.mock.calls[0]?.[0]).toMatchObject({
+      kind: 'play',
+      entityId: 1,
+      sourceKey: 'laser',
+      bytes: clip.bytes,
+    });
+    expect(emit.mock.calls[1]?.[0]).toEqual({
+      kind: 'play',
+      entityId: 2,
+      sourceKey: 'laser',
+      options: PLAY_OPTIONS,
+    });
+  });
+
+  it('republishes bytes when a stable sourceKey receives changed content', () => {
+    const emit = vi.fn();
+    const backend = createAudioIntentBackend({ emit });
+    const clipA = {
+      kind: 'audio' as const,
+      sourceKey: 'laser',
+      mediaType: 'audio/ogg' as const,
+      bytes: new Uint8Array([1, 2, 3]),
+    };
+    const clipB = { ...clipA, bytes: new Uint8Array([1, 2, 4]) };
+
+    backend.play(1, clipA, PLAY_OPTIONS);
+    backend.play(2, clipA, PLAY_OPTIONS);
+    backend.play(3, clipB, PLAY_OPTIONS);
+
+    expect(emit).toHaveBeenCalledTimes(3);
+    expect(emit.mock.calls[1]?.[0]).not.toHaveProperty('bytes');
+    expect(emit.mock.calls[2]?.[0]).toMatchObject({
+      kind: 'play',
+      entityId: 3,
+      sourceKey: 'laser',
+      bytes: clipB.bytes,
+    });
+  });
+
+  it('projects a scaled world matrix into normalized host listener pose', () => {
+    const world = new Float32Array([2, 0, 0, 0, 0, 3, 0, 0, 0, 0, 4, 0, 5, 6, 7, 1]);
+    expect(listenerPoseFromWorldMatrix(world)).toEqual({
+      positionX: 5,
+      positionY: 6,
+      positionZ: 7,
+      forwardX: -0,
+      forwardY: -0,
+      forwardZ: -1,
+      upX: 0,
+      upY: 1,
+      upZ: 0,
+    });
+  });
+});

package/src/__tests__/scriptable-pack-consumer.test-d.ts

@@ -0,0 +1,6 @@
+import type { AudioClipAsset } from '@forgeax/engine-audio';
+import { expectTypeOf } from 'vitest';
+
+declare const loadedClip: AudioClipAsset;
+expectTypeOf(loadedClip.mediaType).toMatchTypeOf<`audio/${string}`>();
+expectTypeOf(loadedClip.bytes).toEqualTypeOf<Uint8Array>();

package/src/__tests__/simulation-intent-order.test.ts

@@ -0,0 +1,41 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { type AudioIntent, AudioSource, audioTickSystem, createAudioIntentBackend } from '../index';
+
+describe('Audio semantic intent order', () => {
+  it('emits one play, one stop, and one disappearance cleanup', () => {
+    const world = new World();
+    const handle = world.allocSharedRef('AudioClipAsset', {
+      kind: 'audio',
+      sourceKey: 'order-tone',
+      bytes: Uint8Array.of(1),
+    });
+    const entity = world
+      .spawn({
+        component: AudioSource,
+        data: {
+          clip: handle,
+          playing: false,
+          loop: true,
+          volume: 1,
+          spatialBlend: 0,
+          bus: 'sfx',
+        },
+      })
+      .unwrap();
+    const intents: AudioIntent[] = [];
+    const backend = createAudioIntentBackend({ emit: (intent) => intents.push(intent) });
+
+    audioTickSystem(world, backend);
+    world.set(entity, AudioSource, { playing: true }).unwrap();
+    audioTickSystem(world, backend);
+    audioTickSystem(world, backend);
+    world.set(entity, AudioSource, { playing: false }).unwrap();
+    audioTickSystem(world, backend);
+    world.despawn(entity).unwrap();
+    audioTickSystem(world, backend);
+
+    expect(intents.map((intent) => intent.kind)).toEqual(['play', 'stop']);
+    expect(intents.filter((intent) => intent.kind === 'stop')).toHaveLength(1);
+  });
+});

package/src/assets/audio-decoder.ts

@@ -0,0 +1,55 @@
+import {
+  type AssetDecoderContribution,
+  type AssetKind,
+  type AudioClipAsset,
+  err,
+  ok,
+} from '@forgeax/engine-types';
+
+export const audioContribution: AssetDecoderContribution<AudioClipAsset, 'audio'> = {
+  kind: { kind: 'audio' } as AssetKind<AudioClipAsset, 'audio'>,
+  consumer: 'AudioBackend',
+  decoder: {
+    async decode({ envelope, artifacts }) {
+      const payload = envelope.payload as unknown;
+      if (payload !== null && typeof payload === 'object') {
+        const source = payload as Record<string, unknown>;
+        let bytes =
+          source.bytes instanceof Uint8Array
+            ? source.bytes
+            : Array.isArray(source.bytes)
+              ? Uint8Array.from(source.bytes as number[])
+              : undefined;
+        const body = envelope.artifacts.body ?? envelope.artifacts.source;
+        if (body !== undefined) {
+          const bodyBytes = await artifacts.read(body);
+          if (!bodyBytes.ok) return bodyBytes;
+          bytes = bodyBytes.value;
+        }
+        if (
+          source.kind === 'audio' &&
+          typeof source.mediaType === 'string' &&
+          source.mediaType.startsWith('audio/') &&
+          bytes !== undefined &&
+          bytes.byteLength > 0
+        ) {
+          return ok({
+            kind: 'audio',
+            sourceKey:
+              typeof source.sourceKey === 'string' && source.sourceKey.length > 0
+                ? source.sourceKey
+                : envelope.guid,
+            mediaType: source.mediaType as `audio/${string}`,
+            bytes,
+          });
+        }
+      }
+      return err({
+        code: 'asset-package-invalid',
+        expected: 'an audio payload with non-empty source bytes and audio mediaType',
+        hint: 'recook the audio source with a browser-supported media type',
+        detail: { guid: envelope.guid, reason: 'audio owner validation failed' },
+      });
+    },
+  },
+};