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

package/src/components/tools/shared/pointer-support-cap.test.ts

@@ -1,22 +1,53 @@
-import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test'
 import {
   type AnyNode,
+  type AnyNodeDefinition,
   type AnyNodeId,
+  getWallBaseElevationForNodes,
+  ItemNode,
+  nodeRegistry,
+  registerNode,
+  type SlabNode,
   sceneRegistry,
   spatialGridManager,
   useScene,
 } from '@pascal-app/core'
-import { useViewer } from '@pascal-app/viewer'
-import { BoxGeometry, Mesh, MeshBasicMaterial, PerspectiveCamera } from 'three'
+import { hideFromScene, showInScene, useViewer } from '@pascal-app/viewer'
+import {
+  BoxGeometry,
+  Mesh,
+  MeshBasicMaterial,
+  OrthographicCamera,
+  PerspectiveCamera,
+  Vector3,
+} from 'three'
+import { z } from 'zod'
+import useInteractionScope from '../../../store/use-interaction-scope'
+import { createWallOnCurrentLevel } from '../wall/wall-drafting'
 import { resolvePointerSupportSurface } from './pointer-support-cap'
 
 const LEVEL_ID = 'level_test' as AnyNodeId
 const WALL_ID = 'wall_test' as AnyNodeId
+const PLATFORM_ID = 'plugin-platform_test' as AnyNodeId
+const PLATFORM_KIND = 'plugin-platform'
 
 describe('resolvePointerSupportSurface node tops', () => {
+  beforeAll(() => {
+    if (nodeRegistry.has(PLATFORM_KIND)) return
+    registerNode({
+      kind: PLATFORM_KIND,
+      schemaVersion: 1,
+      schema: z.object({}),
+      category: 'structure',
+      defaults: () => ({}),
+      capabilities: { surfaces: { top: { height: 2 } } },
+    } as unknown as AnyNodeDefinition)
+  })
+
   beforeEach(() => {
     spatialGridManager.clear()
     sceneRegistry.clear()
+    useInteractionScope.getState().end()
     useViewer.setState({
       selection: {
         buildingId: null,
@@ -59,12 +90,63 @@ describe('resolvePointerSupportSurface node tops', () => {
     sceneRegistry.clear()
   })
 
-  test('prefers the nearest upward-facing registered node surface over the ground', () => {
-    const wallMesh = new Mesh(new BoxGeometry(2, 2, 0.2), new MeshBasicMaterial())
-    wallMesh.position.y = 1
-    wallMesh.updateMatrixWorld(true)
-    sceneRegistry.nodes.set(WALL_ID, wallMesh)
-    sceneRegistry.byType.wall!.add(WALL_ID)
+  const addPluginPlatform = (z = 0, size: [number, number, number] = [4, 2, 4]) => {
+    useScene.setState((state) => ({
+      nodes: {
+        ...state.nodes,
+        [PLATFORM_ID]: {
+          id: PLATFORM_ID,
+          type: PLATFORM_KIND,
+          object: 'node',
+          parentId: LEVEL_ID,
+          visible: true,
+          metadata: {},
+        } as unknown as AnyNode,
+      },
+    }))
+    const platformMesh = new Mesh(new BoxGeometry(...size), new MeshBasicMaterial())
+    platformMesh.position.set(0, 1, z)
+    platformMesh.updateMatrixWorld(true)
+    sceneRegistry.nodes.set(PLATFORM_ID, platformMesh)
+    sceneRegistry.byType[PLATFORM_KIND]!.add(PLATFORM_ID)
+  }
+
+  test('keeps an off-center orthographic ray on the cursor line', () => {
+    const camera = new OrthographicCamera(-20, 20, 20, -20, -1000, 1000)
+    camera.position.set(10, 10, 10)
+    camera.lookAt(0, 0, 0)
+    camera.updateMatrixWorld(true)
+
+    const direction = camera.getWorldDirection(new Vector3())
+    const right = new Vector3(1, 0, 0).applyQuaternion(camera.quaternion)
+    const up = new Vector3(0, 1, 0).applyQuaternion(camera.quaternion)
+    const rayOrigin = camera.position.clone().addScaledVector(right, 3).addScaledVector(up, 2)
+    const groundDistance = -rayOrigin.y / direction.y
+    const worldHit = rayOrigin.clone().addScaledVector(direction, groundDistance)
+    const topDistance = (2 - rayOrigin.y) / direction.y
+    const expectedTop = rayOrigin.clone().addScaledVector(direction, topDistance)
+
+    addPluginPlatform(expectedTop.z, [0.5, 2, 0.5])
+    const platformMesh = sceneRegistry.nodes.get(PLATFORM_ID)!
+    platformMesh.position.set(expectedTop.x, 1, expectedTop.z)
+    platformMesh.updateMatrixWorld(true)
+
+    const support = resolvePointerSupportSurface(
+      camera,
+      worldHit.toArray() as [number, number, number],
+      {
+        includeNodeTopSurfaces: true,
+      },
+    )
+
+    expect(support?.sourceNodeId).toBe(PLATFORM_ID)
+    expect(support?.worldPoint?.[0]).toBeCloseTo(expectedTop.x)
+    expect(support?.worldPoint?.[1]).toBeCloseTo(expectedTop.y)
+    expect(support?.worldPoint?.[2]).toBeCloseTo(expectedTop.z)
+  })
+
+  test('discovers a plugin-declared top surface without a kind-name list', () => {
+    addPluginPlatform()
 
     const camera = new PerspectiveCamera()
     camera.position.set(0, 5, 0)
@@ -74,25 +156,245 @@ describe('resolvePointerSupportSurface node tops', () => {
       includeNodeTopSurfaces: true,
     })
 
-    expect(support?.sourceNodeId).toBe(WALL_ID)
+    expect(support?.sourceNodeId).toBe(PLATFORM_ID)
     expect(support?.elevation).toBeCloseTo(2)
     expect(support?.worldPoint).toEqual([0, 2, 0])
   })
 
-  test('keeps the ground result when node-top surfaces are not requested', () => {
-    const wallMesh = new Mesh(new BoxGeometry(2, 2, 0.2), new MeshBasicMaterial())
-    wallMesh.position.y = 1
-    wallMesh.updateMatrixWorld(true)
-    sceneRegistry.nodes.set(WALL_ID, wallMesh)
-    sceneRegistry.byType.wall!.add(WALL_ID)
+  test('keeps an unhovered item top above a batched slab across batch transitions', () => {
+    const restoreRegistry = nodeRegistry._snapshot()
+    const item = ItemNode.parse({
+      id: 'item_support_batch',
+      parentId: LEVEL_ID,
+      asset: {
+        id: 'table',
+        name: 'Table',
+        src: '/table.glb',
+        category: 'furniture',
+        thumbnail: '/table.png',
+        dimensions: [4, 2, 4],
+      },
+    })
+    const slab = {
+      id: 'slab_support_batch',
+      type: 'slab',
+      parentId: LEVEL_ID,
+      polygon: [
+        [-3, -3],
+        [3, -3],
+        [3, 3],
+        [-3, 3],
+      ],
+      elevation: 0.25,
+      thickness: 0.25,
+      holes: [],
+      visible: true,
+    } as unknown as SlabNode
+    const itemMesh = new Mesh(new BoxGeometry(4, 2, 4), new MeshBasicMaterial())
+    itemMesh.position.y = 1.25
+    itemMesh.updateMatrixWorld(true)
+    const slabMesh = new Mesh(new BoxGeometry(6, 0.25, 6), new MeshBasicMaterial())
+    slabMesh.position.y = 0.125
+    slabMesh.updateMatrixWorld(true)
+    try {
+      registerNode({
+        kind: 'item',
+        schema: ItemNode,
+        schemaVersion: 1,
+        category: 'furnish',
+        defaults: () => ({}),
+        capabilities: { surfaces: { top: { height: 2 } } },
+      } as unknown as AnyNodeDefinition)
+      useScene.setState((state) => ({
+        nodes: { ...state.nodes, [item.id]: item, [slab.id]: slab },
+      }))
+      sceneRegistry.nodes.set(item.id, itemMesh)
+      sceneRegistry.byType.item!.add(item.id)
+      sceneRegistry.nodes.set(slab.id, slabMesh)
+      sceneRegistry.byType.slab!.add(slab.id)
+      spatialGridManager.handleNodeCreated(slab as AnyNode, LEVEL_ID)
+      useViewer.setState({ hoveredId: null })
+      const camera = new PerspectiveCamera()
+      camera.position.set(0, 5, 0)
+      camera.updateMatrixWorld(true)
+      for (const batched of [false, true, false]) {
+        for (const mesh of [itemMesh, slabMesh]) {
+          if (batched) hideFromScene(mesh, 'batched')
+          else showInScene(mesh, 'batched')
+        }
+        const top = resolvePointerSupportSurface(camera, [0, 0, 0], {
+          includeNodeTopSurfaces: true,
+        })
+        expect(top?.sourceNodeId).toBe(item.id)
+        expect(top?.worldPoint).toEqual([0, 2.25, 0])
+        const floor = resolvePointerSupportSurface(camera, [0, 0, 0])
+        expect(floor?.supportSlabId).toBe(slab.id)
+        expect(floor?.worldPoint).toEqual([0, 0.25, 0])
+      }
+    } finally {
+      restoreRegistry()
+      for (const mesh of [itemMesh, slabMesh]) {
+        mesh.geometry.dispose()
+        mesh.material.dispose()
+      }
+    }
+  })
+
+  test('keeps the ground result unless node-top surfaces are asked for', () => {
+    addPluginPlatform()
+
+    const camera = new PerspectiveCamera()
+    camera.position.set(0, 5, 0)
+    camera.updateMatrixWorld(true)
+
+    // The default. A floor placement aims THROUGH whatever upward-facing
+    // geometry sits between the camera and the floor — a room's ceiling, the
+    // top of the wall the ray passes over — so only the tools that build on a
+    // surface opt in.
+    for (const options of [undefined, { includeNodeTopSurfaces: false }]) {
+      const support = resolvePointerSupportSurface(camera, [0, 0, 0], options)
+      expect(support?.sourceNodeId).toBeNull()
+      expect(support?.elevation).toBe(0)
+    }
+  })
+
+  test('never elects the node the active interaction is placing or moving', () => {
+    addPluginPlatform()
+    useInteractionScope.getState().begin({
+      kind: 'placing',
+      node: useScene.getState().nodes[PLATFORM_ID]!,
+      nodeId: PLATFORM_ID,
+      nodeType: PLATFORM_KIND,
+      view: '3d',
+      pressDrag: false,
+      driver: 'registry-tool',
+    })
 
     const camera = new PerspectiveCamera()
     camera.position.set(0, 5, 0)
     camera.updateMatrixWorld(true)
 
-    const support = resolvePointerSupportSurface(camera, [0, 0, 0])
+    const support = resolvePointerSupportSurface(camera, [0, 0, 0], {
+      includeNodeTopSurfaces: true,
+    })
 
+    // Its own top would raise it by its own height on every pointer move.
     expect(support?.sourceNodeId).toBeNull()
     expect(support?.elevation).toBe(0)
   })
+
+  test('uses a plugin-declared top as the wall construction surface', () => {
+    const lowSlab = {
+      id: 'slab_low',
+      type: 'slab',
+      object: 'node',
+      parentId: LEVEL_ID,
+      visible: true,
+      metadata: {},
+      children: [],
+      polygon: [
+        [-2, 1],
+        [2, 1],
+        [2, 3],
+        [-2, 3],
+      ],
+      holes: [],
+      holeMetadata: [],
+      elevation: 0.25,
+      thickness: 0.25,
+      recessed: false,
+      autoFromWalls: false,
+    } as SlabNode
+    const highSlab = {
+      ...lowSlab,
+      id: 'slab_high',
+      polygon: [
+        [-1, 1],
+        [0, 1],
+        [0, 3],
+        [-1, 3],
+      ],
+      elevation: 1,
+    } as SlabNode
+    useScene.setState((state) => ({
+      nodes: {
+        ...state.nodes,
+        [lowSlab.id]: lowSlab,
+        [highSlab.id]: highSlab,
+      },
+    }))
+    spatialGridManager.handleNodeCreated(lowSlab as AnyNode, LEVEL_ID)
+    spatialGridManager.handleNodeCreated(highSlab as AnyNode, LEVEL_ID)
+    addPluginPlatform(2)
+
+    const camera = new PerspectiveCamera()
+    camera.position.set(0, 5, 2)
+    camera.updateMatrixWorld(true)
+
+    const support = resolvePointerSupportSurface(camera, [0, 0, 2], {
+      includeNodeTopSurfaces: true,
+    })
+
+    expect(support?.sourceNodeId).toBe(PLATFORM_ID)
+    expect(support?.elevation).toBeCloseTo(2)
+    expect(support?.worldPoint).toEqual([0, 2, 2])
+
+    const wall = createWallOnCurrentLevel([-0.75, 2], [0.75, 2], {
+      supportCap: support?.elevation,
+      preferredSupportSlabId: support?.supportSlabId,
+      constructionElevation: support?.elevation,
+      constructionHeight: 2.5,
+      flatConstructionBase: support?.sourceNodeId != null,
+    })
+    expect(wall).not.toBeNull()
+    expect(getWallBaseElevationForNodes(wall!, useScene.getState().nodes)).toBeCloseTo(2)
+    const wallSupport = spatialGridManager.getSlabSupportForWall(
+      LEVEL_ID,
+      wall!.start,
+      wall!.end,
+      wall!.curveOffset,
+      wall!.thickness,
+      wall!.supportSlabId,
+      undefined,
+      wall!.supportOffset,
+    )
+    expect(
+      wallSupport.baseSegments.every((segment) => Math.abs(segment.elevation - 2) < 1e-6),
+    ).toBe(true)
+  })
+
+  test('tolerates a registered definition without capabilities', () => {
+    // Gates the pollution class behind the night-8 CI flake (run
+    // 32580694134): `capabilities` is typed required, but a minimal plugin
+    // definition (or a leaked test fixture) can ship without it at runtime.
+    // The resolver enumerates every registered kind, so one capabilities-less
+    // entry must read as "no top surface" — not crash the election.
+    const restoreRegistry = nodeRegistry._snapshot()
+    try {
+      registerNode({
+        kind: 'plugin-minimal-capless',
+        schemaVersion: 1,
+        schema: z.object({}),
+        category: 'structure',
+        defaults: () => ({}),
+        // No `capabilities` — deliberately.
+      } as unknown as AnyNodeDefinition)
+      addPluginPlatform()
+
+      const camera = new PerspectiveCamera()
+      camera.position.set(0, 5, 0)
+      camera.updateMatrixWorld(true)
+
+      const support = resolvePointerSupportSurface(camera, [0, 0, 0], {
+        includeNodeTopSurfaces: true,
+      })
+
+      // No throw, and the election still works: the capabilities-less kind is
+      // skipped while the platform's declared top is found as usual.
+      expect(support?.sourceNodeId).toBe(PLATFORM_ID)
+      expect(support?.elevation).toBeCloseTo(2)
+    } finally {
+      restoreRegistry()
+    }
+  })
 })

package/src/components/tools/shared/pointer-support-cap.ts

@@ -1,16 +1,21 @@
 import {
+  type AnyNode,
   type AnyNodeId,
   canHostOnTop,
   GROUND_SUPPORT_ID,
   type ItemNode,
   isLowProfileItemSurface,
+  nodeRegistry,
   sceneRegistry,
   spatialGridManager,
   useScene,
 } from '@pascal-app/core'
-import { useViewer } from '@pascal-app/viewer'
-import { type Camera, Matrix3, type Object3D, Raycaster, Vector3 } from 'three'
+import { setSurfaceRaycastLayers, useViewer } from '@pascal-app/viewer'
+import { type Camera, type Object3D, Raycaster, Vector3 } from 'three'
 import { resolveTerrainGroundHit } from '../../../lib/ground-surface'
+import { scopeNodeId } from '../../../lib/interaction/scope'
+import useInteractionScope from '../../../store/use-interaction-scope'
+import { surfaceWorldNormalY } from './surface-hit'
 
 const originScratch = new Vector3()
 const hitScratch = new Vector3()
@@ -19,10 +24,7 @@ const pointScratch = new Vector3()
 const worldRayOrigin = new Vector3()
 const worldRayDirection = new Vector3()
 const nodeTopRaycaster = new Raycaster()
-const nodeTopNormal = new Vector3()
-const nodeTopNormalMatrix = new Matrix3()
-
-const NODE_TOP_SURFACE_KINDS = ['wall', 'item', 'column'] as const
+setSurfaceRaycastLayers(nodeTopRaycaster.layers)
 
 export type PointerSupportSurface = {
   /** Level-local elevation of the pointed surface — the election cap. */
@@ -85,7 +87,19 @@ export function resolvePointerSupportSurface(
   // The world ray, kept before the level conversion below: the terrain field is
   // world-space (site geometry, not level-local), so the march needs this frame.
   camera.getWorldPosition(worldRayOrigin)
-  worldRayDirection.set(worldHit[0], worldHit[1], worldHit[2]).sub(worldRayOrigin)
+  const cameraToHit = hitScratch.set(worldHit[0], worldHit[1], worldHit[2]).sub(worldRayOrigin)
+  if ((camera as Camera & { isOrthographicCamera?: boolean }).isOrthographicCamera) {
+    // For an orthographic camera every screen pixel has the same direction. The
+    // hit point is offset from the camera along the view plane, so using
+    // `camera.position -> hit` tilts the ray toward the screen centre and makes
+    // support surfaces drift away from the cursor off-axis.
+    camera.getWorldDirection(worldRayDirection).normalize()
+    worldRayOrigin
+      .set(worldHit[0], worldHit[1], worldHit[2])
+      .addScaledVector(worldRayDirection, -cameraToHit.dot(worldRayDirection))
+  } else {
+    worldRayDirection.copy(cameraToHit).normalize()
+  }
 
   originScratch.copy(worldRayOrigin)
   hitScratch.set(worldHit[0], worldHit[1], worldHit[2])
@@ -151,16 +165,39 @@ export function resolvePointerSupportSurface(
     localPoint = [pointScratch.x, pointScratch.y, pointScratch.z]
   }
 
-  if (options?.includeNodeTopSurfaces) {
+  // Node tops are opt-in. A ray aimed at a floor crosses every upward-facing
+  // face above that floor first — a room's ceiling, the top of the wall it
+  // passes over — so electing "the nearest node top along the ray" silently
+  // lifts anything placed inside a finished room. Only the tools that build ON
+  // a surface (wall / column / fence / stair / block) mean that, and they say
+  // so. Everything else places against the floor the pointer indicates.
+  //
+  // `capabilities` is typed required on NodeDefinition, but this enumerates
+  // EVERY registered kind — including plugin bundles that bypass the type at
+  // runtime. A minimal definition without `capabilities` must read as "no top
+  // surface", not crash the resolver (night-8 CI, run 32580694134).
+  const nodeTopSurfaceKinds = options?.includeNodeTopSurfaces
+    ? Array.from(nodeRegistry.entries())
+        .filter(([, definition]) => definition.capabilities?.surfaces?.top !== undefined)
+        .map(([kind]) => kind)
+    : []
+  if (nodeTopSurfaceKinds.some((kind) => (sceneRegistry.byType[kind]?.size ?? 0) > 0)) {
     nodeTopRaycaster.set(worldRayOrigin, worldRayDirection.clone().normalize())
     const nodes = useScene.getState().nodes
     const registeredOwners = new Map(
       [...sceneRegistry.nodes.entries()].map(([nodeId, object]) => [object, nodeId as AnyNodeId]),
     )
-    const belongsToActiveLevel = (nodeId: AnyNodeId) => {
-      let current = nodes[nodeId]
+    // The node the active interaction is placing/moving cannot be a surface for
+    // itself: its mesh rides the cursor, so electing its own top would raise it
+    // by its own height on every pointer move. Tools neuter the dragged mesh's
+    // `raycast` for their own pointer routing, but that is each tool's private
+    // convention — the election owns the invariant.
+    const interactingNodeId = scopeNodeId(useInteractionScope.getState().scope)
+    const isEligibleCandidate = (nodeId: AnyNodeId) => {
+      let current: AnyNode | undefined = nodes[nodeId]
       const visited = new Set<AnyNodeId>()
       while (current && !visited.has(current.id)) {
+        if (current.id === interactingNodeId) return false
         if (current.id === levelId) return true
         visited.add(current.id)
         current = current.parentId ? nodes[current.parentId as AnyNodeId] : undefined
@@ -179,12 +216,12 @@ export function resolvePointerSupportSurface(
         }
       | undefined
 
-    for (const kind of NODE_TOP_SURFACE_KINDS) {
+    for (const kind of nodeTopSurfaceKinds) {
       for (const rawId of sceneRegistry.byType[kind] ?? []) {
         const nodeId = rawId as AnyNodeId
         const node = nodes[nodeId]
         const object = sceneRegistry.nodes.get(nodeId)
-        if (!(node?.visible && object?.visible && belongsToActiveLevel(nodeId))) continue
+        if (!(node?.visible && object?.visible && isEligibleCandidate(nodeId))) continue
         if (
           node.type === 'item' &&
           (!canHostOnTop(node) || isLowProfileItemSurface(node as ItemNode))
@@ -210,11 +247,13 @@ export function resolvePointerSupportSurface(
             ownerObject = ownerObject.parent
           }
           if (belongsToNestedNode) continue
-          nodeTopNormal
-            .copy(intersection.face.normal)
-            .applyNormalMatrix(nodeTopNormalMatrix.getNormalMatrix(intersection.object.matrixWorld))
-            .normalize()
-          if (nodeTopNormal.y < 0.75) continue
+          if (
+            surfaceWorldNormalY(
+              intersection.face.normal.toArray(),
+              intersection.object.matrixWorld,
+            ) < 0.75
+          )
+            continue
           nearest = {
             distance: intersection.distance,
             nodeId,

package/src/components/tools/shared/shelf-stickiness.ts

@@ -0,0 +1,54 @@
+import {
+  type AnyNodeId,
+  createSceneApi,
+  getSurfaceProvider,
+  sceneRegistry,
+  surfaceRegionContainsPoint,
+  useScene,
+} from '@pascal-app/core'
+import { Box3, type Camera, Matrix4, Ray, Vector3 } from 'three'
+
+export function createShelfStickiness() {
+  const ray = new Ray()
+  const box = new Box3()
+  const matrix = new Matrix4()
+  const cameraPosition = new Vector3()
+
+  // A ray through a board gap can hit the floor behind the shelf while still targeting its volume.
+  return (
+    shelfId: string | null | undefined,
+    camera: Camera,
+    worldPoint: readonly [number, number, number],
+  ) => {
+    if (!shelfId) return false
+    const mesh = sceneRegistry.nodes.get(shelfId)
+    const shelf = useScene.getState().nodes[shelfId as AnyNodeId]
+    if (!mesh || !shelf || (shelf.type !== 'shelf' && shelf.type !== 'cabinet')) return false
+    camera.getWorldPosition(cameraPosition)
+    ray.origin.copy(cameraPosition)
+    ray.direction
+      .set(...worldPoint)
+      .sub(cameraPosition)
+      .normalize()
+    ray.applyMatrix4(matrix.copy(mesh.matrixWorld).invert())
+    if (shelf.type === 'cabinet') {
+      const surfaces =
+        getSurfaceProvider(shelf).surfaces?.(shelf, { scene: createSceneApi(useScene) }) ?? []
+      return surfaces.some((surface) => {
+        if (Math.abs(ray.direction.y) < 1e-8) return false
+        const distance = (surface.position[1] - ray.origin.y) / ray.direction.y
+        if (distance < 0) return false
+        const point = ray.at(distance, new Vector3())
+        return surfaceRegionContainsPoint(surface.region, [
+          point.x - surface.position[0],
+          point.z - surface.position[2],
+        ])
+      })
+    }
+    if (!shelf.width || !shelf.depth || !shelf.height) return false
+    const margin = 0.08
+    box.min.set(-shelf.width / 2 - margin, -margin, -shelf.depth / 2 - margin)
+    box.max.set(shelf.width / 2 + margin, shelf.height + margin, shelf.depth / 2 + margin)
+    return ray.intersectsBox(box)
+  }
+}

package/src/components/tools/shared/surface-hit.test.ts

@@ -0,0 +1,56 @@
+import { afterEach, expect, test } from 'bun:test'
+import { type ItemEvent, ItemNode, sceneRegistry } from '@pascal-app/core'
+import { Group, Matrix3, Vector3 } from 'three'
+import { itemEventToSurfaceHit } from './surface-hit'
+
+const host = ItemNode.parse({
+  id: 'item_hit-adapter',
+  asset: { id: 'host', name: 'Host', category: 'furniture', thumbnail: '', src: '/host.glb' },
+})
+
+afterEach(() => sceneRegistry.nodes.delete(host.id))
+
+test('matches the legacy host-local point and hit-mesh normal exactly under rotation and scale', () => {
+  const mesh = new Group()
+  mesh.position.set(4.3, 2.1, -3.7)
+  mesh.rotation.set(0.2, 0.7, -0.1)
+  mesh.scale.set(2, 0.7, 1.3)
+  const object = new Group()
+  object.name = 'surface-mesh'
+  object.position.set(0.4, 0.8, -0.2)
+  object.rotation.set(-0.1, 0.3, 0.2)
+  object.scale.set(0.8, 1.4, 0.6)
+  mesh.add(object)
+  mesh.updateMatrixWorld(true)
+  sceneRegistry.nodes.set(host.id, mesh)
+  const event = {
+    node: host,
+    object,
+    position: object.localToWorld(new Vector3(0.37, 0.81, -0.39)).toArray(),
+    localPosition: [0.37, 0.81, -0.39],
+    normal: [0.2, 1, -0.3],
+    nativeEvent: {} as ItemEvent['nativeEvent'],
+    stopPropagation() {},
+  } as ItemEvent
+  const before = structuredClone({ position: event.position, normal: event.normal })
+  const expectedPoint = mesh.worldToLocal(new Vector3(...event.position)).toArray()
+  const expectedNormal = new Vector3(...event.normal!)
+    .applyNormalMatrix(new Matrix3().getNormalMatrix(object.matrixWorld))
+    .normalize().y
+  const hit = itemEventToSurfaceHit(host, event)!
+  expect(hit.point).toEqual(expectedPoint)
+  expect(hit.point).not.toEqual(event.localPosition)
+  expect(hit.normalWorldY).toBe(expectedNormal)
+  expect(hit.meshName).toBe(object.name)
+  expect({ position: event.position, normal: event.normal }).toEqual(before)
+
+  const roundTrip = mesh.localToWorld(new Vector3(...expectedPoint)).toArray()
+  expect(itemEventToSurfaceHit(host, { ...event, position: roundTrip })!.point).toEqual(
+    mesh.worldToLocal(new Vector3(...roundTrip)).toArray(),
+  )
+  expect(itemEventToSurfaceHit(host, { ...event, normal: undefined })!.normalWorldY).toBeNaN()
+})
+
+test('a missing registered host mesh yields no hit', () => {
+  expect(itemEventToSurfaceHit(host, {} as ItemEvent)).toBeNull()
+})

package/src/components/tools/shared/surface-hit.ts

@@ -0,0 +1,23 @@
+import { type AnyNode, type NodeEvent, type SurfaceHit, sceneRegistry } from '@pascal-app/core'
+import { Matrix3, type Matrix4, Vector3 } from 'three'
+
+export function surfaceWorldNormalY(
+  normal: NodeEvent<AnyNode>['normal'],
+  matrixWorld: Matrix4,
+): number {
+  return normal
+    ? new Vector3(...normal)
+        .applyNormalMatrix(new Matrix3().getNormalMatrix(matrixWorld))
+        .normalize().y
+    : Number.NaN
+}
+
+export function itemEventToSurfaceHit(host: AnyNode, event: NodeEvent<AnyNode>): SurfaceHit | null {
+  const mesh = sceneRegistry.nodes.get(host.id)
+  if (!mesh) return null
+  return {
+    point: mesh.worldToLocal(new Vector3(...event.position)).toArray(),
+    normalWorldY: surfaceWorldNormalY(event.normal, event.object.matrixWorld),
+    meshName: event.object.name,
+  }
+}