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

package/src/lib/units.ts

@@ -0,0 +1,254 @@
+import {
+  type AnyNode,
+  type AnyNodeId,
+  type BuildingNode,
+  type LevelNode,
+  pointInPolygon2D,
+  resolveAutoZonePolygon,
+  snapWorldXZToBuildingLocal,
+  UnitNode,
+  useScene,
+  type ZoneNode,
+} from '@pascal-app/core'
+import { useViewer } from '@pascal-app/viewer'
+import { useEffect } from 'react'
+import useEditor, { type StructureLayer } from '../store/use-editor'
+import { getActiveBuildingPose } from './world-grid-snap'
+
+type Nodes = Readonly<Record<AnyNodeId, AnyNode>>
+
+// Unit focus is a session gesture: the layer the user was on when focus began
+// comes back when focus ends, unless they switched layers by hand meanwhile.
+let restoreLayer: StructureLayer | null = null
+let entering = false
+let leaving = false
+
+export function focusedUnitNode(): UnitNode | null {
+  const id = useViewer.getState().focusedUnitId
+  const node = id ? useScene.getState().nodes[id] : undefined
+  return node?.type === 'unit' ? node : null
+}
+
+/** Levels carrying member zones, lowest ordinal first. */
+export function unitMemberLevels(unit: UnitNode, nodes: Nodes): LevelNode[] {
+  const levels = new Map<LevelNode['id'], LevelNode>()
+  for (const zoneId of unit.members) {
+    const zone = nodes[zoneId]
+    const level =
+      zone?.type === 'zone' && zone.parentId ? nodes[zone.parentId as AnyNodeId] : undefined
+    if (level?.type === 'level') levels.set(level.id, level)
+  }
+  return [...levels.values()].sort((a, b) => a.level - b.level)
+}
+
+export function enterUnitFocus(unitId: UnitNode['id']): void {
+  if (entering) return
+  entering = true
+  try {
+    const nodes = useScene.getState().nodes
+    const unit = nodes[unitId]
+    if (unit?.type !== 'unit') return
+    const editor = useEditor.getState()
+    if (restoreLayer === null) restoreLayer = editor.structureLayer
+    if (editor.phase !== 'structure') editor.setPhase('structure')
+    if (useEditor.getState().structureLayer !== 'zones') {
+      useEditor.getState().setStructureLayer('zones')
+    }
+    const viewer = useViewer.getState()
+    if (viewer.focusedUnitId !== unitId) viewer.setFocusedUnit(unitId)
+
+    const { selection, setSelection } = useViewer.getState()
+    const levels = unitMemberLevels(unit, nodes)
+    const levelId = levels.some((level) => level.id === selection.levelId)
+      ? selection.levelId
+      : (levels[0]?.id ?? selection.levelId)
+    const buildingId = (unit.parentId as BuildingNode['id'] | null) ?? selection.buildingId
+    const unitSelected = selection.selectedIds.length === 1 && selection.selectedIds[0] === unitId
+    if (selection.buildingId !== buildingId || selection.levelId !== levelId || !unitSelected) {
+      setSelection({ buildingId, levelId, selectedIds: [unitId] })
+    }
+  } finally {
+    entering = false
+  }
+}
+
+function finishLeave(unitId: UnitNode['id'], keepLayer: boolean) {
+  const layer = restoreLayer
+  restoreLayer = null
+  const editor = useEditor.getState()
+  if (
+    !keepLayer &&
+    layer &&
+    layer !== 'zones' &&
+    editor.phase === 'structure' &&
+    editor.structureLayer === 'zones'
+  ) {
+    editor.setStructureLayer(layer)
+  }
+  const { selection, setSelection } = useViewer.getState()
+  if (selection.selectedIds.length === 1 && selection.selectedIds[0] === unitId) {
+    setSelection({ selectedIds: [] })
+  }
+}
+
+/** Ends unit focus. Returns false when no unit was focused. */
+export function leaveUnitFocus(options?: { keepLayer?: boolean }): boolean {
+  const viewer = useViewer.getState()
+  const unitId = viewer.focusedUnitId
+  if (!unitId) return false
+  leaving = true
+  try {
+    viewer.setFocusedUnit(null)
+  } finally {
+    leaving = false
+  }
+  finishLeave(unitId, options?.keepLayer ?? false)
+  return true
+}
+
+/**
+ * Puts a zone in exactly one unit (or none): it leaves every other unit in the
+ * same store update, so the move is one undo step.
+ */
+export function assignZoneToUnit(zoneId: ZoneNode['id'], unitId: UnitNode['id'] | null): void {
+  const { nodes, updateNodes } = useScene.getState()
+  const updates: Array<{ id: AnyNodeId; data: Partial<AnyNode> }> = []
+  for (const node of Object.values(nodes)) {
+    if (node.type !== 'unit' || node.id === unitId || !node.members.includes(zoneId)) continue
+    updates.push({ id: node.id, data: { members: node.members.filter((id) => id !== zoneId) } })
+  }
+  const target = unitId ? nodes[unitId] : undefined
+  if (target?.type === 'unit' && !target.members.includes(zoneId)) {
+    updates.push({ id: target.id, data: { members: [...target.members, zoneId] } })
+  }
+  if (updates.length > 0) updateNodes(updates)
+}
+
+export function toggleZoneMembership(unitId: UnitNode['id'], zoneId: ZoneNode['id']): void {
+  const unit = useScene.getState().nodes[unitId]
+  if (unit?.type !== 'unit') return
+  assignZoneToUnit(zoneId, unit.members.includes(zoneId) ? null : unitId)
+}
+
+/**
+ * The zone under a point on the current level, in building-local XZ. A 3D
+ * click lands on whatever surface is closest (a floor slab sits above the
+ * zone fill), so painting resolves the zone from the hit point instead of the
+ * hit mesh. Nested zones resolve to the smallest one.
+ */
+export function zoneAtLevelPoint(x: number, z: number): ZoneNode | null {
+  const levelId = useViewer.getState().selection.levelId
+  if (!levelId) return null
+  const nodes = useScene.getState().nodes
+  const resolve = (id: AnyNodeId) => nodes[id]
+  let best: ZoneNode | null = null
+  let bestArea = Number.POSITIVE_INFINITY
+  for (const node of Object.values(nodes)) {
+    if (node.type !== 'zone' || node.parentId !== levelId) continue
+    const polygon = resolveAutoZonePolygon(node, resolve)
+    if (!pointInPolygon2D([x, z], polygon)) continue
+    let area = 0
+    for (let i = 0; i < polygon.length; i++) {
+      const a = polygon[i]!
+      const b = polygon[(i + 1) % polygon.length]!
+      area += a[0] * b[1] - b[0] * a[1]
+    }
+    area = Math.abs(area) / 2
+    if (area < bestArea) {
+      best = node
+      bestArea = area
+    }
+  }
+  return best
+}
+
+export function zoneAtWorldPoint(worldX: number, worldZ: number): ZoneNode | null {
+  const pose = getActiveBuildingPose()
+  const [x, z] = pose
+    ? snapWorldXZToBuildingLocal(worldX, worldZ, pose.position, pose.rotationY, 0).local
+    : [worldX, worldZ]
+  return zoneAtLevelPoint(x, z)
+}
+
+export const ZONE_PAINT_DELAY_MS = 250
+const pendingPaints = new Map<ZoneNode['id'], ReturnType<typeof setTimeout>>()
+
+/**
+ * The canvas paint gesture. The toggle waits out the double-click window so
+ * the second click of a double-click cancels it instead of toggling twice;
+ * the double-click itself then selects the zone.
+ */
+export function paintZoneMembership(unitId: UnitNode['id'], zoneId: ZoneNode['id']): void {
+  if (cancelPendingZonePaint(zoneId)) return
+  pendingPaints.set(
+    zoneId,
+    setTimeout(() => {
+      pendingPaints.delete(zoneId)
+      toggleZoneMembership(unitId, zoneId)
+    }, ZONE_PAINT_DELAY_MS),
+  )
+}
+
+export function cancelPendingZonePaint(zoneId: ZoneNode['id']): boolean {
+  const pending = pendingPaints.get(zoneId)
+  if (!pending) return false
+  clearTimeout(pending)
+  pendingPaints.delete(zoneId)
+  return true
+}
+
+export function createUnitInBuilding(buildingId: BuildingNode['id']): UnitNode['id'] | null {
+  const scene = useScene.getState()
+  const building = scene.nodes[buildingId]
+  if (building?.type !== 'building') return null
+  const unitCount = building.children.filter((id) => scene.nodes[id]?.type === 'unit').length
+  const unit = UnitNode.parse({ name: `Unit ${unitCount + 1}` })
+  scene.createNode(unit, buildingId)
+  enterUnitFocus(unit.id)
+  return unit.id
+}
+
+/**
+ * Keeps unit focus coherent with the rest of the editor: a focus set from
+ * anywhere (the unit inspector calls the viewer store directly) gets the full
+ * enter treatment, and focus ends when the user switches layer or phase by
+ * hand, selects anything other than the focused unit, or the unit is deleted.
+ */
+export function useUnitFocusRules(): void {
+  useEffect(() => {
+    const unsubscribeViewer = useViewer.subscribe((state, prev) => {
+      if (state.focusedUnitId !== prev.focusedUnitId) {
+        if (state.focusedUnitId) enterUnitFocus(state.focusedUnitId)
+        else if (prev.focusedUnitId && !leaving) finishLeave(prev.focusedUnitId, false)
+        return
+      }
+      const unitId = state.focusedUnitId
+      if (!unitId || state.selection === prev.selection) return
+      // Selecting a zone keeps focus: renaming or recolouring a zone row is
+      // part of arranging the unit, and zones live on the layer focus uses.
+      const { selectedIds } = state.selection
+      const selectsOther =
+        selectedIds.length > 0 && !(selectedIds.length === 1 && selectedIds[0] === unitId)
+      if (selectsOther) leaveUnitFocus()
+    })
+    const unsubscribeEditor = useEditor.subscribe((state, prev) => {
+      if (state.structureLayer === prev.structureLayer && state.phase === prev.phase) return
+      if (!useViewer.getState().focusedUnitId) return
+      if (state.phase !== 'structure' || state.structureLayer !== 'zones') {
+        leaveUnitFocus({ keepLayer: true })
+      }
+    })
+    const unsubscribeScene = useScene.subscribe((state, prev) => {
+      if (state.nodes === prev.nodes) return
+      const unitId = useViewer.getState().focusedUnitId
+      if (unitId && state.nodes[unitId]?.type !== 'unit') leaveUnitFocus()
+    })
+    return () => {
+      unsubscribeViewer()
+      unsubscribeEditor()
+      unsubscribeScene()
+      for (const pending of pendingPaints.values()) clearTimeout(pending)
+      pendingPaints.clear()
+    }
+  }, [])
+}

package/src/lib/usdz-export.ts

@@ -0,0 +1,65 @@
+import type { AnyNode } from '@pascal-app/core'
+import type { Object3D } from 'three'
+import { USDZExporter } from 'three/examples/jsm/exporters/USDZExporter.js'
+import { createExportTextureUtils } from './export-texture-utils'
+import {
+  DEFAULT_MODEL_EXPORT_TIMEOUT_MS,
+  type GlbExport,
+  type GlbExportOptions,
+  preparePortableSceneFromViewer,
+  withExportDeadline,
+} from './glb-export'
+import { createUsdzScene, disposeExportResources } from './portable-export'
+
+export type UsdzExportOptions = Pick<
+  GlbExportOptions,
+  'excludedNodeTypes' | 'includedPresentationIds' | 'onlyVisible' | 'onWarning' | 'timeoutMs'
+>
+
+/** 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 textureUtils = createExportTextureUtils()
+  const preparation = preparePortableSceneFromViewer(sceneGroup, nodes, {
+    ...options,
+    textures: 'embed',
+    animations: 'none',
+    textureUtils,
+  })
+  // Assigned inside the raced closure, so plain `let`s narrow to `never` in
+  // the `finally`.
+  const run: { prepared: GlbExport | null; scene: Object3D | null; abandoned: boolean } = {
+    prepared: null,
+    scene: null,
+    abandoned: false,
+  }
+  try {
+    return await withExportDeadline(
+      (async () => {
+        run.prepared = await preparation
+        if (run.abandoned) throw new Error('USDZ export abandoned')
+        for (const warning of run.prepared.warnings) options.onWarning?.(warning)
+        run.scene = createUsdzScene(run.prepared.scene)
+        const exporter = new USDZExporter()
+        exporter.textureUtils = textureUtils as unknown as USDZExporter['textureUtils']
+        return exporter.parseAsync(run.scene, {
+          onlyVisible: options.onlyVisible ?? true,
+          quickLookCompatible: true,
+        })
+      })(),
+      options.timeoutMs ?? DEFAULT_MODEL_EXPORT_TIMEOUT_MS,
+      'USDZ',
+      () => {
+        run.abandoned = true
+      },
+    )
+  } finally {
+    if (run.scene) disposeExportResources(run.scene, { textures: false })
+    if (run.prepared) run.prepared.dispose()
+    else preparation.then((late) => late.dispose()).catch(() => {})
+    await textureUtils.dispose()
+  }
+}

package/src/lib/use-linear-display.ts

@@ -1,40 +1,16 @@
 'use client'
 
 import { useViewer } from '@pascal-app/viewer'
-import { useCallback } from 'react'
-import { getLinearUnitLabel, linearUnitToMeters, metersToLinearUnit } from './measurements'
+import { useMemo } from 'react'
+import { getLinearDisplay } from './linear-display'
 
-/**
- * Shared display/storage conversion for numeric property controls so that
- * every length input honors the metric/imperial toggle identically.
- *
- * Values are always STORED in the field's own unit (meters for `unit === 'm'`).
- * When the viewer preference is imperial AND the field is a meter length, the
- * value is DISPLAYED (and edited) in feet; otherwise the conversions are the
- * identity, so metric fields and non-length units (`'°'`, `'%'`, `'in'`, `''`,
- * …) behave exactly as before.
- *
- * Used by both `SliderControl` and `MetricControl` — keep the two in sync via
- * this single source of truth.
- */
-export function useLinearDisplay(unit: string, precision: number) {
+/** Shared display/input conversion; values and bounds stay in the stored unit. */
+export function useLinearDisplay(unit: string, precision: number, step = 1) {
   const viewerUnit = useViewer((state) => state.unit)
-  const isImperial = viewerUnit === 'imperial' && unit === 'm'
-  const displayUnit = isImperial ? getLinearUnitLabel('imperial') : unit
+  const metricNotation = useViewer((state) => state.metricNotation)
 
-  const toDisplay = useCallback(
-    (stored: number) => (isImperial ? metersToLinearUnit(stored, 'imperial') : stored),
-    [isImperial],
+  return useMemo(
+    () => getLinearDisplay(unit, viewerUnit, metricNotation, precision, step),
+    [unit, viewerUnit, metricNotation, precision, step],
   )
-  const toStored = useCallback(
-    (display: number) => (isImperial ? linearUnitToMeters(display, 'imperial') : display),
-    [isImperial],
-  )
-  // Round a stored value so it lands on a clean number of DISPLAY-unit digits.
-  const roundStored = useCallback(
-    (stored: number) => toStored(Number.parseFloat(toDisplay(stored).toFixed(precision))),
-    [toDisplay, toStored, precision],
-  )
-
-  return { isImperial, displayUnit, toDisplay, toStored, roundStored }
 }

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