feat(audio): add recording support to WebAudioLayer

Add optional recording methods to AudioLayer interface and implement
them in WebAudioLayer:
- enableRecording(): creates MediaStreamAudioDestinationNode
- disableRecording(): disconnects recording destination
- getRecordingStream(): returns MediaStream for recording

Implementation changes:
- Add masterGain node for unified audio routing
- Route all audio through master gain for recording capture
- Clean up recording on destroy

Add comprehensive tests:
- Unit tests for all recording methods (11 new tests)
- Playwright browser tests (6 new tests)
- Update browser.setup.ts mocks for MediaStream support

Author: hiddentao

.versionrc.json

@@ -1,10 +1,6 @@
 {
-  "packageFiles": [
-    "packages/core/package.json"
-  ],
-  "bumpFiles": [
-    "packages/core/package.json"
-  ],
+  "packageFiles": ["packages/core/package.json"],
+  "bumpFiles": ["packages/core/package.json"],
   "infile": "CHANGELOG.md",
   "header": "# Changelog\n\nAll notable changes to this project will be documented in this file.\n",
   "types": [

packages/core/src/platform/AudioLayer.ts

@@ -52,4 +52,9 @@ export interface AudioLayer {
   // Context management
   tryResumeOnce(): Promise<void>
   getState(): AudioContextState
+
+  // Recording (optional - only implemented by WebAudioLayer)
+  enableRecording?(): void
+  disableRecording?(): void
+  getRecordingStream?(): MediaStream | null
 }

packages/core/tests/browser/web-audio.spec.playwright.ts

@@ -484,6 +484,146 @@ test.describe("WebAudioLayer Autoplay Policy Fix", () => {
   })
 })
 
+test.describe("WebAudioLayer Recording", () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto("http://localhost:3000/tests/browser/test-page.html")
+  })
+
+  test("should return null stream before recording enabled", async ({
+    page,
+  }) => {
+    const result = await page.evaluate(
+      `(async () => {
+      ${getAudioSetup()}
+
+      return {
+        stream: audio.getRecordingStream(),
+      }
+    })()`,
+    )
+
+    expect(result.stream).toBeNull()
+  })
+
+  test("should enable recording and return MediaStream", async ({ page }) => {
+    const result = await page.evaluate(
+      `(async () => {
+      ${getAudioSetup()}
+
+      audio.enableRecording()
+      const stream = audio.getRecordingStream()
+
+      return {
+        hasStream: stream !== null,
+        isMediaStream: stream instanceof MediaStream,
+        streamActive: stream ? stream.active : false,
+      }
+    })()`,
+    )
+
+    expect(result.hasStream).toBe(true)
+    expect(result.isMediaStream).toBe(true)
+  })
+
+  test("should disable recording and return null stream", async ({ page }) => {
+    const result = await page.evaluate(
+      `(async () => {
+      ${getAudioSetup()}
+
+      audio.enableRecording()
+      const streamBefore = audio.getRecordingStream()
+
+      audio.disableRecording()
+      const streamAfter = audio.getRecordingStream()
+
+      return {
+        hadStreamBefore: streamBefore !== null,
+        hasStreamAfter: streamAfter !== null,
+      }
+    })()`,
+    )
+
+    expect(result.hadStreamBefore).toBe(true)
+    expect(result.hasStreamAfter).toBe(false)
+  })
+
+  test("should handle enable/disable cycle multiple times", async ({
+    page,
+  }) => {
+    const result = await page.evaluate(
+      `(async () => {
+      ${getAudioSetup()}
+
+      const states = []
+
+      for (let i = 0; i < 3; i++) {
+        audio.enableRecording()
+        states.push(audio.getRecordingStream() !== null)
+        audio.disableRecording()
+        states.push(audio.getRecordingStream() === null)
+      }
+
+      return { states }
+    })()`,
+    )
+
+    expect(result.states).toEqual([true, true, true, true, true, true])
+  })
+
+  test("should cleanup recording on destroy", async ({ page }) => {
+    const result = await page.evaluate(
+      `(async () => {
+      ${getAudioSetup()}
+
+      audio.enableRecording()
+      const streamBefore = audio.getRecordingStream()
+
+      audio.destroy()
+      const streamAfter = audio.getRecordingStream()
+
+      return {
+        hadStreamBefore: streamBefore !== null,
+        hasStreamAfter: streamAfter !== null,
+      }
+    })()`,
+    )
+
+    expect(result.hadStreamBefore).toBe(true)
+    expect(result.hasStreamAfter).toBe(false)
+  })
+
+  test("should allow sound playback while recording", async ({ page }) => {
+    const result = await page.evaluate(
+      `(async () => {
+      ${getAudioSetup()}
+      ${CREATE_TEST_BUFFER}
+
+      const buffer = createTestBuffer(audio, 440, 0.05)
+      audio.loadSoundFromBuffer("test-tone", buffer)
+
+      await audio.tryResumeOnce()
+
+      audio.enableRecording()
+      const stream = audio.getRecordingStream()
+
+      audio.playSound("test-tone", 0.5, false)
+
+      await new Promise(resolve => setTimeout(resolve, 50))
+
+      audio.stopSound("test-tone")
+
+      return {
+        hasStream: stream !== null,
+        state: audio.getState(),
+      }
+    })()`,
+    )
+
+    expect(result.hasStream).toBe(true)
+    expect(result.state).toBe(AudioContextState.RUNNING)
+  })
+})
+
 test.describe("WebAudioLayer Data URL Loading", () => {
   test.beforeEach(async ({ page }) => {
     await page.goto("http://localhost:3000/tests/browser/test-page.html")

packages/core/tests/platform/WebAudioLayer.test.ts

@@ -178,4 +178,78 @@ describe("WebAudioLayer", () => {
       expect(() => audio.playSound("test")).not.toThrow()
     })
   })
+
+  describe("Recording", () => {
+    beforeEach(async () => {
+      await audio.initialize()
+    })
+
+    it("should return null stream before recording enabled", () => {
+      expect(audio.getRecordingStream()).toBeNull()
+    })
+
+    it("should enable recording without errors", () => {
+      expect(() => audio.enableRecording()).not.toThrow()
+    })
+
+    it("should return MediaStream when recording enabled", () => {
+      audio.enableRecording()
+      const stream = audio.getRecordingStream()
+      expect(stream).not.toBeNull()
+    })
+
+    it("should be idempotent when enabling recording multiple times", () => {
+      audio.enableRecording()
+      const stream1 = audio.getRecordingStream()
+      audio.enableRecording()
+      const stream2 = audio.getRecordingStream()
+      expect(stream1).toBe(stream2)
+    })
+
+    it("should disable recording without errors", () => {
+      audio.enableRecording()
+      expect(() => audio.disableRecording()).not.toThrow()
+    })
+
+    it("should return null stream after recording disabled", () => {
+      audio.enableRecording()
+      expect(audio.getRecordingStream()).not.toBeNull()
+      audio.disableRecording()
+      expect(audio.getRecordingStream()).toBeNull()
+    })
+
+    it("should be idempotent when disabling recording multiple times", () => {
+      audio.enableRecording()
+      audio.disableRecording()
+      expect(() => audio.disableRecording()).not.toThrow()
+      expect(audio.getRecordingStream()).toBeNull()
+    })
+
+    it("should handle enable/disable cycle multiple times", () => {
+      for (let i = 0; i < 3; i++) {
+        audio.enableRecording()
+        expect(audio.getRecordingStream()).not.toBeNull()
+        audio.disableRecording()
+        expect(audio.getRecordingStream()).toBeNull()
+      }
+    })
+
+    it("should disable recording on destroy", () => {
+      audio.enableRecording()
+      expect(audio.getRecordingStream()).not.toBeNull()
+      audio.destroy()
+      expect(audio.getRecordingStream()).toBeNull()
+    })
+
+    it("should handle enableRecording before initialization", () => {
+      const uninitAudio = new WebAudioLayer()
+      expect(() => uninitAudio.enableRecording()).not.toThrow()
+      expect(uninitAudio.getRecordingStream()).toBeNull()
+    })
+
+    it("should handle disableRecording before initialization", () => {
+      const uninitAudio = new WebAudioLayer()
+      expect(() => uninitAudio.disableRecording()).not.toThrow()
+    })
+  })
 })

packages/core/tests/setup/browser.setup.ts

@@ -22,6 +22,15 @@ export function setupBrowserEnvironment() {
   global.MouseEvent = window.MouseEvent as any
   global.KeyboardEvent = window.KeyboardEvent as any
 
+  // Mock MediaStream for recording tests
+  global.MediaStream = class MediaStream {
+    id = "mock-stream-id"
+    active = true
+    getTracks() {
+      return []
+    }
+  } as any
+
   // Web Audio API mocks (basic stubs for testing)
   global.AudioContext = class AudioContext {
     state = "running"
@@ -50,6 +59,15 @@ export function setupBrowserEnvironment() {
         connect: () => {
           // No-op mock
         },
+        disconnect: () => {
+          // No-op mock
+        },
+      }
+    }
+
+    createMediaStreamDestination() {
+      return {
+        stream: new (global as any).MediaStream(),
       }
     }
 
@@ -91,4 +109,5 @@ export function cleanupBrowserEnvironment() {
   delete (global as any).MouseEvent
   delete (global as any).KeyboardEvent
   delete (global as any).AudioContext
+  delete (global as any).MediaStream
 }

packages/platform-web-pixi/src/WebAudioLayer.ts

@@ -14,6 +14,11 @@ export class WebAudioLayer implements AudioLayer {
   private isClosed = false
   private hasResumed = false
 
+  // Recording support
+  private masterGain: GainNode | null = null
+  private recordingDestination: MediaStreamAudioDestinationNode | null = null
+  private isRecordingEnabled = false
+
   private async resumeWithTimeout(maxWaitMs = 2000): Promise<void> {
     if (!this.context) {
       return
@@ -35,6 +40,10 @@ export class WebAudioLayer implements AudioLayer {
       return
     }
     this.context = new AudioContext()
+
+    // Create master gain node for all audio routing
+    this.masterGain = this.context.createGain()
+    this.masterGain.connect(this.context.destination)
   }
 
   destroy(): void {
@@ -44,6 +53,8 @@ export class WebAudioLayer implements AudioLayer {
     }
 
     this.stopAll()
+    this.disableRecording()
+    this.masterGain = null
     this.context.close()
     this.context = null
     this.buffers.clear()
@@ -95,7 +106,7 @@ export class WebAudioLayer implements AudioLayer {
   }
 
   playSound(id: string, volume = 1.0, loop = false): void {
-    if (!this.context) {
+    if (!this.context || !this.masterGain) {
       return
     }
 
@@ -111,8 +122,9 @@ export class WebAudioLayer implements AudioLayer {
     const gainNode = this.context.createGain()
     gainNode.gain.value = volume
 
+    // Route through master gain for both playback and recording
     source.connect(gainNode)
-    gainNode.connect(this.context.destination)
+    gainNode.connect(this.masterGain)
 
     source.start()
 
@@ -172,4 +184,38 @@ export class WebAudioLayer implements AudioLayer {
     }
     return this.context.state as AudioContextState
   }
+
+  // Recording methods
+  enableRecording(): void {
+    if (!this.context || !this.masterGain || this.isRecordingEnabled) {
+      return
+    }
+
+    // Create recording destination and connect master gain to it
+    this.recordingDestination = this.context.createMediaStreamDestination()
+    this.masterGain.connect(this.recordingDestination)
+    this.isRecordingEnabled = true
+  }
+
+  disableRecording(): void {
+    if (
+      !this.masterGain ||
+      !this.recordingDestination ||
+      !this.isRecordingEnabled
+    ) {
+      return
+    }
+
+    // Disconnect recording destination
+    this.masterGain.disconnect(this.recordingDestination)
+    this.recordingDestination = null
+    this.isRecordingEnabled = false
+  }
+
+  getRecordingStream(): MediaStream | null {
+    if (!this.recordingDestination) {
+      return null
+    }
+    return this.recordingDestination.stream
+  }
 }