@pascal-app/editor 0.9.1 → 1.0.0-beta.1

package/src/lib/sfx-bus.ts

@@ -1,5 +1,14 @@
+import type { TerrainVerb } from '@pascal-app/core'
 import mitt from 'mitt'
-import { playSFX } from './sfx-player'
+import useAudio from '../store/use-audio'
+import {
+  disposeSFX,
+  type LoopSFXName,
+  playSFX,
+  startLoopSFX,
+  stopLoopSFX,
+  updateSFXVolumes,
+} from './sfx-player'
 
 /**
  * SFX-specific events that tools can trigger
@@ -10,14 +19,22 @@ type SFXEvents = {
   'sfx:item-pick': undefined
   'sfx:item-place': undefined
   'sfx:item-rotate': undefined
+  'sfx:resize': undefined
   'sfx:structure-build-start': undefined
   'sfx:structure-build': undefined
   'sfx:structure-delete': undefined
   'sfx:snapshot-capture': undefined
   'sfx:menu-hover': undefined
   'sfx:menu-click': undefined
+  'sfx:paint-apply': undefined
+  'sfx:terrain-sculpt-start': TerrainVerb
+  'sfx:terrain-sculpt-stop': undefined
 }
 
+type TriggerSFXEvent = {
+  [Event in keyof SFXEvents]: SFXEvents[Event] extends undefined ? Event : never
+}[keyof SFXEvents]
+
 /**
  * Dedicated event emitter for SFX
  * Tools should use this to trigger sound effects
@@ -26,6 +43,29 @@ export const sfxEmitter = mitt<SFXEvents>()
 
 let sfxBusInitialized = false
 
+const handleGridSnap = () => playSFX('gridSnap')
+const handleItemDelete = () => playSFX('itemDelete')
+const handleItemPick = () => playSFX('itemPick')
+const handleItemPlace = () => playSFX('itemPlace')
+const handleItemRotate = () => playSFX('itemRotate')
+const handleResize = () => playSFX('resize')
+const handleStructureBuildStart = () => playSFX('structureBuildStart')
+const handleStructureBuild = () => playSFX('structureBuildEnd')
+const handleStructureDelete = () => playSFX('structureDelete')
+const handleSnapshotCapture = () => playSFX('snapshotCapture')
+const handleMenuHover = () => playSFX('menuHover')
+const handleMenuClick = () => playSFX('menuClick')
+const handlePaintApply = () => playSFX('paintApply')
+const TERRAIN_LOOP_BY_VERB = {
+  raise: 'terrainRaise',
+  lower: 'terrainLower',
+  flatten: 'terrainFlatten',
+  smooth: 'terrainSmooth',
+} as const satisfies Record<TerrainVerb, LoopSFXName>
+const handleTerrainSculptStart = (verb: TerrainVerb) => startLoopSFX(TERRAIN_LOOP_BY_VERB[verb])
+const handleTerrainSculptStop = () => stopLoopSFX()
+let unsubscribeAudio: (() => void) | null = null
+
 /**
  * Initialize SFX Bus - connects SFX events to actual sound playback.
  * Safe to call multiple times; re-registration is a no-op once initialized.
@@ -33,18 +73,46 @@ let sfxBusInitialized = false
 export function initSFXBus() {
   if (sfxBusInitialized) return
   sfxBusInitialized = true
-  // Map SFX events to sound playback
-  sfxEmitter.on('sfx:grid-snap', () => playSFX('gridSnap'))
-  sfxEmitter.on('sfx:item-delete', () => playSFX('itemDelete'))
-  sfxEmitter.on('sfx:item-pick', () => playSFX('itemPick'))
-  sfxEmitter.on('sfx:item-place', () => playSFX('itemPlace'))
-  sfxEmitter.on('sfx:item-rotate', () => playSFX('itemRotate'))
-  sfxEmitter.on('sfx:structure-build-start', () => playSFX('structureBuildStart'))
-  sfxEmitter.on('sfx:structure-build', () => playSFX('structureBuildEnd'))
-  sfxEmitter.on('sfx:structure-delete', () => playSFX('structureDelete'))
-  sfxEmitter.on('sfx:snapshot-capture', () => playSFX('snapshotCapture'))
-  sfxEmitter.on('sfx:menu-hover', () => playSFX('menuHover'))
-  sfxEmitter.on('sfx:menu-click', () => playSFX('menuClick'))
+  sfxEmitter.on('sfx:grid-snap', handleGridSnap)
+  sfxEmitter.on('sfx:item-delete', handleItemDelete)
+  sfxEmitter.on('sfx:item-pick', handleItemPick)
+  sfxEmitter.on('sfx:item-place', handleItemPlace)
+  sfxEmitter.on('sfx:item-rotate', handleItemRotate)
+  sfxEmitter.on('sfx:resize', handleResize)
+  sfxEmitter.on('sfx:structure-build-start', handleStructureBuildStart)
+  sfxEmitter.on('sfx:structure-build', handleStructureBuild)
+  sfxEmitter.on('sfx:structure-delete', handleStructureDelete)
+  sfxEmitter.on('sfx:snapshot-capture', handleSnapshotCapture)
+  sfxEmitter.on('sfx:menu-hover', handleMenuHover)
+  sfxEmitter.on('sfx:menu-click', handleMenuClick)
+  sfxEmitter.on('sfx:paint-apply', handlePaintApply)
+  sfxEmitter.on('sfx:terrain-sculpt-start', handleTerrainSculptStart)
+  sfxEmitter.on('sfx:terrain-sculpt-stop', handleTerrainSculptStop)
+  unsubscribeAudio = useAudio.subscribe(updateSFXVolumes)
+}
+
+export function disposeSFXBus() {
+  if (sfxBusInitialized) {
+    sfxEmitter.off('sfx:grid-snap', handleGridSnap)
+    sfxEmitter.off('sfx:item-delete', handleItemDelete)
+    sfxEmitter.off('sfx:item-pick', handleItemPick)
+    sfxEmitter.off('sfx:item-place', handleItemPlace)
+    sfxEmitter.off('sfx:item-rotate', handleItemRotate)
+    sfxEmitter.off('sfx:resize', handleResize)
+    sfxEmitter.off('sfx:structure-build-start', handleStructureBuildStart)
+    sfxEmitter.off('sfx:structure-build', handleStructureBuild)
+    sfxEmitter.off('sfx:structure-delete', handleStructureDelete)
+    sfxEmitter.off('sfx:snapshot-capture', handleSnapshotCapture)
+    sfxEmitter.off('sfx:menu-hover', handleMenuHover)
+    sfxEmitter.off('sfx:menu-click', handleMenuClick)
+    sfxEmitter.off('sfx:paint-apply', handlePaintApply)
+    sfxEmitter.off('sfx:terrain-sculpt-start', handleTerrainSculptStart)
+    sfxEmitter.off('sfx:terrain-sculpt-stop', handleTerrainSculptStop)
+    unsubscribeAudio?.()
+    unsubscribeAudio = null
+    sfxBusInitialized = false
+  }
+  disposeSFX()
 }
 
 /**
@@ -52,7 +120,7 @@ export function initSFXBus() {
  * @example
  * triggerSFX('sfx:item-place')
  */
-export function triggerSFX(event: keyof SFXEvents) {
+export function triggerSFX(event: TriggerSFXEvent) {
   sfxEmitter.emit(event)
 }
 

package/src/lib/sfx-player.test.ts

@@ -0,0 +1,266 @@
+import { afterAll, beforeEach, describe, expect, mock, test } from 'bun:test'
+
+type FakeContext = { id: string }
+
+let activeContext: FakeContext = { id: 'first' }
+let initialState: 'loaded' | 'loading' = 'loaded'
+let muted = false
+let throwOnPlay = false
+const instances: FakeHowl[] = []
+
+class FakeHowl {
+  loadCallbacks: Array<() => void> = []
+  loop = false
+  src: string | undefined
+  stateValue: 'loaded' | 'loading' | 'unloaded' = initialState
+  unloadCount = 0
+  playCount = 0
+  stopCount = 0
+  fadeCalls: Array<[number, number, number, number | undefined]> = []
+  stereoCalls: Array<[number, number | undefined]> = []
+  volumeCalls: Array<[number, number | undefined]> = []
+
+  constructor(options: { loop?: boolean; src?: string[] }) {
+    this.loop = options.loop ?? false
+    this.src = options.src?.[0]
+    instances.push(this)
+  }
+
+  play() {
+    this.playCount++
+    if (throwOnPlay) throw new DOMException('stale graph', 'InvalidAccessError')
+    return 1
+  }
+
+  volume(value: number, id?: number) {
+    this.volumeCalls.push([value, id])
+    return this
+  }
+
+  fade(from: number, to: number, duration: number, id?: number) {
+    this.fadeCalls.push([from, to, duration, id])
+    return this
+  }
+
+  once(event: string, callback: () => void) {
+    if (event === 'load') {
+      this.loadCallbacks.push(callback)
+      return this
+    }
+    callback()
+    return this
+  }
+
+  finishLoading() {
+    this.stateValue = 'loaded'
+    for (const callback of this.loadCallbacks.splice(0)) callback()
+  }
+
+  playing() {
+    return this.playCount > this.stopCount
+  }
+
+  stop() {
+    this.stopCount++
+    return this
+  }
+
+  stereo(value: number, id?: number) {
+    this.stereoCalls.push([value, id])
+    return this
+  }
+
+  rate() {
+    return this
+  }
+
+  state() {
+    return this.stateValue
+  }
+
+  unload() {
+    this.unloadCount++
+    this.stateValue = 'unloaded'
+    return null
+  }
+}
+
+const fakeHowler = {
+  get ctx() {
+    return activeContext
+  },
+}
+
+mock.module('howler', () => ({ Howl: FakeHowl, Howler: fakeHowler }))
+mock.module('../store/use-audio', () => ({
+  default: {
+    getState: () => ({ masterVolume: 100, muted, sfxVolume: 100 }),
+    subscribe: () => () => {},
+  },
+}))
+
+const { disposeSFX, playSFX, preloadSFX, startLoopSFX, stopLoopSFX, updateSFXVolumes } =
+  await import('./sfx-player')
+const { disposeSFXBus, initSFXBus, sfxEmitter, triggerSFX } = await import('./sfx-bus')
+
+beforeEach(() => {
+  disposeSFXBus()
+  activeContext = { id: 'first' }
+  initialState = 'loaded'
+  muted = false
+  throwOnPlay = false
+  instances.length = 0
+})
+
+afterAll(() => {
+  disposeSFXBus()
+  mock.restore()
+})
+
+describe('SFX audio context lifecycle', () => {
+  test('reuses the preloaded cache while the Howler context is unchanged', () => {
+    preloadSFX()
+    const initialCount = instances.length
+
+    playSFX('itemDelete')
+
+    expect(instances).toHaveLength(initialCount)
+  })
+
+  test('rebuilds every cached Howl before playing against a new context', () => {
+    preloadSFX()
+    const oldSounds = [...instances]
+    const initialCount = instances.length
+    activeContext = { id: 'second' }
+
+    playSFX('itemDelete')
+
+    expect(oldSounds.every((sound) => sound.unloadCount === 1)).toBe(true)
+    expect(instances.length).toBe(initialCount * 2)
+    expect(instances.slice(initialCount).some((sound) => sound.playCount === 1)).toBe(true)
+  })
+
+  test('contains a stale graph failure and backs off instead of rebuilding per cue', () => {
+    preloadSFX()
+    const initialCount = instances.length
+    throwOnPlay = true
+
+    expect(() => playSFX('menuHover')).not.toThrow()
+    expect(instances.slice(0, initialCount).every((sound) => sound.unloadCount === 1)).toBe(true)
+
+    throwOnPlay = false
+    playSFX('menuHover')
+    expect(instances.length).toBe(initialCount)
+  })
+
+  test('does not queue spatial mutations while a sound is still loading', () => {
+    initialState = 'loading'
+
+    playSFX('itemDelete', { source: 'remote', stereo: 0.65, volumeMultiplier: 0.25 })
+
+    expect(instances.every((sound) => sound.playCount === 0)).toBe(true)
+    expect(instances.every((sound) => sound.stereoCalls.length === 0)).toBe(true)
+    expect(instances.every((sound) => sound.volumeCalls.length === 0)).toBe(true)
+  })
+
+  test('disposes idempotently and recreates sounds after remount', () => {
+    preloadSFX()
+    const initialCount = instances.length
+
+    disposeSFX()
+    disposeSFX()
+    playSFX('itemDelete')
+
+    expect(instances.length).toBe(initialCount * 2)
+  })
+
+  test('does not let an emitted SFX failure escape an editor callback', () => {
+    initSFXBus()
+    throwOnPlay = true
+
+    expect(() => triggerSFX('sfx:item-delete')).not.toThrow()
+  })
+
+  test('applies bounded gain and stereo positioning to a remote cue', () => {
+    playSFX('itemDelete', { source: 'remote', stereo: 0.65, volumeMultiplier: 0.25 })
+
+    const played = instances.find((sound) => sound.playCount === 1)
+    expect(played?.volumeCalls[0]?.[0]).toBeGreaterThanOrEqual(0.225)
+    expect(played?.volumeCalls[0]?.[0]).toBeLessThanOrEqual(0.25)
+    expect(played?.stereoCalls).toEqual([[0.65, 1]])
+  })
+
+  test('keeps local feedback audible after the same remote cue', () => {
+    playSFX('itemDelete', { source: 'remote', volumeMultiplier: 0.25 })
+    playSFX('itemDelete')
+
+    expect(instances.reduce((total, sound) => total + sound.playCount, 0)).toBe(2)
+  })
+
+  test('keeps one faded terrain loop active and stops it on release', () => {
+    startLoopSFX('terrainRaise')
+    const raise = instances.find((sound) => sound.loop && sound.playCount === 1)
+
+    expect(raise?.volumeCalls[0]).toEqual([0, 1])
+    expect(raise?.fadeCalls).toEqual([[0, 0.2, 90, 1]])
+
+    startLoopSFX('terrainRaise')
+    expect(raise?.playCount).toBe(1)
+
+    stopLoopSFX()
+    expect(raise?.stopCount).toBe(1)
+    expect(raise?.fadeCalls.at(-1)).toEqual([0.2, 0, 90, 1])
+  })
+
+  test('maps each terrain verb to a distinct loop through the SFX bus', () => {
+    initSFXBus()
+
+    for (const verb of ['raise', 'lower', 'flatten', 'smooth'] as const) {
+      sfxEmitter.emit('sfx:terrain-sculpt-start', verb)
+      sfxEmitter.emit('sfx:terrain-sculpt-stop')
+    }
+
+    expect(
+      instances.filter((sound) => sound.loop && sound.playCount === 1).map((sound) => sound.src),
+    ).toEqual([
+      '/audios/sfx/terrain_raise.mp3',
+      '/audios/sfx/terrain_lower.mp3',
+      '/audios/sfx/terrain_flatten.mp3',
+      '/audios/sfx/terrain_smooth.mp3',
+    ])
+  })
+
+  test('fades an active terrain loop out when sound is muted', () => {
+    startLoopSFX('terrainLower')
+    const lower = instances.find((sound) => sound.loop && sound.playCount === 1)
+
+    muted = true
+    updateSFXVolumes()
+
+    expect(lower?.fadeCalls.at(-1)).toEqual([0.2, 0, 90, 1])
+    expect(lower?.stopCount).toBe(1)
+  })
+
+  test('starts a requested terrain loop when its asset finishes loading', () => {
+    initialState = 'loading'
+    startLoopSFX('terrainRaise')
+    const raise = instances.find((sound) => sound.src === '/audios/sfx/terrain_raise.mp3')
+
+    expect(raise?.playCount).toBe(0)
+
+    raise?.finishLoading()
+
+    expect(raise?.playCount).toBe(1)
+  })
+
+  test('does not start a terrain loop after the sculpt press was released', () => {
+    initialState = 'loading'
+    startLoopSFX('terrainLower')
+    const lower = instances.find((sound) => sound.src === '/audios/sfx/terrain_lower.mp3')
+
+    stopLoopSFX()
+    lower?.finishLoading()
+
+    expect(lower?.playCount).toBe(0)
+  })
+})