@pascal-app/editor 0.8.0 → 0.9.2

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

@@ -0,0 +1,124 @@
+import { afterAll, beforeEach, describe, expect, mock, test } from 'bun:test'
+
+type FakeContext = { id: string }
+
+let activeContext: FakeContext = { id: 'first' }
+let throwOnPlay = false
+const instances: FakeHowl[] = []
+
+class FakeHowl {
+  stateValue: 'loaded' | 'unloaded' = 'loaded'
+  unloadCount = 0
+  playCount = 0
+
+  constructor(_options: unknown) {
+    instances.push(this)
+  }
+
+  play() {
+    this.playCount++
+    if (throwOnPlay) throw new DOMException('stale graph', 'InvalidAccessError')
+    return 1
+  }
+
+  volume() {
+    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: false, sfxVolume: 100 }),
+  },
+}))
+
+const { disposeSFX, playSFX, preloadSFX } = await import('./sfx-player')
+const { disposeSFXBus, initSFXBus, triggerSFX } = await import('./sfx-bus')
+
+beforeEach(() => {
+  disposeSFXBus()
+  activeContext = { id: 'first' }
+  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('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()
+  })
+})

package/src/lib/sfx-player.ts

@@ -1,11 +1,12 @@
-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×),
 // so a rate range of ~0.88–1.12 reads as a subtle ±2 semitones — enough to kill the
 // machine-gun feeling when the same SFX fires in rapid succession.
 type SFXConfig = {
-  src: string
+  // One file, or several pre-rendered variations cycled round-robin per play.
+  src: string | string[]
   // Random playback-rate range applied per play (1 = unchanged).
   rateRange?: [number, number]
   // Random volume multiplier range applied per play (1 = unchanged).
@@ -13,62 +14,96 @@ 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
 }
 
 const DEFAULT_MIN_INTERVAL_MS = 30
+const SFX_FAILURE_BACKOFF_MS = 5_000
 
 // SFX sound definitions
 export const SFX: Record<string, SFXConfig> = {
   gridSnap: {
-    src: '/audios/sfx/grid_snap.mp3',
-    rateRange: [0.94, 1.06],
-    volumeRange: [0.92, 1.0],
-    panJitter: 0.15,
+    src: [
+      '/audios/sfx/grid_snap_0.mp3',
+      '/audios/sfx/grid_snap_1.mp3',
+      '/audios/sfx/grid_snap_2.mp3',
+    ],
+    rateRange: [0.98, 1.02],
+    volumeRange: [0.5, 0.6],
+    minIntervalMs: 50,
   },
   itemDelete: {
     src: '/audios/sfx/item_delete.mp3',
     rateRange: [0.9, 1.1],
     volumeRange: [0.9, 1.0],
-    panJitter: 0.15,
   },
   itemPick: {
     src: '/audios/sfx/item_pick.mp3',
-    rateRange: [0.92, 1.08],
+    rateRange: [0.95, 1.05],
     volumeRange: [0.92, 1.0],
-    panJitter: 0.15,
   },
   itemPlace: {
     src: '/audios/sfx/item_place.mp3',
-    rateRange: [0.98, 1.06],
+    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,
   },
-  structureBuild: {
-    src: '/audios/sfx/structure_build.mp3',
+  // 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],
+  },
+  // 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.15,
   },
   snapshotCapture: {
     // Shutter should sound consistent — no variation.
     src: '/audios/sfx/snapshot_capture.mp3',
   },
+  // Soft tick when hovering a main category in the Build / Items panels.
+  // Kept quiet and rate-locked so sweeping across the grid reads as texture,
+  // not a melody.
+  menuHover: {
+    src: '/audios/sfx/menu_hover.mp3',
+    rateRange: [0.98, 1.02],
+    volumeRange: [0.2, 0.3],
+    minIntervalMs: 0,
+  },
+  // Fired when a main category in the Build / Items panels is clicked.
+  menuClick: {
+    src: '/audios/sfx/menu_click.mp3',
+    rateRange: [0.98, 1.02],
+    volumeRange: [0.5, 0.6],
+  },
+  // 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
@@ -77,56 +112,105 @@ function randomInRange([min, max]: [number, number]): number {
   return min + Math.random() * (max - min)
 }
 
-// Preload all SFX sounds
-const sfxCache = new Map<SFXName, Howl>()
+let sfxCache = new Map<SFXName, Howl[]>()
+let sfxAudioContext: AudioContext | null = null
+let sfxRetryAfter = 0
 const lastPlayedAt = new Map<SFXName, number>()
+const lastVariation = new Map<SFXName, number>()
 
-// Initialize all sounds
-Object.entries(SFX).forEach(([name, config]) => {
-  const sound = new Howl({
-    src: [config.src],
-    preload: true,
-    volume: 0.5, // Will be adjusted by the bus
-  })
-  sfxCache.set(name as SFXName, sound)
-})
+function unloadCachedSounds(resetPlaybackState: boolean) {
+  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
+}
+
+export function preloadSFX() {
+  if (!cacheNeedsRebuild()) return
+  unloadCachedSounds(false)
+
+  for (const [name, config] of Object.entries(SFX)) {
+    const sources = Array.isArray(config.src) ? config.src : [config.src]
+    sfxCache.set(
+      name as SFXName,
+      sources.map(
+        (src) =>
+          new Howl({
+            src: [src],
+            preload: true,
+            volume: 0.5,
+          }),
+      ),
+    )
+  }
+  sfxAudioContext = Howler.ctx ?? null
+}
+
+export function disposeSFX() {
+  unloadCachedSounds(true)
+}
 
 /**
  * Play a sound effect with volume based on audio settings
  */
 export function playSFX(name: SFXName) {
-  const sound = sfxCache.get(name)
-  if (!sound) {
-    console.warn(`SFX not found: ${name}`)
-    return
-  }
   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)
   if (last !== undefined && now - last < minInterval) return
   lastPlayedAt.set(name, now)
 
-  const { masterVolume, sfxVolume, muted } = useAudio.getState()
+  try {
+    preloadSFX()
+    const sounds = sfxCache.get(name)
+    if (!sounds || sounds.length === 0) return
 
-  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]!
+    const baseVolume = (masterVolume / 100) * (sfxVolume / 100)
+    const volumeJitter = config.volumeRange ? randomInRange(config.volumeRange) : 1
+    const rate = config.rateRange ? randomInRange(config.rateRange) : 1
+    const id = sound.play()
+    sound.volume(baseVolume * volumeJitter, 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
   }
 }
 
@@ -137,7 +221,16 @@ export function updateSFXVolumes() {
   const { masterVolume, sfxVolume } = useAudio.getState()
   const finalVolume = (masterVolume / 100) * (sfxVolume / 100)
 
-  sfxCache.forEach((sound) => {
-    sound.volume(finalVolume)
-  })
+  try {
+    if (performance.now() < sfxRetryAfter) return
+    preloadSFX()
+    sfxCache.forEach((sounds) => {
+      sounds.forEach((sound) => {
+        sound.volume(finalVolume)
+      })
+    })
+  } catch {
+    unloadCachedSounds(false)
+    sfxRetryAfter = performance.now() + SFX_FAILURE_BACKOFF_MS
+  }
 }

package/src/lib/site-boundary.ts

@@ -0,0 +1 @@
+export const SITE_BOUNDARY_DRAG_LABEL = 'site-boundary'

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()
+  })
+})

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

@@ -0,0 +1,108 @@
+import { type AnyNode, snapSlabEdgeToWallBand, useScene } from '@pascal-app/core'
+import { WALL_CONNECT_SNAP_RADIUS } from '../components/tools/wall/wall-drafting'
+import useAlignmentGuides from '../store/use-alignment-guides'
+import { isMagneticSnapActive } from '../store/use-editor'
+import useWallSnapIndicator from '../store/use-wall-snap-indicator'
+import {
+  clearSurfacePlanSnapFeedback,
+  getLevelWalls,
+  resolveSurfacePlanPointSnap,
+  SURFACE_ALIGNMENT_THRESHOLD_M,
+  type SurfacePlanSnapInput,
+  type SurfacePlanSnapResult,
+} from './surface-plan-snap'
+
+const SLAB_SNAP_MOVING_ID = '__slab_snap__'
+
+export const SLAB_ALIGNMENT_THRESHOLD_M = SURFACE_ALIGNMENT_THRESHOLD_M
+export type SlabPlanSnapInput = SurfacePlanSnapInput
+export type SlabPlanSnapResult = SurfacePlanSnapResult
+
+export function clearSlabSnapFeedback() {
+  clearSurfacePlanSnapFeedback()
+}
+
+export function resolveSlabPlanPointSnap(input: SlabPlanSnapInput): SlabPlanSnapResult {
+  return resolveSurfacePlanPointSnap({
+    ...input,
+    highlightWalls: input.highlightWalls ?? false,
+    movingId: input.movingId ?? SLAB_SNAP_MOVING_ID,
+  })
+}
+
+export type SlabEdgeBandSnapInput = {
+  /** Candidate edge endpoints after the raw/grid perpendicular translation. */
+  edge: [[number, number], [number, number]]
+  levelId?: string | null
+  nodes?: Readonly<Record<string, AnyNode>>
+  /**
+   * Plan point (typically the cursor) the snap beacon should hug along
+   * the wall. Falls back to the snapped edge's midpoint.
+   */
+  referencePoint?: [number, number]
+  /** Override the mode-driven magnetic gate (tests). */
+  magnetic?: boolean
+}
+
+export type SlabEdgeBandSnapResult = {
+  /** The candidate edge translated onto the wall centerline. */
+  edge: [[number, number], [number, number]]
+  wallId: string
+}
+
+/**
+ * Edge-level slab reshape snap against wall footprint bands. Unlike the
+ * cursor-based `resolveSlabPlanPointSnap`, this tests the DRAGGED EDGE
+ * itself (band adoption, span overlap — same permissiveness as the
+ * render rule) and sticks it onto the wall CENTERLINE, the canonical
+ * stored position; the render rule then places it flush with the face.
+ * The beacon, the live preview and the committed polygon therefore all
+ * agree. In non-magnetic modes only a tight connect-radius stick
+ * remains, mirroring the sanctioned wall connect snap. Publishes /
+ * clears the wall-snap beacon as a side effect.
+ */
+export function resolveSlabEdgeBandSnap(
+  input: SlabEdgeBandSnapInput,
+): SlabEdgeBandSnapResult | null {
+  const nodes = input.nodes ?? useScene.getState().nodes
+  const walls = getLevelWalls(nodes, input.levelId)
+  const magnetic = input.magnetic ?? isMagneticSnapActive()
+
+  const snap = snapSlabEdgeToWallBand(
+    input.edge[0],
+    input.edge[1],
+    walls,
+    magnetic ? undefined : { maxLateral: WALL_CONNECT_SNAP_RADIUS },
+  )
+  if (!snap) {
+    useWallSnapIndicator.getState().clear()
+    useAlignmentGuides.getState().clear()
+    return null
+  }
+
+  const [a, b] = snap.edge
+  const dx = b[0] - a[0]
+  const dz = b[1] - a[1]
+  const lengthSquared = dx * dx + dz * dz
+  let beacon: [number, number] = [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2]
+  if (input.referencePoint && lengthSquared > 1e-12) {
+    const t = Math.max(
+      0,
+      Math.min(
+        1,
+        ((input.referencePoint[0] - a[0]) * dx + (input.referencePoint[1] - a[1]) * dz) /
+          lengthSquared,
+      ),
+    )
+    beacon = [a[0] + dx * t, a[1] + dz * t]
+  }
+  useWallSnapIndicator.getState().set({
+    x: beacon[0],
+    z: beacon[1],
+    kind: 'wall',
+    wallIds: [snap.wallId],
+  })
+  useAlignmentGuides.getState().clear()
+
+  return { edge: snap.edge, wallId: snap.wallId }
+}