@pascal-app/editor 0.4.0 → 0.6.0

package/src/components/ui/sidebar/panels/site-panel/zone-tree-node.tsx

@@ -1,62 +1,61 @@
-import { useScene, type ZoneNode } from '@pascal-app/core'
+import { type AnyNodeId, useScene, type ZoneNode } from '@pascal-app/core'
 import { useViewer } from '@pascal-app/viewer'
-import { useState } from 'react'
+import { memo, useCallback, useState } from 'react'
 import { ColorDot } from './../../../../../components/ui/primitives/color-dot'
 import { InlineRenameInput } from './inline-rename-input'
 import { focusTreeNode, TreeNodeWrapper } from './tree-node'
 import { TreeNodeActions } from './tree-node-actions'
 
 interface ZoneTreeNodeProps {
-  node: ZoneNode
+  nodeId: AnyNodeId
   depth: number
   isLast?: boolean
 }
 
-export function ZoneTreeNode({ node, depth, isLast }: ZoneTreeNodeProps) {
+export const ZoneTreeNode = memo(function ZoneTreeNode({
+  nodeId,
+  depth,
+  isLast,
+}: ZoneTreeNodeProps) {
   const [isEditing, setIsEditing] = useState(false)
   const updateNode = useScene((state) => state.updateNode)
-  const isSelected = useViewer((state) => state.selection.zoneId === node.id)
-  const isHovered = useViewer((state) => state.hoveredId === node.id)
+  const isVisible = useScene((s) => s.nodes[nodeId]?.visible !== false)
+  const color = useScene((s) => (s.nodes[nodeId] as ZoneNode | undefined)?.color)
+  const polygon = useScene((s) => (s.nodes[nodeId] as ZoneNode | undefined)?.polygon ?? [])
+  const isSelected = useViewer((state) => state.selection.zoneId === nodeId)
+  const isHovered = useViewer((state) => state.hoveredId === nodeId)
   const setSelection = useViewer((state) => state.setSelection)
   const setHoveredId = useViewer((state) => state.setHoveredId)
 
-  const handleClick = () => {
-    setSelection({ zoneId: node.id })
-  }
-
-  const handleDoubleClick = () => {
-    focusTreeNode(node.id)
-  }
-
-  const handleMouseEnter = () => {
-    setHoveredId(node.id)
-  }
-
-  const handleMouseLeave = () => {
-    setHoveredId(null)
-  }
+  const handleClick = useCallback(() => setSelection({ zoneId: nodeId }), [nodeId, setSelection])
+  const handleDoubleClick = useCallback(() => focusTreeNode(nodeId), [nodeId])
+  const handleMouseEnter = useCallback(() => setHoveredId(nodeId), [nodeId, setHoveredId])
+  const handleMouseLeave = useCallback(() => setHoveredId(null), [setHoveredId])
+  const handleStartEditing = useCallback(() => setIsEditing(true), [])
+  const handleStopEditing = useCallback(() => setIsEditing(false), [])
 
   // Calculate approximate area from polygon
-  const area = calculatePolygonArea(node.polygon).toFixed(1)
+  const area = calculatePolygonArea(polygon).toFixed(1)
   const defaultName = `Zone (${area}m²)`
 
   return (
     <TreeNodeWrapper
-      actions={<TreeNodeActions node={node} />}
+      actions={<TreeNodeActions nodeId={nodeId} />}
       depth={depth}
       expanded={false}
       hasChildren={false}
-      icon={<ColorDot color={node.color} onChange={(color) => updateNode(node.id, { color })} />}
+      icon={<ColorDot color={color} onChange={(c) => updateNode(nodeId, { color: c })} />}
       isHovered={isHovered}
       isLast={isLast}
       isSelected={isSelected}
+      isVisible={isVisible}
       label={
         <InlineRenameInput
           defaultName={defaultName}
           isEditing={isEditing}
-          node={node}
-          onStartEditing={() => setIsEditing(true)}
-          onStopEditing={() => setIsEditing(false)}
+          nodeId={nodeId}
+          onStartEditing={handleStartEditing}
+          onStopEditing={handleStopEditing}
         />
       }
       onClick={handleClick}
@@ -66,7 +65,7 @@ export function ZoneTreeNode({ node, depth, isLast }: ZoneTreeNodeProps) {
       onToggle={() => {}}
     />
   )
-}
+})
 
 /**
  * Calculate the area of a polygon using the shoelace formula

package/src/components/ui/viewer-toolbar.tsx

@@ -2,11 +2,17 @@
 
 import { Icon as IconifyIcon } from '@iconify/react'
 import { useViewer } from '@pascal-app/viewer'
-import { ChevronsLeft, ChevronsRight, Columns2, Eye, Footprints, Moon, Sun } from 'lucide-react'
+import { Check, ChevronsLeft, ChevronsRight, Columns2, Eye, Footprints, Moon, Sun } from 'lucide-react'
 import { useCallback } from 'react'
 import { cn } from '../../lib/utils'
 import useEditor from '../../store/use-editor'
-import type { ViewMode } from '../../store/use-editor'
+import type { GridSnapStep, ViewMode } from '../../store/use-editor'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from './primitives/dropdown-menu'
 import { useSidebarStore } from './primitives/sidebar'
 import { Tooltip, TooltipContent, TooltipTrigger } from './primitives/tooltip'
 
@@ -174,6 +180,18 @@ const levelModeLabels: Record<string, string> = {
   solo: 'Solo',
 }
 
+const gridSnapOrder: GridSnapStep[] = [0.5, 0.25, 0.1, 0.05]
+const gridSnapLabels: Record<GridSnapStep, string> = {
+  0.5: '0.50',
+  0.25: '0.25',
+  0.1: '0.10',
+  0.05: '0.05',
+}
+
+function formatGridSnapStep(step: GridSnapStep): string {
+  return gridSnapLabels[step]
+}
+
 function LevelModeToggle() {
   const levelMode = useViewer((s) => s.levelMode)
   const setLevelMode = useViewer((s) => s.setLevelMode)
@@ -219,6 +237,40 @@ function LevelModeToggle() {
   )
 }
 
+function GridSnapToggle() {
+  const gridSnapStep = useEditor((s) => s.gridSnapStep)
+  const setGridSnapStep = useEditor((s) => s.setGridSnapStep)
+
+  return (
+    <DropdownMenu>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <DropdownMenuTrigger asChild>
+            <button className={cn(TOOLBAR_BTN, 'w-auto gap-1.5 px-2.5')} type="button">
+              <IconifyIcon height={14} icon="lucide:grid-2x2" width={14} />
+              <span className="font-medium text-xs">{formatGridSnapStep(gridSnapStep)}</span>
+            </button>
+          </DropdownMenuTrigger>
+        </TooltipTrigger>
+        <TooltipContent side="bottom">Grid snap: {formatGridSnapStep(gridSnapStep)}</TooltipContent>
+      </Tooltip>
+      <DropdownMenuContent align="center" side="bottom">
+        {gridSnapOrder.map((step) => {
+          const isActive = step === gridSnapStep
+          return (
+            <DropdownMenuItem key={step} onSelect={() => setGridSnapStep(step)}>
+              <span className="flex min-w-12 items-center justify-between gap-3">
+                <span>{formatGridSnapStep(step)}</span>
+                {isActive ? <Check className="h-3.5 w-3.5" /> : <span className="h-3.5 w-3.5" />}
+              </span>
+            </DropdownMenuItem>
+          )
+        })}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+
 // ── Wall mode toggle ────────────────────────────────────────────────────────
 
 const wallModeOrder = ['cutaway', 'up', 'down'] as const
@@ -330,6 +382,7 @@ export function ViewerToolbarRight() {
     <div className={TOOLBAR_CONTAINER}>
       <LevelModeToggle />
       <WallModeToggle />
+      <GridSnapToggle />
       <div className="my-1.5 w-px bg-border/50" />
       <UnitToggle />
       <ThemeToggle />

package/src/components/viewer-overlay.tsx

@@ -14,6 +14,7 @@ import { useViewer } from '@pascal-app/viewer'
 import { ArrowLeft, Camera, ChevronRight, Diamond, Layers, Moon, Sun } from 'lucide-react'
 import { motion } from 'motion/react'
 import Link from 'next/link'
+import { useShallow } from 'zustand/react/shallow'
 import { cn } from '../lib/utils'
 import { ActionButton } from './ui/action-menu/action-button'
 import { TooltipProvider } from './ui/primitives/tooltip'
@@ -62,6 +63,7 @@ const wallModeConfig = {
 const getNodeName = (node: AnyNode): string => {
   if ('name' in node && node.name) return node.name
   if (node.type === 'wall') return 'Wall'
+  if (node.type === 'fence') return 'Fence'
   if (node.type === 'item') return (node as { asset: { name: string } }).asset?.name || 'Item'
   if (node.type === 'slab') return 'Slab'
   if (node.type === 'ceiling') return 'Ceiling'
@@ -86,7 +88,6 @@ export const ViewerOverlay = ({
   onBack,
 }: ViewerOverlayProps) => {
   const selection = useViewer((s) => s.selection)
-  const nodes = useScene((s) => s.nodes)
   const showScans = useViewer((s) => s.showScans)
   const showGuides = useViewer((s) => s.showGuides)
   const cameraMode = useViewer((s) => s.cameraMode)
@@ -94,24 +95,30 @@ export const ViewerOverlay = ({
   const wallMode = useViewer((s) => s.wallMode)
   const theme = useViewer((s) => s.theme)
 
-  const building = selection.buildingId
-    ? (nodes[selection.buildingId] as BuildingNode | undefined)
-    : null
-  const level = selection.levelId ? (nodes[selection.levelId] as LevelNode | undefined) : null
-  const zone = selection.zoneId ? (nodes[selection.zoneId] as ZoneNode | undefined) : null
-
-  // Get the first selected item (if any)
-  const selectedNode =
-    selection.selectedIds.length > 0
-      ? (nodes[selection.selectedIds[0] as AnyNodeId] as AnyNode | undefined)
-      : null
-
-  // Get all levels for the selected building
-  const levels =
-    building?.children
-      .map((id) => nodes[id as AnyNodeId] as LevelNode | undefined)
-      .filter((n): n is LevelNode => n?.type === 'level')
-      .sort((a, b) => a.level - b.level) ?? []
+  // Subscribe only to the specific nodes we read so that creating an unrelated
+  // node elsewhere in the scene doesn't re-render this overlay.
+  const firstSelectedId = selection.selectedIds[0] ?? null
+  const building = useScene((s) =>
+    selection.buildingId ? (s.nodes[selection.buildingId] as BuildingNode | undefined) : null,
+  )
+  const level = useScene((s) =>
+    selection.levelId ? (s.nodes[selection.levelId] as LevelNode | undefined) : null,
+  )
+  const zone = useScene((s) =>
+    selection.zoneId ? (s.nodes[selection.zoneId] as ZoneNode | undefined) : null,
+  )
+  const selectedNode = useScene((s) =>
+    firstSelectedId ? (s.nodes[firstSelectedId as AnyNodeId] as AnyNode | undefined) : null,
+  )
+  const levels = useScene(
+    useShallow((s) => {
+      if (!building) return []
+      return building.children
+        .map((id) => s.nodes[id as AnyNodeId] as LevelNode | undefined)
+        .filter((n): n is LevelNode => n?.type === 'level')
+        .sort((a, b) => a.level - b.level)
+    }),
+  )
 
   const handleLevelClick = (levelId: LevelNode['id']) => {
     // When switching levels, deselect zone and items

package/src/hooks/use-auto-save.ts

@@ -1,7 +1,7 @@
 'use client'
 
 import { useScene } from '@pascal-app/core'
-import { type MutableRefObject, useCallback, useEffect, useRef, useState } from 'react'
+import { type MutableRefObject, useCallback, useEffect, useRef } from 'react'
 import { type SceneGraph, saveSceneToLocalStorage } from '../lib/scene'
 
 const AUTOSAVE_DEBOUNCE_MS = 1000
@@ -26,9 +26,7 @@ export function useAutoSave({
   onDirty,
   onSaveStatusChange,
   isVersionPreviewMode = false,
-}: UseAutoSaveOptions): { saveStatus: SaveStatus; isLoadingSceneRef: MutableRefObject<boolean> } {
-  const [saveStatus, _setSaveStatus] = useState<SaveStatus>('idle')
-
+}: UseAutoSaveOptions): { isLoadingSceneRef: MutableRefObject<boolean> } {
   const saveTimeoutRef = useRef<NodeJS.Timeout | undefined>(undefined)
   const isSavingRef = useRef(false)
   const isLoadingSceneRef = useRef(false)
@@ -56,7 +54,6 @@ export function useAutoSave({
   }, [isVersionPreviewMode])
 
   const setSaveStatus = useCallback((status: SaveStatus) => {
-    _setSaveStatus(status)
     onSaveStatusChangeRef.current?.(status)
   }, [])
 
@@ -190,5 +187,5 @@ export function useAutoSave({
     setSaveStatus('saved')
   }, [isVersionPreviewMode, setSaveStatus])
 
-  return { saveStatus, isLoadingSceneRef }
+  return { isLoadingSceneRef }
 }

package/src/hooks/use-contextual-tools.ts

@@ -1,12 +1,18 @@
 import { type AnyNodeId, useScene } from '@pascal-app/core'
 import { useViewer } from '@pascal-app/viewer'
 import { useMemo } from 'react'
+import { useShallow } from 'zustand/react/shallow'
 import useEditor, { type StructureTool } from '../store/use-editor'
 
 export function useContextualTools() {
   const selection = useViewer((s) => s.selection)
-  const nodes = useScene((s) => s.nodes)
-  const phase = useEditor((s) => s.phase)
+  // Only resubscribe when the *types* of selected nodes change, not when any
+  // node in the scene mutates.
+  const selectedTypes = useScene(
+    useShallow((s) =>
+      selection.selectedIds.map((id) => s.nodes[id as AnyNodeId]?.type).filter(Boolean),
+    ),
+  )
   const structureLayer = useEditor((s) => s.structureLayer)
 
   return useMemo(() => {
@@ -16,37 +22,40 @@ export function useContextualTools() {
     }
 
     // Default tools when nothing is selected
-    const defaultTools: StructureTool[] = ['wall', 'slab', 'ceiling', 'roof', 'door', 'window']
-
-    if (selection.selectedIds.length === 0) {
+    const defaultTools: StructureTool[] = [
+      'wall',
+      'fence',
+      'slab',
+      'ceiling',
+      'roof',
+      'door',
+      'window',
+    ]
+
+    if (selectedTypes.length === 0) {
       return defaultTools
     }
 
-    // Get types of selected nodes
-    const selectedTypes = new Set(
-      selection.selectedIds.map((id) => nodes[id as AnyNodeId]?.type).filter(Boolean),
-    )
-
     // If a wall is selected, prioritize wall-hosted elements
-    if (selectedTypes.has('wall')) {
-      return ['window', 'door', 'wall'] as StructureTool[]
+    if (selectedTypes.includes('wall')) {
+      return ['window', 'door', 'wall', 'fence'] as StructureTool[]
     }
 
     // If a slab is selected, prioritize slab editing
-    if (selectedTypes.has('slab')) {
+    if (selectedTypes.includes('slab')) {
       return ['slab', 'wall'] as StructureTool[]
     }
 
     // If a ceiling is selected, prioritize ceiling editing
-    if (selectedTypes.has('ceiling')) {
+    if (selectedTypes.includes('ceiling')) {
       return ['ceiling'] as StructureTool[]
     }
 
     // If a roof is selected, prioritize roof editing
-    if (selectedTypes.has('roof')) {
+    if (selectedTypes.includes('roof')) {
       return ['roof'] as StructureTool[]
     }
 
     return defaultTools
-  }, [selection.selectedIds, nodes, structureLayer])
+  }, [selectedTypes, structureLayer])
 }

package/src/hooks/use-grid-events.ts

@@ -1,4 +1,10 @@
-import { type EventSuffix, emitter, type GridEvent } from '@pascal-app/core'
+import {
+  type AnyNodeId,
+  type EventSuffix,
+  emitter,
+  type GridEvent,
+  sceneRegistry,
+} from '@pascal-app/core'
 import { useViewer } from '@pascal-app/viewer'
 import { useThree } from '@react-three/fiber'
 import { useEffect, useRef } from 'react'
@@ -44,9 +50,15 @@ export function useGridEvents(gridY: number) {
       const point = getIntersection(nativeEvent)
       if (!point) return
 
+      // Convert world-space point to building-local for tools that live inside a building.
+      const buildingId = useViewer.getState().selection.buildingId
+      const buildingMesh = buildingId ? sceneRegistry.nodes.get(buildingId as AnyNodeId) : null
+      const localPoint = buildingMesh ? buildingMesh.worldToLocal(point.clone()) : point
+
       const eventKey = `grid:${suffix}` as `grid:${EventSuffix}`
       const payload: GridEvent = {
         position: [point.x, point.y, point.z],
+        localPosition: [localPoint.x, localPoint.y, localPoint.z],
         nativeEvent: nativeEvent as any, // Type compatibility with ThreeEvent
       }
 

package/src/hooks/use-keyboard.ts

@@ -1,6 +1,7 @@
 import { type AnyNodeId, emitter, useScene } from '@pascal-app/core'
 import { useViewer } from '@pascal-app/viewer'
 import { useEffect } from 'react'
+import { runRedo, runUndo } from '../lib/history'
 import { sfxEmitter } from '../lib/sfx-bus'
 import useEditor from '../store/use-editor'
 
@@ -84,14 +85,18 @@ export const useKeyboard = ({ isVersionPreviewMode = false } = {}) => {
         useEditor.getState().setPhase('structure')
         useEditor.getState().setStructureLayer('elements')
         useEditor.getState().setMode('build')
+      } else if (e.key === 'd' && !e.metaKey && !e.ctrlKey) {
+        if (isVersionPreviewMode) return
+        e.preventDefault()
+        useEditor.getState().setMode('delete')
       } else if (e.key === 'z' && (e.metaKey || e.ctrlKey)) {
         if (isVersionPreviewMode) return
         e.preventDefault()
-        useScene.temporal.getState().undo()
+        runUndo()
       } else if (e.key === 'Z' && e.shiftKey && (e.metaKey || e.ctrlKey)) {
         if (isVersionPreviewMode) return
         e.preventDefault()
-        useScene.temporal.getState().redo()
+        runRedo()
       } else if (e.key === 'ArrowUp' && (e.metaKey || e.ctrlKey)) {
         e.preventDefault()
         const { buildingId, levelId } = useViewer.getState().selection

package/src/index.tsx

@@ -15,11 +15,13 @@ export {
 } from './components/ui/sidebar/panels/settings-panel'
 export type { SitePanelProps } from './components/ui/sidebar/panels/site-panel'
 export type { SidebarTab } from './components/ui/sidebar/tab-bar'
+export { ViewerToolbarLeft, ViewerToolbarRight } from './components/ui/viewer-toolbar'
 export type { PresetsAdapter, PresetsTab } from './contexts/presets-context'
 export { PresetsProvider } from './contexts/presets-context'
 export type { SaveStatus } from './hooks/use-auto-save'
 export type { SceneGraph } from './lib/scene'
 export { applySceneGraphToEditor } from './lib/scene'
+export { triggerSFX } from './lib/sfx-bus'
 export { default as useAudio } from './store/use-audio'
 export { type CommandAction, useCommandRegistry } from './store/use-command-registry'
 export type { FloorplanSelectionTool, SplitOrientation, ViewMode } from './store/use-editor'
@@ -30,4 +32,3 @@ export {
   usePaletteViewRegistry,
 } from './store/use-palette-view-registry'
 export { useUploadStore } from './store/use-upload'
-export { ViewerToolbarLeft, ViewerToolbarRight } from './components/ui/viewer-toolbar'

package/src/lib/history.ts

@@ -0,0 +1,20 @@
+import { useLiveTransforms, useScene } from '@pascal-app/core'
+
+function refreshSceneAfterHistoryJump() {
+  useLiveTransforms.getState().clearAll()
+
+  const state = useScene.getState()
+  for (const node of Object.values(state.nodes)) {
+    state.markDirty(node.id)
+  }
+}
+
+export function runUndo() {
+  useScene.temporal.getState().undo()
+  refreshSceneAfterHistoryJump()
+}
+
+export function runRedo() {
+  useScene.temporal.getState().redo()
+  refreshSceneAfterHistoryJump()
+}

package/src/lib/sfx-player.ts

@@ -1,26 +1,90 @@
 import { Howl } 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
+  // Random playback-rate range applied per play (1 = unchanged).
+  rateRange?: [number, number]
+  // Random volume multiplier range applied per play (1 = unchanged).
+  volumeRange?: [number, number]
+  // 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 centered 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
+
 // SFX sound definitions
-export const SFX = {
-  gridSnap: '/audios/sfx/grid_snap.mp3',
-  itemDelete: '/audios/sfx/item_delete.mp3',
-  itemPick: '/audios/sfx/item_pick.mp3',
-  itemPlace: '/audios/sfx/item_place.mp3',
-  itemRotate: '/audios/sfx/item_rotate.mp3',
-  structureBuild: '/audios/sfx/structure_build.mp3',
-  structureDelete: '/audios/sfx/structure_delete.mp3',
+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,
+  },
+  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],
+    volumeRange: [0.92, 1.0],
+    panJitter: 0.15,
+  },
+  itemPlace: {
+    src: '/audios/sfx/item_place.mp3',
+    rateRange: [0.98, 1.06],
+    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',
+    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',
+  },
 } as const
 
 export type SFXName = keyof typeof SFX
 
+function randomInRange([min, max]: [number, number]): number {
+  return min + Math.random() * (max - min)
+}
+
 // Preload all SFX sounds
 const sfxCache = new Map<SFXName, Howl>()
+const lastPlayedAt = new Map<SFXName, number>()
 
 // Initialize all sounds
-Object.entries(SFX).forEach(([name, path]) => {
+Object.entries(SFX).forEach(([name, config]) => {
   const sound = new Howl({
-    src: [path],
+    src: [config.src],
     preload: true,
     volume: 0.5, // Will be adjusted by the bus
   })
@@ -36,15 +100,34 @@ export function playSFX(name: SFXName) {
     console.warn(`SFX not found: ${name}`)
     return
   }
+  const config = SFX[name]!
+
+  // 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()
+  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()
 
   if (muted) return
 
   // Calculate final volume (masterVolume and sfxVolume are 0-100)
-  const finalVolume = (masterVolume / 100) * (sfxVolume / 100)
-  sound.volume(finalVolume)
-  sound.play()
+  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)
+  }
 }
 
 /**