@pascal-app/editor 1.0.4 → 1.0.6

package/README.md

@@ -0,0 +1,106 @@
+# @pascal-app/editor
+
+The Pascal building editor as a React component: tools, panels, the floor plan, views and the agent chat surfaces, composed over `@pascal-app/viewer`.
+
+## Installation
+
+```bash
+npm install @pascal-app/core @pascal-app/viewer @pascal-app/editor @pascal-app/nodes
+```
+
+Load the built-in plugin once before mounting, as for the viewer (see the [viewer quick start](../viewer/README.md#usage)).
+
+## Usage
+
+```tsx
+import { Editor } from '@pascal-app/editor'
+
+export function ProjectPage({ projectId }: { projectId: string }) {
+  return (
+    <div className="dark" style={{ width: '100vw', height: '100vh' }}>
+      <Editor
+        layoutVersion="v2"
+        projectId={projectId}
+        onLoad={() => loadScene(projectId)}
+        onSave={(scene) => saveScene(projectId, scene)}
+        actionMenuPlacement="top"
+        loadingSlot={<MyProjectSpinner />}
+        onLoaderChange={(visible) => track('editor-loading', visible)}
+      />
+    </div>
+  )
+}
+```
+
+`apps/editor/components/scene-loader.tsx` is a complete host: navbar, sidebar tabs, toolbars and persistence.
+
+## Host props
+
+| Prop                  | What it does                                                                                                                                                                                                                                                                                     |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `loadingSlot`         | Your loading surface, shown in the canvas panes of both layouts and in 2D and 3D while the scene loads. The editor still decides when loading is over and fires `onLoaderChange`; a failed load always shows the editor's error and retry screen. Omit it or pass `null` for the default loader. |
+| `actionMenuPlacement` | `'bottom'` (default) or `'top'`. With `'top'`, the v2 layout gives the tool menu its own row under the toolbar, centred on the scene panes and following them in split, so the bottom strip is free; v1 floats it at the top edge. Mobile keeps the bottom rail.                                 |
+| `viewBar`             | Each pane's view bar (v2, default `true`). Turn it off for a host that shows one fixed view.                                                                                                                                                                                                     |
+| `sceneOverlay`        | Chrome over the 3D and 2D panes with the level selector and tool dock, hidden while no scene view is on screen.                                                                                                                                                                                  |
+| `stageOverlay`        | A full-bleed surface over the whole stage; the scene stays mounted underneath. To show something beside the scene, register a view instead.                                                                                                                                                      |
+
+## Theme
+
+The editor sets no theme of its own: its chrome follows the nearest `.dark` ancestor, so leave the class off for a light editor. Menus and tooltips portal to `<body>`, so put `dark` there too (or on `<html>`) for a dark one. Hand the person a theme switch with `InterfaceThemeRow` in the settings panel's `preferences` slot:
+
+```tsx
+import { InterfaceThemeRow, SettingsPanel, type InterfaceTheme } from '@pascal-app/editor'
+
+<SettingsPanel
+  preferences={<InterfaceThemeRow value={theme} onChange={(next: InterfaceTheme) => setTheme(next)} />}
+/>
+```
+
+`theme` is `'system' | 'light' | 'dark'`; applying it (toggling `.dark`) is the host's. A host that passes no row gets none. The Preview stage, the walkthrough HUD and the controls bar stay dark in either theme. The viewer's own "Scene theme" is separate (see [materials and themes](../../wiki/architecture/materials-and-themes.md)).
+
+## Views
+
+The stage is one or two panes, each showing a view: 3D, 2D, or one a plugin registers.
+
+```tsx
+import { openEditorView, PLUGINS_VIEW_ID, registerEditorHostView } from '@pascal-app/editor'
+
+registerEditorHostView({
+  id: 'acme:signage:schedule',
+  label: 'Sign schedule',
+  icon: { kind: 'url', src: '/icons/signs.webp' },
+  component: () => import('./schedule-view'),
+  pluginId: 'acme:signage',
+})
+
+openEditorView('acme:signage:schedule', { beside: true }) // split, next to the scene
+openEditorView(PLUGINS_VIEW_ID) // the plugin directory
+```
+
+Each workspace keeps its own layout, and swapping panes never remounts the 3D canvas or the plan. `\` toggles split. The full contract is in [plugin authoring](../../wiki/architecture/plugin-authoring.md).
+
+## Selecting and showing a node
+
+The helpers the editor's own lists use:
+
+```ts
+import { enterUnitFocus, frameViewerNode, selectZoneOrRoom } from '@pascal-app/editor'
+
+selectZoneOrRoom(zoneId) // 'room' for an enclosed room, else 'zone'
+frameViewerNode(nodeId, source) // the node's saved view, else its box; the plan frames it when no 3D view is on screen
+enterUnitFocus(unitId) // focus a unit, as the site panel does
+```
+
+What a host's chat points at (`useViewer.pointedIds`) lights in the plan and as a room outline, as well as in 3D. See [selection managers](../../wiki/architecture/selection-managers.md) and [point and ask](../../wiki/architecture/point-and-ask.md).
+
+## Plugin chat surfaces
+
+A plugin's `PluginChatExtension` can give a host's chat a start screen (`start`), shown while the thread is empty and acting through `ChatStartProps` (`send`, `attach`, `requirePro`). `IconRefGlyph` and `IconRefImage` render registry icons the way the editor does:
+
+```tsx
+import { IconRefGlyph } from '@pascal-app/editor'
+
+<IconRefGlyph icon={view.icon} />
+```
+
+See [plugin authoring, agent tools and chat extensions](../../wiki/architecture/plugin-authoring.md#agent-tools-and-chat-extensions).

package/package.json

@@ -1,21 +1,23 @@
 {
   "name": "@pascal-app/editor",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Pascal building editor component",
   "license": "MIT",
   "type": "module",
   "exports": {
     ".": "./src/index.tsx",
     "./catalog": "./src/components/ui/item-catalog/catalog-items.tsx",
-    "./procedural-items": "./src/components/procedural-items/inspector.tsx"
+    "./procedural-items": "./src/components/procedural-items/inspector.tsx",
+    "./distribution": "./src/components/tools/distribution/distribution-public.ts"
   },
   "scripts": {
+    "bench:room-labels": "bun run src/components/editor/__bench__/room-label-placement.bench.ts",
     "check-types": "tsgo --noEmit",
     "test": "bun test src"
   },
   "peerDependencies": {
-    "@pascal-app/core": "^1.0.4",
-    "@pascal-app/viewer": "^1.0.4",
+    "@pascal-app/core": "^1.0.6",
+    "@pascal-app/viewer": "^1.0.6",
     "@react-three/drei": "^10",
     "@react-three/fiber": "^9",
     "next": ">=15",
@@ -27,23 +29,23 @@
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
-    "@iconify/react": "^6.0.2",
-    "@number-flow/react": "^0.6.0",
-    "@pascal-app/geometry-script": "^1.0.4",
-    "@pascal-app/ifc-converter": "^1.0.4",
-    "@pascal-app/lingo": "^0.2.0",
-    "@radix-ui/react-alert-dialog": "^1.1.15",
-    "@radix-ui/react-context-menu": "^2.2.16",
-    "@radix-ui/react-dialog": "^1.1.15",
-    "@radix-ui/react-dropdown-menu": "^2.1.16",
-    "@radix-ui/react-popover": "^1.1.15",
-    "@radix-ui/react-select": "^2.2.6",
-    "@radix-ui/react-separator": "^1.1.8",
-    "@radix-ui/react-slider": "^1.3.6",
-    "@radix-ui/react-slot": "^1.2.4",
-    "@radix-ui/react-switch": "^1.2.6",
-    "@radix-ui/react-tabs": "^1.1.13",
-    "@radix-ui/react-tooltip": "^1.2.8",
+    "@iconify/react": "^6.0.3",
+    "@number-flow/react": "^0.6.2",
+    "@pascal-app/geometry-script": "^1.0.6",
+    "@pascal-app/ifc-converter": "^1.0.6",
+    "@pascal-app/lingo": "^0.5.0",
+    "@radix-ui/react-alert-dialog": "^1.2.1",
+    "@radix-ui/react-context-menu": "^2.4.1",
+    "@radix-ui/react-dialog": "^1.3.1",
+    "@radix-ui/react-dropdown-menu": "^2.2.1",
+    "@radix-ui/react-popover": "^1.3.1",
+    "@radix-ui/react-select": "^2.4.1",
+    "@radix-ui/react-separator": "^1.2.0",
+    "@radix-ui/react-slider": "^1.6.1",
+    "@radix-ui/react-slot": "^1.5.0",
+    "@radix-ui/react-switch": "^1.4.1",
+    "@radix-ui/react-tabs": "^1.2.1",
+    "@radix-ui/react-tooltip": "^1.4.1",
     "@visual-json/react": "^0.4.0",
     "blob-stream": "^0.1.3",
     "class-variance-authority": "^0.7.1",
@@ -51,32 +53,32 @@
     "cmdk": "^1.1.1",
     "fflate": "^0.8.3",
     "howler": "^2.2.4",
-    "lucide-react": "^1.7.0",
-    "manifold-3d": "3.5.1",
+    "lucide-react": "^1.61.0",
+    "manifold-3d": "3.5.4",
     "mitt": "^3.0.1",
-    "motion": "^12.34.3",
-    "nanoid": "^5.1.6",
-    "pdfkit": "^0.19.1",
-    "tailwind-merge": "^3.5.0",
+    "motion": "^14.6.0",
+    "nanoid": "^6.0.2",
+    "pdfkit": "^0.20.2",
+    "tailwind-merge": "^3.7.0",
     "three-bvh-csg": "^0.0.18",
-    "three-mesh-bvh": "~0.9.8",
-    "zod": ">=4.5.4 <4.6",
-    "zustand": "^5.0.11"
+    "three-mesh-bvh": "~0.9.16",
+    "zod": ">=4.6.7 <4.7",
+    "zustand": "^5.0.16"
   },
   "devDependencies": {
-    "@pascal-app/core": "^1.0.4",
-    "@pascal-app/viewer": "^1.0.4",
+    "@pascal-app/core": "^1.0.6",
+    "@pascal-app/viewer": "^1.0.6",
     "@pascal/typescript-config": "*",
-    "@react-three/test-renderer": "^9.1.0",
+    "@react-three/test-renderer": "^9.1.1",
     "@types/blob-stream": "^0.1.33",
-    "@types/bun": "^1.4.2",
-    "@types/howler": "^2.2.12",
-    "@types/pdfkit": "^0.17.6",
+    "@types/bun": "^1.4.3",
+    "@types/howler": "^2.2.13",
+    "@types/pdfkit": "^0.17.7",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
-    "@types/three": "^0.184.0",
+    "@types/three": "^0.186.0",
     "fast-xml-parser": "^5.11.2",
-    "typescript": "6.0.3"
+    "typescript": "7.0.2"
   },
   "repository": {
     "type": "git",

package/src/components/editor/__bench__/room-label-placement.bench.ts

@@ -0,0 +1,108 @@
+import type { Polygon } from '@pascal-app/core'
+import {
+  type PillCandidate,
+  placePills,
+  type RoomHit,
+  type RoomLabelEntry,
+  roomAt,
+} from '../room-labels'
+
+// One room-label placement pass and one pointer pick, for a 900 × 600 px house of 31, 60 and 120
+// rooms (every third an L), printed as JSON medians in ms. Run with `bun run <this file>`.
+let seed = 11
+const random = () => {
+  seed = (seed * 1_103_515_245 + 12_345) % 2 ** 31
+  return seed / 2 ** 31
+}
+
+function house(count: number) {
+  const columns = Math.ceil(Math.sqrt(count * 1.5))
+  const rows = Math.ceil(count / columns)
+  const width = 900 / columns
+  const depth = 600 / rows
+  return Array.from({ length: count }, (_, i) => {
+    const left = 270 + (i % columns) * width
+    const top = 150 + Math.floor(i / columns) * depth
+    const right = left + width
+    const bottom = top + depth
+    const outer: [number, number][] =
+      i % 3 === 0
+        ? [
+            [left, top],
+            [right, top],
+            [right, top + depth / 2],
+            [left + width / 2, top + depth / 2],
+            [left + width / 2, bottom],
+            [left, bottom],
+          ]
+        : [
+            [left, top],
+            [right, top],
+            [right, bottom],
+            [left, bottom],
+          ]
+    const outline: Polygon = { outer, holes: [] }
+    const pill = 60 + random() * 110
+    const candidate: PillCandidate = {
+      id: `room_${i}`,
+      x: left + width / 4,
+      y: top + depth / 4,
+      size: [pill, 24, pill * 0.6],
+      area: width * depth * (i % 3 === 0 ? 0.75 : 1),
+      outline,
+    }
+    const entry: RoomLabelEntry = {
+      zoneId: candidate.id,
+      polygon: outer,
+      holes: [],
+      area: candidate.area,
+    }
+    return { candidate, entry }
+  })
+}
+
+const median = (samples: number[]) => samples.sort((a, b) => a - b)[samples.length >> 1]!
+
+const pane = { width: 1440, height: 900 }
+const results: Record<string, unknown> = {}
+for (const count of [31, 60, 120]) {
+  const rooms = house(count)
+  const candidates = rooms.map((room) => room.candidate)
+  const entries = rooms.map((room) => room.entry)
+  for (let i = 0; i < 20; i++) placePills(candidates, pane)
+  const cold: number[] = []
+  const warm: number[] = []
+  let previous = placePills(candidates, pane)
+  for (let i = 0; i < 100; i++) {
+    let started = performance.now()
+    placePills(candidates, pane)
+    cold.push(performance.now() - started)
+    started = performance.now()
+    previous = placePills(candidates, pane, previous)
+    warm.push(performance.now() - started)
+  }
+  const points = Array.from(
+    { length: 1000 },
+    (): RoomHit => [270 + random() * 900, 150 + random() * 600, 0],
+  )
+  for (const point of points) roomAt(entries, () => point)
+  const picks: number[] = []
+  for (let i = 0; i < 20; i++) {
+    const started = performance.now()
+    for (const point of points) roomAt(entries, () => point)
+    picks.push((performance.now() - started) / points.length)
+  }
+  const tiers = Object.fromEntries(
+    ['full', 'name', 'dot', 'hidden'].map((tier) => [
+      tier,
+      [...previous.values()].filter((placement) => placement.tier === tier).length,
+    ]),
+  )
+  results[count] = {
+    placeMs: median(cold),
+    placeWithPreviousMs: median(warm),
+    pickMs: median(picks),
+    tiers,
+  }
+}
+console.log(JSON.stringify(results, null, 2))

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

@@ -12,7 +12,9 @@ import {
   setKeyLightDirectionOverride,
   setProceduralEmission,
   setSlotDefaultOverrides,
+  siteSurfaces,
   temporarilyHideNodeTypes,
+  temporarilyWithoutAmbiance,
   useSceneAtmosphere,
   useViewer,
 } from '@pascal-app/viewer'
@@ -92,20 +94,6 @@ async function settledHeroFraming() {
   return framing
 }
 
-/** The site's own surfaces (ground fill, horizon disc, property ribbons) —
- *  not its registered children (buildings, items), which are groups. */
-function siteSurfaces(): Object3D[] {
-  const surfaces: Object3D[] = []
-  for (const siteId of sceneRegistry.byType.site ?? []) {
-    for (const child of sceneRegistry.nodes.get(siteId)?.children ?? []) {
-      if (child.visible && !(child.type === 'Group' && child.children.length > 0)) {
-        surfaces.push(child)
-      }
-    }
-  }
-  return surfaces
-}
-
 /**
  * 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
@@ -221,6 +209,8 @@ 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)) {
@@ -333,7 +323,7 @@ export function BakeThumbnail({
         }
 
         pipeline.applyEnvironment({
-          theme: useViewer.getState().sceneTheme,
+          theme: useViewer.getState().sceneAppearance,
           transparent: false,
           grade: true,
           edges: useViewer.getState().edges,
@@ -399,6 +389,7 @@ export function BakeThumbnail({
             .getState()
             .setProceduralLights(id as import('@pascal-app/core').AnyNodeId, on)
         restoreNodeVisibility()
+        restoreAmbiance()
       }
     }
 

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
+}