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

package/src/lib/camera-pose.test.ts

@@ -0,0 +1,237 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  normalizeCameraPose,
+  planCameraPoseApplication,
+  publishInitialCameraPose,
+  releaseCameraPoseEventSuppression,
+  stepCameraPoseInterpolation,
+  withCameraPoseDistance,
+} from './camera-pose'
+
+describe('camera pose', () => {
+  test('normalizes a finite pose without retaining input tuples', () => {
+    const position: [number, number, number] = [1, 2, 3]
+    const target: [number, number, number] = [4, 5, 6]
+    const pose = normalizeCameraPose({
+      position,
+      target,
+      projection: 'perspective',
+      fov: 50,
+      viewWidth: 12,
+    })
+
+    expect(pose).toEqual({
+      fov: 50,
+      position,
+      projection: 'perspective',
+      target,
+      viewWidth: 12,
+    })
+    expect(pose?.position).not.toBe(position)
+    expect(pose?.target).not.toBe(target)
+  })
+
+  test('rejects non-finite, malformed, and unknown camera poses', () => {
+    expect(normalizeCameraPose(null)).toBeNull()
+    expect(
+      normalizeCameraPose({
+        position: [1, 2],
+        target: [4, 5, 6],
+        projection: 'perspective',
+      }),
+    ).toBeNull()
+    expect(
+      normalizeCameraPose({
+        position: [1, Number.NaN, 3],
+        target: [4, 5, 6],
+        projection: 'perspective',
+      }),
+    ).toBeNull()
+    expect(
+      normalizeCameraPose({
+        position: [1, 2, 3],
+        target: [4, 5, Number.POSITIVE_INFINITY],
+        projection: 'perspective',
+      }),
+    ).toBeNull()
+    expect(
+      normalizeCameraPose({
+        position: [1, 2, 3],
+        target: [4, 5, 6],
+        projection: 'panoramic',
+      }),
+    ).toBeNull()
+    expect(
+      normalizeCameraPose({
+        position: [1, 2, 3],
+        target: [4, 5, 6],
+        projection: 'perspective',
+        fov: Number.NaN,
+      }),
+    ).toBeNull()
+    expect(
+      normalizeCameraPose({
+        position: [1, 2, 3],
+        target: [4, 5, 6],
+        projection: 'orthographic',
+        viewWidth: 0,
+      }),
+    ).toBeNull()
+    expect(
+      normalizeCameraPose({
+        position: [1, 2, 3],
+        target: [4, 5, 6],
+        projection: 'orthographic',
+        viewWidth: Number.POSITIVE_INFINITY,
+      }),
+    ).toBeNull()
+  })
+
+  test('plans only perspective fov application and clamps it to a safe range', () => {
+    expect(
+      planCameraPoseApplication({
+        position: [1, 2, 3],
+        target: [4, 5, 6],
+        projection: 'perspective',
+        fov: 0,
+      })?.perspectiveFov,
+    ).toBe(1)
+    expect(
+      planCameraPoseApplication({
+        position: [1, 2, 3],
+        target: [4, 5, 6],
+        projection: 'perspective',
+        fov: 200,
+      })?.perspectiveFov,
+    ).toBe(179)
+    expect(
+      planCameraPoseApplication({
+        position: [1, 2, 3],
+        target: [4, 5, 6],
+        projection: 'orthographic',
+        fov: 70,
+      })?.perspectiveFov,
+    ).toBeNull()
+  })
+
+  test('interpolates toward the latest pose and converges exactly', () => {
+    const destination = {
+      position: [12, 6, -4] as [number, number, number],
+      target: [2, 1, 3] as [number, number, number],
+      projection: 'perspective' as const,
+    }
+    const first = stepCameraPoseInterpolation([0, 0, 0], [0, 0, 0], destination, 0.016)
+    expect(first.settled).toBe(false)
+    expect(first.position[0]).toBeGreaterThan(0)
+    expect(first.position[0]).toBeLessThan(destination.position[0])
+
+    let position = first.position
+    let target = first.target
+    let settled = first.settled
+    for (let frame = 0; frame < 240 && !settled; frame += 1) {
+      const step = stepCameraPoseInterpolation(position, target, destination, 0.016)
+      position = step.position
+      target = step.target
+      settled = step.settled
+    }
+
+    expect(settled).toBe(true)
+    expect(position).toEqual(destination.position)
+    expect(target).toEqual(destination.target)
+  })
+
+  test('settles an already-current pose without advancing on an invalid delta', () => {
+    const destination = {
+      position: [1, 2, 3] as [number, number, number],
+      target: [4, 5, 6] as [number, number, number],
+      projection: 'orthographic' as const,
+    }
+    expect(
+      stepCameraPoseInterpolation(
+        destination.position,
+        destination.target,
+        destination,
+        Number.NaN,
+      ),
+    ).toEqual({
+      position: destination.position,
+      settled: true,
+      target: destination.target,
+    })
+    expect(stepCameraPoseInterpolation([0, 0, 0], [0, 0, 0], destination, Number.NaN)).toEqual({
+      position: [0, 0, 0],
+      settled: false,
+      target: [0, 0, 0],
+    })
+  })
+
+  test('publishes the initial pose before any camera control update event', () => {
+    let publishCount = 0
+
+    publishInitialCameraPose(() => {
+      publishCount += 1
+    })
+
+    expect(publishCount).toBe(1)
+  })
+
+  test('publishes the settled pose when programmatic interpolation releases suppression', () => {
+    const suppression = { current: true }
+    let publishCount = 0
+
+    releaseCameraPoseEventSuppression(suppression, () => {
+      publishCount += 1
+    })
+
+    expect(suppression.current).toBe(false)
+    expect(publishCount).toBe(1)
+  })
+
+  test('retargets the bounded interpolation owner to the latest pose', () => {
+    const first = stepCameraPoseInterpolation(
+      [0, 0, 0],
+      [0, 0, 0],
+      {
+        position: [10, 0, 0],
+        target: [5, 0, 0],
+        projection: 'perspective',
+      },
+      0.016,
+    )
+    const retargeted = stepCameraPoseInterpolation(
+      first.position,
+      first.target,
+      {
+        position: [-10, 0, 0],
+        target: [-5, 0, 0],
+        projection: 'perspective',
+      },
+      0.1,
+    )
+
+    expect(retargeted.position[0]).toBeLessThan(first.position[0])
+    expect(retargeted.target[0]).toBeLessThan(first.target[0])
+  })
+
+  test('preserves view direction while adapting distance to the local viewport', () => {
+    const pose = {
+      position: [4, 6, 12] as [number, number, number],
+      target: [1, 2, 3] as [number, number, number],
+      projection: 'perspective' as const,
+      viewWidth: 20,
+    }
+    const adapted = withCameraPoseDistance(pose, 5)
+    const sourceDirection = pose.position.map((value, index) => value - pose.target[index]!)
+    const adaptedDirection = adapted.position.map((value, index) => value - adapted.target[index]!)
+    const sourceLength = Math.hypot(...sourceDirection)
+
+    expect(Math.hypot(...adaptedDirection)).toBeCloseTo(5)
+    const expectedDirection = sourceDirection.map((component) => component * (5 / sourceLength))
+    expect(adaptedDirection[0]).toBeCloseTo(expectedDirection[0]!)
+    expect(adaptedDirection[1]).toBeCloseTo(expectedDirection[1]!)
+    expect(adaptedDirection[2]).toBeCloseTo(expectedDirection[2]!)
+    expect(adapted.target).toEqual(pose.target)
+    expect(adapted.target).not.toBe(pose.target)
+    expect(pose.position).toEqual([4, 6, 12])
+  })
+})

package/src/lib/camera-pose.ts

@@ -0,0 +1,172 @@
+import type { CameraPose } from '@pascal-app/core'
+
+const MIN_PERSPECTIVE_FOV = 1
+const MAX_PERSPECTIVE_FOV = 179
+const INTERPOLATION_TIME_CONSTANT_SECONDS = 0.08
+const MAX_INTERPOLATION_DELTA_SECONDS = 0.1
+const INTERPOLATION_SETTLE_DISTANCE = 0.001
+
+export type CameraPoseApplicationPlan = {
+  pose: CameraPose
+  perspectiveFov: number | null
+}
+
+export type CameraPoseInterpolationStep = {
+  position: [number, number, number]
+  settled: boolean
+  target: [number, number, number]
+}
+
+export function publishInitialCameraPose(publishCurrentPose: () => void): void {
+  publishCurrentPose()
+}
+
+export function releaseCameraPoseEventSuppression(
+  suppression: { current: boolean },
+  publishCurrentPose: () => void,
+): void {
+  suppression.current = false
+  publishCurrentPose()
+}
+
+function finiteVectorTuple(value: unknown): [number, number, number] | null {
+  if (
+    !(
+      Array.isArray(value) &&
+      value.length === 3 &&
+      value.every((component) => typeof component === 'number' && Number.isFinite(component))
+    )
+  ) {
+    return null
+  }
+
+  return [value[0], value[1], value[2]]
+}
+
+export function normalizeCameraPose(value: unknown): CameraPose | null {
+  if (!(typeof value === 'object' && value !== null)) {
+    return null
+  }
+
+  const candidate = value as Partial<CameraPose>
+  const position = finiteVectorTuple(candidate.position)
+  const target = finiteVectorTuple(candidate.target)
+  if (
+    !(
+      position &&
+      target &&
+      (candidate.projection === 'perspective' || candidate.projection === 'orthographic')
+    )
+  ) {
+    return null
+  }
+
+  if (
+    candidate.fov !== undefined &&
+    !(typeof candidate.fov === 'number' && Number.isFinite(candidate.fov))
+  ) {
+    return null
+  }
+
+  if (
+    candidate.viewWidth !== undefined &&
+    !(
+      typeof candidate.viewWidth === 'number' &&
+      Number.isFinite(candidate.viewWidth) &&
+      candidate.viewWidth > 0
+    )
+  ) {
+    return null
+  }
+
+  return {
+    ...(candidate.fov === undefined ? {} : { fov: candidate.fov }),
+    position,
+    projection: candidate.projection,
+    target,
+    ...(candidate.viewWidth === undefined ? {} : { viewWidth: candidate.viewWidth }),
+  }
+}
+
+export function planCameraPoseApplication(value: unknown): CameraPoseApplicationPlan | null {
+  const pose = normalizeCameraPose(value)
+  if (!pose) {
+    return null
+  }
+
+  return {
+    pose,
+    perspectiveFov:
+      pose.projection === 'perspective' && pose.fov !== undefined
+        ? Math.min(Math.max(pose.fov, MIN_PERSPECTIVE_FOV), MAX_PERSPECTIVE_FOV)
+        : null,
+  }
+}
+
+function interpolateVectorTuple(
+  current: [number, number, number],
+  destination: [number, number, number],
+  alpha: number,
+): { settled: boolean; value: [number, number, number] } {
+  const dx = destination[0] - current[0]
+  const dy = destination[1] - current[1]
+  const dz = destination[2] - current[2]
+  const settleDistanceSquared = INTERPOLATION_SETTLE_DISTANCE ** 2
+  if (dx * dx + dy * dy + dz * dz <= settleDistanceSquared) {
+    return { settled: true, value: [...destination] }
+  }
+
+  const value: [number, number, number] = [
+    current[0] + dx * alpha,
+    current[1] + dy * alpha,
+    current[2] + dz * alpha,
+  ]
+  const remainingX = destination[0] - value[0]
+  const remainingY = destination[1] - value[1]
+  const remainingZ = destination[2] - value[2]
+  const settled =
+    remainingX * remainingX + remainingY * remainingY + remainingZ * remainingZ <=
+    settleDistanceSquared
+
+  return { settled, value: settled ? [...destination] : value }
+}
+
+export function withCameraPoseDistance(pose: CameraPose, distance: number): CameraPose {
+  const dx = pose.position[0] - pose.target[0]
+  const dy = pose.position[1] - pose.target[1]
+  const dz = pose.position[2] - pose.target[2]
+  const currentDistance = Math.hypot(dx, dy, dz)
+  if (!(Number.isFinite(distance) && distance > 0 && currentDistance > 0)) {
+    return { ...pose, position: [...pose.position], target: [...pose.target] }
+  }
+
+  const scale = distance / currentDistance
+  return {
+    ...pose,
+    position: [
+      pose.target[0] + dx * scale,
+      pose.target[1] + dy * scale,
+      pose.target[2] + dz * scale,
+    ],
+    target: [...pose.target],
+  }
+}
+
+export function stepCameraPoseInterpolation(
+  currentPosition: [number, number, number],
+  currentTarget: [number, number, number],
+  destination: CameraPose,
+  deltaSeconds: number,
+): CameraPoseInterpolationStep {
+  const finiteDelta = Number.isFinite(deltaSeconds) ? deltaSeconds : 0
+  const elapsed = Math.min(Math.max(finiteDelta, 0), MAX_INTERPOLATION_DELTA_SECONDS)
+  const alpha = 1 - Math.exp(-elapsed / INTERPOLATION_TIME_CONSTANT_SECONDS)
+  const position = interpolateVectorTuple(currentPosition, destination.position, alpha)
+  const target = interpolateVectorTuple(currentTarget, destination.target, alpha)
+
+  return {
+    position: position.value,
+    settled: position.settled && target.settled,
+    target: target.value,
+  }
+}

package/src/lib/ceiling-plan-snap.ts

@@ -0,0 +1,24 @@
+import {
+  clearSurfacePlanSnapFeedback,
+  resolveSurfacePlanPointSnap,
+  SURFACE_ALIGNMENT_THRESHOLD_M,
+  type SurfacePlanSnapInput,
+  type SurfacePlanSnapResult,
+} from './surface-plan-snap'
+
+const CEILING_SNAP_MOVING_ID = '__ceiling_snap__'
+
+export const CEILING_ALIGNMENT_THRESHOLD_M = SURFACE_ALIGNMENT_THRESHOLD_M
+export type CeilingPlanSnapInput = SurfacePlanSnapInput
+export type CeilingPlanSnapResult = SurfacePlanSnapResult
+
+export function clearCeilingSnapFeedback() {
+  clearSurfacePlanSnapFeedback()
+}
+
+export function resolveCeilingPlanPointSnap(input: CeilingPlanSnapInput): CeilingPlanSnapResult {
+  return resolveSurfacePlanPointSnap({
+    ...input,
+    movingId: input.movingId ?? CEILING_SNAP_MOVING_ID,
+  })
+}

package/src/lib/contextual-help.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, test } from 'bun:test'
+import { resolveSelectModeHelpHints } from './contextual-help'
+
+describe('resolveSelectModeHelpHints', () => {
+  test('stays hidden in idle select mode with no selection', () => {
+    expect(
+      resolveSelectModeHelpHints({
+        selectedCount: 0,
+        hasMovableSelection: false,
+        hasRotatableSelection: false,
+        commandPressed: false,
+        shiftPressed: false,
+      }),
+    ).toEqual([])
+  })
+
+  test('shows multi-select guidance when a modifier is held without selection', () => {
+    expect(
+      resolveSelectModeHelpHints({
+        selectedCount: 0,
+        hasMovableSelection: false,
+        hasRotatableSelection: false,
+        commandPressed: true,
+        shiftPressed: false,
+      }),
+    ).toEqual([
+      {
+        keys: [['Cmd/Ctrl', 'Shift'], 'Left click'],
+        label: 'Add or remove objects from the selection',
+        active: true,
+      },
+    ])
+  })
+
+  test('shows direct manipulation tips for selected movable and rotatable nodes', () => {
+    const hints = resolveSelectModeHelpHints({
+      selectedCount: 1,
+      hasMovableSelection: true,
+      hasRotatableSelection: true,
+      commandPressed: false,
+      shiftPressed: false,
+    })
+
+    expect(hints).toContainEqual({
+      keys: ['Left click'],
+      label: 'Drag selected movable object',
+    })
+    expect(hints).toContainEqual({
+      keys: ['Cmd/Ctrl', 'Right click'],
+      label: 'Drag left or right to rotate selected object',
+    })
+    // Cmd/Ctrl and Shift click both toggle selection membership (3D selection
+    // manager and 2D floorplan alike) — advertised as a single or-group row.
+    expect(hints).toContainEqual({
+      keys: [['Cmd/Ctrl', 'Shift'], 'Left click'],
+      label: 'Add or remove objects from the selection',
+      active: false,
+    })
+  })
+
+  test('multi-selection advertises the group move + rotate gestures', () => {
+    const hints = resolveSelectModeHelpHints({
+      selectedCount: 3,
+      hasMovableSelection: true,
+      hasRotatableSelection: true,
+      commandPressed: false,
+      shiftPressed: false,
+    })
+
+    expect(hints).toEqual([
+      {
+        keys: ['Left click'],
+        label: 'Click or drag the selection to move it as one',
+      },
+      { keys: ['R / T'], label: 'Rotate the selection ±45°' },
+      {
+        keys: [['Cmd/Ctrl', 'Shift'], 'Left click'],
+        label: 'Add or remove objects from the selection',
+        active: false,
+      },
+      { keys: ['Esc'], label: 'Clear the selection (or click outside)' },
+    ])
+  })
+
+  test('holding a modifier keeps the same rows and only lights the selection one', () => {
+    // Guides/snapping are governed by the snapping mode (Shift toggles it),
+    // so no modifier-specific "freely / with guides / bypass" variants exist.
+    const hints = resolveSelectModeHelpHints({
+      selectedCount: 1,
+      hasMovableSelection: true,
+      hasRotatableSelection: true,
+      commandPressed: true,
+      shiftPressed: true,
+    })
+
+    expect(hints).toEqual([
+      {
+        keys: ['Left click'],
+        label: 'Drag selected movable object',
+      },
+      {
+        keys: ['Cmd/Ctrl', 'Right click'],
+        label: 'Drag left or right to rotate selected object',
+      },
+      {
+        keys: [['Cmd/Ctrl', 'Shift'], 'Left click'],
+        label: 'Add or remove objects from the selection',
+        active: true,
+      },
+    ])
+  })
+})

package/src/lib/contextual-help.ts

@@ -0,0 +1,144 @@
+export type ContextualShortcutHint = {
+  // A combo of keys pressed together (rendered joined by "+"). An entry may
+  // itself be an array of alternatives (rendered joined by "/"), e.g.
+  // [['Cmd/Ctrl', 'Shift'], 'Left click'] → "⌘ / ⇧ + click".
+  keys: Array<string | string[]>
+  label: string
+  // Optional secondary line under the label for a terser qualifier
+  // (e.g. "disable 15° snap"). The HUD wraps both lines rather than truncating.
+  subtitle?: string
+  active?: boolean
+}
+
+// `activeHandleDrag.label` value a rotate gizmo sets while dragging, so the
+// contextual HUD can surface the Shift = free-rotation toggle for the duration
+// (mirrors how wall drafting advertises Shift). Distinct from resize handles,
+// which route their own measurement label here.
+export const ROTATE_HANDLE_DRAG_LABEL = 'rotate-handle'
+
+// `activeHandleDrag.label` a plain resize / radial-resize arrow sets while
+// dragging (when it carries no dimension `measureLabel`). It exists only so the
+// interaction scope is non-idle during a resize, which keeps the idle
+// select-mode hints off-screen — a resize is its own action, not a selection.
+export const RESIZE_HANDLE_DRAG_LABEL = 'resize-handle'
+
+// `activeHandleDrag.label`s for the multi-selection group drags: the body
+// drag sessions (2D floorplan + 3D ground plane) and the rotate gizmo. Kept
+// here (not in the session/gizmo modules) so `snapping-mode.ts` can resolve
+// the group move to the 'item' snap context without importing component code.
+export const GROUP_MOVE_DRAG_LABEL = 'group-move-handle'
+export const GROUP_ROTATE_DRAG_LABEL = 'group-rotate-handle'
+
+// Hints shown while a rotate gizmo is mid-drag: Shift bypasses the angle step
+// (free rotation), the same toggle wall drafting exposes. `active` lights the
+// pill while Shift is held.
+export function resolveRotateHandleHelpHints(shiftPressed: boolean): ContextualShortcutHint[] {
+  return [
+    {
+      keys: [SHIFT_KEY],
+      label: shiftPressed ? 'Rotating freely (no angle step)' : 'Hold to rotate freely',
+      active: shiftPressed,
+    },
+  ]
+}
+
+export type SelectModeHelpContext = {
+  selectedCount: number
+  hasMovableSelection: boolean
+  hasRotatableSelection: boolean
+  commandPressed: boolean
+  shiftPressed: boolean
+  // When a single MEP node is selected its in-world handle rig (click a dot to
+  // reveal move arrows) is the real editing path, so the panel leads with the
+  // handle-specific hints instead of just the generic Cmd-drag tips.
+  mepSelection?: 'run' | 'fitting' | null
+}
+
+const COMMAND_KEY = 'Cmd/Ctrl'
+const LEFT_CLICK = 'Left click'
+const RIGHT_CLICK = 'Right click'
+const SHIFT_KEY = 'Shift'
+const CLICK = 'Click'
+const ALT_KEY = 'Alt'
+const ROTATE_KEYS = 'R / T'
+const ESC_KEY = 'Esc'
+
+export function resolveSelectModeHelpHints({
+  selectedCount,
+  hasMovableSelection,
+  hasRotatableSelection,
+  commandPressed,
+  shiftPressed,
+  mepSelection = null,
+}: SelectModeHelpContext): ContextualShortcutHint[] {
+  const hints: ContextualShortcutHint[] = []
+
+  if (selectedCount === 0) {
+    if (!commandPressed && !shiftPressed) return hints
+
+    hints.push({
+      keys: [[COMMAND_KEY, SHIFT_KEY], LEFT_CLICK],
+      label: 'Add or remove objects from the selection',
+      active: true,
+    })
+    return hints
+  }
+
+  // Multi-selection — advertise the group gestures: drag any member to slide
+  // the whole selection (2D floor plan body drag + the 3D move gizmo), R / T
+  // to step-rotate the group around its bounding-box center.
+  if (selectedCount > 1) {
+    hints.push({
+      keys: [LEFT_CLICK],
+      label: 'Click or drag the selection to move it as one',
+    })
+    hints.push({ keys: [ROTATE_KEYS], label: 'Rotate the selection ±45°' })
+    hints.push({
+      keys: [[COMMAND_KEY, SHIFT_KEY], LEFT_CLICK],
+      label: 'Add or remove objects from the selection',
+      active: commandPressed || shiftPressed,
+    })
+    hints.push({ keys: [ESC_KEY], label: 'Clear the selection (or click outside)' })
+    return hints
+  }
+
+  // MEP handle workflow — duct/pipe runs and fittings are edited through the
+  // in-world arrow rig that a click on the handle dot reveals, so surface those
+  // hints first. A run endpoint's side / up-down arrows swing the run and Alt
+  // detaches the joint mid-drag; a fitting's cluster adds rotate arcs, with
+  // R / T (and Alt to switch axis) for keyboard rotation.
+  if (mepSelection === 'run') {
+    hints.push({ keys: [CLICK], label: 'Click a handle dot to show move arrows' })
+    hints.push({ keys: [ALT_KEY], label: 'Detach the joint while dragging an arrow' })
+  } else if (mepSelection === 'fitting') {
+    hints.push({ keys: [CLICK], label: 'Click the handle dot to show move + rotate handles' })
+    hints.push({ keys: [ROTATE_KEYS], label: 'Rotate ±45°' })
+    hints.push({ keys: [ALT_KEY], label: 'Switch the rotation axis (Y → X → Z)' })
+  }
+
+  // The rows are the same whatever modifier is held — guides/snapping are
+  // governed by the snapping mode (Shift toggles it), not by the modifier of
+  // this gesture, so there are no modifier-specific variants to advertise.
+  // Holding Cmd/Ctrl or Shift just lights the selection row.
+  if (hasMovableSelection) {
+    hints.push({
+      keys: [LEFT_CLICK],
+      label: 'Drag selected movable object',
+    })
+  }
+
+  if (hasRotatableSelection) {
+    hints.push({
+      keys: [COMMAND_KEY, RIGHT_CLICK],
+      label: 'Drag left or right to rotate selected object',
+    })
+  }
+
+  hints.push({
+    keys: [[COMMAND_KEY, SHIFT_KEY], LEFT_CLICK],
+    label: 'Add or remove objects from the selection',
+    active: commandPressed || shiftPressed,
+  })
+
+  return hints
+}