@pascal-app/editor 0.5.1 → 0.6.0

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

@@ -1,7 +1,7 @@
 import { type AnyNodeId, type SlabNode, useScene } from '@pascal-app/core'
 import { useViewer } from '@pascal-app/viewer'
 import Image from 'next/image'
-import { useCallback, useState } from 'react'
+import { memo, useCallback, useState } from 'react'
 import useEditor from './../../../../../store/use-editor'
 import { InlineRenameInput } from './inline-rename-input'
 import { focusTreeNode, handleTreeSelection, TreeNodeWrapper } from './tree-node'
@@ -13,7 +13,11 @@ interface SlabTreeNodeProps {
   isLast?: boolean
 }
 
-export function SlabTreeNode({ nodeId, depth, isLast }: SlabTreeNodeProps) {
+export const SlabTreeNode = memo(function SlabTreeNode({
+  nodeId,
+  depth,
+  isLast,
+}: SlabTreeNodeProps) {
   const [isEditing, setIsEditing] = useState(false)
   const isVisible = useScene((s) => s.nodes[nodeId]?.visible !== false)
   const polygon = useScene((s) => (s.nodes[nodeId] as SlabNode | undefined)?.polygon ?? [])
@@ -74,7 +78,7 @@ export function SlabTreeNode({ nodeId, depth, isLast }: SlabTreeNodeProps) {
       onToggle={() => {}}
     />
   )
-}
+})
 
 /**
  * Calculate the area of a polygon using the shoelace formula

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

@@ -2,7 +2,7 @@ import { type AnyNodeId, type StairNode, type StairSegmentNode, useScene } from
 import { useViewer } from '@pascal-app/viewer'
 import { AnimatePresence } from 'motion/react'
 import Image from 'next/image'
-import { useCallback, useEffect, useState } from 'react'
+import { memo, useCallback, useEffect, useState } from 'react'
 import { useShallow } from 'zustand/react/shallow'
 import useEditor from '../../../../../store/use-editor'
 import { InlineRenameInput } from './inline-rename-input'
@@ -16,7 +16,11 @@ interface StairTreeNodeProps {
   isLast?: boolean
 }
 
-export function StairTreeNode({ nodeId, depth, isLast }: StairTreeNodeProps) {
+export const StairTreeNode = memo(function StairTreeNode({
+  nodeId,
+  depth,
+  isLast,
+}: StairTreeNodeProps) {
   const [isEditing, setIsEditing] = useState(false)
   const [expanded, setExpanded] = useState(false)
   const isVisible = useScene((s) => s.nodes[nodeId]?.visible !== false)
@@ -147,7 +151,7 @@ export function StairTreeNode({ nodeId, depth, isLast }: StairTreeNodeProps) {
       </TreeNodeWrapper>
     </div>
   )
-}
+})
 
 function StairSegmentTreeNode({
   node,

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

@@ -1,7 +1,7 @@
 import { type AnyNodeId, emitter, useScene } from '@pascal-app/core'
 import { useViewer } from '@pascal-app/viewer'
 import { Camera, Eye, EyeOff, Trash2 } from 'lucide-react'
-import { useState } from 'react'
+import { memo, useState } from 'react'
 import {
   Popover,
   PopoverContent,
@@ -12,7 +12,7 @@ interface TreeNodeActionsProps {
   nodeId: AnyNodeId
 }
 
-export function TreeNodeActions({ nodeId }: TreeNodeActionsProps) {
+export const TreeNodeActions = memo(function TreeNodeActions({ nodeId }: TreeNodeActionsProps) {
   const [open, setOpen] = useState(false)
   const updateNode = useScene((state) => state.updateNode)
   const updateNodes = useScene((state) => state.updateNodes)
@@ -112,4 +112,4 @@ export function TreeNodeActions({ nodeId }: TreeNodeActionsProps) {
       </Popover>
     </div>
   )
-}
+})

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

@@ -1,7 +1,7 @@
 import { type AnyNodeId, emitter, useScene } from '@pascal-app/core'
 import { ChevronRight } from 'lucide-react'
 import { AnimatePresence, motion } from 'motion/react'
-import { forwardRef, useEffect, useRef } from 'react'
+import { forwardRef, memo, useEffect, useRef } from 'react'
 
 export function handleTreeSelection(
   e: React.MouseEvent,
@@ -73,7 +73,7 @@ interface TreeNodeProps {
   isLast?: boolean
 }
 
-export function TreeNode({ nodeId, depth = 0, isLast }: TreeNodeProps) {
+export const TreeNode = memo(function TreeNode({ nodeId, depth = 0, isLast }: TreeNodeProps) {
   const nodeType = useScene((state) => state.nodes[nodeId]?.type)
 
   if (!nodeType) return null
@@ -106,7 +106,7 @@ export function TreeNode({ nodeId, depth = 0, isLast }: TreeNodeProps) {
     default:
       return null
   }
-}
+})
 
 interface TreeNodeWrapperProps {
   nodeId?: string

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

@@ -1,7 +1,7 @@
 import { type AnyNodeId, useScene, type WallNode } from '@pascal-app/core'
 import { useViewer } from '@pascal-app/viewer'
 import Image from 'next/image'
-import { useCallback, useEffect, useRef, useState } from 'react'
+import { memo, useCallback, useEffect, useRef, useState } from 'react'
 import { useShallow } from 'zustand/react/shallow'
 import useEditor from './../../../../../store/use-editor'
 import { InlineRenameInput } from './inline-rename-input'
@@ -14,7 +14,11 @@ interface WallTreeNodeProps {
   isLast?: boolean
 }
 
-export function WallTreeNode({ nodeId, depth, isLast }: WallTreeNodeProps) {
+export const WallTreeNode = memo(function WallTreeNode({
+  nodeId,
+  depth,
+  isLast,
+}: WallTreeNodeProps) {
   const [expanded, setExpanded] = useState(false)
   const [isEditing, setIsEditing] = useState(false)
   const isVisible = useScene((s) => s.nodes[nodeId as AnyNodeId]?.visible !== false)
@@ -107,4 +111,4 @@ export function WallTreeNode({ nodeId, depth, isLast }: WallTreeNodeProps) {
       ))}
     </TreeNodeWrapper>
   )
-}
+})

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

@@ -3,7 +3,7 @@
 import { type AnyNodeId, useScene } from '@pascal-app/core'
 import { useViewer } from '@pascal-app/viewer'
 import Image from 'next/image'
-import { useCallback, useState } from 'react'
+import { memo, useCallback, useState } from 'react'
 import useEditor from './../../../../../store/use-editor'
 import { InlineRenameInput } from './inline-rename-input'
 import { focusTreeNode, handleTreeSelection, TreeNodeWrapper } from './tree-node'
@@ -15,7 +15,11 @@ interface WindowTreeNodeProps {
   isLast?: boolean
 }
 
-export function WindowTreeNode({ nodeId, depth, isLast }: WindowTreeNodeProps) {
+export const WindowTreeNode = memo(function WindowTreeNode({
+  nodeId,
+  depth,
+  isLast,
+}: WindowTreeNodeProps) {
   const [isEditing, setIsEditing] = useState(false)
   const isVisible = useScene((s) => s.nodes[nodeId as AnyNodeId]?.visible !== false)
   const isSelected = useViewer((state) => state.selection.selectedIds.includes(nodeId))
@@ -72,4 +76,4 @@ export function WindowTreeNode({ nodeId, depth, isLast }: WindowTreeNodeProps) {
       onToggle={() => {}}
     />
   )
-}
+})

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

@@ -1,6 +1,6 @@
 import { type AnyNodeId, useScene, type ZoneNode } from '@pascal-app/core'
 import { useViewer } from '@pascal-app/viewer'
-import { useCallback, 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'
@@ -12,7 +12,11 @@ interface ZoneTreeNodeProps {
   isLast?: boolean
 }
 
-export function ZoneTreeNode({ nodeId, 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 isVisible = useScene((s) => s.nodes[nodeId]?.visible !== false)
@@ -61,7 +65,7 @@ export function ZoneTreeNode({ nodeId, 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'
@@ -87,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)
@@ -95,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-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(() => {
@@ -26,35 +32,30 @@ export function useContextualTools() {
       'window',
     ]
 
-    if (selection.selectedIds.length === 0) {
+    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')) {
+    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-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'
 
@@ -91,11 +92,11 @@ export const useKeyboard = ({ isVersionPreviewMode = false } = {}) => {
       } 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)
+  }
 }
 
 /**