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

package/src/lib/sfx-player.ts

@@ -16,8 +16,16 @@ type SFXConfig = {
   minIntervalMs?: number
 }
 
+type LoopSFXConfig = {
+  src: string
+  volumeMultiplier: number
+  fadeInMs?: number
+  fadeOutMs?: number
+}
+
 const DEFAULT_MIN_INTERVAL_MS = 30
 const SFX_FAILURE_BACKOFF_MS = 5_000
+const DEFAULT_LOOP_FADE_MS = 90
 
 // SFX sound definitions
 export const SFX: Record<string, SFXConfig> = {
@@ -108,17 +116,79 @@ export const SFX: Record<string, SFXConfig> = {
 
 export type SFXName = keyof typeof SFX
 
+export const LOOP_SFX = {
+  terrainRaise: {
+    src: '/audios/sfx/terrain_raise.mp3',
+    volumeMultiplier: 0.2,
+  },
+  terrainLower: {
+    src: '/audios/sfx/terrain_lower.mp3',
+    volumeMultiplier: 0.2,
+  },
+  terrainFlatten: {
+    src: '/audios/sfx/terrain_flatten.mp3',
+    volumeMultiplier: 0.2,
+  },
+  terrainSmooth: {
+    src: '/audios/sfx/terrain_smooth.mp3',
+    volumeMultiplier: 0.2,
+  },
+} as const satisfies Record<string, LoopSFXConfig>
+
+export type LoopSFXName = keyof typeof LOOP_SFX
+type CachedSFXName = SFXName | LoopSFXName
+
+function loopConfig(name: LoopSFXName): LoopSFXConfig {
+  return LOOP_SFX[name]
+}
+
+export type SFXPlaybackOptions = {
+  source?: 'local' | 'remote'
+  stereo?: number
+  volumeMultiplier?: number
+}
+
 function randomInRange([min, max]: [number, number]): number {
   return min + Math.random() * (max - min)
 }
 
-let sfxCache = new Map<SFXName, Howl[]>()
+let sfxCache = new Map<CachedSFXName, Howl[]>()
 let sfxAudioContext: AudioContext | null = null
 let sfxRetryAfter = 0
 const lastPlayedAt = new Map<SFXName, number>()
 const lastVariation = new Map<SFXName, number>()
+let activeLoop: {
+  id: number
+  name: LoopSFXName
+  sound: Howl
+  volume: number
+} | null = null
+let pendingLoop: { name: LoopSFXName; sound: Howl } | null = null
+let requestedLoop: LoopSFXName | null = null
+
+function loopVolume(name: LoopSFXName): number {
+  const { masterVolume, sfxVolume } = useAudio.getState()
+  return (masterVolume / 100) * (sfxVolume / 100) * LOOP_SFX[name].volumeMultiplier
+}
+
+function stopActiveLoop(fadeMs: number) {
+  const active = activeLoop
+  if (!active) return
+  activeLoop = null
+
+  if (fadeMs <= 0) {
+    active.sound.stop(active.id)
+    return
+  }
+
+  active.sound.once('fade', () => active.sound.stop(active.id), active.id)
+  active.sound.fade(active.volume, 0, fadeMs, active.id)
+}
 
 function unloadCachedSounds(resetPlaybackState: boolean) {
+  requestedLoop = null
+  pendingLoop = null
+  stopActiveLoop(0)
   for (const sounds of sfxCache.values()) {
     for (const sound of sounds) {
       try {
@@ -148,13 +218,15 @@ export function preloadSFX() {
   if (!cacheNeedsRebuild()) return
   unloadCachedSounds(false)
 
-  for (const [name, config] of Object.entries(SFX)) {
+  const definitions = { ...SFX, ...LOOP_SFX }
+  for (const [name, config] of Object.entries(definitions)) {
     const sources = Array.isArray(config.src) ? config.src : [config.src]
     sfxCache.set(
-      name as SFXName,
+      name as CachedSFXName,
       sources.map(
         (src) =>
           new Howl({
+            loop: name in LOOP_SFX,
             src: [src],
             preload: true,
             volume: 0.5,
@@ -169,10 +241,62 @@ export function disposeSFX() {
   unloadCachedSounds(true)
 }
 
+export function startLoopSFX(name: LoopSFXName) {
+  const { muted } = useAudio.getState()
+  if (muted) {
+    stopLoopSFX()
+    return
+  }
+
+  requestedLoop = name
+  const current = activeLoop
+  if (current?.name === name && current.sound.playing(current.id)) return
+  if (current) stopActiveLoop(loopConfig(current.name).fadeOutMs ?? DEFAULT_LOOP_FADE_MS)
+
+  const now = performance.now()
+  if (now < sfxRetryAfter) return
+
+  try {
+    preloadSFX()
+    // A fresh Howler context rebuilds the cache and clears stale playback
+    // state. Restore this current press after that cleanup so a first-use loop
+    // can still begin when its asset finishes loading.
+    requestedLoop = name
+    const sound = sfxCache.get(name)?.[0]
+    if (!sound) return
+    if (sound.state() !== 'loaded') {
+      if (pendingLoop?.name === name && pendingLoop.sound === sound) return
+      pendingLoop = { name, sound }
+      sound.once('load', () => {
+        if (pendingLoop?.sound === sound) pendingLoop = null
+        if (requestedLoop === name) startLoopSFX(name)
+      })
+      return
+    }
+
+    const config = loopConfig(name)
+    const volume = loopVolume(name)
+    const id = sound.play()
+    sound.volume(0, id)
+    activeLoop = { id, name, sound, volume }
+    sound.fade(0, volume, config.fadeInMs ?? DEFAULT_LOOP_FADE_MS, id)
+  } catch {
+    unloadCachedSounds(false)
+    sfxRetryAfter = now + SFX_FAILURE_BACKOFF_MS
+  }
+}
+
+export function stopLoopSFX() {
+  requestedLoop = null
+  pendingLoop = null
+  const fadeMs = activeLoop ? (loopConfig(activeLoop.name).fadeOutMs ?? DEFAULT_LOOP_FADE_MS) : 0
+  stopActiveLoop(fadeMs)
+}
+
 /**
  * Play a sound effect with volume based on audio settings
  */
-export function playSFX(name: SFXName) {
+export function playSFX(name: SFXName, options: SFXPlaybackOptions = {}) {
   const config = SFX[name]!
   const { masterVolume, sfxVolume, muted } = useAudio.getState()
 
@@ -183,9 +307,15 @@ export function playSFX(name: SFXName) {
   const now = performance.now()
   if (now < sfxRetryAfter) return
   const minInterval = config.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS
-  const last = lastPlayedAt.get(name)
+  const source = options.source ?? 'local'
+  const playbackKey = `${source}:${name}`
+  const last = lastPlayedAt.get(playbackKey)
   if (last !== undefined && now - last < minInterval) return
-  lastPlayedAt.set(name, now)
+  // Local feedback stays legible when a collaborator makes the same kind of
+  // change at nearly the same time; the quieter remote cue yields instead.
+  const lastLocal = lastPlayedAt.get(`local:${name}`)
+  if (source === 'remote' && lastLocal !== undefined && now - lastLocal < 120) return
+  lastPlayedAt.set(playbackKey, now)
 
   try {
     preloadSFX()
@@ -200,11 +330,21 @@ export function playSFX(name: SFXName) {
     }
     lastVariation.set(name, index)
     const sound = sounds[index]!
+    // Howler queues per-play mutations while a sound is loading. If its global
+    // AudioContext is replaced before that queue drains, stereo setup can try
+    // to connect nodes from different contexts and throw asynchronously.
+    if (sound.state() !== 'loaded') return
     const baseVolume = (masterVolume / 100) * (sfxVolume / 100)
     const volumeJitter = config.volumeRange ? randomInRange(config.volumeRange) : 1
+    const volumeMultiplier = Number.isFinite(options.volumeMultiplier)
+      ? Math.max(0, Math.min(2, options.volumeMultiplier!))
+      : 1
     const rate = config.rateRange ? randomInRange(config.rateRange) : 1
     const id = sound.play()
-    sound.volume(baseVolume * volumeJitter, id)
+    sound.volume(baseVolume * volumeJitter * volumeMultiplier, id)
+    if (Number.isFinite(options.stereo)) {
+      sound.stereo(Math.max(-1, Math.min(1, options.stereo!)), id)
+    }
     if (rate !== 1) sound.rate(rate, id)
   } catch {
     // Optional audio must never abort an editor input callback. Rebuild from
@@ -218,7 +358,11 @@ export function playSFX(name: SFXName) {
  * Update all cached SFX volumes (useful when settings change)
  */
 export function updateSFXVolumes() {
-  const { masterVolume, sfxVolume } = useAudio.getState()
+  const { masterVolume, muted, sfxVolume } = useAudio.getState()
+  if (muted) {
+    stopLoopSFX()
+    return
+  }
   const finalVolume = (masterVolume / 100) * (sfxVolume / 100)
 
   try {
@@ -229,6 +373,10 @@ export function updateSFXVolumes() {
         sound.volume(finalVolume)
       })
     })
+    if (activeLoop) {
+      activeLoop.volume = loopVolume(activeLoop.name)
+      activeLoop.sound.volume(activeLoop.volume, activeLoop.id)
+    }
   } catch {
     unloadCachedSounds(false)
     sfxRetryAfter = performance.now() + SFX_FAILURE_BACKOFF_MS

package/src/lib/site-boundary.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from 'bun:test'
+import type { Mode, Phase } from '../store/use-editor'
+import { siteBoundaryHandlesEnabled } from './site-boundary'
+
+/**
+ * The site handles are the one affordance both views draw from the same state, so
+ * they are also the one place a 2D/3D parity break hides: each pane used to derive
+ * this rule locally, and the sculpt exclusion existed in the 3D copy only.
+ */
+
+const MODES: Mode[] = ['select', 'edit', 'delete', 'build', 'material-paint', 'terrain-sculpt']
+const PHASES: Phase[] = ['site', 'structure', 'furnish']
+
+describe('siteBoundaryHandlesEnabled', () => {
+  test('sculpt hides the handles in every phase', () => {
+    // Including `site` — which is the case that matters, because arming sculpt
+    // *promotes* the phase to `site`, so this is the only combination the brush is
+    // ever actually in.
+    for (const phase of PHASES) {
+      expect(siteBoundaryHandlesEnabled({ mode: 'terrain-sculpt', phase })).toBe(false)
+    }
+  })
+
+  test('the site phase offers them in every other mode', () => {
+    for (const mode of MODES.filter((m) => m !== 'terrain-sculpt')) {
+      expect(siteBoundaryHandlesEnabled({ mode, phase: 'site' })).toBe(true)
+    }
+  })
+
+  test('select mode offers them outside the site phase', () => {
+    // The flags double as the affordance that *enters* site editing, so select mode
+    // has to show them from structure/furnish or the lot becomes unreachable.
+    expect(siteBoundaryHandlesEnabled({ mode: 'select', phase: 'structure' })).toBe(true)
+    expect(siteBoundaryHandlesEnabled({ mode: 'select', phase: 'furnish' })).toBe(true)
+  })
+
+  test('a drafting or painting mode outside the site phase hides them', () => {
+    for (const mode of ['edit', 'delete', 'build', 'material-paint'] as Mode[]) {
+      expect(siteBoundaryHandlesEnabled({ mode, phase: 'structure' })).toBe(false)
+      expect(siteBoundaryHandlesEnabled({ mode, phase: 'furnish' })).toBe(false)
+    }
+  })
+
+  test('sculpt is excluded before the phase term, not alongside it', () => {
+    // Ordering is the whole fix: `phase === 'site' || mode === 'select'` alone is
+    // *true* while sculpting, so an implementation that ORs the sculpt check in
+    // rather than early-returning would still show the handles.
+    const sculptInSite = siteBoundaryHandlesEnabled({ mode: 'terrain-sculpt', phase: 'site' })
+    const selectInSite = siteBoundaryHandlesEnabled({ mode: 'select', phase: 'site' })
+    expect(sculptInSite).toBe(false)
+    expect(selectInSite).toBe(true)
+  })
+})

package/src/lib/site-boundary.ts

@@ -1 +1,28 @@
+import type { Mode, Phase } from '../store/use-editor'
+
 export const SITE_BOUNDARY_DRAG_LABEL = 'site-boundary'
+
+/**
+ * Whether the site's vertex/midpoint handles are grabbable right now.
+ *
+ * Shared by the 3D boundary editor (`tool-manager.tsx`) and the floorplan's SVG
+ * handles (`floorplan-panel.tsx`) because they must agree, and until this existed
+ * they did not: each derived the rule from `phase`/`mode` locally, and the sculpt
+ * clause was added to only one of them.
+ *
+ * The disagreement was reachable in exactly one configuration, which is why it was
+ * easy to miss: arming sculpt from the 2D view promotes `viewMode` to `split` *and*
+ * the phase to `site`, so the floorplan's `phase === 'site'` term went true at the
+ * same moment the 3D editor's `!sculpting` term went false — handles gone in one
+ * pane, live in the other. Grabbing one then calls `begin({kind: 'handle-drag'})`,
+ * which atomically replaces the held `sculpting` scope: the brush stays armed and
+ * still paints, while the rest of the editor believes a boundary drag is running.
+ *
+ * Sculpt is excluded rather than merely deprioritised because the flags sit *on* the
+ * ground the brush is aimed at — leaving them mounted puts a grabbable handle under
+ * every dab near the lot line, in either view.
+ */
+export function siteBoundaryHandlesEnabled(args: { mode: Mode; phase: Phase }): boolean {
+  if (args.mode === 'terrain-sculpt') return false
+  return args.phase === 'site' || args.mode === 'select'
+}

package/src/lib/snapping-mode.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'bun:test'
+import { ROTATE_HANDLE_DRAG_LABEL } from './contextual-help'
 import {
   cycleSnappingModeIn,
   DEFAULT_SNAPPING_MODE,
@@ -84,11 +85,20 @@ describe('snapContextOf (profile-driven, node-declared)', () => {
     zone: 'structural',
   }
   const profileOf = (t: string) => declared[t]
+  const profileOfNode = (id: string) =>
+    id === 'cabinet-module_1' ? declared.item : id === 'wall_1' ? declared.wall : undefined
   const ctx = (
-    scope: { kind: string; nodeType?: string; reshape?: string; tool?: string },
+    scope: {
+      kind: string
+      nodeType?: string
+      reshape?: string
+      nodeId?: string
+      tool?: string
+      handle?: string
+    },
     mode = 'select',
     tool: string | null = null,
-  ) => snapContextOf({ scope, mode, tool, profileOf })
+  ) => snapContextOf({ scope, mode, tool, profileOf, profileOfNode })
 
   it('translating a whole structural node has no angle (polygon, not wall)', () => {
     expect(ctx({ kind: 'moving', nodeType: 'wall' })).toBe('polygon')
@@ -96,6 +106,15 @@ describe('snapContextOf (profile-driven, node-declared)', () => {
     expect(ctx({ kind: 'placing', nodeType: 'item' }, 'build', 'item')).toBe('item')
   })
 
+  it('resolves handle drags from the target node profile', () => {
+    expect(ctx({ kind: 'handle-drag', nodeId: 'cabinet-module_1' })).toBe('item')
+    expect(ctx({ kind: 'handle-drag', nodeId: 'wall_1' })).toBe('polygon')
+    expect(ctx({ kind: 'handle-drag', nodeId: 'unknown_1' })).toBeNull()
+    expect(
+      ctx({ kind: 'handle-drag', nodeId: 'cabinet-module_1', handle: ROTATE_HANDLE_DRAG_LABEL }),
+    ).toBeNull()
+  })
+
   it('endpoint reshape is angle-bearing (wall); curve + polygon vertex edits are not', () => {
     expect(ctx({ kind: 'reshaping', reshape: 'endpoint' })).toBe('wall')
     expect(ctx({ kind: 'reshaping', reshape: 'curve' })).toBe('polygon')
@@ -115,6 +134,14 @@ describe('snapContextOf (profile-driven, node-declared)', () => {
     expect(ctx({ kind: 'idle' }, 'build', 'shelf')).toBeNull()
   })
 
+  it('the room-preset stamp tool (not a node kind) resolves to polygon', () => {
+    // The host app's room stamp drives placement with `tool='room'`, which has
+    // no registry entry — the tool map must still give it the no-angle set so
+    // Shift cycling and the HUD chip work during preset placement.
+    expect(ctx({ kind: 'idle' }, 'build', 'room')).toBe('polygon')
+    expect(ctx({ kind: 'idle' }, 'select', 'room')).toBeNull()
+  })
+
   it('drafting a non-directional structural kind is angle-less (polygon, not wall)', () => {
     // Roof / stair / elevator are placed as footprints, not directional draws →
     // declared `snapDraftDirectional: false`, so their draft context drops the

package/src/lib/snapping-mode.ts

@@ -1,5 +1,5 @@
 import type { SnapProfile } from '@pascal-app/core'
-import { GROUP_MOVE_DRAG_LABEL } from './contextual-help'
+import { GROUP_MOVE_DRAG_LABEL, ROTATE_HANDLE_DRAG_LABEL } from './contextual-help'
 
 /**
  * Snapping mode is a single global, user-cyclable control that maps onto the
@@ -122,6 +122,13 @@ function contextForProfile(
   return null
 }
 
+// Tools that are not registered node kinds (no `snapProfile` to look up) but
+// still place a whole footprint — the host app's room-preset stamp. A stamp is
+// a whole-footprint translate: no direction to set → the no-angle 'polygon'
+// set. Without an entry here the tool has no snap context at all, so Shift
+// cycling and the HUD chip stay dead while it drives placement.
+const TOOL_SNAP_CONTEXTS: Record<string, SnapContext> = { room: 'polygon' }
+
 /**
  * The active snapping context, derived from what the user is doing — fully
  * node-declared: the kind's `snapProfile` (looked up via the injected
@@ -145,12 +152,13 @@ export function snapContextOf(args: {
   mode: string
   tool: string | null
   profileOf: (typeOrTool: string) => SnapProfile | undefined
+  profileOfNode?: (nodeId: string) => SnapProfile | undefined
   // Whether drafting a kind sets a direction (angle-lock meaningful). Injected
   // like `profileOf` so `snapping-mode` need not import the registry; defaults
   // to `true` (the structural draw default) when not supplied.
   draftDirectionalOf?: (typeOrTool: string) => boolean
 }): SnapContext | null {
-  const { scope, mode, tool, profileOf, draftDirectionalOf } = args
+  const { scope, mode, tool, profileOf, profileOfNode, draftDirectionalOf } = args
   // The group-move gizmo translates the whole selection — same no-angle
   // treatment as a single-node move, so Shift cycles the 'item' modes and the
   // HUD shows the item snapping chips for the drag.
@@ -158,6 +166,9 @@ export function snapContextOf(args: {
     return 'item'
   }
   switch (scope.kind) {
+    case 'handle-drag':
+      if (scope.handle === ROTATE_HANDLE_DRAG_LABEL) return null
+      return scope.nodeId ? contextForProfile(profileOfNode?.(scope.nodeId), false) : null
     case 'placing':
     case 'moving':
       // A whole-node translate never sets direction → no angle.
@@ -173,7 +184,8 @@ export function snapContextOf(args: {
         : null
     default:
       return mode === 'build' && tool
-        ? contextForProfile(profileOf(tool), draftDirectionalOf?.(tool) ?? true)
+        ? (TOOL_SNAP_CONTEXTS[tool] ??
+            contextForProfile(profileOf(tool), draftDirectionalOf?.(tool) ?? true))
         : null
   }
 }

package/src/lib/stair-duplication.test.ts

@@ -0,0 +1,103 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import {
+  type AnyNode,
+  type AnyNodeId,
+  LevelNode,
+  StairNode,
+  StairSegmentNode,
+  useScene,
+} from '@pascal-app/core'
+import { useViewer } from '@pascal-app/viewer'
+import useInteractionScope, { getMovingNode } from '../store/use-interaction-scope'
+import { duplicateStairSubtree } from './stair-duplication'
+
+const LEVEL_ID = 'level_stair-duplicate' as AnyNodeId
+const STAIR_ID = 'stair_original' as AnyNodeId
+const SEGMENT_ID = 'sseg_original' as AnyNodeId
+
+function seedStraightStair() {
+  const level = LevelNode.parse({
+    id: LEVEL_ID,
+    type: 'level',
+    children: [STAIR_ID],
+  })
+  const stair = StairNode.parse({
+    id: STAIR_ID,
+    type: 'stair',
+    parentId: LEVEL_ID,
+    children: [SEGMENT_ID],
+    position: [2, 0, 3],
+  })
+  const segment = StairSegmentNode.parse({
+    id: SEGMENT_ID,
+    type: 'stair-segment',
+    parentId: STAIR_ID,
+  })
+  useScene.setState({
+    nodes: {
+      [LEVEL_ID]: level as AnyNode,
+      [STAIR_ID]: stair as AnyNode,
+      [SEGMENT_ID]: segment as AnyNode,
+    },
+    rootNodeIds: [LEVEL_ID],
+    collections: {},
+    dirtyNodes: new Set(),
+  } as never)
+}
+
+describe('duplicateStairSubtree', () => {
+  beforeEach(() => {
+    useInteractionScope.getState().end()
+    useViewer.getState().setSelection({ selectedIds: [STAIR_ID] })
+    useScene.temporal.getState().clear()
+    useScene.temporal.getState().resume()
+    seedStraightStair()
+  })
+
+  afterEach(() => {
+    useInteractionScope.getState().end()
+    useScene.temporal.getState().resume()
+    useViewer.getState().setSelection({ selectedIds: [] })
+  })
+
+  test('moves the exact fresh scene subtree and clears the original selection', () => {
+    const result = duplicateStairSubtree(STAIR_ID, { mode: 'move' })
+    const nodes = useScene.getState().nodes
+    const draft = nodes[result.stair.id as AnyNodeId]
+
+    expect(result.stair.id).not.toBe(STAIR_ID)
+    expect(draft).toBe(result.stair)
+    expect(getMovingNode()?.id).toBe(result.stair.id)
+    expect(useViewer.getState().selection.selectedIds).toEqual([])
+    expect((result.stair.metadata as Record<string, unknown>)?.isNew).toBe(true)
+    expect(result.stair.position).toEqual([3, 0, 4])
+    expect(result.segmentIds).toHaveLength(1)
+    expect(result.segmentIds[0]).not.toBe(SEGMENT_ID)
+    expect(nodes[result.segmentIds[0] as AnyNodeId]?.parentId).toBe(result.stair.id)
+    expect(nodes[STAIR_ID]).toBeDefined()
+    expect(nodes[SEGMENT_ID]).toBeDefined()
+    expect(useScene.temporal.getState().isTracking).toBe(false)
+  })
+
+  test('keeps childless curved stairs on the same real draft path', () => {
+    const curved = StairNode.parse({
+      ...(useScene.getState().nodes[STAIR_ID] as AnyNode),
+      children: [],
+      stairType: 'curved',
+    })
+    useScene.setState((state) => ({
+      nodes: {
+        ...state.nodes,
+        [LEVEL_ID]: { ...state.nodes[LEVEL_ID], children: [STAIR_ID] } as AnyNode,
+        [STAIR_ID]: curved as AnyNode,
+      },
+    }))
+
+    const result = duplicateStairSubtree(STAIR_ID, { mode: 'move', offset: [0, 0, 0] })
+
+    expect(result.segmentIds).toEqual([])
+    expect(useScene.getState().nodes[result.stair.id as AnyNodeId]).toBe(result.stair)
+    expect(getMovingNode()?.id).toBe(result.stair.id)
+    expect((result.stair.metadata as Record<string, unknown>)?.isNew).toBe(true)
+  })
+})