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

package/src/components/tools/registry/item-surface-move.ts

@@ -0,0 +1,441 @@
+import {
+  type AnyNode,
+  type AnyNodeId,
+  createSceneApi,
+  findLevelAncestorId,
+  type GridEvent,
+  NON_PHYSICAL_HOST_KINDS,
+  type NodeEvent,
+  nodeRegistry,
+  resolveSurfacePlacement,
+  sceneRegistry,
+  useLiveTransforms,
+  useScene,
+} from '@pascal-app/core'
+import { boxCorners } from '@pascal-app/core/procedural-items'
+import { type Camera, Euler, Quaternion, Vector3 } from 'three'
+import { isFreshPlacementMetadata } from '../../../lib/placement-metadata'
+import {
+  surfaceAttachmentId,
+  surfaceFramePose,
+  updateSurfaceNode,
+} from '../../../lib/surface-attachment'
+import { snapToGrid, snapToHalf } from '../item/placement-math'
+import { createShelfStickiness } from '../shared/shelf-stickiness'
+import { itemEventToSurfaceHit } from '../shared/surface-hit'
+import { createSurfaceRejectionFeedback } from '../shared/surface-rejection'
+
+export function createItemSurfacePointerArbitration() {
+  let hostId: string | null = null
+  let hitEvent: object | null = null
+  return {
+    hit(id: string, event: object) {
+      hostId = id
+      hitEvent = event
+    },
+    clear() {
+      hostId = null
+      hitEvent = null
+    },
+    blocksGrid(event: object) {
+      return hostId !== null && event === hitEvent
+    },
+  }
+}
+
+function pointerEventOf(event: GridEvent | NodeEvent<AnyNode>): object {
+  return event.nativeEvent.nativeEvent ?? event.nativeEvent
+}
+
+export function createItemSurfaceGridDispatch(apply: (event: GridEvent) => void) {
+  let pending: GridEvent | null = null
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const cancel = () => {
+    clearTimeout(timer)
+    timer = undefined
+    pending = null
+  }
+  const flush = () => {
+    const event = pending
+    cancel()
+    if (event) apply(event)
+  }
+  return {
+    schedule(event: GridEvent) {
+      pending = event
+      // Canvas grid listeners precede R3F's wrapper listener. A task waits for both;
+      // a microtask can run between native DOM listeners, before the host hit arrives.
+      if (timer === undefined) timer = setTimeout(flush, 0)
+    },
+    flush,
+    cancel,
+  }
+}
+
+export type ItemSurfaceGrab = {
+  hostId: string
+  start: [number, number, number]
+  anchor: [number, number, number] | null
+}
+
+export function resolveItemSurfaceGrab(
+  grab: ItemSurfaceGrab | null,
+  hostId: string,
+  raw: [number, number, number],
+): { grab: ItemSurfaceGrab | null; position: [number, number, number] } {
+  if (!grab || grab.hostId !== hostId) return { grab: null, position: raw }
+  const anchor = grab.anchor ?? raw
+  return {
+    grab: { ...grab, anchor },
+    position: [grab.start[0] + (raw[0] - anchor[0]), raw[1], grab.start[2] + (raw[2] - anchor[2])],
+  }
+}
+
+function parentWorldYaw(parentId: string | null | undefined): number {
+  const mesh = parentId ? sceneRegistry.nodes.get(parentId) : undefined
+  return mesh
+    ? new Euler().setFromQuaternion(mesh.getWorldQuaternion(new Quaternion()), 'YXZ').y
+    : 0
+}
+
+export function createRegistryItemSurfaceMove(node: AnyNode) {
+  const capabilities = nodeRegistry.get(node.type)?.capabilities
+  const floorPlaced = capabilities?.floorPlaced
+  if (!floorPlaced || (floorPlaced.applies && !floorPlaced.applies(node))) return null
+
+  const original = node as AnyNode & {
+    position: [number, number, number]
+    rotation: number | [number, number, number]
+    supportSlabId?: string
+  }
+  const originalSurfaceId = surfaceAttachmentId(node)
+  let changed = false
+  let valid = true
+  const feedback = createSurfaceRejectionFeedback()
+  const scene = createSceneApi(useScene)
+  const pointer = createItemSurfacePointerArbitration()
+  const originalParent = original.parentId
+    ? useScene.getState().nodes[original.parentId as AnyNodeId]
+    : null
+  const initialGrab = (): ItemSurfaceGrab | null =>
+    originalParent &&
+    !NON_PHYSICAL_HOST_KINDS.includes(originalParent.type) &&
+    !isFreshPlacementMetadata(original.metadata)
+      ? {
+          hostId: originalParent.id,
+          start: surfaceFramePose(
+            original.parentId,
+            originalSurfaceId,
+            {
+              position: original.position,
+              rotation: Array.isArray(original.rotation)
+                ? original.rotation
+                : [0, original.rotation, 0],
+            },
+            false,
+          ).position,
+          anchor: null,
+        }
+      : null
+  let grab = initialGrab()
+  const cursorRayIntersectsShelf = createShelfStickiness()
+  const liveNode = () => useScene.getState().nodes[node.id] ?? node
+  const levelId = () => findLevelAncestorId(node.id, useScene.getState().nodes)
+  const rotation = (yaw: number) =>
+    Array.isArray(original.rotation)
+      ? ([original.rotation[0], yaw, original.rotation[2]] as [number, number, number])
+      : yaw
+  const write = (
+    parentId: string | null | undefined,
+    position: [number, number, number],
+    yaw: number,
+    fullRotation?: readonly [number, number, number],
+    surfaceId?: string | null,
+  ) => {
+    changed = true
+    // Hosted renderers and floorplan builders need the same parent-local pose.
+    updateSurfaceNode(
+      node.id,
+      {
+        parentId,
+        position,
+        rotation: fullRotation ? [...fullRotation] : rotation(yaw),
+        supportSlabId: undefined,
+      } as Partial<AnyNode>,
+      surfaceId,
+    )
+    useLiveTransforms.getState().clear(node.id)
+  }
+  const session = {
+    get rejection() {
+      return feedback.reason
+    },
+    clearRejectionForGrid(event: GridEvent) {
+      feedback.grid(pointerEventOf(event))
+    },
+    get valid() {
+      return valid && !feedback.reason
+    },
+    get hosted() {
+      const parentId = liveNode().parentId
+      const parent = parentId ? useScene.getState().nodes[parentId as AnyNodeId] : null
+      return !!parent && !NON_PHYSICAL_HOST_KINDS.includes(parent.type)
+    },
+    worldYaw(yaw: number) {
+      const live = liveNode() as typeof original
+      const pose = surfaceFramePose(
+        live.parentId,
+        surfaceAttachmentId(live),
+        { position: live.position, rotation: [0, yaw, 0] },
+        false,
+      )
+      return pose.rotation[1] + parentWorldYaw(live.parentId)
+    },
+    planPose(position: [number, number, number], yaw: number) {
+      const parentId = liveNode().parentId
+      const parentMesh = parentId ? sceneRegistry.nodes.get(parentId) : undefined
+      const level = levelId()
+      const levelMesh = level ? sceneRegistry.nodes.get(level) : undefined
+      const local = surfaceFramePose(
+        parentId,
+        surfaceAttachmentId(liveNode()),
+        { position, rotation: [0, yaw, 0] },
+        false,
+      )
+      const point = new Vector3(...local.position)
+      parentMesh?.localToWorld(point)
+      levelMesh?.worldToLocal(point)
+      return {
+        position: [point.x, point.y, point.z] as [number, number, number],
+        rotationY: session.worldYaw(yaw) - parentWorldYaw(level),
+      }
+    },
+    enter(event: NodeEvent<AnyNode>, dimensions: [number, number, number], yaw: number) {
+      pointer.clear()
+      feedback.clear()
+      const live = liveNode()
+      if (floorPlaced.applies && !floorPlaced.applies(live)) return null
+      const host = useScene.getState().nodes[event.node.id]
+      if (!host || NON_PHYSICAL_HOST_KINDS.includes(host.type)) return null
+      let ancestor: AnyNode | undefined = host
+      while (ancestor) {
+        if (ancestor.id === node.id) return null
+        ancestor = ancestor.parentId ? scene.get(ancestor.parentId as AnyNodeId) : undefined
+      }
+      const mesh = sceneRegistry.nodes.get(host.id)
+      if (!mesh) return null
+      const raw = mesh.worldToLocal(new Vector3(...event.position)).toArray()
+      const corrected = resolveItemSurfaceGrab(grab, host.id, raw)
+      const position = mesh.localToWorld(new Vector3(...corrected.position)).toArray()
+      // Keep the legacy world round-trip so existing poses retain identical floating-point values.
+      const hit = itemEventToSurfaceHit(host, { ...event, position })
+      if (!hit) return null
+      const counterHit =
+        host.type === 'cabinet' || host.type === 'procedural-item'
+          ? itemEventToSurfaceHit(host, event)
+          : null
+      const stayingOnShelf = host.type === 'shelf' && live.parentId === host.id
+      const localYaw = session.worldYaw(yaw) - parentWorldYaw(host.id)
+      const bounds = capabilities?.dragBounds?.(live, scene.nodes())
+      const center = bounds?.center
+      const localRotation = rotation(localYaw)
+      const offset = center
+        ? new Vector3(...center).applyEuler(
+            new Euler(
+              ...(Array.isArray(localRotation) ? localRotation : ([0, localYaw, 0] as const)),
+            ),
+          )
+        : new Vector3()
+      if (host.type !== 'item') {
+        const origin = [...hit.point]
+        if (!corrected.grab) {
+          origin[0]! -= offset.x
+          origin[2]! -= offset.z
+        }
+        hit.point = [
+          snapToGrid(origin[0]! + offset.x, dimensions[0]) - offset.x,
+          origin[1]!,
+          snapToGrid(origin[2]! + offset.z, dimensions[2]) - offset.z,
+        ]
+        if (stayingOnShelf) hit.normalWorldY = 1
+      }
+      const placement = resolveSurfacePlacement({
+        host,
+        childKind: node.type,
+        childFootprint: {
+          size: dimensions,
+          rotationY: localYaw,
+          rotation: Array.isArray(localRotation) ? localRotation : [0, localYaw, 0],
+          localBounds: center
+            ? {
+                min: center.map((v, i) => v - dimensions[i]! / 2) as [number, number, number],
+                max: center.map((v, i) => v + dimensions[i]! / 2) as [number, number, number],
+              }
+            : undefined,
+        },
+        hit: counterHit ?? hit,
+        origin: counterHit ? hit.point : undefined,
+        scene,
+        snapScalar: host.type !== 'item' ? undefined : snapToGrid,
+        checkFootprint: true,
+        onReject: (reason) => feedback.reject(reason, pointerEventOf(event)),
+      })
+      if (!placement) return null
+      valid = true
+      const childPose =
+        placement.childFrame === 'surface-local' ? placement.surfaceLocal : placement
+      if (!childPose) return null
+      const pose = {
+        position: [...childPose.position] as [number, number, number],
+        rotationY: childPose.rotationY,
+        worldPosition: mesh.localToWorld(new Vector3(...placement.position)).toArray(),
+      }
+      grab = corrected.grab
+      pointer.hit(host.id, pointerEventOf(event))
+      event.stopPropagation()
+      write(
+        host.id,
+        pose.position,
+        pose.rotationY,
+        placement.childFrame === 'surface-local' ? placement.surfaceLocal?.rotation : undefined,
+        placement.surfaceId,
+      )
+      return pose
+    },
+    blocksGrid(event: GridEvent, camera?: Camera) {
+      return (
+        session.hosted &&
+        (pointer.blocksGrid(pointerEventOf(event)) ||
+          Boolean(camera && cursorRayIntersectsShelf(liveNode().parentId, camera, event.position)))
+      )
+    },
+    leave(event: NodeEvent<AnyNode>, yaw: number) {
+      if (event.node.id !== liveNode().parentId) return null
+      if (event.node.type === 'shelf' || event.node.type === 'cabinet') return null
+      return session.detach(event.position, yaw)
+    },
+    detach(worldPosition: [number, number, number], yaw: number) {
+      if (!session.hosted) return null
+      const level = levelId()
+      if (!level) return null
+      pointer.clear()
+      feedback.clear()
+      valid = true
+      grab = null
+      const point = new Vector3(...worldPosition)
+      sceneRegistry.nodes.get(level)?.worldToLocal(point)
+      const rotationY = session.worldYaw(yaw) - parentWorldYaw(level)
+      const position: [number, number, number] = [snapToHalf(point.x), 0, snapToHalf(point.z)]
+      write(level, position, rotationY)
+      return { position, rotationY }
+    },
+    rotate(yaw: number) {
+      if (!session.hosted) return null
+      const live = liveNode() as typeof original
+      const position: [number, number, number] = [...live.position]
+      const host = live.parentId ? scene.get(live.parentId as AnyNodeId) : undefined
+      const storedRotation = Array.isArray(live.rotation)
+        ? ([live.rotation[0], yaw, live.rotation[2]] as [number, number, number])
+        : ([0, yaw, 0] as [number, number, number])
+      const local = surfaceFramePose(
+        live.parentId,
+        surfaceAttachmentId(live),
+        { position, rotation: storedRotation },
+        false,
+      )
+      if (host?.type === 'procedural-item') position.splice(0, 3, ...local.position)
+      if (
+        host?.type === 'cabinet' ||
+        host?.type === 'shelf' ||
+        host?.type === 'item' ||
+        host?.type === 'procedural-item'
+      ) {
+        const footprint = floorPlaced.footprint?.(live, { nodes: scene.nodes() })
+        const bounds:
+          | { size: [number, number, number]; center?: [number, number, number] }
+          | undefined =
+          capabilities?.dragBounds?.(live, scene.nodes()) ??
+          (footprint ? { size: footprint.dimensions } : undefined)
+        if (!bounds) return null
+        const center = bounds.center ?? [0, bounds.size[1] / 2, 0]
+        const localRotation = host.type === 'procedural-item' ? local.rotation : rotation(yaw)
+        const euler = new Euler(
+          ...(Array.isArray(localRotation) ? localRotation : ([0, yaw, 0] as const)),
+        )
+        const offset = new Vector3(...center).applyEuler(euler)
+        const localBounds = {
+          min: center.map((v, i) => v - bounds.size[i]! / 2) as [number, number, number],
+          max: center.map((v, i) => v + bounds.size[i]! / 2) as [number, number, number],
+        }
+        const bottom = Math.min(
+          ...boxCorners(localBounds.min, localBounds.max).map(
+            (point) => new Vector3(...point).applyEuler(euler).y,
+          ),
+        )
+        feedback.clear()
+        const placement = resolveSurfacePlacement({
+          host,
+          childKind: live.type,
+          childFootprint: {
+            size: bounds.size,
+            rotationY: Array.isArray(localRotation) ? localRotation[1] : localRotation,
+            rotation: Array.isArray(localRotation) ? localRotation : [0, yaw, 0],
+            localBounds,
+          },
+          hit: {
+            point:
+              host.type === 'item'
+                ? position
+                : [position[0] + offset.x, position[1] + bottom, position[2] + offset.z],
+            normalWorldY: 1,
+          },
+          origin: position,
+          scene,
+          onReject: (reason) => feedback.reject(reason),
+        })
+        valid = !!placement
+        if (placement && host.type === 'procedural-item') {
+          const pose =
+            placement.childFrame === 'surface-local'
+              ? placement.surfaceLocal!
+              : { ...placement, rotation: local.rotation }
+          write(host.id, [...pose.position], pose.rotationY, pose.rotation, placement.surfaceId)
+          return {
+            position: [...pose.position] as [number, number, number],
+            rotationY: pose.rotationY,
+          }
+        }
+        if (placement) position[1] = placement.position[1]
+        else if (
+          feedback.reason === 'footprint-outside-surface' ||
+          feedback.reason === 'footprint-exceeds-host' ||
+          feedback.reason === 'no-surface'
+        ) {
+          const mesh = sceneRegistry.nodes.get(host.id)
+          if (mesh)
+            return session.detach(mesh.localToWorld(new Vector3(...position)).toArray(), yaw)
+        }
+      }
+      write(live.parentId, position, yaw)
+      return { position, rotationY: yaw }
+    },
+    restore() {
+      feedback.clear()
+      valid = true
+      pointer.clear()
+      grab = initialGrab()
+      if (!changed || !useScene.getState().nodes[node.id]) return
+      updateSurfaceNode(
+        node.id,
+        {
+          parentId: original.parentId,
+          position: original.position,
+          rotation: original.rotation,
+          supportSlabId: original.supportSlabId,
+        } as Partial<AnyNode>,
+        originalSurfaceId,
+      )
+    },
+  }
+  return session
+}

package/src/components/tools/registry/item-surface-resolver.test.ts

@@ -0,0 +1,257 @@
+import { afterEach, beforeEach, expect, spyOn, test } from 'bun:test'
+import * as core from '@pascal-app/core'
+import {
+  type AnyNodeId,
+  type GridEvent,
+  type ItemEvent,
+  ItemNode,
+  LevelNode,
+  nodeRegistry,
+  registerNode,
+  type SurfacePlacement,
+  sceneRegistry,
+  useLiveTransforms,
+  useScene,
+} from '@pascal-app/core'
+import { Group, Vector3 } from 'three'
+import { commitFreshPlacementSubtree } from '../../../lib/fresh-planar-placement'
+import useEditor from '../../../store/use-editor'
+import useInteractionScope from '../../../store/use-interaction-scope'
+import { createRegistryItemSurfaceMove } from './item-surface-move'
+
+const level = LevelNode.parse({ id: 'level_resolver' })
+const asset = {
+  id: 'table',
+  name: 'Table',
+  category: 'furniture',
+  thumbnail: '',
+  src: '/table.glb',
+  dimensions: [3, 1, 3],
+}
+const host = ItemNode.parse({
+  id: 'item_resolver-host',
+  parentId: level.id,
+  asset,
+  position: [4, 0, 5],
+  rotation: [0, 0.6, 0],
+})
+const child = ItemNode.parse({
+  id: 'item_resolver-child',
+  parentId: level.id,
+  asset,
+  position: [1, 0, 2],
+  rotation: [0.1, 0.3, 0.2],
+  metadata: { isNew: true },
+  visible: false,
+})
+const dimensions: [number, number, number] = [1, 1, 0.5]
+const savedRaf = globalThis.requestAnimationFrame
+const savedCancelRaf = globalThis.cancelAnimationFrame
+let savedNodes: ReturnType<typeof useScene.getState>['nodes']
+let savedRoots: AnyNodeId[]
+let savedEditor: ReturnType<typeof useEditor.getState>
+let savedScope: ReturnType<typeof useInteractionScope.getState>
+let restoreRegistry: () => void
+let resolver: ReturnType<typeof spyOn<typeof core, 'resolveSurfacePlacement'>>
+
+beforeEach(() => {
+  globalThis.requestAnimationFrame = (callback) => {
+    callback(0)
+    return 0
+  }
+  globalThis.cancelAnimationFrame = () => {}
+  savedEditor = useEditor.getState()
+  savedScope = useInteractionScope.getState()
+  useInteractionScope.setState({ scope: { kind: 'idle' } })
+  useEditor.setState({ mode: 'build', tool: 'item' })
+  useEditor.getState().setSnappingMode('item', 'off')
+  savedNodes = useScene.getState().nodes
+  savedRoots = useScene.getState().rootNodeIds
+  restoreRegistry = nodeRegistry._snapshot()
+  nodeRegistry._reset()
+  registerNode({
+    kind: 'item',
+    schemaVersion: 1,
+    schema: ItemNode,
+    category: 'furnish',
+    defaults: () => ({}),
+    capabilities: {
+      hostable: { parents: ['level', 'item'], align: 'face' },
+      floorPlaced: {},
+    },
+  })
+  useScene.setState({
+    nodes: {
+      [level.id]: { ...level, children: [host.id, child.id] },
+      [host.id]: host,
+      [child.id]: child,
+    },
+    rootNodeIds: [level.id],
+  })
+  useScene.temporal.getState().clear()
+  useScene.temporal.getState().pause()
+  const levelMesh = new Group()
+  levelMesh.position.set(10, 3, 20)
+  levelMesh.rotation.y = 0.4
+  const hostMesh = new Group()
+  hostMesh.position.set(...host.position)
+  hostMesh.rotation.set(...host.rotation)
+  levelMesh.add(hostMesh)
+  levelMesh.updateMatrixWorld(true)
+  sceneRegistry.nodes.set(level.id, levelMesh)
+  sceneRegistry.nodes.set(host.id, hostMesh)
+  resolver = spyOn(core, 'resolveSurfacePlacement')
+})
+
+afterEach(() => {
+  resolver.mockRestore()
+  useEditor.setState(savedEditor)
+  useInteractionScope.setState(savedScope)
+  restoreRegistry()
+  useLiveTransforms.getState().clear(child.id)
+  sceneRegistry.nodes.delete(level.id)
+  sceneRegistry.nodes.delete(host.id)
+  useScene.setState({ nodes: savedNodes, rootNodeIds: savedRoots })
+  useScene.temporal.getState().clear()
+  useScene.temporal.getState().resume()
+  globalThis.requestAnimationFrame = savedRaf
+  globalThis.cancelAnimationFrame = savedCancelRaf
+})
+
+function hit(local: [number, number, number] = [0.2, 1, 0.3]): ItemEvent {
+  const object = sceneRegistry.nodes.get(host.id)!
+  return {
+    node: host,
+    object,
+    normal: [0, 1, 0],
+    localPosition: local,
+    position: object.localToWorld(new Vector3(...local)).toArray(),
+    nativeEvent: {},
+    stopPropagation() {},
+  } as ItemEvent
+}
+
+test('the registry asks the shared resolver with host-local input and keeps the frozen live output', () => {
+  const event = hit()
+  const session = createRegistryItemSurfaceMove(child)!
+  // Captured from resolveItemSurfacePlacement at ad2a57b8 with snapping off.
+  const expected: {
+    position: [number, number, number]
+    worldPosition: [number, number, number]
+    rotationY: number
+  } = {
+    position: [0.20000000000000284, 1, 0.29999999999999716],
+    worldPosition: [15.991837444170788, 4, 23.04142809557868],
+    rotationY: -0.30000000000000004,
+  }
+  expect(session.enter(event, dimensions, 0.3)).toEqual(expected)
+  expect(resolver).toHaveBeenCalledTimes(1)
+  const args = resolver.mock.calls[0]![0]
+  expect(args.host).toBe(host)
+  expect(args.childKind).toBe(child.type)
+  expect(args.childFootprint.size).toEqual(dimensions)
+  expect(args.childFootprint.rotationY).toBe(expected!.rotationY)
+  expect(args.hit.normalWorldY).toBe(1)
+  expect(args.scene.get(host.id)).toBe(useScene.getState().nodes[host.id])
+  expect(args.snapScalar).toBeFunction()
+  expect(args.checkFootprint).toBe(true)
+})
+
+test('a null resolver result leaves the fresh floor draft and live transform untouched', () => {
+  resolver.mockReturnValue(null)
+  const session = createRegistryItemSurfaceMove(child)!
+  const event = hit()
+  const stopped = spyOn(event, 'stopPropagation')
+  useLiveTransforms.getState().set(child.id, { position: [8, 0, 9], rotation: 0.3 })
+  const before = useScene.getState().nodes
+  expect(session.enter(event, dimensions, 0.3)).toBeNull()
+  expect(resolver).toHaveBeenCalledTimes(1)
+  expect(session.hosted).toBe(false)
+  expect(session.blocksGrid(event as unknown as GridEvent)).toBe(false)
+  expect(stopped).not.toHaveBeenCalled()
+  expect(useScene.getState().nodes).toBe(before)
+  expect(useLiveTransforms.getState().get(child.id)?.position).toEqual([8, 0, 9])
+  session.restore()
+  expect(useScene.getState().nodes[child.id]).toBe(child)
+})
+
+test('registry entry and subsequent moves keep checking fit; commit uses the accepted stored pose', () => {
+  const session = createRegistryItemSurfaceMove(child)!
+  const first = session.enter(hit(), dimensions, 0.3)!
+  const moved = session.enter(hit([0.7, 1, -0.4]), dimensions, first.rotationY)!
+  expect(moved).not.toBeNull()
+  const oversized = session.enter(hit(), [4, 1, 4], moved.rotationY)!
+  expect(oversized).not.toBeNull()
+  const accepted = useScene.getState().nodes[child.id]
+  expect(session.enter(hit([2, 1, 0]), [4, 1, 4], moved.rotationY)).toBeNull()
+  expect(useScene.getState().nodes[child.id]).toBe(accepted)
+  expect(resolver.mock.calls.map(([args]) => args.checkFootprint)).toEqual([true, true, true, true])
+  const finalId = commitFreshPlacementSubtree(child.id, { visible: true })!
+  expect(useScene.getState().nodes[finalId]).toMatchObject({
+    parentId: host.id,
+    position: oversized.position,
+    rotation: [0.1, oversized.rotationY, 0.2],
+  })
+  expect(resolver).toHaveBeenCalledTimes(4)
+})
+
+test('the mover rejects itself before asking the resolver', () => {
+  const session = createRegistryItemSurfaceMove(host)!
+  const before = useScene.getState().nodes
+  expect(session.enter(hit(), dimensions, 0.6)).toBeNull()
+  expect(resolver).not.toHaveBeenCalled()
+  expect(useScene.getState().nodes).toBe(before)
+})
+
+test('the mover rejects an indirect descendant before asking the resolver', () => {
+  const intermediate = ItemNode.parse({ id: 'item_resolver-middle', parentId: child.id, asset })
+  useScene.setState({
+    nodes: {
+      ...useScene.getState().nodes,
+      [intermediate.id]: intermediate,
+      [host.id]: { ...host, parentId: intermediate.id },
+    },
+  })
+  const session = createRegistryItemSurfaceMove(child)!
+  const before = useScene.getState().nodes
+  expect(session.enter(hit(), dimensions, 0.3)).toBeNull()
+  expect(resolver).not.toHaveBeenCalled()
+  expect(useScene.getState().nodes).toBe(before)
+})
+
+test.each([
+  'host-local',
+  'surface-local',
+] as const)('writes the resolver pose in its %s child frame', (childFrame) => {
+  const placement: SurfacePlacement = {
+    position: [0.25, 1.5, -0.75],
+    rotationY: 0.4,
+    surfaceId: 'test-surface',
+    childFrame,
+    surfaceLocal: { position: [-0.5, 0, 0.25], rotationY: -0.2, rotation: [0.7, -0.2, 0.8] },
+  }
+  resolver.mockReturnValue(placement)
+  const session = createRegistryItemSurfaceMove(child)!
+  const pose = session.enter(hit(), dimensions, 0.3)!
+  const expected = childFrame === 'surface-local' ? placement.surfaceLocal! : placement
+  expect(pose.position).toEqual([...expected.position])
+  expect(pose.rotationY).toBe(expected.rotationY)
+  expect(useScene.getState().nodes[child.id]).toMatchObject({
+    parentId: host.id,
+    position: expected.position,
+    rotation:
+      childFrame === 'surface-local'
+        ? placement.surfaceLocal!.rotation
+        : [0.1, placement.rotationY, 0.2],
+  })
+})
+
+test('non-item events never reach the resolver', () => {
+  const session = createRegistryItemSurfaceMove(child)!
+  const before = useScene.getState().nodes
+  expect(
+    session.enter({ ...hit(), node: level } as unknown as ItemEvent, dimensions, 0.3),
+  ).toBeNull()
+  expect(resolver).not.toHaveBeenCalled()
+  expect(useScene.getState().nodes).toBe(before)
+})

package/src/components/tools/registry/move-registry-node-tool.test.ts

@@ -0,0 +1,10 @@
+import { expect, test } from 'bun:test'
+import { resolveMoveRotationStep } from './move-registry-node-tool'
+
+test('applies a free rotation step while the move is unattached', () => {
+  expect(resolveMoveRotationStep(0.5, 0.25, null)).toBeCloseTo(0.75)
+})
+
+test('rejects rotation steps while the move is wall-attached', () => {
+  expect(resolveMoveRotationStep(0.5, 0.25, Math.PI / 2)).toBeNull()
+})