@pascal-app/editor 1.0.0-beta.5 → 1.0.0

package/src/lib/print-wall-solids.ts

@@ -0,0 +1,328 @@
+import {
+  type AnyNode,
+  type DoorNode,
+  getWallThickness,
+  type WallNode,
+  type WindowNode,
+} from '@pascal-app/core'
+import * as THREE from 'three'
+import { mergeVertices } from 'three/examples/jsm/utils/BufferGeometryUtils.js'
+
+// Manufacturing geometry belongs to the editor layer, not the read-only viewer runtime.
+const DIMENSION_EPSILON = 1e-7
+const SOLID_JOIN_OVERLAP = 1e-5
+
+type PrintWallOpening = DoorNode | WindowNode
+
+type OpeningInterval = {
+  node: PrintWallOpening
+  left: number
+  right: number
+  bottom: number
+  top: number
+}
+
+export type PrintWallSolidDiagnostic = {
+  severity: 'error'
+  code:
+    | 'invalid_wall_print_dimensions'
+    | 'unsupported_wall_print_curve'
+    | 'unsupported_wall_print_terrain'
+    | 'unsupported_wall_print_opening_shape'
+    | 'invalid_wall_print_opening'
+    | 'unresolved_wall_print_child'
+  message: string
+  nodeIds: string[]
+}
+
+export type PrintWallSolidOptions = {
+  effectiveHeight: number
+  includedNodeIds?: ReadonlySet<string>
+}
+
+export type PrintWallSolidResult =
+  | { status: 'ready'; object: THREE.Group; diagnostics: [] }
+  | { status: 'blocked'; object: null; diagnostics: PrintWallSolidDiagnostic[] }
+
+function finite(values: number[]): boolean {
+  return values.every(Number.isFinite)
+}
+
+function openingInterval(
+  wall: WallNode,
+  opening: PrintWallOpening,
+  length: number,
+  height: number,
+): { interval: OpeningInterval | null; diagnostic: PrintWallSolidDiagnostic | null } {
+  if (opening.wallId && opening.wallId !== wall.id) {
+    return {
+      interval: null,
+      diagnostic: {
+        severity: 'error',
+        code: 'invalid_wall_print_opening',
+        message: `Opening ${opening.id} is listed by wall ${wall.id} but references ${opening.wallId}.`,
+        nodeIds: [wall.id, opening.id].sort(),
+      },
+    }
+  }
+  if (opening.openingShape !== 'rectangle') {
+    return {
+      interval: null,
+      diagnostic: {
+        severity: 'error',
+        code: 'unsupported_wall_print_opening_shape',
+        message: `Opening ${opening.id} uses a ${opening.openingShape} profile that does not yet have a printable wall fixture.`,
+        nodeIds: [wall.id, opening.id].sort(),
+      },
+    }
+  }
+
+  const [centerX, centerY] = opening.position
+  const { width, height: openingHeight } = opening
+  if (
+    !finite([centerX, centerY, width, openingHeight]) ||
+    width <= DIMENSION_EPSILON ||
+    openingHeight <= DIMENSION_EPSILON
+  ) {
+    return {
+      interval: null,
+      diagnostic: {
+        severity: 'error',
+        code: 'invalid_wall_print_opening',
+        message: `Opening ${opening.id} has invalid printable dimensions.`,
+        nodeIds: [wall.id, opening.id].sort(),
+      },
+    }
+  }
+
+  const interval = {
+    node: opening,
+    left: centerX - width / 2,
+    right: centerX + width / 2,
+    bottom: centerY - openingHeight / 2,
+    top: centerY + openingHeight / 2,
+  }
+  if (
+    interval.left < -DIMENSION_EPSILON ||
+    interval.right > length + DIMENSION_EPSILON ||
+    interval.bottom < -DIMENSION_EPSILON ||
+    interval.top > height + DIMENSION_EPSILON ||
+    interval.left >= interval.right - DIMENSION_EPSILON ||
+    interval.bottom >= interval.top - DIMENSION_EPSILON
+  ) {
+    return {
+      interval: null,
+      diagnostic: {
+        severity: 'error',
+        code: 'invalid_wall_print_opening',
+        message: `Opening ${opening.id} extends outside printable wall ${wall.id}.`,
+        nodeIds: [wall.id, opening.id].sort(),
+      },
+    }
+  }
+
+  interval.left = THREE.MathUtils.clamp(interval.left, 0, length)
+  interval.right = THREE.MathUtils.clamp(interval.right, 0, length)
+  interval.bottom = THREE.MathUtils.clamp(interval.bottom, 0, height)
+  interval.top = THREE.MathUtils.clamp(interval.top, 0, height)
+  return { interval, diagnostic: null }
+}
+
+function collectOpenings(
+  wall: WallNode,
+  nodes: Record<string, AnyNode> | undefined,
+  options: PrintWallSolidOptions,
+  length: number,
+): { openings: OpeningInterval[]; diagnostics: PrintWallSolidDiagnostic[] } {
+  const openings: OpeningInterval[] = []
+  const diagnostics: PrintWallSolidDiagnostic[] = []
+
+  for (const childId of wall.children) {
+    const child = nodes?.[childId]
+    if (!child) {
+      diagnostics.push({
+        severity: 'error',
+        code: 'unresolved_wall_print_child',
+        message: `Wall ${wall.id} references unresolved child ${childId}.`,
+        nodeIds: [wall.id, childId].sort(),
+      })
+      continue
+    }
+    if (options.includedNodeIds && !options.includedNodeIds.has(child.id)) continue
+    if (child.type !== 'door' && child.type !== 'window') continue
+
+    const result = openingInterval(wall, child, length, options.effectiveHeight)
+    if (result.diagnostic) diagnostics.push(result.diagnostic)
+    if (result.interval) openings.push(result.interval)
+  }
+
+  return { openings, diagnostics }
+}
+
+function uniqueBreakpoints(values: number[]): number[] {
+  const sorted = [...values].sort((a, b) => a - b)
+  const result: number[] = []
+  for (const value of sorted) {
+    if (result.length === 0 || value - result[result.length - 1]! > DIMENSION_EPSILON) {
+      result.push(value)
+    }
+  }
+  return result
+}
+
+function mergedVerticalCuts(openings: OpeningInterval[], x: number): [number, number][] {
+  const intervals = openings
+    .filter((opening) => opening.left < x && opening.right > x)
+    .map((opening) => [opening.bottom, opening.top] as [number, number])
+    .sort((a, b) => a[0] - b[0])
+  const merged: [number, number][] = []
+
+  for (const interval of intervals) {
+    const previous = merged[merged.length - 1]
+    if (!previous || interval[0] > previous[1] + DIMENSION_EPSILON) {
+      merged.push([...interval])
+    } else {
+      previous[1] = Math.max(previous[1], interval[1])
+    }
+  }
+  return merged
+}
+
+function addSolid(
+  root: THREE.Group,
+  wallId: string,
+  index: number,
+  left: number,
+  right: number,
+  bottom: number,
+  top: number,
+  thickness: number,
+  wallLength: number,
+) {
+  if (right - left <= DIMENSION_EPSILON || top - bottom <= DIMENSION_EPSILON) return
+  const joinedLeft = Math.max(0, left - (left > DIMENSION_EPSILON ? SOLID_JOIN_OVERLAP : 0))
+  const joinedRight = Math.min(
+    wallLength,
+    right + (right < wallLength - DIMENSION_EPSILON ? SOLID_JOIN_OVERLAP : 0),
+  )
+  const box = new THREE.BoxGeometry(joinedRight - joinedLeft, top - bottom, thickness)
+  box.deleteAttribute('normal')
+  box.deleteAttribute('uv')
+  const geometry = mergeVertices(box, DIMENSION_EPSILON)
+  box.dispose()
+  geometry.computeVertexNormals()
+  const mesh = new THREE.Mesh(geometry)
+  mesh.name = `print-wall-solid-${index}`
+  mesh.position.set((joinedLeft + joinedRight) / 2, (bottom + top) / 2, 0)
+  mesh.userData = { pascalId: wallId }
+  root.add(mesh)
+}
+
+export function buildPrintableWallSolids(
+  node: WallNode,
+  options: PrintWallSolidOptions,
+  nodes?: Record<string, AnyNode>,
+): PrintWallSolidResult {
+  const dx = node.end[0] - node.start[0]
+  const dz = node.end[1] - node.start[1]
+  const length = Math.hypot(dx, dz)
+  const thickness = getWallThickness(node)
+  const diagnostics: PrintWallSolidDiagnostic[] = []
+
+  if (
+    !finite([
+      node.start[0],
+      node.start[1],
+      node.end[0],
+      node.end[1],
+      length,
+      thickness,
+      options.effectiveHeight,
+    ]) ||
+    length <= DIMENSION_EPSILON ||
+    thickness <= DIMENSION_EPSILON ||
+    options.effectiveHeight <= DIMENSION_EPSILON
+  ) {
+    diagnostics.push({
+      severity: 'error',
+      code: 'invalid_wall_print_dimensions',
+      message: `Wall ${node.id} has invalid printable length, thickness, or height.`,
+      nodeIds: [node.id],
+    })
+  }
+  if (Math.abs(node.curveOffset ?? 0) > DIMENSION_EPSILON) {
+    diagnostics.push({
+      severity: 'error',
+      code: 'unsupported_wall_print_curve',
+      message: `Curved wall ${node.id} does not yet have a canonical printable solid.`,
+      nodeIds: [node.id],
+    })
+  }
+  if (node.fillToTerrain) {
+    diagnostics.push({
+      severity: 'error',
+      code: 'unsupported_wall_print_terrain',
+      message: `Terrain-filled wall ${node.id} requires a terrain-aware printable base fixture.`,
+      nodeIds: [node.id],
+    })
+  }
+  if (diagnostics.length > 0) return { status: 'blocked', object: null, diagnostics }
+
+  const collected = collectOpenings(node, nodes, options, length)
+  diagnostics.push(...collected.diagnostics)
+  if (diagnostics.length > 0) return { status: 'blocked', object: null, diagnostics }
+
+  const root = new THREE.Group()
+  root.name = 'print-wall-solids'
+  root.userData = { pascalId: node.id }
+  root.position.set(node.start[0], 0, node.start[1])
+  root.rotation.y = -Math.atan2(dz, dx)
+
+  const breakpoints = uniqueBreakpoints([
+    0,
+    length,
+    ...collected.openings.flatMap((opening) => [opening.left, opening.right]),
+  ])
+  let solidIndex = 0
+  for (let index = 0; index < breakpoints.length - 1; index += 1) {
+    const left = breakpoints[index]!
+    const right = breakpoints[index + 1]!
+    if (right - left <= DIMENSION_EPSILON) continue
+    const cuts = mergedVerticalCuts(collected.openings, (left + right) / 2)
+    let bottom = 0
+    for (const [cutBottom, cutTop] of cuts) {
+      addSolid(root, node.id, solidIndex, left, right, bottom, cutBottom, thickness, length)
+      if (cutBottom - bottom > DIMENSION_EPSILON) solidIndex += 1
+      bottom = Math.max(bottom, cutTop)
+    }
+    addSolid(
+      root,
+      node.id,
+      solidIndex,
+      left,
+      right,
+      bottom,
+      options.effectiveHeight,
+      thickness,
+      length,
+    )
+    if (options.effectiveHeight - bottom > DIMENSION_EPSILON) solidIndex += 1
+  }
+
+  if (root.children.length === 0) {
+    return {
+      status: 'blocked',
+      object: null,
+      diagnostics: [
+        {
+          severity: 'error',
+          code: 'invalid_wall_print_opening',
+          message: `Openings remove all printable material from wall ${node.id}.`,
+          nodeIds: [node.id, ...collected.openings.map((opening) => opening.node.id)].sort(),
+        },
+      ],
+    }
+  }
+
+  return { status: 'ready', object: root, diagnostics: [] }
+}

package/src/lib/rigid-plan-svg-transform.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from 'bun:test'
+import { resolveAttachmentPreviewRotation, rigidPlanSvgTransform } from './rigid-plan-svg-transform'
+
+describe('resolveAttachmentPreviewRotation', () => {
+  test('uses wall yaw only while attached and restores the free yaw after detaching', () => {
+    const freeRotation = Math.PI / 4
+
+    expect(resolveAttachmentPreviewRotation(freeRotation, 0)).toBe(0)
+    expect(resolveAttachmentPreviewRotation(freeRotation, null)).toBe(freeRotation)
+  })
+})
+
+describe('rigidPlanSvgTransform', () => {
+  test('preserves the existing translation-only preview when yaw is unchanged', () => {
+    expect(
+      rigidPlanSvgTransform({
+        from: [1, 2],
+        fromRotation: 0,
+        to: [1.5, 3],
+        toRotation: 0,
+      }),
+    ).toBe('translate(0.5 1)')
+  })
+
+  test('rotates the plan entry around the moved node origin while translating it', () => {
+    expect(
+      rigidPlanSvgTransform({
+        from: [1, 2],
+        fromRotation: Math.PI / 2,
+        to: [3, 4],
+        toRotation: 0,
+      }),
+    ).toBe('translate(3 4) rotate(90) translate(-1 -2)')
+  })
+})

package/src/lib/rigid-plan-svg-transform.ts

@@ -0,0 +1,24 @@
+export function resolveAttachmentPreviewRotation(
+  freeRotation: number,
+  attachmentRotation: number | null,
+): number {
+  return attachmentRotation ?? freeRotation
+}
+
+export function rigidPlanSvgTransform({
+  from,
+  fromRotation,
+  to,
+  toRotation,
+}: {
+  from: readonly [number, number]
+  fromRotation: number
+  to: readonly [number, number]
+  toRotation: number
+}): string {
+  const rotationDegrees = (-(toRotation - fromRotation) * 180) / Math.PI
+  if (Math.abs(rotationDegrees) < 1e-10) {
+    return `translate(${to[0] - from[0]} ${to[1] - from[1]})`
+  }
+  return `translate(${to[0]} ${to[1]}) rotate(${rotationDegrees}) translate(${-from[0]} ${-from[1]})`
+}

package/src/lib/scene.ts

@@ -155,11 +155,18 @@ function getEditorUiStateForRestoredSelection(
   fallbackUiState: PersistedEditorUiState,
 ): PersistedEditorUiState {
   if (!selection.levelId) {
+    const mode = fallbackUiState.phase === 'site' ? fallbackUiState.mode : 'select'
     return {
       ...fallbackUiState,
       phase: 'site',
-      mode: fallbackUiState.phase === 'site' ? fallbackUiState.mode : 'select',
-      tool: null,
+      toolMode:
+        mode === 'build'
+          ? { mode, tool: 'property-line' }
+          : mode === 'terrain-sculpt'
+            ? { mode }
+            : { mode: 'select' },
+      mode,
+      tool: mode === 'build' ? 'property-line' : null,
       structureLayer: 'elements',
       catalogCategory: null,
     }
@@ -169,6 +176,7 @@ function getEditorUiStateForRestoredSelection(
     return {
       ...fallbackUiState,
       phase: 'structure',
+      toolMode: { mode: 'select' },
       mode: 'select',
       tool: null,
       structureLayer: 'zones',
@@ -192,6 +200,7 @@ function getEditorUiStateForRestoredSelection(
   return {
     ...fallbackUiState,
     phase: shouldRestoreFurnishPhase ? 'furnish' : 'structure',
+    toolMode: { mode: 'select' },
     mode: 'select',
     tool: null,
     structureLayer: 'elements',
@@ -304,14 +313,14 @@ export function syncEditorSelectionFromCurrentScene() {
         // SelectionPath expects branded ids. The runtime values match the
         // brand; the cast bridges the static gap.
         useViewer.getState().setSelection(restoredSelection as never)
-        useEditor.setState(
+        restoreEditorUiState(
           restoredEditorUiState.phase === 'site'
             ? (selectionDrivenEditorUiState ?? restoredEditorUiState)
             : restoredEditorUiState,
         )
       } else if (restoredEditorUiState.phase === 'site') {
         useViewer.getState().resetSelection()
-        useEditor.setState(restoredEditorUiState)
+        restoreEditorUiState(restoredEditorUiState)
       } else {
         useViewer.getState().setSelection({
           buildingId: firstBuilding.id,
@@ -319,7 +328,7 @@ export function syncEditorSelectionFromCurrentScene() {
           selectedIds: [],
           zoneId: null,
         })
-        useEditor.setState(restoredEditorUiState)
+        restoreEditorUiState(restoredEditorUiState)
       }
       return
     }
@@ -327,7 +336,7 @@ export function syncEditorSelectionFromCurrentScene() {
     if (restoredSelection) {
       useViewer.getState().setSelection(restoredSelection as never)
       if (selectionDrivenEditorUiState) {
-        useEditor.setState(selectionDrivenEditorUiState)
+        restoreEditorUiState(selectionDrivenEditorUiState)
       }
       return
     }
@@ -351,6 +360,12 @@ export function syncEditorSelectionFromCurrentScene() {
   }
 }
 
+function restoreEditorUiState(state: PersistedEditorUiState) {
+  const { toolMode, mode: _mode, tool: _tool, ...rest } = state
+  useEditor.setState(rest)
+  useEditor.getState().armToolMode(toolMode)
+}
+
 function resetEditorInteractionState() {
   useViewer.getState().setHoveredId(null)
   useViewer.getState().resetSelection()
@@ -362,8 +377,6 @@ function resetEditorInteractionState() {
   sceneRegistry.clear()
   useEditor.setState({
     phase: 'site',
-    mode: 'select',
-    tool: null,
     structureLayer: 'elements',
     catalogCategory: null,
     selectedItem: null,
@@ -372,6 +385,7 @@ function resetEditorInteractionState() {
     hoveredHole: null,
     isPreviewMode: false,
   })
+  useEditor.getState().armToolMode({ mode: 'select' })
 }
 
 function hasUsableSceneGraph(sceneGraph?: SceneGraph | null): sceneGraph is SceneGraph {

package/src/lib/selection-routing.test.ts

@@ -1,6 +1,15 @@
 import { describe, expect, test } from 'bun:test'
-import { type AnyNode, emitter, nodeRegistry, registerNode } from '@pascal-app/core'
+import {
+  type AnyNode,
+  BlockNode,
+  emitter,
+  nodeRegistry,
+  registerNode,
+  useScene,
+} from '@pascal-app/core'
+import { useViewer } from '@pascal-app/viewer'
 import { z } from 'zod'
+import useEditor from '../store/use-editor'
 import {
   emitCanvasNodeSelection,
   resolveCanvasSelectionNode,
@@ -71,6 +80,64 @@ describe('emitCanvasNodeSelection', () => {
     emitter.off('selection:canvas-node-click', onSelection)
     expect(received).toEqual([node])
   })
+
+  test('deletes an accepted floorplan node when Delete mode is active', () => {
+    const node = BlockNode.parse({ id: 'block_floorplan-delete-target' })
+    const previousToolMode = useEditor.getState().toolMode
+    const previousScene = useScene.getState()
+    const previousSelection = useViewer.getState().selection
+    const received: AnyNode[] = []
+    const listener = (selectedNode: AnyNode) => received.push(selectedNode)
+
+    emitter.on('selection:canvas-node-click', listener)
+
+    try {
+      useEditor.getState().armToolMode({ mode: 'delete' })
+      useScene.setState({
+        nodes: { [node.id]: node },
+        rootNodeIds: [node.id],
+        readOnly: false,
+      })
+      useViewer.getState().setSelection({ selectedIds: [node.id] })
+
+      emitCanvasNodeSelection(node)
+
+      expect(useScene.getState().nodes[node.id]).toBeUndefined()
+      expect(useViewer.getState().selection.selectedIds).toEqual([])
+      expect(received).toEqual([])
+    } finally {
+      emitter.off('selection:canvas-node-click', listener)
+      useEditor.getState().armToolMode(previousToolMode)
+      useScene.setState(previousScene)
+      useViewer.setState({ selection: previousSelection })
+    }
+  })
+
+  test('preserves a floorplan node and its selection when the scene is read-only', () => {
+    const node = BlockNode.parse({ id: 'block_floorplan-read-only-target' })
+    const previousToolMode = useEditor.getState().toolMode
+    const previousScene = useScene.getState()
+    const previousSelection = useViewer.getState().selection
+
+    try {
+      useEditor.getState().armToolMode({ mode: 'delete' })
+      useScene.setState({
+        nodes: { [node.id]: node },
+        rootNodeIds: [node.id],
+        readOnly: true,
+      })
+      useViewer.getState().setSelection({ selectedIds: [node.id] })
+
+      emitCanvasNodeSelection(node)
+
+      expect(useScene.getState().nodes[node.id]).toEqual(node)
+      expect(useViewer.getState().selection.selectedIds).toEqual([node.id])
+    } finally {
+      useEditor.getState().armToolMode(previousToolMode)
+      useScene.setState(previousScene)
+      useViewer.setState({ selection: previousSelection })
+    }
+  })
 })
 
 describe('selectionModifiersFromEvent', () => {
@@ -287,6 +354,43 @@ describe('resolveCanvasSelectionNode', () => {
       }),
     ).toBe(proxyGroup)
   })
+
+  test('routes proxied lean-to roof children to the owning extension', () => {
+    const leanTo = {
+      id: 'lean_to_1',
+      type: 'lean-to-extension',
+      metadata: {},
+    } as unknown as AnyNode
+    const roof = {
+      id: 'roof_lean_to',
+      type: 'roof',
+      parentId: leanTo.id,
+      metadata: {
+        managedByLeanTo: leanTo.id,
+        leanToRole: 'roof',
+        nodeSelectionProxyId: leanTo.id,
+      },
+    } as unknown as AnyNode
+    const segment = {
+      id: 'rseg_lean_to',
+      type: 'roof-segment',
+      parentId: roof.id,
+      metadata: {
+        managedByLeanTo: leanTo.id,
+        leanToRole: 'roof-segment',
+        nodeSelectionProxyId: leanTo.id,
+      },
+    } as unknown as AnyNode
+
+    const nodes = {
+      [leanTo.id]: leanTo,
+      [roof.id]: roof,
+      [segment.id]: segment,
+    }
+
+    expect(resolveCanvasSelectionNode({ node: roof, nodes, selectedIds: [] })).toBe(leanTo)
+    expect(resolveCanvasSelectionNode({ node: segment, nodes, selectedIds: [] })).toBe(leanTo)
+  })
 })
 
 describe('shouldPreserveSelectedRoofHostTarget', () => {

package/src/lib/selection-routing.ts

@@ -1,10 +1,15 @@
 import {
   type AnyNode,
+  type AnyNodeId,
   emitter,
   type ItemNode,
   nodeRegistry,
   resolveSelectionProxyId,
+  useScene,
 } from '@pascal-app/core'
+import { useViewer } from '@pascal-app/viewer'
+import useEditor from '../store/use-editor'
+import { emitDeleteSFX } from './sfx-bus'
 
 export type SelectionModifierKeys = {
   meta: boolean
@@ -20,6 +25,20 @@ export type NodeSelectionTarget = {
 }
 
 export function emitCanvasNodeSelection(node: AnyNode): void {
+  if (useEditor.getState().mode === 'delete') {
+    const scene = useScene.getState()
+    if (scene.readOnly) return
+
+    emitDeleteSFX(node.type)
+    scene.deleteNode(node.id as AnyNodeId)
+    if (node.parentId) scene.dirtyNodes.add(node.parentId as AnyNodeId)
+    useViewer.getState().setSelection({ selectedIds: [] })
+    if (useViewer.getState().hoveredId === node.id) {
+      useViewer.setState({ hoveredId: null })
+    }
+    return
+  }
+
   emitter.emit('selection:canvas-node-click', node)
 }
 

package/src/lib/sfx-bus.ts

@@ -27,6 +27,7 @@ type SFXEvents = {
   'sfx:menu-hover': undefined
   'sfx:menu-click': undefined
   'sfx:paint-apply': undefined
+  'sfx:success': undefined
   'sfx:terrain-sculpt-start': TerrainVerb
   'sfx:terrain-sculpt-stop': undefined
 }
@@ -56,6 +57,7 @@ const handleSnapshotCapture = () => playSFX('snapshotCapture')
 const handleMenuHover = () => playSFX('menuHover')
 const handleMenuClick = () => playSFX('menuClick')
 const handlePaintApply = () => playSFX('paintApply')
+const handleSuccess = () => playSFX('success')
 const TERRAIN_LOOP_BY_VERB = {
   raise: 'terrainRaise',
   lower: 'terrainLower',
@@ -86,6 +88,7 @@ export function initSFXBus() {
   sfxEmitter.on('sfx:menu-hover', handleMenuHover)
   sfxEmitter.on('sfx:menu-click', handleMenuClick)
   sfxEmitter.on('sfx:paint-apply', handlePaintApply)
+  sfxEmitter.on('sfx:success', handleSuccess)
   sfxEmitter.on('sfx:terrain-sculpt-start', handleTerrainSculptStart)
   sfxEmitter.on('sfx:terrain-sculpt-stop', handleTerrainSculptStop)
   unsubscribeAudio = useAudio.subscribe(updateSFXVolumes)
@@ -106,6 +109,7 @@ export function disposeSFXBus() {
     sfxEmitter.off('sfx:menu-hover', handleMenuHover)
     sfxEmitter.off('sfx:menu-click', handleMenuClick)
     sfxEmitter.off('sfx:paint-apply', handlePaintApply)
+    sfxEmitter.off('sfx:success', handleSuccess)
     sfxEmitter.off('sfx:terrain-sculpt-start', handleTerrainSculptStart)
     sfxEmitter.off('sfx:terrain-sculpt-stop', handleTerrainSculptStop)
     unsubscribeAudio?.()

package/src/lib/sfx-player.ts

@@ -112,6 +112,14 @@ export const SFX: Record<string, SFXConfig> = {
     volumeRange: [0.85, 1.0],
     minIntervalMs: 60,
   },
+  // A three-second jingle for finishing something, not a click cue. No pitch or
+  // volume jitter — a fanfare that lands a semitone off reads as broken rather
+  // than as varied — and a gap longer than the sound itself, so two milestones
+  // that land together play once instead of phasing over each other.
+  success: {
+    src: '/audios/sfx/success.mp3',
+    minIntervalMs: 3_000,
+  },
 } as const
 
 export type SFXName = keyof typeof SFX