@pascal-app/editor 0.9.2 → 1.0.0-beta.2

package/src/lib/scene-clipboard.ts

@@ -2,8 +2,12 @@ import {
   AnyNode,
   type AnyNodeId,
   generateId,
+  generateSceneMaterialId,
   type LevelNode,
+  nodeRegistry,
   remapMeasurementReferences,
+  SceneMaterial,
+  type SceneMaterialId,
   type StairNode,
   useScene,
 } from '@pascal-app/core'
@@ -11,18 +15,25 @@ import { useViewer } from '@pascal-app/viewer'
 
 type ClipboardPayload = {
   copiedAt: number
+  materials: SceneMaterial[]
   nodes: AnyNode[]
   rootIds: AnyNodeId[]
 }
 
-type PasteResult = {
+export type PasteResult = {
+  createdMaterialIds: SceneMaterialId[]
   pastedIds: AnyNodeId[]
   skippedIds: AnyNodeId[]
 }
 
+const SYSTEM_CLIPBOARD_KIND = 'pascal.scene-nodes'
+const SYSTEM_CLIPBOARD_VERSION = 1
+
 const COPYABLE_ROOT_TYPES = new Set<AnyNode['type']>([
   'wall',
   'fence',
+  'door',
+  'window',
   'column',
   'item',
   'slab',
@@ -37,6 +48,7 @@ const COPYABLE_ROOT_TYPES = new Set<AnyNode['type']>([
 ])
 
 let clipboardPayload: ClipboardPayload | null = null
+let pendingSystemClipboardWrite: Promise<boolean> | null = null
 const subscribers = new Set<() => void>()
 
 function notifySubscribers() {
@@ -97,10 +109,29 @@ function hasSelectedAncestor(
   return false
 }
 
-function isLevelChildRoot(nodes: Record<AnyNodeId, AnyNode>, node: AnyNode) {
+function isClipboardRoot(
+  nodes: Record<AnyNodeId, AnyNode>,
+  node: AnyNode,
+  allowHostedOpening: boolean,
+) {
   const parentId = node.parentId as AnyNodeId | null
   if (!parentId) return true
-  return nodes[parentId]?.type === 'level'
+  const parent = nodes[parentId]
+  if (parent?.type === 'level') return true
+  if (
+    allowHostedOpening &&
+    (node.type === 'door' || node.type === 'window') &&
+    (parent?.type === 'wall' || parent?.type === 'roof-segment')
+  ) {
+    return true
+  }
+  return parent?.type === 'building' && nodeRegistry.get(node.type)?.floorplanScope === 'building'
+}
+
+function isCopyableRootType(node: AnyNode) {
+  if (COPYABLE_ROOT_TYPES.has(node.type)) return true
+  const definition = nodeRegistry.get(node.type)
+  return !!definition && definition.capabilities?.duplicable !== false
 }
 
 function getPromotedCabinetRunId(
@@ -160,14 +191,28 @@ function remapNodeReferences(
   oldId: AnyNodeId,
   targetLevel: LevelNode,
   idMap: Map<AnyNodeId, AnyNodeId>,
+  materialIdMap: Map<SceneMaterialId, SceneMaterialId>,
   rootIds: Set<AnyNodeId>,
   nodes: Record<AnyNodeId, AnyNode>,
 ) {
-  const clone = JSON.parse(JSON.stringify(node)) as AnyNode
+  const clone = remapSceneMaterialReferences(
+    JSON.parse(JSON.stringify(node)),
+    materialIdMap,
+  ) as AnyNode
   ;(clone as Record<string, unknown>).id = idMap.get(oldId)
 
   if (rootIds.has(oldId)) {
-    clone.parentId = targetLevel.id
+    const buildingId = targetLevel.parentId as AnyNodeId | null
+    clone.parentId =
+      nodeRegistry.get(node.type)?.floorplanScope === 'building' &&
+      buildingId &&
+      nodes[buildingId]?.type === 'building'
+        ? buildingId
+        : targetLevel.id
+    if (clone.type === 'door' || clone.type === 'window') {
+      delete clone.roofSegmentId
+      delete clone.roofFace
+    }
   } else if (clone.parentId && typeof clone.parentId === 'string') {
     clone.parentId = idMap.get(clone.parentId as AnyNodeId) ?? clone.parentId
   }
@@ -208,9 +253,47 @@ function remapNodeReferences(
   return AnyNode.parse(clone)
 }
 
+function remapSceneMaterialReferences(
+  value: unknown,
+  materialIdMap: Map<SceneMaterialId, SceneMaterialId>,
+): unknown {
+  if (typeof value === 'string' && value.startsWith('scene:')) {
+    const oldId = value.slice('scene:'.length) as SceneMaterialId
+    const nextId = materialIdMap.get(oldId)
+    return nextId ? `scene:${nextId}` : value
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => remapSceneMaterialReferences(entry, materialIdMap))
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [
+        key,
+        remapSceneMaterialReferences(entry, materialIdMap),
+      ]),
+    )
+  }
+  return value
+}
+
+function collectReferencedSceneMaterialIds(value: unknown, ids: Set<SceneMaterialId>) {
+  if (typeof value === 'string' && value.startsWith('scene:')) {
+    ids.add(value.slice('scene:'.length) as SceneMaterialId)
+    return
+  }
+  if (Array.isArray(value)) {
+    for (const entry of value) collectReferencedSceneMaterialIds(entry, ids)
+    return
+  }
+  if (value && typeof value === 'object') {
+    for (const entry of Object.values(value)) collectReferencedSceneMaterialIds(entry, ids)
+  }
+}
+
 function buildClipboardPayload(ids: AnyNodeId[]): ClipboardPayload | null {
   const scene = useScene.getState()
   const selectedIdSet = new Set(ids)
+  const allowHostedOpening = ids.length === 1
   const promotedIds = ids.map((id) => {
     const node = scene.nodes[id]
     return node ? (getPromotedCabinetRunId(scene.nodes, node, selectedIdSet) ?? id) : id
@@ -219,8 +302,8 @@ function buildClipboardPayload(ids: AnyNodeId[]): ClipboardPayload | null {
     const node = scene.nodes[id]
     return (
       node &&
-      COPYABLE_ROOT_TYPES.has(node.type) &&
-      isLevelChildRoot(scene.nodes, node) &&
+      isCopyableRootType(node) &&
+      isClipboardRoot(scene.nodes, node, allowHostedOpening) &&
       !hasSelectedAncestor(scene.nodes, id, selectedIdSet)
     )
   })
@@ -234,16 +317,99 @@ function buildClipboardPayload(ids: AnyNodeId[]): ClipboardPayload | null {
     collectSubtreeIds(scene.nodes, rootId, subtreeIds)
   }
 
+  const copiedNodes = [...subtreeIds]
+    .map((id) => scene.nodes[id])
+    .filter((node): node is AnyNode => !!node)
+    .map((node) => JSON.parse(JSON.stringify(node)) as AnyNode)
+  const materialIds = new Set<SceneMaterialId>()
+  collectReferencedSceneMaterialIds(copiedNodes, materialIds)
+
   return {
     copiedAt: Date.now(),
-    nodes: [...subtreeIds]
-      .map((id) => scene.nodes[id])
-      .filter((node): node is AnyNode => !!node)
-      .map((node) => JSON.parse(JSON.stringify(node)) as AnyNode),
+    materials: [...materialIds]
+      .map((id) => scene.materials[id])
+      .filter((material): material is SceneMaterial => !!material)
+      .map((material) => JSON.parse(JSON.stringify(material)) as SceneMaterial),
+    nodes: copiedNodes,
     rootIds,
   }
 }
 
+function serializeClipboardPayload(payload: ClipboardPayload) {
+  return JSON.stringify({
+    kind: SYSTEM_CLIPBOARD_KIND,
+    version: SYSTEM_CLIPBOARD_VERSION,
+    payload,
+  })
+}
+
+function parseClipboardPayload(text: string): ClipboardPayload | null {
+  try {
+    const envelope = JSON.parse(text) as {
+      kind?: unknown
+      payload?: unknown
+      version?: unknown
+    }
+    if (
+      envelope.kind !== SYSTEM_CLIPBOARD_KIND ||
+      envelope.version !== SYSTEM_CLIPBOARD_VERSION ||
+      !envelope.payload ||
+      typeof envelope.payload !== 'object'
+    ) {
+      return null
+    }
+
+    const candidate = envelope.payload as {
+      copiedAt?: unknown
+      materials?: unknown
+      nodes?: unknown
+      rootIds?: unknown
+    }
+    if (
+      typeof candidate.copiedAt !== 'number' ||
+      !Array.isArray(candidate.nodes) ||
+      !Array.isArray(candidate.rootIds) ||
+      !candidate.rootIds.every((id) => typeof id === 'string')
+    ) {
+      return null
+    }
+
+    const nodes = candidate.nodes.map((node) => AnyNode.safeParse(node))
+    if (nodes.some((result) => !result.success)) return null
+    const materials = Array.isArray(candidate.materials)
+      ? candidate.materials.map((material) => SceneMaterial.safeParse(material))
+      : []
+    if (materials.some((result) => !result.success)) return null
+
+    const parsedNodes = nodes.filter((result) => result.success).map((result) => result.data)
+    const nodeIds = new Set(parsedNodes.map((node) => node.id))
+    const rootIds = candidate.rootIds as AnyNodeId[]
+    if (rootIds.length === 0 || rootIds.some((id) => !nodeIds.has(id))) return null
+
+    return {
+      copiedAt: candidate.copiedAt,
+      materials: materials.filter((result) => result.success).map((result) => result.data),
+      nodes: parsedNodes,
+      rootIds,
+    }
+  } catch {
+    return null
+  }
+}
+
+function writeSystemClipboard(payload: ClipboardPayload) {
+  if (typeof navigator === 'undefined' || !navigator.clipboard?.writeText) {
+    pendingSystemClipboardWrite = null
+    return
+  }
+  pendingSystemClipboardWrite = navigator.clipboard
+    .writeText(serializeClipboardPayload(payload))
+    .then(
+      () => true,
+      () => false,
+    )
+}
+
 export function copySelectedNodesToEditorClipboard(selectedIds?: AnyNodeId[]) {
   const ids = selectedIds ?? (useViewer.getState().selection.selectedIds as AnyNodeId[])
   const payload = buildClipboardPayload(ids)
@@ -251,7 +417,33 @@ export function copySelectedNodesToEditorClipboard(selectedIds?: AnyNodeId[]) {
 
   clipboardPayload = payload
   notifySubscribers()
+  writeSystemClipboard(payload)
+
+  return true
+}
+
+export async function readEditorClipboardFromSystem() {
+  const pendingWrite = pendingSystemClipboardWrite
+  pendingSystemClipboardWrite = null
+  if (pendingWrite && !(await pendingWrite)) {
+    return hasEditorClipboard()
+  }
+
+  if (typeof navigator === 'undefined' || !navigator.clipboard?.readText) {
+    return hasEditorClipboard()
+  }
 
+  let text: string
+  try {
+    text = await navigator.clipboard.readText()
+  } catch {
+    return hasEditorClipboard()
+  }
+
+  const payload = parseClipboardPayload(text)
+  if (!payload) return false
+  clipboardPayload = payload
+  notifySubscribers()
   return true
 }
 
@@ -275,6 +467,13 @@ export function pasteEditorClipboardToLevel(targetLevelId?: AnyNodeId): PasteRes
   return applyClipboardPayloadToLevel(clipboardPayload, targetLevelId)
 }
 
+export async function pasteSystemEditorClipboardToLevel(
+  targetLevelId?: AnyNodeId,
+): Promise<PasteResult | null> {
+  if (!(await readEditorClipboardFromSystem())) return null
+  return pasteEditorClipboardToLevel(targetLevelId)
+}
+
 function applyClipboardPayloadToLevel(
   payload: ClipboardPayload,
   targetLevelId?: AnyNodeId,
@@ -284,10 +483,23 @@ function applyClipboardPayloadToLevel(
 
   const scene = useScene.getState()
   const idMap = new Map<AnyNodeId, AnyNodeId>()
+  const materialIdMap = new Map<SceneMaterialId, SceneMaterialId>()
+  const materialsToCreate: SceneMaterial[] = []
 
   for (const node of payload.nodes) {
     idMap.set(node.id as AnyNodeId, generateId(extractIdPrefix(node.id)) as AnyNodeId)
   }
+  for (const material of payload.materials) {
+    const oldId = material.id as SceneMaterialId
+    const existing = scene.materials[oldId]
+    if (existing && JSON.stringify(existing) === JSON.stringify(material)) {
+      materialIdMap.set(oldId, oldId)
+      continue
+    }
+    const nextId = existing ? generateSceneMaterialId() : oldId
+    materialIdMap.set(oldId, nextId)
+    materialsToCreate.push({ ...material, id: nextId })
+  }
 
   const rootIdSet = new Set(payload.rootIds)
   const pastedNodes: AnyNode[] = []
@@ -296,7 +508,15 @@ function applyClipboardPayloadToLevel(
   for (const node of payload.nodes) {
     try {
       pastedNodes.push(
-        remapNodeReferences(node, node.id as AnyNodeId, targetLevel, idMap, rootIdSet, scene.nodes),
+        remapNodeReferences(
+          node,
+          node.id as AnyNodeId,
+          targetLevel,
+          idMap,
+          materialIdMap,
+          rootIdSet,
+          scene.nodes,
+        ),
       )
     } catch (error) {
       console.error('Failed to paste copied node', node.id, error)
@@ -305,9 +525,12 @@ function applyClipboardPayloadToLevel(
   }
 
   if (pastedNodes.length === 0) {
-    return { pastedIds: [], skippedIds }
+    return { createdMaterialIds: [], pastedIds: [], skippedIds }
   }
 
+  for (const material of materialsToCreate) {
+    scene.addSceneMaterial(material)
+  }
   scene.createNodes(
     pastedNodes.map((node) => ({
       node,
@@ -326,6 +549,7 @@ function applyClipboardPayloadToLevel(
   })
 
   return {
+    createdMaterialIds: materialsToCreate.map((material) => material.id as SceneMaterialId),
     pastedIds: pastedRootIds,
     skippedIds,
   }

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

@@ -1,7 +1,8 @@
 import { describe, expect, test } from 'bun:test'
-import { type AnyNode, nodeRegistry, registerNode } from '@pascal-app/core'
+import { type AnyNode, emitter, nodeRegistry, registerNode } from '@pascal-app/core'
 import { z } from 'zod'
 import {
+  emitCanvasNodeSelection,
   resolveCanvasSelectionNode,
   resolveNodeSelectionTarget,
   resolveSelectedIdsForNodeClick,
@@ -47,6 +48,20 @@ describe('resolveSelectedIdsForNodeClick', () => {
   })
 })
 
+describe('emitCanvasNodeSelection', () => {
+  test('publishes the accepted canvas node once', () => {
+    const node = { id: 'wall_1', type: 'wall' } as unknown as AnyNode
+    const received: AnyNode[] = []
+    const onSelection = (selectedNode: AnyNode) => received.push(selectedNode)
+    emitter.on('selection:canvas-node-click', onSelection)
+
+    emitCanvasNodeSelection(node)
+
+    emitter.off('selection:canvas-node-click', onSelection)
+    expect(received).toEqual([node])
+  })
+})
+
 describe('selectionModifiersFromEvent', () => {
   test('falls back to tracked modifier state when the click event omits keys', () => {
     expect(selectionModifiersFromEvent({}, { meta: false, ctrl: true, shift: false })).toEqual({

package/src/lib/selection-routing.ts

@@ -1,5 +1,6 @@
 import {
   type AnyNode,
+  emitter,
   type ItemNode,
   nodeRegistry,
   resolveSelectionProxyId,
@@ -16,6 +17,10 @@ export type NodeSelectionTarget = {
   structureLayer?: 'zones' | 'elements'
 }
 
+export function emitCanvasNodeSelection(node: AnyNode): void {
+  emitter.emit('selection:canvas-node-click', node)
+}
+
 function shouldBypassSelectionProxy(node: AnyNode, target: AnyNode): boolean {
   if (node.id === target.id) return false
   // Kind-declared bypass (`def.selectionProxy.bypassDirectPick`): the kind

package/src/lib/sfx-bus.ts

@@ -1,5 +1,14 @@
+import type { TerrainVerb } from '@pascal-app/core'
 import mitt from 'mitt'
-import { disposeSFX, playSFX } from './sfx-player'
+import useAudio from '../store/use-audio'
+import {
+  disposeSFX,
+  type LoopSFXName,
+  playSFX,
+  startLoopSFX,
+  stopLoopSFX,
+  updateSFXVolumes,
+} from './sfx-player'
 
 /**
  * SFX-specific events that tools can trigger
@@ -18,8 +27,14 @@ type SFXEvents = {
   'sfx:menu-hover': undefined
   'sfx:menu-click': undefined
   'sfx:paint-apply': undefined
+  'sfx:terrain-sculpt-start': TerrainVerb
+  'sfx:terrain-sculpt-stop': undefined
 }
 
+type TriggerSFXEvent = {
+  [Event in keyof SFXEvents]: SFXEvents[Event] extends undefined ? Event : never
+}[keyof SFXEvents]
+
 /**
  * Dedicated event emitter for SFX
  * Tools should use this to trigger sound effects
@@ -41,6 +56,15 @@ const handleSnapshotCapture = () => playSFX('snapshotCapture')
 const handleMenuHover = () => playSFX('menuHover')
 const handleMenuClick = () => playSFX('menuClick')
 const handlePaintApply = () => playSFX('paintApply')
+const TERRAIN_LOOP_BY_VERB = {
+  raise: 'terrainRaise',
+  lower: 'terrainLower',
+  flatten: 'terrainFlatten',
+  smooth: 'terrainSmooth',
+} as const satisfies Record<TerrainVerb, LoopSFXName>
+const handleTerrainSculptStart = (verb: TerrainVerb) => startLoopSFX(TERRAIN_LOOP_BY_VERB[verb])
+const handleTerrainSculptStop = () => stopLoopSFX()
+let unsubscribeAudio: (() => void) | null = null
 
 /**
  * Initialize SFX Bus - connects SFX events to actual sound playback.
@@ -62,6 +86,9 @@ export function initSFXBus() {
   sfxEmitter.on('sfx:menu-hover', handleMenuHover)
   sfxEmitter.on('sfx:menu-click', handleMenuClick)
   sfxEmitter.on('sfx:paint-apply', handlePaintApply)
+  sfxEmitter.on('sfx:terrain-sculpt-start', handleTerrainSculptStart)
+  sfxEmitter.on('sfx:terrain-sculpt-stop', handleTerrainSculptStop)
+  unsubscribeAudio = useAudio.subscribe(updateSFXVolumes)
 }
 
 export function disposeSFXBus() {
@@ -79,6 +106,10 @@ export function disposeSFXBus() {
     sfxEmitter.off('sfx:menu-hover', handleMenuHover)
     sfxEmitter.off('sfx:menu-click', handleMenuClick)
     sfxEmitter.off('sfx:paint-apply', handlePaintApply)
+    sfxEmitter.off('sfx:terrain-sculpt-start', handleTerrainSculptStart)
+    sfxEmitter.off('sfx:terrain-sculpt-stop', handleTerrainSculptStop)
+    unsubscribeAudio?.()
+    unsubscribeAudio = null
     sfxBusInitialized = false
   }
   disposeSFX()
@@ -89,7 +120,7 @@ export function disposeSFXBus() {
  * @example
  * triggerSFX('sfx:item-place')
  */
-export function triggerSFX(event: keyof SFXEvents) {
+export function triggerSFX(event: TriggerSFXEvent) {
   sfxEmitter.emit(event)
 }
 

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

@@ -3,15 +3,26 @@ import { afterAll, beforeEach, describe, expect, mock, test } from 'bun:test'
 type FakeContext = { id: string }
 
 let activeContext: FakeContext = { id: 'first' }
+let initialState: 'loaded' | 'loading' = 'loaded'
+let muted = false
 let throwOnPlay = false
 const instances: FakeHowl[] = []
 
 class FakeHowl {
-  stateValue: 'loaded' | 'unloaded' = 'loaded'
+  loadCallbacks: Array<() => void> = []
+  loop = false
+  src: string | undefined
+  stateValue: 'loaded' | 'loading' | 'unloaded' = initialState
   unloadCount = 0
   playCount = 0
+  stopCount = 0
+  fadeCalls: Array<[number, number, number, number | undefined]> = []
+  stereoCalls: Array<[number, number | undefined]> = []
+  volumeCalls: Array<[number, number | undefined]> = []
 
-  constructor(_options: unknown) {
+  constructor(options: { loop?: boolean; src?: string[] }) {
+    this.loop = options.loop ?? false
+    this.src = options.src?.[0]
     instances.push(this)
   }
 
@@ -21,7 +32,41 @@ class FakeHowl {
     return 1
   }
 
-  volume() {
+  volume(value: number, id?: number) {
+    this.volumeCalls.push([value, id])
+    return this
+  }
+
+  fade(from: number, to: number, duration: number, id?: number) {
+    this.fadeCalls.push([from, to, duration, id])
+    return this
+  }
+
+  once(event: string, callback: () => void) {
+    if (event === 'load') {
+      this.loadCallbacks.push(callback)
+      return this
+    }
+    callback()
+    return this
+  }
+
+  finishLoading() {
+    this.stateValue = 'loaded'
+    for (const callback of this.loadCallbacks.splice(0)) callback()
+  }
+
+  playing() {
+    return this.playCount > this.stopCount
+  }
+
+  stop() {
+    this.stopCount++
+    return this
+  }
+
+  stereo(value: number, id?: number) {
+    this.stereoCalls.push([value, id])
     return this
   }
 
@@ -49,16 +94,20 @@ const fakeHowler = {
 mock.module('howler', () => ({ Howl: FakeHowl, Howler: fakeHowler }))
 mock.module('../store/use-audio', () => ({
   default: {
-    getState: () => ({ masterVolume: 100, muted: false, sfxVolume: 100 }),
+    getState: () => ({ masterVolume: 100, muted, sfxVolume: 100 }),
+    subscribe: () => () => {},
   },
 }))
 
-const { disposeSFX, playSFX, preloadSFX } = await import('./sfx-player')
-const { disposeSFXBus, initSFXBus, triggerSFX } = await import('./sfx-bus')
+const { disposeSFX, playSFX, preloadSFX, startLoopSFX, stopLoopSFX, updateSFXVolumes } =
+  await import('./sfx-player')
+const { disposeSFXBus, initSFXBus, sfxEmitter, triggerSFX } = await import('./sfx-bus')
 
 beforeEach(() => {
   disposeSFXBus()
   activeContext = { id: 'first' }
+  initialState = 'loaded'
+  muted = false
   throwOnPlay = false
   instances.length = 0
 })
@@ -104,6 +153,16 @@ describe('SFX audio context lifecycle', () => {
     expect(instances.length).toBe(initialCount)
   })
 
+  test('does not queue spatial mutations while a sound is still loading', () => {
+    initialState = 'loading'
+
+    playSFX('itemDelete', { source: 'remote', stereo: 0.65, volumeMultiplier: 0.25 })
+
+    expect(instances.every((sound) => sound.playCount === 0)).toBe(true)
+    expect(instances.every((sound) => sound.stereoCalls.length === 0)).toBe(true)
+    expect(instances.every((sound) => sound.volumeCalls.length === 0)).toBe(true)
+  })
+
   test('disposes idempotently and recreates sounds after remount', () => {
     preloadSFX()
     const initialCount = instances.length
@@ -121,4 +180,87 @@ describe('SFX audio context lifecycle', () => {
 
     expect(() => triggerSFX('sfx:item-delete')).not.toThrow()
   })
+
+  test('applies bounded gain and stereo positioning to a remote cue', () => {
+    playSFX('itemDelete', { source: 'remote', stereo: 0.65, volumeMultiplier: 0.25 })
+
+    const played = instances.find((sound) => sound.playCount === 1)
+    expect(played?.volumeCalls[0]?.[0]).toBeGreaterThanOrEqual(0.225)
+    expect(played?.volumeCalls[0]?.[0]).toBeLessThanOrEqual(0.25)
+    expect(played?.stereoCalls).toEqual([[0.65, 1]])
+  })
+
+  test('keeps local feedback audible after the same remote cue', () => {
+    playSFX('itemDelete', { source: 'remote', volumeMultiplier: 0.25 })
+    playSFX('itemDelete')
+
+    expect(instances.reduce((total, sound) => total + sound.playCount, 0)).toBe(2)
+  })
+
+  test('keeps one faded terrain loop active and stops it on release', () => {
+    startLoopSFX('terrainRaise')
+    const raise = instances.find((sound) => sound.loop && sound.playCount === 1)
+
+    expect(raise?.volumeCalls[0]).toEqual([0, 1])
+    expect(raise?.fadeCalls).toEqual([[0, 0.2, 90, 1]])
+
+    startLoopSFX('terrainRaise')
+    expect(raise?.playCount).toBe(1)
+
+    stopLoopSFX()
+    expect(raise?.stopCount).toBe(1)
+    expect(raise?.fadeCalls.at(-1)).toEqual([0.2, 0, 90, 1])
+  })
+
+  test('maps each terrain verb to a distinct loop through the SFX bus', () => {
+    initSFXBus()
+
+    for (const verb of ['raise', 'lower', 'flatten', 'smooth'] as const) {
+      sfxEmitter.emit('sfx:terrain-sculpt-start', verb)
+      sfxEmitter.emit('sfx:terrain-sculpt-stop')
+    }
+
+    expect(
+      instances.filter((sound) => sound.loop && sound.playCount === 1).map((sound) => sound.src),
+    ).toEqual([
+      '/audios/sfx/terrain_raise.mp3',
+      '/audios/sfx/terrain_lower.mp3',
+      '/audios/sfx/terrain_flatten.mp3',
+      '/audios/sfx/terrain_smooth.mp3',
+    ])
+  })
+
+  test('fades an active terrain loop out when sound is muted', () => {
+    startLoopSFX('terrainLower')
+    const lower = instances.find((sound) => sound.loop && sound.playCount === 1)
+
+    muted = true
+    updateSFXVolumes()
+
+    expect(lower?.fadeCalls.at(-1)).toEqual([0.2, 0, 90, 1])
+    expect(lower?.stopCount).toBe(1)
+  })
+
+  test('starts a requested terrain loop when its asset finishes loading', () => {
+    initialState = 'loading'
+    startLoopSFX('terrainRaise')
+    const raise = instances.find((sound) => sound.src === '/audios/sfx/terrain_raise.mp3')
+
+    expect(raise?.playCount).toBe(0)
+
+    raise?.finishLoading()
+
+    expect(raise?.playCount).toBe(1)
+  })
+
+  test('does not start a terrain loop after the sculpt press was released', () => {
+    initialState = 'loading'
+    startLoopSFX('terrainLower')
+    const lower = instances.find((sound) => sound.src === '/audios/sfx/terrain_lower.mp3')
+
+    stopLoopSFX()
+    lower?.finishLoading()
+
+    expect(lower?.playCount).toBe(0)
+  })
 })