@pascal-app/editor 1.0.3 → 1.0.5

package/src/components/editor/bake-thumbnail.tsx

@@ -1,20 +1,194 @@
 'use client'
 
+import { type AnyNodeId, sceneRegistry, useInteractive, useScene } from '@pascal-app/core'
+import { evaluateRecipe } from '@pascal-app/core/procedural-items'
 import {
   computeHeroFraming,
   createSnapshotPipeline,
   GRID_LAYER,
+  type HeroFraming,
   heroCameraPose,
+  proceduralSlotMeshes,
+  setKeyLightDirectionOverride,
+  setProceduralEmission,
+  setSlotDefaultOverrides,
+  siteSurfaces,
   temporarilyHideNodeTypes,
+  temporarilyWithoutAmbiance,
   useSceneAtmosphere,
   useViewer,
 } from '@pascal-app/viewer'
 import { useThree } from '@react-three/fiber'
 import { useEffect, useRef } from 'react'
-import { PerspectiveCamera } from 'three'
-import type { WebGPURenderer } from 'three/webgpu'
+import {
+  Box3,
+  CanvasTexture,
+  type Material,
+  Mesh,
+  type Object3D,
+  PerspectiveCamera,
+  PlaneGeometry,
+  Vector3,
+} from 'three'
+import { MeshBasicNodeMaterial, ShadowNodeMaterial, type WebGPURenderer } from 'three/webgpu'
 import { EDITOR_LAYER } from '../../lib/constants'
 
+// The published-thumbnail look. One look for every project, independent of
+// the scene's own display preferences.
+const THUMBNAIL_FOV_DEG = 40
+const THUMBNAIL_PADDING = 1.12
+/** Roofless scenes look down into the rooms; roofed ones show the roofline. */
+const THUMBNAIL_ELEVATION_DEG = { roofed: 24, roofless: 35 }
+/** Key light relative to the hero camera: 30° off its azimuth, 45° up — both
+ *  facades lit, shadows raking across the ground. */
+const THUMBNAIL_KEY_AZIMUTH_OFFSET_DEG = 30
+const THUMBNAIL_KEY_ELEVATION_DEG = 45
+const THUMBNAIL_BACKDROP = { inner: '#FAFAFA', outer: '#E4E4E4' }
+const THUMBNAIL_SHADOW_CATCHER_OPACITY = 0.7
+/** Soft shade hugging the ground-floor walls so the building never floats. */
+const THUMBNAIL_WALL_CONTACT = { opacity: 0.5, spreadM: 0.9 }
+/** Unpainted walls render as smooth plaster rather than the screw-dotted
+ *  prepared-drywall default, which reads as unfinished at card size. */
+const THUMBNAIL_SLOT_DEFAULT_OVERRIDES = {
+  'library:concrete-drywall': 'library:concrete-plaster',
+} as const
+// Past the capture camera's far plane (1000): a catcher edge inside the frame
+// leaves an SSGI AO line along its depth discontinuity.
+const SHADOW_CATCHER_EXTENT = 4000
+
+/**
+ * Forces the published-thumbnail look on the bake page. Call before the scene
+ * builds (the finish swap applies as materials are created); the returned
+ * cleanup restores the declared finishes.
+ */
+export function prepareBakeThumbnailLook(): () => void {
+  const viewer = useViewer.getState()
+  viewer.setSceneTheme('studio')
+  viewer.setEdges('soft')
+  viewer.setShadows(true)
+  setSlotDefaultOverrides(THUMBNAIL_SLOT_DEFAULT_OVERRIDES)
+  return () => setSlotDefaultOverrides(null)
+}
+
+// Scene-ready fires before every system has finished its geometry: roofs
+// rebuild their merged mesh a few frames later (measured: Starter House ridge
+// 5.75 m at scene-ready, 6.24 m at capture), so a pose fit at scene-ready
+// clips the roof. Re-measure until the framing bounds hold still.
+async function settledHeroFraming() {
+  const boundsKey = (framing: HeroFraming | null) => {
+    if (!framing) return ''
+    const union = new Box3()
+    for (const box of framing.boxes) union.union(box)
+    return [...union.min.toArray(), ...union.max.toArray()].map((v) => v.toFixed(3)).join(',')
+  }
+  let framing = computeHeroFraming({ sitePlates: false })
+  let previous = boundsKey(framing)
+  let stableChecks = 0
+  for (let i = 0; i < 40 && stableChecks < 3; i++) {
+    await new Promise<void>((resolve) => setTimeout(resolve, 100))
+    framing = computeHeroFraming({ sitePlates: false })
+    const next = boundsKey(framing)
+    stableChecks = next === previous ? stableChecks + 1 : 0
+    previous = next
+  }
+  return framing
+}
+
+/**
+ * A soft contact shade on the ground along every ground-floor wall: the wall
+ * centrelines stroked onto a canvas in the building's facade axes, then
+ * blurred. Per wall rather than per footprint, so a walled lot shades its
+ * boundary walls and leaves the open courtyard clean.
+ */
+function wallContactShade(yaw: number, groundY: number): Mesh | null {
+  const u = new Vector3(Math.cos(yaw), 0, Math.sin(yaw))
+  const v = new Vector3(-Math.sin(yaw), 0, Math.cos(yaw))
+  const segments: Array<{ a: [number, number]; b: [number, number]; thickness: number }> = []
+  const point = new Vector3()
+  // A wall mesh sits at its start, rotated along the run: `start`/`end` are
+  // in its parent's (the level's) frame.
+  const toUv = (x: number, z: number, object: Object3D): [number, number] => {
+    point.set(x, 0, z)
+    if (object.parent) point.applyMatrix4(object.parent.matrixWorld)
+    return [point.dot(u), point.dot(v)]
+  }
+  for (const wallId of sceneRegistry.byType.wall ?? []) {
+    const object = sceneRegistry.nodes.get(wallId)
+    const node = useScene.getState().nodes[wallId as AnyNodeId]
+    if (!(object && node?.type === 'wall' && node.visible !== false)) continue
+    const bounds = new Box3().setFromObject(object)
+    if (bounds.isEmpty() || bounds.min.y > groundY + 0.5) continue
+    segments.push({
+      a: toUv(node.start[0], node.start[1], object),
+      b: toUv(node.end[0], node.end[1], object),
+      thickness: node.thickness ?? 0.2,
+    })
+  }
+  if (segments.length === 0) return null
+
+  const { spreadM, opacity } = THUMBNAIL_WALL_CONTACT
+  let uMin = Number.POSITIVE_INFINITY
+  let uMax = Number.NEGATIVE_INFINITY
+  let vMin = Number.POSITIVE_INFINITY
+  let vMax = Number.NEGATIVE_INFINITY
+  for (const { a, b } of segments) {
+    uMin = Math.min(uMin, a[0], b[0])
+    uMax = Math.max(uMax, a[0], b[0])
+    vMin = Math.min(vMin, a[1], b[1])
+    vMax = Math.max(vMax, a[1], b[1])
+  }
+  const margin = spreadM * 2
+  const width = uMax - uMin + margin * 2
+  const depth = vMax - vMin + margin * 2
+  const scale = 1024 / Math.max(width, depth)
+  const canvas = document.createElement('canvas')
+  canvas.width = Math.max(8, Math.round(width * scale))
+  canvas.height = Math.max(8, Math.round(depth * scale))
+  const ctx = canvas.getContext('2d')
+  if (!ctx) return null
+  // alphaMap samples the green channel: white strokes on opaque black.
+  ctx.fillStyle = '#000'
+  ctx.fillRect(0, 0, canvas.width, canvas.height)
+  ctx.filter = `blur(${Math.max(2, spreadM * scale * 0.35)}px)`
+  ctx.strokeStyle = '#fff'
+  ctx.lineCap = 'square'
+  for (const { a, b, thickness } of segments) {
+    ctx.lineWidth = (thickness + spreadM * 0.6) * scale
+    ctx.beginPath()
+    ctx.moveTo((a[0] - uMin + margin) * scale, (a[1] - vMin + margin) * scale)
+    ctx.lineTo((b[0] - uMin + margin) * scale, (b[1] - vMin + margin) * scale)
+    ctx.stroke()
+  }
+
+  const shade = new Mesh(
+    new PlaneGeometry(width, depth),
+    new MeshBasicNodeMaterial({
+      color: '#000000',
+      alphaMap: new CanvasTexture(canvas),
+      transparent: true,
+      depthWrite: false,
+      opacity,
+    }),
+  )
+  // Plane x → u; plane y → −v, so the canvas's downward rows run along +v.
+  shade.rotation.set(-Math.PI / 2, 0, -yaw)
+  shade.position
+    .copy(u)
+    .multiplyScalar((uMin + uMax) / 2)
+    .addScaledVector(v, (vMin + vMax) / 2)
+    .setY(groundY - 0.005)
+  shade.renderOrder = -1
+  return shade
+}
+
+function disposeMesh(mesh: Mesh) {
+  mesh.removeFromParent()
+  mesh.geometry.dispose()
+  const material = mesh.material as MeshBasicNodeMaterial
+  material.alphaMap?.dispose()
+  material.dispose()
+}
+
 export function BakeThumbnail({
   active,
   onComplete,
@@ -35,10 +209,39 @@ export function BakeThumbnail({
 
     const run = async () => {
       const restoreNodeVisibility = temporarilyHideNodeTypes(['scan', 'guide', 'spawn'])
+      // The hero is the building in the world's own light, wherever the person's eye is.
+      const restoreAmbiance = temporarilyWithoutAmbiance()
+      const priorLights = new Map<string, boolean>()
+      const restGroups = new Map<string, [number, number, number]>()
+      for (const node of Object.values(useScene.getState().nodes)) {
+        if (node.type !== 'procedural-item') continue
+        const evaluation = evaluateRecipe(node.recipe, node.parameters)
+        if (evaluation.lights.length) {
+          priorLights.set(
+            node.id,
+            useInteractive.getState().procedural[node.id]?.lightsOn ??
+              useInteractive.getState().lampDefault,
+          )
+          useInteractive.getState().setProceduralLights(node.id, true)
+        }
+        for (const motion of evaluation.motions)
+          restGroups.set(`${node.id}:${motion.id}`, motion.pivot)
+      }
+      const transforms: Array<{
+        object: import('three').Object3D
+        position: import('three').Vector3
+        rotation: import('three').Euler
+      }> = []
+      const emission = new Map<Material, number>()
       let pipeline: Awaited<ReturnType<typeof createSnapshotPipeline>> = null
+      // The studio backdrop replaces the site's ground and horizon: a shadow
+      // catcher keeps cast shadows, the wall shade keeps contact. Items the
+      // framing leaves out are hidden so what's framed is what's shown.
+      const hidden: Object3D[] = []
+      const added: Mesh[] = []
 
       try {
-        const framing = computeHeroFraming()
+        const framing = await settledHeroFraming()
         if (!framing) {
           onError('scene has no framable content')
           return
@@ -46,24 +249,73 @@ export function BakeThumbnail({
 
         const { width, height } = renderer.domElement
         const aspect = width / height
-        const camera = new PerspectiveCamera(60, aspect, 0.1, 1000)
+        const camera = new PerspectiveCamera(THUMBNAIL_FOV_DEG, aspect, 0.1, 1000)
         camera.layers.disable(EDITOR_LAYER)
         camera.layers.disable(GRID_LAYER)
+        const hasRoof = (sceneRegistry.byType.roof?.size ?? 0) > 0
+        const elevationDeg = hasRoof
+          ? THUMBNAIL_ELEVATION_DEG.roofed
+          : THUMBNAIL_ELEVATION_DEG.roofless
         const pose = heroCameraPose({
           boxes: framing.boxes,
           aim: framing.aim,
           azimuthRad: framing.azimuthRad,
           aspect,
+          fovDeg: THUMBNAIL_FOV_DEG,
+          elevationRad: (elevationDeg * Math.PI) / 180,
+          padding: THUMBNAIL_PADDING,
+          tightFit: true,
         })
         camera.position.set(pose.position[0], pose.position[1], pose.position[2])
         camera.lookAt(pose.target[0], pose.target[1], pose.target[2])
         camera.updateMatrixWorld()
 
+        const keyAzimuth = framing.azimuthRad + (THUMBNAIL_KEY_AZIMUTH_OFFSET_DEG * Math.PI) / 180
+        const keyElevation = (THUMBNAIL_KEY_ELEVATION_DEG * Math.PI) / 180
+        setKeyLightDirectionOverride([
+          Math.sin(keyAzimuth) * Math.cos(keyElevation),
+          Math.sin(keyElevation),
+          Math.cos(keyAzimuth) * Math.cos(keyElevation),
+        ])
+
+        for (const object of [
+          ...siteSurfaces(),
+          ...framing.detachedItemIds.flatMap((id) => sceneRegistry.nodes.get(id) ?? []),
+        ]) {
+          if (!object.visible) continue
+          object.visible = false
+          hidden.push(object)
+        }
+        const union = new Box3()
+        for (const box of framing.boxes) union.union(box)
+        const groundY = Math.max(0, union.min.y)
+        const catcher = new Mesh(
+          new PlaneGeometry(SHADOW_CATCHER_EXTENT, SHADOW_CATCHER_EXTENT),
+          new ShadowNodeMaterial({ opacity: THUMBNAIL_SHADOW_CATCHER_OPACITY }),
+        )
+        catcher.rotation.x = -Math.PI / 2
+        catcher.position.set(framing.aim[0], groundY - 0.01, framing.aim[2])
+        catcher.receiveShadow = true
+        added.push(catcher)
+        const contact = wallContactShade(Math.PI / 4 - framing.azimuthRad, groundY)
+        if (contact) added.push(contact)
+        for (const mesh of added) scene.add(mesh)
+
+        // Backdrop centred on the building's mid-height, where it's lightest.
+        const center = new Vector3(
+          framing.aim[0],
+          (groundY + framing.aim[1]) / 2,
+          framing.aim[2],
+        ).project(camera)
         pipeline = await createSnapshotPipeline({
           renderer: renderer as unknown as WebGPURenderer,
           scene,
           camera,
           atmosphere,
+          studioBackdrop: {
+            ...THUMBNAIL_BACKDROP,
+            center: [(center.x + 1) / 2, (1 - center.y) / 2],
+          },
         })
         if (!pipeline) {
           onError('thumbnail pipeline failed to build')
@@ -71,12 +323,47 @@ export function BakeThumbnail({
         }
 
         pipeline.applyEnvironment({
-          theme: useViewer.getState().sceneTheme,
+          theme: useViewer.getState().sceneAppearance,
           transparent: false,
           grade: true,
           edges: useViewer.getState().edges,
           camera,
         })
+        await new Promise<void>((resolve) => setTimeout(resolve, 250))
+        for (const node of Object.values(useScene.getState().nodes)) {
+          if (node.type !== 'procedural-item') continue
+          const slots = new Set(
+            evaluateRecipe(node.recipe, node.parameters).lights.flatMap((light) =>
+              light.emissiveSlot ? [light.emissiveSlot] : [],
+            ),
+          )
+          const object = sceneRegistry.nodes.get(node.id)
+          for (const mesh of object ? proceduralSlotMeshes(object, slots) : []) {
+            const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material]
+            for (const material of materials) {
+              const current = material as Material & { emissiveIntensity?: number }
+              if (typeof current.emissiveIntensity !== 'number') continue
+              emission.set(material, current.emissiveIntensity)
+              setProceduralEmission(material, true)
+            }
+          }
+        }
+        scene.traverse((object) => {
+          const motion = object.userData.proceduralMotion as
+            | { nodeId?: string; groupId?: string }
+            | undefined
+          if (!motion) return
+          const pivot = restGroups.get(`${motion.nodeId}:${motion.groupId}`)
+          if (!pivot) return
+          transforms.push({
+            object,
+            position: object.position.clone(),
+            rotation: object.rotation.clone(),
+          })
+          object.position.set(...pivot)
+          object.rotation.set(0, 0, 0)
+        })
+        scene.updateMatrixWorld(true)
         const { blob, outW, outH } = await pipeline.capture({ captureMode: 'standard' })
         onComplete(blob, { w: outW, h: outH })
       } catch (error) {
@@ -87,7 +374,22 @@ export function BakeThumbnail({
         onError(error instanceof Error ? error.message : String(error))
       } finally {
         pipeline?.dispose()
+        setKeyLightDirectionOverride(null)
+        for (const mesh of added) disposeMesh(mesh)
+        for (const object of hidden) object.visible = true
+        for (const [material, intensity] of emission)
+          (material as Material & { emissiveIntensity: number }).emissiveIntensity = intensity
+        for (const { object, position, rotation } of transforms) {
+          object.position.copy(position)
+          object.rotation.copy(rotation)
+        }
+        scene.updateMatrixWorld(true)
+        for (const [id, on] of priorLights)
+          useInteractive
+            .getState()
+            .setProceduralLights(id as import('@pascal-app/core').AnyNodeId, on)
         restoreNodeVisibility()
+        restoreAmbiance()
       }
     }
 

package/src/components/editor/capture-level-picker.tsx

@@ -0,0 +1,72 @@
+'use client'
+
+import { type BuildingNode, getLevelDisplayName, type LevelNode, useScene } from '@pascal-app/core'
+import { useViewer } from '@pascal-app/viewer'
+import { useShallow } from 'zustand/react/shallow'
+import { cn } from '../../lib/utils'
+import useEditor from '../../store/use-editor'
+
+const rowClass = (selected: boolean) =>
+  cn(
+    'flex w-full min-w-0 items-center rounded-lg px-2.5 py-1.5 text-left font-medium text-xs transition-colors',
+    selected
+      ? 'bg-white/10 text-foreground'
+      : 'text-muted-foreground/70 hover:bg-white/5 hover:text-muted-foreground',
+  )
+
+/**
+ * The capture view's level picker: the editor's level list, top floor first,
+ * under a "Whole building" row that shows every level (the default on entering
+ * capture). A level shows itself and the levels below it, as while editing.
+ */
+export function CaptureLevelPicker() {
+  const captureLevelId = useEditor((s) => s.captureLevelId)
+  const setCaptureLevel = useEditor((s) => s.setCaptureLevel)
+  const buildingId = useViewer((s) => s.selection.buildingId)
+  const levels = useScene(
+    useShallow((state) => {
+      const building = (
+        buildingId
+          ? state.nodes[buildingId]
+          : Object.values(state.nodes).find((n) => n?.type === 'building')
+      ) as BuildingNode | undefined
+      if (building?.type !== 'building') return [] as LevelNode[]
+      return building.children
+        .map((id) => state.nodes[id])
+        .filter((node): node is LevelNode => node?.type === 'level')
+        .sort((a, b) => b.level - a.level)
+    }),
+  )
+  if (levels.length < 2) return null
+
+  return (
+    <div
+      aria-label="Levels in the shot"
+      className="pointer-events-auto absolute top-4 left-4 flex w-36 flex-col gap-0.5 rounded-xl border border-border bg-background/90 p-1 shadow-2xl backdrop-blur-md"
+      data-capture-level-picker
+      role="group"
+    >
+      <button
+        aria-pressed={captureLevelId === null}
+        className={rowClass(captureLevelId === null)}
+        onClick={() => setCaptureLevel(null)}
+        type="button"
+      >
+        <span className="truncate">Whole building</span>
+      </button>
+      <div className="mx-1.5 my-0.5 h-px bg-border/60" />
+      {levels.map((level) => (
+        <button
+          aria-pressed={captureLevelId === level.id}
+          className={rowClass(captureLevelId === level.id)}
+          key={level.id}
+          onClick={() => setCaptureLevel(level.id)}
+          title={getLevelDisplayName(level)}
+          type="button"
+        >
+          <span className="truncate">{getLevelDisplayName(level)}</span>
+        </button>
+      ))}
+    </div>
+  )
+}

package/src/components/editor/construction-reveal-audio.test.tsx

@@ -0,0 +1,150 @@
+import { expect, spyOn, test } from 'bun:test'
+import {
+  type AnyNode,
+  type AnyNodeDefinition,
+  BaseNode,
+  LevelNode,
+  nodeRegistry,
+  objectId,
+  registerNode,
+  runAsSceneCommitAuthor,
+  sceneRegistry,
+  useScene,
+} from '@pascal-app/core'
+import {
+  type RevealGroupEvent,
+  startConstructionReveal,
+  subscribeRevealEvents,
+  useViewer,
+} from '@pascal-app/viewer'
+import { act, create } from '@react-three/test-renderer'
+import { BoxGeometry, Mesh, MeshBasicMaterial } from 'three'
+import { sfxEmitter } from '../../lib/sfx-bus'
+import { ConstructionRevealAudio } from './construction-reveal-audio'
+
+test('real reveal landings respect audio controls and the shared cue clock', async () => {
+  const restore = nodeRegistry._snapshot()
+  const savedScene = useScene.getState()
+  const savedHistory = useScene.temporal.getState()
+  const savedViewer = useViewer.getState()
+  const savedObjects = new Map(sceneRegistry.nodes)
+  const actDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'IS_REACT_ACT_ENVIRONMENT')
+  const rafDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'requestAnimationFrame')
+  const cancelDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'cancelAnimationFrame')
+  Object.defineProperties(globalThis, {
+    IS_REACT_ACT_ENVIRONMENT: { configurable: true, value: true },
+    requestAnimationFrame: { configurable: true, value: () => 0 },
+    cancelAnimationFrame: { configurable: true, value: () => {} },
+  })
+  let audioClock = 0
+  const clock = spyOn(performance, 'now').mockImplementation(() => audioClock)
+  const cues: string[] = []
+  const observe = (name: string) => cues.push(name)
+  sfxEmitter.on('*', observe)
+  const events: RevealGroupEvent[] = []
+  const stopObserve = subscribeRevealEvents((event) => {
+    if (event.type === 'land') events.push(event)
+  })
+  let instant = false
+  let time = 0
+  let index = 0
+  const meshes: Mesh[] = []
+  const schema = BaseNode.extend({ id: objectId('audio-smoke') })
+  for (const [kind, phase] of [
+    ['audio:structure', 'structure'],
+    ['audio:furnishing', 'furnishing'],
+  ] as const) {
+    registerNode({
+      kind,
+      schemaVersion: 1,
+      schema,
+      category: 'utility',
+      defaults: () => ({}),
+      capabilities: { reveal: { phase, style: 'scale' } },
+    } as unknown as AnyNodeDefinition)
+  }
+  const level = LevelNode.parse({ id: 'level_audio_smoke' })
+  useScene.setState({ nodes: { [level.id]: level }, rootNodeIds: [level.id], readOnly: false })
+  useViewer.setState({ renderContext: 'editor', isExporting: false })
+  useViewer
+    .getState()
+    .setSelection({ levelId: level.id, buildingId: null, selectedIds: [], zoneId: null })
+  const driver = startConstructionReveal({
+    reveals: (commit) => commit.author === 'agent',
+    level: () => 'full',
+    prefersReducedMotion: () => instant,
+  })
+  const renderer = await create(<ConstructionRevealAudio enabled={false} level="full" />)
+  async function land(kind = 'audio:structure') {
+    const id = `audio-smoke_${++index}`
+    const node = { ...schema.parse({ id }), type: kind, parentId: level.id } as unknown as AnyNode
+    const mesh = new Mesh(new BoxGeometry(1, 1, 1), new MeshBasicMaterial())
+    meshes.push(mesh)
+    sceneRegistry.nodes.set(node.id, mesh)
+    const before = events.length
+    await act(async () =>
+      runAsSceneCommitAuthor('agent', () => useScene.getState().createNode(node, level.id)),
+    )
+    // A real CPU mesh supplies the renderer's ready handshake, not drawn pixels.
+    useScene.getState().clearDirty(node.id)
+    for (let frame = 0; frame < 150; frame++) {
+      time += 20
+      await act(async () => driver.tick(time, 20))
+    }
+    expect(events.length).toBeGreaterThan(before)
+    expect(Boolean(events.at(-1)?.instant)).toBe(instant)
+  }
+  try {
+    await land()
+    expect(cues).toEqual([])
+    await renderer.update(<ConstructionRevealAudio enabled={true} level="simple" />)
+    await land()
+    expect(cues).toEqual([])
+    await renderer.update(<ConstructionRevealAudio enabled={true} level="off" />)
+    await land()
+    expect(cues).toEqual([])
+    await renderer.update(<ConstructionRevealAudio enabled={true} level="full" />)
+    await land()
+    expect(cues).toEqual(['sfx:structure-build'])
+    await renderer.update(<ConstructionRevealAudio enabled={false} level="full" />)
+    await renderer.update(<ConstructionRevealAudio enabled={true} level="framing" />)
+    audioClock = 249
+    await land()
+    expect(cues).toEqual(['sfx:structure-build'])
+    audioClock = 250
+    await land('audio:furnishing')
+    expect(cues).toEqual(['sfx:structure-build', 'sfx:item-place'])
+    audioClock = 1000
+    instant = true
+    await land()
+    expect(cues).toHaveLength(2)
+    await renderer.unmount()
+    instant = false
+    await land()
+    expect(cues).toHaveLength(2)
+  } finally {
+    driver.stop()
+    await renderer.unmount()
+    stopObserve()
+    sfxEmitter.off('*', observe)
+    clock.mockRestore()
+    restore()
+    useScene.setState(savedScene, true)
+    useScene.temporal.setState(savedHistory, true)
+    useViewer.setState(savedViewer, true)
+    sceneRegistry.nodes.clear()
+    for (const [id, mesh] of savedObjects) sceneRegistry.nodes.set(id, mesh)
+    for (const mesh of meshes) {
+      mesh.geometry.dispose()
+      ;(mesh.material as MeshBasicMaterial).dispose()
+    }
+    for (const [name, descriptor] of [
+      ['IS_REACT_ACT_ENVIRONMENT', actDescriptor],
+      ['requestAnimationFrame', rafDescriptor],
+      ['cancelAnimationFrame', cancelDescriptor],
+    ] as const) {
+      if (descriptor) Object.defineProperty(globalThis, name, descriptor)
+      else Reflect.deleteProperty(globalThis, name)
+    }
+  }
+})

package/src/components/editor/construction-reveal-audio.tsx

@@ -0,0 +1,40 @@
+'use client'
+
+import type { RevealPhase } from '@pascal-app/core'
+import { type ConstructionRevealLevel, subscribeRevealEvents } from '@pascal-app/viewer'
+import { useEffect, useRef } from 'react'
+import { triggerSFX } from '../../lib/sfx-bus'
+
+const REVEAL_PHASE_CUES = {
+  foundation: 'sfx:structure-build',
+  structure: 'sfx:structure-build',
+  circulation: 'sfx:structure-build',
+  openings: 'sfx:structure-build',
+  roof: 'sfx:structure-build',
+  furnishing: 'sfx:item-place',
+} as const satisfies Record<RevealPhase, 'sfx:structure-build' | 'sfx:item-place'>
+
+/** Mount once alongside ConstructionReveal; its driver owns the commit policy. */
+export function ConstructionRevealAudio({
+  enabled,
+  level,
+}: {
+  enabled: boolean
+  level: ConstructionRevealLevel
+}) {
+  // Prop changes and Strict Effects must not reset the shared phase/level gate.
+  const lastPlayedMs = useRef(Number.NEGATIVE_INFINITY)
+
+  useEffect(() => {
+    if (!enabled || (level !== 'full' && level !== 'framing')) return
+    return subscribeRevealEvents((event) => {
+      if (event.type !== 'land' || event.instant) return
+      const nowMs = performance.now()
+      if (nowMs - lastPlayedMs.current < 250) return
+      lastPlayedMs.current = nowMs
+      triggerSFX(REVEAL_PHASE_CUES[event.phase])
+    })
+  }, [enabled, level])
+
+  return null
+}