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

package/src/lib/sfx-player.ts

@@ -1,4 +1,4 @@
-import { Howl } from 'howler'
+import { Howl, Howler } from 'howler'
 import useAudio from '../store/use-audio'
 
 // Per-sound variation config. Playback rate also shifts pitch (one semitone ≈ 1.0595×),
@@ -14,13 +14,18 @@ type SFXConfig = {
   // Minimum gap between two plays of this SFX. Triggers within this window
   // are silently dropped so bursty sequences don't phase-stack into noise.
   minIntervalMs?: number
-  // Random stereo pan per play — max absolute offset (0 = center, 1 = hard
-  // right). A small value like 0.15 keeps things centred but adds just enough
-  // spread to stop repeats from stacking on the same point in the field.
-  panJitter?: number
+}
+
+type LoopSFXConfig = {
+  src: string
+  volumeMultiplier: number
+  fadeInMs?: number
+  fadeOutMs?: number
 }
 
 const DEFAULT_MIN_INTERVAL_MS = 30
+const SFX_FAILURE_BACKOFF_MS = 5_000
+const DEFAULT_LOOP_FADE_MS = 90
 
 // SFX sound definitions
 export const SFX: Record<string, SFXConfig> = {
@@ -32,52 +37,53 @@ export const SFX: Record<string, SFXConfig> = {
     ],
     rateRange: [0.98, 1.02],
     volumeRange: [0.5, 0.6],
-    panJitter: 0.15,
     minIntervalMs: 50,
   },
   itemDelete: {
     src: '/audios/sfx/item_delete.mp3',
     rateRange: [0.9, 1.1],
     volumeRange: [0.9, 1.0],
-    panJitter: 0.05,
   },
   itemPick: {
     src: '/audios/sfx/item_pick.mp3',
     rateRange: [0.95, 1.05],
     volumeRange: [0.92, 1.0],
-    panJitter: 0.15,
   },
   itemPlace: {
     src: '/audios/sfx/item_place.mp3',
     rateRange: [0.98, 1.02],
     volumeRange: [0.9, 1.0],
-    panJitter: 0.15,
   },
   itemRotate: {
     src: '/audios/sfx/item_rotate.mp3',
     rateRange: [0.94, 1.06],
     volumeRange: [0.92, 1.0],
-    panJitter: 0.15,
+  },
+  // Ticks as a resize handle is dragged across snap steps. Fires in rapid
+  // succession, so it mirrors gridSnap: three variations cycled round-robin
+  // with pitch jitter and a gap so the run reads as texture, not a tone.
+  resize: {
+    src: ['/audios/sfx/resize_0.mp3', '/audios/sfx/resize_1.mp3', '/audios/sfx/resize_2.mp3'],
+    rateRange: [0.98, 1.02],
+    volumeRange: [0.26, 0.34],
+    minIntervalMs: 80,
   },
   // Fired when a structure draft begins (first click of a wall/slab/etc).
   structureBuildStart: {
     src: '/audios/sfx/structure_build_start.mp3',
     rateRange: [0.95, 1.05],
     volumeRange: [0.88, 1.0],
-    panJitter: 0.15,
   },
   // Fired when a structure is committed (segment placed / polygon closed).
   structureBuildEnd: {
     src: '/audios/sfx/structure_build_end.mp3',
     rateRange: [0.95, 1.05],
     volumeRange: [0.88, 1.0],
-    panJitter: 0.15,
   },
   structureDelete: {
     src: '/audios/sfx/structure_delete.mp3',
     rateRange: [0.9, 1.1],
     volumeRange: [0.9, 1.0],
-    panJitter: 0.08,
   },
   snapshotCapture: {
     // Shutter should sound consistent — no variation.
@@ -90,7 +96,6 @@ export const SFX: Record<string, SFXConfig> = {
     src: '/audios/sfx/menu_hover.mp3',
     rateRange: [0.98, 1.02],
     volumeRange: [0.2, 0.3],
-    panJitter: 0.1,
     minIntervalMs: 0,
   },
   // Fired when a main category in the Build / Items panels is clicked.
@@ -98,81 +103,254 @@ export const SFX: Record<string, SFXConfig> = {
     src: '/audios/sfx/menu_click.mp3',
     rateRange: [0.98, 1.02],
     volumeRange: [0.5, 0.6],
-    panJitter: 0.1,
+  },
+  // Fired when a material is applied to a surface in paint mode. Painting can
+  // fire in quick succession across faces, so keep variation + a small gap.
+  paintApply: {
+    src: '/audios/sfx/paint_apply.mp3',
+    rateRange: [0.95, 1.05],
+    volumeRange: [0.85, 1.0],
+    minIntervalMs: 60,
   },
 } as const
 
 export type SFXName = keyof typeof SFX
 
+export const LOOP_SFX = {
+  terrainRaise: {
+    src: '/audios/sfx/terrain_raise.mp3',
+    volumeMultiplier: 0.2,
+  },
+  terrainLower: {
+    src: '/audios/sfx/terrain_lower.mp3',
+    volumeMultiplier: 0.2,
+  },
+  terrainFlatten: {
+    src: '/audios/sfx/terrain_flatten.mp3',
+    volumeMultiplier: 0.2,
+  },
+  terrainSmooth: {
+    src: '/audios/sfx/terrain_smooth.mp3',
+    volumeMultiplier: 0.2,
+  },
+} as const satisfies Record<string, LoopSFXConfig>
+
+export type LoopSFXName = keyof typeof LOOP_SFX
+type CachedSFXName = SFXName | LoopSFXName
+
+function loopConfig(name: LoopSFXName): LoopSFXConfig {
+  return LOOP_SFX[name]
+}
+
+export type SFXPlaybackOptions = {
+  source?: 'local' | 'remote'
+  stereo?: number
+  volumeMultiplier?: number
+}
+
 function randomInRange([min, max]: [number, number]): number {
   return min + Math.random() * (max - min)
 }
 
-// Preload all SFX sounds. Each variation gets its own Howl so they can overlap
-// and be cycled round-robin.
-const sfxCache = new Map<SFXName, Howl[]>()
+let sfxCache = new Map<CachedSFXName, Howl[]>()
+let sfxAudioContext: AudioContext | null = null
+let sfxRetryAfter = 0
 const lastPlayedAt = new Map<SFXName, number>()
 const lastVariation = new Map<SFXName, number>()
+let activeLoop: {
+  id: number
+  name: LoopSFXName
+  sound: Howl
+  volume: number
+} | null = null
+let pendingLoop: { name: LoopSFXName; sound: Howl } | null = null
+let requestedLoop: LoopSFXName | null = null
+
+function loopVolume(name: LoopSFXName): number {
+  const { masterVolume, sfxVolume } = useAudio.getState()
+  return (masterVolume / 100) * (sfxVolume / 100) * LOOP_SFX[name].volumeMultiplier
+}
+
+function stopActiveLoop(fadeMs: number) {
+  const active = activeLoop
+  if (!active) return
+  activeLoop = null
+
+  if (fadeMs <= 0) {
+    active.sound.stop(active.id)
+    return
+  }
+
+  active.sound.once('fade', () => active.sound.stop(active.id), active.id)
+  active.sound.fade(active.volume, 0, fadeMs, active.id)
+}
+
+function unloadCachedSounds(resetPlaybackState: boolean) {
+  requestedLoop = null
+  pendingLoop = null
+  stopActiveLoop(0)
+  for (const sounds of sfxCache.values()) {
+    for (const sound of sounds) {
+      try {
+        sound.unload()
+      } catch {}
+    }
+  }
+  sfxCache.clear()
+  sfxAudioContext = null
+  if (resetPlaybackState) {
+    sfxRetryAfter = 0
+    lastPlayedAt.clear()
+    lastVariation.clear()
+  }
+}
+
+function cacheNeedsRebuild(): boolean {
+  if (sfxCache.size === 0) return true
+  if (sfxAudioContext !== Howler.ctx) return true
+  for (const sounds of sfxCache.values()) {
+    if (sounds.some((sound) => sound.state() === 'unloaded')) return true
+  }
+  return false
+}
 
-// Initialize all sounds
-Object.entries(SFX).forEach(([name, config]) => {
-  const sources = Array.isArray(config.src) ? config.src : [config.src]
-  const sounds = sources.map(
-    (src) =>
-      new Howl({
-        src: [src],
-        preload: true,
-        volume: 0.5, // Will be adjusted by the bus
-      }),
-  )
-  sfxCache.set(name as SFXName, sounds)
-})
+export function preloadSFX() {
+  if (!cacheNeedsRebuild()) return
+  unloadCachedSounds(false)
+
+  const definitions = { ...SFX, ...LOOP_SFX }
+  for (const [name, config] of Object.entries(definitions)) {
+    const sources = Array.isArray(config.src) ? config.src : [config.src]
+    sfxCache.set(
+      name as CachedSFXName,
+      sources.map(
+        (src) =>
+          new Howl({
+            loop: name in LOOP_SFX,
+            src: [src],
+            preload: true,
+            volume: 0.5,
+          }),
+      ),
+    )
+  }
+  sfxAudioContext = Howler.ctx ?? null
+}
+
+export function disposeSFX() {
+  unloadCachedSounds(true)
+}
+
+export function startLoopSFX(name: LoopSFXName) {
+  const { muted } = useAudio.getState()
+  if (muted) {
+    stopLoopSFX()
+    return
+  }
+
+  requestedLoop = name
+  const current = activeLoop
+  if (current?.name === name && current.sound.playing(current.id)) return
+  if (current) stopActiveLoop(loopConfig(current.name).fadeOutMs ?? DEFAULT_LOOP_FADE_MS)
+
+  const now = performance.now()
+  if (now < sfxRetryAfter) return
+
+  try {
+    preloadSFX()
+    // A fresh Howler context rebuilds the cache and clears stale playback
+    // state. Restore this current press after that cleanup so a first-use loop
+    // can still begin when its asset finishes loading.
+    requestedLoop = name
+    const sound = sfxCache.get(name)?.[0]
+    if (!sound) return
+    if (sound.state() !== 'loaded') {
+      if (pendingLoop?.name === name && pendingLoop.sound === sound) return
+      pendingLoop = { name, sound }
+      sound.once('load', () => {
+        if (pendingLoop?.sound === sound) pendingLoop = null
+        if (requestedLoop === name) startLoopSFX(name)
+      })
+      return
+    }
+
+    const config = loopConfig(name)
+    const volume = loopVolume(name)
+    const id = sound.play()
+    sound.volume(0, id)
+    activeLoop = { id, name, sound, volume }
+    sound.fade(0, volume, config.fadeInMs ?? DEFAULT_LOOP_FADE_MS, id)
+  } catch {
+    unloadCachedSounds(false)
+    sfxRetryAfter = now + SFX_FAILURE_BACKOFF_MS
+  }
+}
+
+export function stopLoopSFX() {
+  requestedLoop = null
+  pendingLoop = null
+  const fadeMs = activeLoop ? (loopConfig(activeLoop.name).fadeOutMs ?? DEFAULT_LOOP_FADE_MS) : 0
+  stopActiveLoop(fadeMs)
+}
 
 /**
  * Play a sound effect with volume based on audio settings
  */
-export function playSFX(name: SFXName) {
-  const sounds = sfxCache.get(name)
-  if (!sounds || sounds.length === 0) {
-    console.warn(`SFX not found: ${name}`)
-    return
-  }
+export function playSFX(name: SFXName, options: SFXPlaybackOptions = {}) {
   const config = SFX[name]!
+  const { masterVolume, sfxVolume, muted } = useAudio.getState()
+
+  if (muted) return
 
   // Drop rapid repeats — two plays of the same SFX within minIntervalMs just
   // smear into noise, they don't add useful information.
   const now = performance.now()
+  if (now < sfxRetryAfter) return
   const minInterval = config.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS
-  const last = lastPlayedAt.get(name)
+  const source = options.source ?? 'local'
+  const playbackKey = `${source}:${name}`
+  const last = lastPlayedAt.get(playbackKey)
   if (last !== undefined && now - last < minInterval) return
-  lastPlayedAt.set(name, now)
+  // Local feedback stays legible when a collaborator makes the same kind of
+  // change at nearly the same time; the quieter remote cue yields instead.
+  const lastLocal = lastPlayedAt.get(`local:${name}`)
+  if (source === 'remote' && lastLocal !== undefined && now - lastLocal < 120) return
+  lastPlayedAt.set(playbackKey, now)
 
-  // Pick a random variation, avoiding an immediate repeat of the last one so
-  // consecutive plays don't land on the same file.
-  let index = Math.floor(Math.random() * sounds.length)
-  if (sounds.length > 1 && index === lastVariation.get(name)) {
-    index = (index + 1) % sounds.length
-  }
-  lastVariation.set(name, index)
-  const sound = sounds[index]!
+  try {
+    preloadSFX()
+    const sounds = sfxCache.get(name)
+    if (!sounds || sounds.length === 0) return
 
-  const { masterVolume, sfxVolume, muted } = useAudio.getState()
-
-  if (muted) return
-
-  // Calculate final volume (masterVolume and sfxVolume are 0-100)
-  const baseVolume = (masterVolume / 100) * (sfxVolume / 100)
-  const volumeJitter = config.volumeRange ? randomInRange(config.volumeRange) : 1
-  const rate = config.rateRange ? randomInRange(config.rateRange) : 1
-
-  // Apply per-play variation using the returned sound id so overlapping plays
-  // don't fight over shared properties on the Howl.
-  const id = sound.play()
-  sound.volume(baseVolume * volumeJitter, id)
-  if (rate !== 1) sound.rate(rate, id)
-  if (config.panJitter) {
-    const pan = (Math.random() * 2 - 1) * config.panJitter
-    sound.stereo(pan, id)
+    // Pick a random variation, avoiding an immediate repeat of the last one so
+    // consecutive plays don't land on the same file.
+    let index = Math.floor(Math.random() * sounds.length)
+    if (sounds.length > 1 && index === lastVariation.get(name)) {
+      index = (index + 1) % sounds.length
+    }
+    lastVariation.set(name, index)
+    const sound = sounds[index]!
+    // Howler queues per-play mutations while a sound is loading. If its global
+    // AudioContext is replaced before that queue drains, stereo setup can try
+    // to connect nodes from different contexts and throw asynchronously.
+    if (sound.state() !== 'loaded') return
+    const baseVolume = (masterVolume / 100) * (sfxVolume / 100)
+    const volumeJitter = config.volumeRange ? randomInRange(config.volumeRange) : 1
+    const volumeMultiplier = Number.isFinite(options.volumeMultiplier)
+      ? Math.max(0, Math.min(2, options.volumeMultiplier!))
+      : 1
+    const rate = config.rateRange ? randomInRange(config.rateRange) : 1
+    const id = sound.play()
+    sound.volume(baseVolume * volumeJitter * volumeMultiplier, id)
+    if (Number.isFinite(options.stereo)) {
+      sound.stereo(Math.max(-1, Math.min(1, options.stereo!)), id)
+    }
+    if (rate !== 1) sound.rate(rate, id)
+  } catch {
+    // Optional audio must never abort an editor input callback. Rebuild from
+    // the current Howler context after a backoff instead of retrying every pointer cue.
+    unloadCachedSounds(false)
+    sfxRetryAfter = now + SFX_FAILURE_BACKOFF_MS
   }
 }
 
@@ -180,12 +358,27 @@ export function playSFX(name: SFXName) {
  * Update all cached SFX volumes (useful when settings change)
  */
 export function updateSFXVolumes() {
-  const { masterVolume, sfxVolume } = useAudio.getState()
+  const { masterVolume, muted, sfxVolume } = useAudio.getState()
+  if (muted) {
+    stopLoopSFX()
+    return
+  }
   const finalVolume = (masterVolume / 100) * (sfxVolume / 100)
 
-  sfxCache.forEach((sounds) => {
-    sounds.forEach((sound) => {
-      sound.volume(finalVolume)
+  try {
+    if (performance.now() < sfxRetryAfter) return
+    preloadSFX()
+    sfxCache.forEach((sounds) => {
+      sounds.forEach((sound) => {
+        sound.volume(finalVolume)
+      })
     })
-  })
+    if (activeLoop) {
+      activeLoop.volume = loopVolume(activeLoop.name)
+      activeLoop.sound.volume(activeLoop.volume, activeLoop.id)
+    }
+  } catch {
+    unloadCachedSounds(false)
+    sfxRetryAfter = performance.now() + SFX_FAILURE_BACKOFF_MS
+  }
 }

package/src/lib/site-boundary.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from 'bun:test'
+import type { Mode, Phase } from '../store/use-editor'
+import { siteBoundaryHandlesEnabled } from './site-boundary'
+
+/**
+ * The site handles are the one affordance both views draw from the same state, so
+ * they are also the one place a 2D/3D parity break hides: each pane used to derive
+ * this rule locally, and the sculpt exclusion existed in the 3D copy only.
+ */
+
+const MODES: Mode[] = ['select', 'edit', 'delete', 'build', 'material-paint', 'terrain-sculpt']
+const PHASES: Phase[] = ['site', 'structure', 'furnish']
+
+describe('siteBoundaryHandlesEnabled', () => {
+  test('sculpt hides the handles in every phase', () => {
+    // Including `site` — which is the case that matters, because arming sculpt
+    // *promotes* the phase to `site`, so this is the only combination the brush is
+    // ever actually in.
+    for (const phase of PHASES) {
+      expect(siteBoundaryHandlesEnabled({ mode: 'terrain-sculpt', phase })).toBe(false)
+    }
+  })
+
+  test('the site phase offers them in every other mode', () => {
+    for (const mode of MODES.filter((m) => m !== 'terrain-sculpt')) {
+      expect(siteBoundaryHandlesEnabled({ mode, phase: 'site' })).toBe(true)
+    }
+  })
+
+  test('select mode offers them outside the site phase', () => {
+    // The flags double as the affordance that *enters* site editing, so select mode
+    // has to show them from structure/furnish or the lot becomes unreachable.
+    expect(siteBoundaryHandlesEnabled({ mode: 'select', phase: 'structure' })).toBe(true)
+    expect(siteBoundaryHandlesEnabled({ mode: 'select', phase: 'furnish' })).toBe(true)
+  })
+
+  test('a drafting or painting mode outside the site phase hides them', () => {
+    for (const mode of ['edit', 'delete', 'build', 'material-paint'] as Mode[]) {
+      expect(siteBoundaryHandlesEnabled({ mode, phase: 'structure' })).toBe(false)
+      expect(siteBoundaryHandlesEnabled({ mode, phase: 'furnish' })).toBe(false)
+    }
+  })
+
+  test('sculpt is excluded before the phase term, not alongside it', () => {
+    // Ordering is the whole fix: `phase === 'site' || mode === 'select'` alone is
+    // *true* while sculpting, so an implementation that ORs the sculpt check in
+    // rather than early-returning would still show the handles.
+    const sculptInSite = siteBoundaryHandlesEnabled({ mode: 'terrain-sculpt', phase: 'site' })
+    const selectInSite = siteBoundaryHandlesEnabled({ mode: 'select', phase: 'site' })
+    expect(sculptInSite).toBe(false)
+    expect(selectInSite).toBe(true)
+  })
+})

package/src/lib/site-boundary.ts

@@ -1 +1,28 @@
+import type { Mode, Phase } from '../store/use-editor'
+
 export const SITE_BOUNDARY_DRAG_LABEL = 'site-boundary'
+
+/**
+ * Whether the site's vertex/midpoint handles are grabbable right now.
+ *
+ * Shared by the 3D boundary editor (`tool-manager.tsx`) and the floorplan's SVG
+ * handles (`floorplan-panel.tsx`) because they must agree, and until this existed
+ * they did not: each derived the rule from `phase`/`mode` locally, and the sculpt
+ * clause was added to only one of them.
+ *
+ * The disagreement was reachable in exactly one configuration, which is why it was
+ * easy to miss: arming sculpt from the 2D view promotes `viewMode` to `split` *and*
+ * the phase to `site`, so the floorplan's `phase === 'site'` term went true at the
+ * same moment the 3D editor's `!sculpting` term went false — handles gone in one
+ * pane, live in the other. Grabbing one then calls `begin({kind: 'handle-drag'})`,
+ * which atomically replaces the held `sculpting` scope: the brush stays armed and
+ * still paints, while the rest of the editor believes a boundary drag is running.
+ *
+ * Sculpt is excluded rather than merely deprioritised because the flags sit *on* the
+ * ground the brush is aimed at — leaving them mounted puts a grabbable handle under
+ * every dab near the lot line, in either view.
+ */
+export function siteBoundaryHandlesEnabled(args: { mode: Mode; phase: Phase }): boolean {
+  if (args.mode === 'terrain-sculpt') return false
+  return args.phase === 'site' || args.mode === 'select'
+}

package/src/lib/slab-plan-snap.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, test } from 'bun:test'
+import { type AnyNode, WallNode } from '@pascal-app/core'
+import useWallSnapIndicator from '../store/use-wall-snap-indicator'
+import { resolveSlabEdgeBandSnap } from './slab-plan-snap'
+
+function sceneWithWall(thickness = 0.1) {
+  const wall = WallNode.parse({ start: [0, 0], end: [4, 0], thickness })
+  const nodes: Record<string, AnyNode> = { [wall.id]: wall }
+  return { wall, nodes }
+}
+
+describe('resolveSlabEdgeBandSnap', () => {
+  test('magnetic: an edge inside the wall band sticks to the centerline and shows the beacon', () => {
+    const { wall, nodes } = sceneWithWall()
+    useWallSnapIndicator.getState().clear()
+
+    const snap = resolveSlabEdgeBandSnap({
+      edge: [
+        [0.5, 0.08],
+        [3.5, 0.08],
+      ],
+      nodes,
+      referencePoint: [1, 0.08],
+      magnetic: true,
+    })
+
+    expect(snap).not.toBeNull()
+    expect(snap!.wallId).toBe(wall.id)
+    expect(snap!.edge[0][1]).toBeCloseTo(0)
+    expect(snap!.edge[1][1]).toBeCloseTo(0)
+
+    const beacon = useWallSnapIndicator.getState().point
+    expect(beacon).not.toBeNull()
+    expect(beacon!.kind).toBe('wall')
+    expect(beacon!.wallIds).toEqual([wall.id])
+    // Beacon hugs the reference point projected onto the snapped edge.
+    expect(beacon!.x).toBeCloseTo(1)
+    expect(beacon!.z).toBeCloseTo(0)
+  })
+
+  test('non-magnetic: only the tight connect stick remains', () => {
+    const { nodes } = sceneWithWall()
+
+    // 8cm off the centerline: inside the band but beyond the connect radius.
+    expect(
+      resolveSlabEdgeBandSnap({
+        edge: [
+          [0.5, 0.08],
+          [3.5, 0.08],
+        ],
+        nodes,
+        magnetic: false,
+      }),
+    ).toBeNull()
+    expect(useWallSnapIndicator.getState().point).toBeNull()
+
+    // 4cm: genuinely dropped on the wall — still sticks.
+    expect(
+      resolveSlabEdgeBandSnap({
+        edge: [
+          [0.5, 0.04],
+          [3.5, 0.04],
+        ],
+        nodes,
+        magnetic: false,
+      }),
+    ).not.toBeNull()
+  })
+
+  test('clears the beacon when the edge leaves every band', () => {
+    const { nodes } = sceneWithWall()
+
+    resolveSlabEdgeBandSnap({
+      edge: [
+        [0.5, 0.05],
+        [3.5, 0.05],
+      ],
+      nodes,
+      magnetic: true,
+    })
+    expect(useWallSnapIndicator.getState().point).not.toBeNull()
+
+    resolveSlabEdgeBandSnap({
+      edge: [
+        [0.5, 1.5],
+        [3.5, 1.5],
+      ],
+      nodes,
+      magnetic: true,
+    })
+    expect(useWallSnapIndicator.getState().point).toBeNull()
+  })
+})