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

package/src/lib/walkthrough-pointer-lock.ts

@@ -0,0 +1,47 @@
+/**
+ * Grab pointer lock on the viewer canvas for a walkthrough (walk / drone)
+ * entry. Must run synchronously inside a user-gesture task — callers flip the
+ * first-person flags in a `flushSync` first so the controls are mounted when
+ * the lock lands.
+ *
+ * `retryWhile`: the browser's re-lock cooldown (~1.25s after any unlock)
+ * rejects the request outright, which bites the natural "free the cursor,
+ * immediately pick the other camera" flow. When given, one delayed retry
+ * fires after the cooldown — only while the predicate still holds.
+ */
+export function requestWalkthroughPointerLock(options?: { retryWhile?: () => boolean }) {
+  const canvas = document.querySelector<HTMLCanvasElement>('[data-pascal-viewer-3d] canvas')
+  if (!canvas) return
+
+  if (!canvas.hasAttribute('tabindex')) {
+    canvas.tabIndex = -1
+  }
+  canvas.focus({ preventScroll: true })
+
+  if (document.pointerLockElement === canvas) return
+
+  try {
+    // The request can also reject ASYNC (browser cooldown after a recent
+    // unlock) — swallow it like the P-resume path; clicking the canvas
+    // re-requests once the cooldown passes.
+    const result = canvas.requestPointerLock?.() as Promise<void> | undefined
+    if (result && typeof result.catch === 'function') {
+      result.catch(() => {
+        const retryWhile = options?.retryWhile
+        if (!retryWhile) return
+        window.setTimeout(() => {
+          if (!retryWhile()) return
+          if (document.pointerLockElement === canvas) return
+          try {
+            const retried = canvas.requestPointerLock?.() as Promise<void> | undefined
+            if (retried && typeof retried.catch === 'function') retried.catch(() => {})
+          } catch {
+            // Best effort — clicking the canvas still locks.
+          }
+        }, 1400)
+      })
+    }
+  } catch {
+    return
+  }
+}

package/src/store/live-draft-preview-stores.test.ts

@@ -85,6 +85,7 @@ describe('live draft preview stores', () => {
       {
         angle: 90,
         branchAngle: 90,
+        damperAngle: 0,
         diameter: 6,
         diameter2: 6,
         ductMaterial: 'sheet-metal' as const,
@@ -94,6 +95,8 @@ describe('live draft preview stores', () => {
         id: 'duct-fitting_live-draft-0' as const,
         metadata: {},
         object: 'node' as const,
+        panelHeight: 0.15,
+        panelWidth: 0.25,
         parentId: 'level_1' as const,
         position: [1, 2, 3] as [number, number, number],
         rotation: [0, 0, 0] as [number, number, number],

package/src/store/terrain-sculpt-mode.test.ts

@@ -52,8 +52,7 @@ describe('terrain-sculpt mode lifecycle', () => {
 
   test('a phase switch out of site drops the scope', () => {
     useEditor.getState().setMode('terrain-sculpt')
-    // This path rewrites `mode` without going through `setMode`, which is
-    // exactly why the scope sync is its own function.
+    // The phase setter delegates its mode rewrite to the ToolMode transition.
     useEditor.getState().setPhase('structure')
     expect(useInteractionScope.getState().scope.kind).toBe('idle')
   })
@@ -153,10 +152,8 @@ describe('the brush and the 3D canvas travel together', () => {
 
 describe('the modes that hide the editing canvas release the brush', () => {
   // Preview / walkthrough / studio all unmount `ToolManager` (via `noEditing`),
-  // so the sculpt tool that would release the scope on unmount is gone. Each one
-  // resets `mode` with a raw `set` rather than `setMode`, which is exactly the
-  // bug class `setPhase` had: a `sculpting` scope leaked here disables selection
-  // across the whole editor with nothing left mounted to clear it.
+  // so the sculpt tool that would release the scope on unmount is gone. Their
+  // ToolMode transitions must release the scope before the canvas disappears.
   test('entering preview releases it', () => {
     useEditor.getState().setMode('terrain-sculpt')
     useEditor.getState().setPreviewMode(true)

package/src/store/tool-mode.test.ts

@@ -0,0 +1,87 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import useEditor, { normalizePersistedEditorUiState } from './use-editor'
+
+function resetToolMode() {
+  useEditor.getState().setPhase('structure')
+  useEditor.getState().setStructureLayer('elements')
+  useEditor.getState().armToolMode({ mode: 'select' })
+  useEditor.getState().setActivePaintMaterial(null)
+}
+
+beforeEach(resetToolMode)
+afterEach(resetToolMode)
+
+describe('ToolMode transition', () => {
+  test('choosing a paint swatch while selected arms material paint', () => {
+    useEditor.getState().armToolMode({ mode: 'select' })
+    useEditor.getState().armMaterialPaint({
+      materialPreset: 'library:test-paint',
+      sourceTarget: 'wall',
+    })
+
+    expect(useEditor.getState().toolMode).toEqual({ mode: 'material-paint' })
+    expect(useEditor.getState().mode).toBe('material-paint')
+    expect(useEditor.getState().tool).toBeNull()
+    expect(useEditor.getState().activePaintMaterial?.materialPreset).toBe('library:test-paint')
+  })
+
+  test('leaving build clears the materialized tool', () => {
+    useEditor.getState().armToolMode({ mode: 'build', tool: 'wall' })
+    useEditor.getState().armToolMode({ mode: 'select' })
+
+    expect(useEditor.getState().toolMode).toEqual({ mode: 'select' })
+    expect(useEditor.getState().mode).toBe('select')
+    expect(useEditor.getState().tool).toBeNull()
+  })
+
+  test('the setMode compatibility wrapper elects a default build tool', () => {
+    useEditor.getState().setMode('build')
+
+    expect(useEditor.getState().toolMode).toEqual({ mode: 'build', tool: 'wall' })
+    expect(useEditor.getState().mode).toBe('build')
+    expect(useEditor.getState().tool).toBe('wall')
+  })
+
+  test('setTool enters build and null exits it', () => {
+    useEditor.getState().armToolMode({ mode: 'select' })
+    useEditor.getState().setTool('slab')
+
+    expect(useEditor.getState().toolMode).toEqual({ mode: 'build', tool: 'slab' })
+    expect(useEditor.getState().mode).toBe('build')
+    expect(useEditor.getState().tool).toBe('slab')
+
+    useEditor.getState().setTool(null)
+    expect(useEditor.getState().toolMode).toEqual({ mode: 'select' })
+    expect(useEditor.getState().tool).toBeNull()
+  })
+})
+
+describe('persisted ToolMode normalization', () => {
+  test('elects a default for build with a null tool', () => {
+    const state = normalizePersistedEditorUiState({
+      phase: 'structure',
+      toolMode: { mode: 'build', tool: null as never },
+      mode: 'select',
+      tool: 'slab',
+      structureLayer: 'elements',
+    })
+
+    expect(state.toolMode).toEqual({ mode: 'build', tool: 'wall' })
+    expect(state.mode).toBe('build')
+    expect(state.tool).toBe('wall')
+  })
+
+  test('clears a persisted tool from a non-build mode', () => {
+    const state = normalizePersistedEditorUiState({
+      phase: 'structure',
+      toolMode: { mode: 'select' },
+      mode: 'build',
+      tool: 'wall',
+      structureLayer: 'elements',
+    })
+
+    expect(state.toolMode).toEqual({ mode: 'select' })
+    expect(state.mode).toBe('select')
+    expect(state.tool).toBeNull()
+  })
+})

package/src/store/use-camera-hint-focus.ts

@@ -0,0 +1,48 @@
+import { create } from 'zustand'
+
+/** The camera actions the canvas hint can name. */
+export type CameraHintAction = 'Pan' | 'Rotate' | 'Zoom'
+
+/**
+ * Which camera controls the canvas hint is currently allowed to name.
+ *
+ * `null` — the default — means all of them, which is what the editor shows on
+ * its own: a first-time user has no idea which button does what, and the panel
+ * is there to answer that once.
+ *
+ * A host teaching the camera one gesture at a time needs the opposite. Showing
+ * three controls while asking for one turns the answer into a search, and
+ * leaving all three up after the lesson leaves a permanent widget over the
+ * canvas explaining something the user has just been walked through. So a host
+ * can narrow the panel to the gesture it is asking for, and to nothing at all
+ * once it is done — an empty list hides the panel outright.
+ *
+ * Deliberately a store rather than a prop: the thing that knows which gesture
+ * is being taught is a host surface several levels away from the canvas, and
+ * threading it through would put a teaching concern in every component between.
+ * The editor knows only "show these actions"; it never learns why.
+ */
+type CameraHintFocus = {
+  actions: readonly CameraHintAction[] | null
+  focus: (actions: readonly CameraHintAction[] | null) => void
+}
+
+export const useCameraHintFocus = create<CameraHintFocus>((set) => ({
+  actions: null,
+  focus: (actions) =>
+    set((state) => {
+      const current = state.actions
+      if (
+        current === actions ||
+        (current !== null &&
+          actions !== null &&
+          current.length === actions.length &&
+          current.every((action, index) => action === actions[index]))
+      ) {
+        return state
+      }
+      return { actions }
+    }),
+}))
+
+export default useCameraHintFocus