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

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'bun:test'
-import { ROTATE_HANDLE_DRAG_LABEL } from './contextual-help'
+import { GROUP_MOVE_DRAG_LABEL, ROTATE_HANDLE_DRAG_LABEL } from './contextual-help'
 import {
   cycleSnappingModeIn,
   DEFAULT_SNAPPING_MODE,
@@ -49,12 +49,24 @@ describe('resolveSnapFlags', () => {
 })
 
 describe('per-context snapping', () => {
-  it('items default to grid with no angle lock', () => {
-    expect(defaultSnappingModeFor('item')).toBe('grid')
+  it('items default to magnetic alignment with no angle lock', () => {
+    expect(defaultSnappingModeFor('item')).toBe('lines')
     expect(snappingModesFor('item')).toEqual(['lines', 'grid', 'off'])
     expect(snappingModesFor('item')).not.toContain('angles')
   })
 
+  it('group moves use the magnetic item context by default', () => {
+    const context = snapContextOf({
+      scope: { kind: 'handle-drag', handle: GROUP_MOVE_DRAG_LABEL },
+      mode: 'select',
+      tool: null,
+      profileOf: () => undefined,
+    })
+
+    expect(context).toBe('item')
+    expect(resolveSnapFlags(defaultSnappingModeFor(context!)).magnetic).toBe(true)
+  })
+
   it('walls default to grid and expose the angle lock; polygons do NOT', () => {
     expect(defaultSnappingModeFor('wall')).toBe('grid')
     expect(defaultSnappingModeFor('polygon')).toBe('grid')
@@ -83,10 +95,17 @@ describe('snapContextOf (profile-driven, node-declared)', () => {
     ceiling: 'structural',
     roof: 'structural',
     zone: 'structural',
+    block: 'structural',
   }
   const profileOf = (t: string) => declared[t]
   const profileOfNode = (id: string) =>
-    id === 'cabinet-module_1' ? declared.item : id === 'wall_1' ? declared.wall : undefined
+    id === 'cabinet-module_1'
+      ? declared.item
+      : id === 'wall_1'
+        ? declared.wall
+        : id === 'block_1'
+          ? declared['block']
+          : undefined
   const ctx = (
     scope: {
       kind: string
@@ -95,6 +114,7 @@ describe('snapContextOf (profile-driven, node-declared)', () => {
       nodeId?: string
       tool?: string
       handle?: string
+      operator?: string
     },
     mode = 'select',
     tool: string | null = null,
@@ -115,6 +135,14 @@ describe('snapContextOf (profile-driven, node-declared)', () => {
     ).toBeNull()
   })
 
+  it('gives mesh rotation the angle context and other edit operations polygon snapping', () => {
+    expect(ctx({ kind: 'mesh-editing', nodeId: 'block_1' })).toBe('polygon')
+    expect(ctx({ kind: 'mesh-editing', nodeId: 'block_1', operator: 'translate' })).toBe('polygon')
+    expect(ctx({ kind: 'mesh-editing', nodeId: 'block_1', operator: 'scale' })).toBe('polygon')
+    expect(ctx({ kind: 'mesh-editing', nodeId: 'block_1', operator: 'loop-cut' })).toBe('polygon')
+    expect(ctx({ kind: 'mesh-editing', nodeId: 'block_1', operator: 'rotate' })).toBe('wall')
+  })
+
   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')

package/src/lib/snapping-mode.ts

@@ -4,10 +4,9 @@ import { GROUP_MOVE_DRAG_LABEL, ROTATE_HANDLE_DRAG_LABEL } from './contextual-he
 /**
  * Snapping mode is a single global, user-cyclable control that maps onto the
  * two pre-existing snap knobs (`gridSnapStep` grid snap + `magneticSnap`).
- * The default `'grid'` resolves to the exact pair the editor shipped with
- * before this control existed (grid on, magnetic on), so the default path is
- * behaviourally unchanged — only when a user opts into `'lines'` or `'off'`
- * does any snap math get suppressed.
+ * Each context chooses its own default. Item movement defaults to magnetic
+ * alignment so a picked-up group catches neighboring geometry; grid and off
+ * remain explicit alternatives in the contextual chip.
  */
 export type SnappingMode = 'grid' | 'lines' | 'angles' | 'off'
 
@@ -82,9 +81,9 @@ type SnapModeSet = { modes: SnappingMode[]; default: SnappingMode }
 const SNAP_PROFILES: Record<SnapContext, SnapModeSet> = {
   // Wall / fence drafting + endpoint reshape: direction matters → angle lock.
   wall: { modes: ['grid', 'lines', 'angles', 'off'], default: 'grid' },
-  // Item placement / move: grid by default; lines = magnetic alignment only (no
-  // grid lattice), no angle lock (meaningless for a footprint).
-  item: { modes: ['lines', 'grid', 'off'], default: 'grid' },
+  // Item placement / move: magnetic alignment by default; grid is an explicit
+  // alternative, and angle lock is meaningless for a footprint.
+  item: { modes: ['lines', 'grid', 'off'], default: 'lines' },
   // Structural / surface, no direction to set: slab / ceiling / roof draft+move,
   // whole wall/fence translate, curve reshape, polygon boundary edit. Grid by
   // default, NO angle lock.
@@ -148,6 +147,7 @@ export function snapContextOf(args: {
     nodeId?: string
     tool?: string
     handle?: string
+    operator?: string
   }
   mode: string
   tool: string | null
@@ -166,6 +166,10 @@ export function snapContextOf(args: {
     return 'item'
   }
   switch (scope.kind) {
+    case 'mesh-editing':
+      return scope.nodeId
+        ? contextForProfile(profileOfNode?.(scope.nodeId), scope.operator === 'rotate')
+        : null
     case 'handle-drag':
       if (scope.handle === ROTATE_HANDLE_DRAG_LABEL) return null
       return scope.nodeId ? contextForProfile(profileOfNode?.(scope.nodeId), false) : null

package/src/lib/usdz-export.ts

@@ -0,0 +1,38 @@
+import type { AnyNode } from '@pascal-app/core'
+import type { Object3D } from 'three'
+import { USDZExporter } from 'three/examples/jsm/exporters/USDZExporter.js'
+import * as WebGPUTextureUtils from 'three/examples/jsm/utils/WebGPUTextureUtils.js'
+import { type GlbExportOptions, preparePortableSceneFromViewer } from './glb-export'
+import { createUsdzScene, disposeExportResources } from './portable-export'
+
+export type UsdzExportOptions = Pick<
+  GlbExportOptions,
+  'excludedNodeTypes' | 'includedPresentationIds' | 'onlyVisible' | 'onWarning'
+>
+
+/** Export a native, self-contained USDZ with no glTF conversion fallback. */
+export async function exportSceneToUsdz(
+  sceneGroup: Object3D,
+  nodes: Record<string, AnyNode>,
+  options: UsdzExportOptions = {},
+): Promise<Uint8Array<ArrayBuffer>> {
+  const prepared = await preparePortableSceneFromViewer(sceneGroup, nodes, {
+    ...options,
+    textures: 'embed',
+  })
+  for (const warning of prepared.warnings) options.onWarning?.(warning)
+
+  let scene: Object3D | null = null
+  try {
+    scene = createUsdzScene(prepared.scene)
+    const exporter = new USDZExporter()
+    exporter.textureUtils = WebGPUTextureUtils
+    return await exporter.parseAsync(scene, {
+      onlyVisible: options.onlyVisible ?? true,
+      quickLookCompatible: true,
+    })
+  } finally {
+    if (scene) disposeExportResources(scene, { textures: false })
+    prepared.dispose()
+  }
+}

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