@pascal-app/editor 0.9.2 → 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/direct-manipulation.test.ts

@@ -11,6 +11,7 @@ import {
   canDirectMoveNode,
   resolveDirectManipulationNode,
   resolveDirectRotationDragDelta,
+  resolveMoveActionNode,
   snapDirectRotationDelta,
 } from './direct-manipulation'
 
@@ -190,3 +191,85 @@ describe('resolveDirectManipulationNode', () => {
     ).toBe(parent)
   })
 })
+
+describe('resolveMoveActionNode', () => {
+  test('routes a nested same-kind child move to its host', () => {
+    const kind = 'move-action-nested-kind-test'
+    registerTestDefinition(kind, {
+      capabilities: {
+        movable: {
+          axes: ['x', 'z'],
+          parentFrame: {
+            resolveParent: (node: AnyNode, nodes: Readonly<Record<string, AnyNode>>) =>
+              (node.parentId ? nodes[node.parentId] : null) ?? null,
+            parentRotationY: () => 0,
+            localToPlan: (_parent: AnyNode, local: readonly [number, number, number]) => [
+              local[0],
+              local[1],
+              local[2],
+            ],
+            planToLocal: (_parent: AnyNode, planX: number, localY: number, planZ: number) => [
+              planX,
+              localY,
+              planZ,
+            ],
+          },
+        },
+      },
+    })
+    const parent = { id: 'move_action_parent', type: kind } as unknown as AnyNode
+    const child = {
+      id: 'move_action_child',
+      type: kind,
+      parentId: parent.id,
+    } as unknown as AnyNode
+
+    expect(
+      resolveMoveActionNode(child, {
+        [parent.id]: parent,
+        [child.id]: child,
+      }),
+    ).toBe(parent)
+  })
+
+  test('keeps a child independently movable when its parent is a different kind', () => {
+    const parentKind = 'move-action-parent-kind-test'
+    const childKind = 'move-action-child-kind-test'
+    registerTestDefinition(parentKind, {})
+    registerTestDefinition(childKind, {
+      capabilities: {
+        movable: {
+          axes: ['x', 'z'],
+          parentFrame: {
+            resolveParent: (node: AnyNode, nodes: Readonly<Record<string, AnyNode>>) =>
+              (node.parentId ? nodes[node.parentId] : null) ?? null,
+            parentRotationY: () => 0,
+            localToPlan: (_parent: AnyNode, local: readonly [number, number, number]) => [
+              local[0],
+              local[1],
+              local[2],
+            ],
+            planToLocal: (_parent: AnyNode, planX: number, localY: number, planZ: number) => [
+              planX,
+              localY,
+              planZ,
+            ],
+          },
+        },
+      },
+    })
+    const parent = { id: 'move_action_run', type: parentKind } as unknown as AnyNode
+    const child = {
+      id: 'move_action_module',
+      type: childKind,
+      parentId: parent.id,
+    } as unknown as AnyNode
+
+    expect(
+      resolveMoveActionNode(child, {
+        [parent.id]: parent,
+        [child.id]: child,
+      }),
+    ).toBe(child)
+  })
+})

package/src/lib/direct-manipulation.ts

@@ -74,6 +74,15 @@ export function resolveDirectManipulationNode(
   return parent && canDirectRotateNode(parent) ? parent : target
 }
 
+export function resolveMoveActionNode(
+  node: AnyNode,
+  nodes: Readonly<Record<string, AnyNode | undefined>>,
+): AnyNode {
+  const parentFrame = nodeRegistry.get(node.type)?.capabilities?.movable?.parentFrame
+  const parent = parentFrame?.resolveParent(node, nodes as Readonly<Record<string, AnyNode>>)
+  return parent?.type === node.type ? parent : node
+}
+
 export function snapDirectRotationDelta(delta: number, free: boolean): number {
   return free ? delta : Math.round(delta / DEFAULT_ANGLE_STEP) * DEFAULT_ANGLE_STEP
 }

package/src/lib/door-interaction.ts

@@ -15,7 +15,7 @@ type DoorOpenAnimationOptions = {
   persist?: boolean
 }
 
-function getDisplayedDoorValue(
+export function getDisplayedDoorValue(
   doorId: AnyNodeId,
   field: keyof DoorInteractiveState,
   nodeValue: number | undefined,

package/src/lib/elevation-guides.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, test } from 'bun:test'
+import { type AnyNode, CeilingNode, LevelNode, SlabNode } from '@pascal-app/core'
+import useElevationGuides from '../store/use-elevation-guides'
+import {
+  clearStructuralElevationGuide,
+  collectElevationSnapTargets,
+  publishStructuralElevationGuide,
+  resolveElevationSnapMatch,
+  resolveStructuralElevationSnap,
+} from './elevation-guides'
+
+function structuralScene() {
+  const rawLevel = LevelNode.parse({ level: 0, height: 3 })
+  const slab = SlabNode.parse({
+    parentId: rawLevel.id,
+    polygon: [
+      [2, -1],
+      [4, -1],
+      [4, 1],
+      [2, 1],
+    ],
+    elevation: 0.6,
+    thickness: 0.2,
+  })
+  const ceiling = CeilingNode.parse({
+    parentId: rawLevel.id,
+    polygon: [
+      [-4, -1],
+      [-2, -1],
+      [-2, 1],
+      [-4, 1],
+    ],
+    height: 2.4,
+  })
+  const level = { ...rawLevel, children: [slab.id, ceiling.id] }
+  const nodes: Record<string, AnyNode> = {
+    [level.id]: level,
+    [slab.id]: slab,
+    [ceiling.id]: ceiling,
+  }
+  return { ceiling, level, nodes, slab }
+}
+
+describe('elevation guides', () => {
+  test('collects the level, slab faces, and ceiling plane on the source level', () => {
+    const { level, nodes, slab } = structuralScene()
+    const targets = collectElevationSnapTargets(
+      { nodeId: 'wall_moving', levelId: level.id, anchor: [0, 0] },
+      nodes,
+    )
+
+    expect(targets.map((target) => [target.label, target.elevation])).toEqual([
+      ['Level', 0],
+      ['Slab top', 0.6],
+      ['Slab underside', 0.39999999999999997],
+      ['Ceiling', 2.4],
+    ])
+
+    const withoutSelf = collectElevationSnapTargets(
+      { nodeId: slab.id, levelId: level.id, anchor: [0, 0] },
+      nodes,
+    )
+    expect(withoutSelf.some((target) => target.id.startsWith(slab.id))).toBe(false)
+  })
+
+  test('snaps inside the Y tolerance and leaves values outside it alone', () => {
+    const { level, nodes } = structuralScene()
+    const source = { nodeId: 'wall_moving', levelId: level.id, anchor: [0, 0] } as const
+
+    expect(resolveStructuralElevationSnap(source, 0.54, nodes)).toBe(0.6)
+    expect(resolveStructuralElevationSnap(source, 0.49, nodes)).toBe(0.49)
+    expect(resolveStructuralElevationSnap(source, 2.34, nodes)).toBe(2.4)
+  })
+
+  test('uses plan distance to disambiguate datums at the same elevation', () => {
+    const match = resolveElevationSnapMatch(
+      1,
+      [0, 0],
+      [
+        { id: 'far', elevation: 1, anchor: [10, 0], label: 'Far' },
+        { id: 'near', elevation: 1, anchor: [2, 0], label: 'Near' },
+      ],
+    )
+
+    expect(match?.target.id).toBe('near')
+  })
+
+  test('publishes one owner-scoped guide only while exactly aligned', () => {
+    const { level, nodes } = structuralScene()
+    const source = { nodeId: 'wall_moving', levelId: level.id, anchor: [0, 0] } as const
+    useElevationGuides.setState({ guide: null })
+
+    publishStructuralElevationGuide(source, 0.6, nodes)
+    expect(useElevationGuides.getState().guide).toMatchObject({
+      ownerId: 'wall_moving',
+      elevation: 0.6,
+      label: 'Slab top',
+      direction: [1, 0],
+    })
+
+    clearStructuralElevationGuide('someone_else')
+    expect(useElevationGuides.getState().guide).not.toBeNull()
+
+    publishStructuralElevationGuide(source, 0.7, nodes)
+    expect(useElevationGuides.getState().guide).toBeNull()
+  })
+})