@pascal-app/editor 1.0.0-beta.4 → 1.0.0

package/src/components/tools/item/placement-strategies.ts

@@ -6,6 +6,7 @@ import type {
   GridEvent,
   ItemEvent,
   ItemNode,
+  NodeEvent,
   RoofEvent,
   RoofNode,
   RoofSegmentNode,
@@ -30,7 +31,6 @@ import { Euler, Matrix3, Quaternion, Vector3 } from 'three'
 import { hasRoofFaceChildOverlap, resolveRoofWallHit } from '../../../lib/roof-wall-hit'
 import { snapWorldXZForActiveBuilding } from '../../../lib/world-grid-snap'
 import {
-  calculateCursorRotation,
   calculateItemRotation,
   getGridAlignedDimensions,
   getSideFromNormal,
@@ -178,6 +178,51 @@ export const floorStrategy = {
 // WALL STRATEGY
 // ============================================================================
 
+/**
+ * Resolve the wall-local node position AND the world pose of the placement
+ * wireframe from ONE wall-local point, so the box can't drift from the item it
+ * previews.
+ *
+ * `event.object` is the wall's collision mesh — the frame `event.localPosition`
+ * was measured in — so `localToWorld` is the exact inverse of the hit. Snapping
+ * the raw world hit per axis instead (the old path) put the box on a different
+ * lattice than the node: wall-local X runs from `wall.start`, and wall-local Y
+ * is measured from the supporting slab's elevation, not from world zero.
+ *
+ * `z` follows the hosting convention rather than the hit depth: `wall` items
+ * center in the thickness, `wall-side` items mount on the hit face — mirroring
+ * `ItemSystem`'s per-frame push, so the wireframe's `z = 0` face lands flush
+ * with the wall instead of extending through it.
+ */
+function resolveWallPlacementPose(
+  event: WallEvent,
+  localX: number,
+  localY: number,
+  attachTo: 'wall' | 'wall-side',
+  side: 'front' | 'back',
+  itemRotation: number,
+): {
+  position: [number, number, number]
+  cursorPosition: [number, number, number]
+  cursorRotationY: number
+} {
+  const localZ =
+    attachTo === 'wall-side' ? ((event.node.thickness ?? 0.1) / 2) * (side === 'front' ? 1 : -1) : 0
+  event.object.updateWorldMatrix(true, false)
+  const world = event.object.localToWorld(new Vector3(localX, localY, localZ))
+  const wallYaw = -Math.atan2(
+    event.node.end[1] - event.node.start[1],
+    event.node.end[0] - event.node.start[0],
+  )
+  return {
+    position: [localX, localY, localZ],
+    cursorPosition: [world.x, world.y, world.z],
+    // Same composition the 2D floorplan resolves a wall child with
+    // (`resolveItemTransform`): the cursor frame IS the item frame.
+    cursorRotationY: wallYaw + itemRotation,
+  }
+}
+
 export const wallStrategy = {
   /**
    * Handle wall:enter — transition from floor to wall surface.
@@ -201,11 +246,9 @@ export const wallStrategy = {
 
     const side = getSideFromNormal(event.normal)
     const itemRotation = calculateItemRotation(event.normal)
-    const cursorRotation = calculateCursorRotation(event.normal, event.node.start, event.node.end)
 
     const x = snapToHalf(event.localPosition[0])
     const y = snapToHalf(event.localPosition[1])
-    const z = snapToHalf(event.localPosition[2])
 
     // Get auto-adjusted Y position from validator
     const rawDims = ctx.draftItem
@@ -223,25 +266,27 @@ export const wallStrategy = {
     )
 
     const adjustedY = validation.adjustedY ?? y
+    const pose = resolveWallPlacementPose(event, x, adjustedY, attachTo, side, itemRotation)
 
     return {
-      stateUpdate: { surface: 'wall', wallId: event.node.id, roofSegmentId: null },
+      stateUpdate: {
+        surface: 'wall',
+        wallId: event.node.id,
+        roofSegmentId: null,
+      },
       nodeUpdate: {
-        position: [x, adjustedY, z],
+        position: pose.position,
         parentId: event.node.id,
         // The draft may arrive from a roof-segment wall face.
         roofSegmentId: undefined,
         roofFace: undefined,
+        blockFaceId: undefined,
         side,
         rotation: [0, itemRotation, 0],
       },
-      cursorRotationY: cursorRotation,
-      gridPosition: [x, adjustedY, z],
-      cursorPosition: [
-        snapToHalf(event.position[0]),
-        snapToHalf(event.position[1]),
-        snapToHalf(event.position[2]),
-      ],
+      cursorRotationY: pose.cursorRotationY,
+      gridPosition: pose.position,
+      cursorPosition: pose.cursorPosition,
       stopPropagation: true,
     }
   },
@@ -262,11 +307,10 @@ export const wallStrategy = {
 
     const side = getSideFromNormal(event.normal)
     const itemRotation = calculateItemRotation(event.normal)
-    const cursorRotation = calculateCursorRotation(event.normal, event.node.start, event.node.end)
+    const attachTo = ctx.draftItem.asset.attachTo as 'wall' | 'wall-side'
 
     const snappedX = snapToHalf(event.localPosition[0])
     const snappedY = snapToHalf(event.localPosition[1])
-    const snappedZ = snapToHalf(event.localPosition[2])
 
     // Get auto-adjusted Y position from validator
     const validation = validators.canPlaceOnWall(
@@ -275,23 +319,20 @@ export const wallStrategy = {
       snappedX,
       snappedY,
       getGridAlignedDimensions(getScaledDimensions(ctx.draftItem), ctx.draftItem.asset.attachTo),
-      ctx.draftItem.asset.attachTo as 'wall' | 'wall-side',
+      attachTo,
       side,
       [ctx.draftItem.id],
     )
 
     const adjustedY = validation.adjustedY ?? snappedY
+    const pose = resolveWallPlacementPose(event, snappedX, adjustedY, attachTo, side, itemRotation)
 
     return {
-      gridPosition: [snappedX, adjustedY, snappedZ],
-      cursorPosition: [
-        snapToHalf(event.position[0]),
-        snapToHalf(event.position[1]),
-        snapToHalf(event.position[2]),
-      ],
-      cursorRotationY: cursorRotation,
+      gridPosition: pose.position,
+      cursorPosition: pose.cursorPosition,
+      cursorRotationY: pose.cursorRotationY,
       nodeUpdate: {
-        position: [snappedX, adjustedY, snappedZ],
+        position: pose.position,
         side,
         rotation: [0, itemRotation, 0],
       },
@@ -332,6 +373,7 @@ export const wallStrategy = {
         parentId: event.node.id,
         roofSegmentId: undefined,
         roofFace: undefined,
+        blockFaceId: undefined,
         side: ctx.draftItem.side,
         rotation: ctx.draftItem.rotation,
         metadata: stripTransient(ctx.draftItem.metadata),
@@ -485,12 +527,17 @@ export const roofWallStrategy = {
     if (!target) return null
 
     return {
-      stateUpdate: { surface: 'roof-wall', roofSegmentId: target.segment.id, wallId: null },
+      stateUpdate: {
+        surface: 'roof-wall',
+        roofSegmentId: target.segment.id,
+        wallId: null,
+      },
       nodeUpdate: {
         position: target.position,
         parentId: target.segment.id,
         roofSegmentId: target.segment.id,
         roofFace: target.faceId,
+        blockFaceId: undefined,
         wallId: undefined,
         side: 'front',
         rotation: [0, 0, 0],
@@ -548,6 +595,7 @@ export const roofWallStrategy = {
         parentId: ctx.state.roofSegmentId,
         roofSegmentId: ctx.state.roofSegmentId,
         roofFace: ctx.draftItem.roofFace,
+        blockFaceId: undefined,
         wallId: undefined,
         side: 'front',
         rotation: [0, 0, 0],
@@ -580,6 +628,114 @@ export const roofWallStrategy = {
   },
 }
 
+// ============================================================================
+// FACE HOST STRATEGY
+// ============================================================================
+
+function resolveFaceHostTarget(ctx: PlacementContext, event: NodeEvent) {
+  const faceHost = nodeRegistry.get(event.node.type)?.capabilities.faceHost
+  if (!faceHost) return null
+  const rawDimensions = ctx.draftItem
+    ? getScaledDimensions(ctx.draftItem)
+    : (ctx.asset.dimensions ?? DEFAULT_DIMENSIONS)
+  return faceHost.resolvePlacement({
+    host: event.node,
+    asset: ctx.asset,
+    draftItem: ctx.draftItem,
+    localPosition: event.localPosition,
+    faceIndex: event.faceIndex,
+    object: event.object,
+    currentFaceId: faceHost.currentFaceId(ctx.draftItem),
+    rawDimensions,
+    dimensions: getGridAlignedDimensions(rawDimensions, ctx.asset.attachTo),
+    snapScalar: snapToHalf,
+  })
+}
+
+function clearFaceHostItemFields(ctx: PlacementContext): Partial<ItemNode> {
+  const host = ctx.state.blockId ? useScene.getState().nodes[ctx.state.blockId] : undefined
+  const clearFields = host
+    ? nodeRegistry.get(host.type)?.capabilities.faceHost?.clearItemFields
+    : undefined
+  const patch: Partial<ItemNode> = {}
+  for (const field of clearFields ?? []) {
+    ;(patch as Record<string, unknown>)[field] = undefined
+  }
+  return patch
+}
+
+export const faceHostStrategy = {
+  enter(ctx: PlacementContext, event: NodeEvent): TransitionResult | null {
+    const target = resolveFaceHostTarget(ctx, event)
+    if (!target) return null
+    return {
+      stateUpdate: {
+        surface: 'block-face',
+        blockId: event.node.id,
+        wallId: null,
+        roofSegmentId: null,
+      },
+      nodeUpdate: {
+        ...target.nodeUpdate,
+      },
+      gridPosition: target.position,
+      cursorPosition: target.cursorPosition,
+      cursorRotationY: target.cursorRotation[1],
+      cursorRotation: target.cursorRotation,
+      stopPropagation: true,
+      hostFaceId: target.faceId,
+    }
+  },
+
+  move(ctx: PlacementContext, event: NodeEvent): PlacementResult | null {
+    if (ctx.state.surface !== 'block-face' || !ctx.draftItem) return null
+    const target = resolveFaceHostTarget(ctx, event)
+    if (!target || event.node.id !== ctx.state.blockId) return null
+    return {
+      gridPosition: target.position,
+      cursorPosition: target.cursorPosition,
+      cursorRotationY: target.cursorRotation[1],
+      cursorRotation: target.cursorRotation,
+      nodeUpdate: target.nodeUpdate,
+      stopPropagation: true,
+      dirtyNodeId: null,
+      hostFaceId: target.faceId,
+    }
+  },
+
+  click(ctx: PlacementContext, event: NodeEvent): CommitResult | null {
+    if (ctx.state.surface !== 'block-face' || !ctx.draftItem) return null
+    const target = resolveFaceHostTarget(ctx, event)
+    if (!target || event.node.id !== ctx.state.blockId) return null
+    return {
+      nodeUpdate: {
+        ...target.nodeUpdate,
+        metadata: stripTransient(ctx.draftItem.metadata),
+      },
+      stopPropagation: true,
+      dirtyNodeId: null,
+    }
+  },
+
+  leave(ctx: PlacementContext): TransitionResult | null {
+    if (ctx.state.surface !== 'block-face') return null
+    const floorPosition: [number, number, number] = [ctx.gridPosition.x, 0, ctx.gridPosition.z]
+    return {
+      stateUpdate: { surface: 'floor', blockId: null },
+      nodeUpdate: {
+        ...clearFaceHostItemFields(ctx),
+        position: floorPosition,
+        parentId: ctx.levelId,
+        rotation: [0, ctx.currentCursorRotationY, 0],
+      },
+      cursorRotationY: ctx.currentCursorRotationY,
+      gridPosition: floorPosition,
+      cursorPosition: floorPosition,
+      stopPropagation: true,
+    }
+  },
+}
+
 // ============================================================================
 // CEILING STRATEGY
 // ============================================================================
@@ -1020,6 +1176,18 @@ export function checkCanPlace(ctx: PlacementContext, validators: SpatialValidato
 
   const alignedDims = getGridAlignedDimensions(getScaledDimensions(ctx.draftItem), attachTo)
 
+  if (ctx.state.surface === 'block-face') {
+    const hostId = ctx.state.blockId
+    const host = hostId ? useScene.getState().nodes[hostId as AnyNodeId] : undefined
+    const faceHost = host ? nodeRegistry.get(host.type)?.capabilities.faceHost : undefined
+    if (!(host && faceHost)) return false
+    return faceHost.isStoredPlacementValid({
+      host,
+      item: ctx.draftItem,
+      asset: ctx.draftItem.asset,
+    })
+  }
+
   if (attachTo === 'ceiling') {
     if (ctx.state.surface !== 'ceiling' || !ctx.state.ceilingId) return false
     return validators.canPlaceOnCeiling(

package/src/components/tools/item/placement-surface.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from 'bun:test'
+import { Matrix4, Quaternion, Vector3 } from 'three'
+import { resolveItemPlacementSurfaceNormal } from './placement-surface'
+
+describe('resolveItemPlacementSurfaceNormal', () => {
+  test('uses the full face normal for a sloped block host', () => {
+    const normal = new Vector3(0, 0.6, 0.8).normalize()
+    const xAxis = new Vector3(1, 0, 0)
+    const yAxis = new Vector3().crossVectors(normal, xAxis).normalize()
+    const faceQuaternion = new Quaternion().setFromRotationMatrix(
+      new Matrix4().makeBasis(xAxis, yAxis, normal),
+    )
+
+    const resolved = resolveItemPlacementSurfaceNormal(
+      'block-face',
+      faceQuaternion,
+      null,
+      new Vector3(),
+      'wall',
+    )
+
+    expect(resolved.toArray()).toEqual(normal.toArray())
+  })
+
+  test('uses the upward host normal for a floor item on a block top face', () => {
+    const faceQuaternion = new Quaternion().setFromRotationMatrix(
+      new Matrix4().makeBasis(new Vector3(1, 0, 0), new Vector3(0, 0, -1), new Vector3(0, 1, 0)),
+    )
+    const itemQuaternion = faceQuaternion.multiply(
+      new Quaternion().setFromAxisAngle(new Vector3(1, 0, 0), Math.PI / 2),
+    )
+
+    const resolved = resolveItemPlacementSurfaceNormal(
+      'block-face',
+      itemQuaternion,
+      null,
+      new Vector3(),
+    )
+
+    expect(resolved.toArray().map((value) => Math.round(value))).toEqual([0, 1, 0])
+  })
+
+  test('uses the downward host normal for a block ceiling attachment', () => {
+    const faceQuaternion = new Quaternion().setFromRotationMatrix(
+      new Matrix4().makeBasis(new Vector3(1, 0, 0), new Vector3(0, 0, 1), new Vector3(0, -1, 0)),
+    )
+    const itemQuaternion = faceQuaternion.multiply(
+      new Quaternion().setFromAxisAngle(new Vector3(1, 0, 0), -Math.PI / 2),
+    )
+
+    const resolved = resolveItemPlacementSurfaceNormal(
+      'block-face',
+      itemQuaternion,
+      null,
+      new Vector3(),
+      'ceiling',
+    )
+
+    expect(resolved.toArray().map((value) => Math.round(value))).toEqual([0, -1, 0])
+  })
+})

package/src/components/tools/item/placement-surface.ts

@@ -0,0 +1,24 @@
+import type { Quaternion, Vector3 } from 'three'
+import type { SurfaceType } from './placement-types'
+
+export function resolveItemPlacementSurfaceNormal(
+  surface: SurfaceType,
+  ghostWorldQuaternion: Quaternion,
+  hostedItemWorldQuaternion: Quaternion | null,
+  target: Vector3,
+  attachTo?: 'wall' | 'wall-side' | 'ceiling',
+): Vector3 {
+  if (surface === 'block-face') {
+    if (attachTo === 'ceiling') target.set(0, -1, 0)
+    else if (attachTo === 'wall' || attachTo === 'wall-side') target.set(0, 0, 1)
+    else target.set(0, 1, 0)
+    target.applyQuaternion(ghostWorldQuaternion)
+    if (target.lengthSq() > 1e-6) return target.normalize()
+  }
+  if (surface === 'wall' || surface === 'roof-wall') {
+    target.set(0, 0, 1).applyQuaternion(hostedItemWorldQuaternion ?? ghostWorldQuaternion)
+    target.y = 0
+    if (target.lengthSq() > 1e-6) return target.normalize()
+  }
+  return target.set(0, 1, 0)
+}

package/src/components/tools/item/placement-types.ts

@@ -1,5 +1,6 @@
 import type {
   AnyNode,
+  AnyNodeId,
   AssetInput,
   CeilingNode,
   ItemNode,
@@ -16,6 +17,7 @@ export type SurfaceType =
   | 'floor'
   | 'wall'
   | 'roof-wall'
+  | 'block-face'
   | 'ceiling'
   | 'item-surface'
   | 'shelf-surface'
@@ -33,6 +35,8 @@ export interface PlacementState {
    * (base walls + coplanar gable ends).
    */
   roofSegmentId: string | null
+  /** Active planar node face used as a wall-like attachment host. */
+  blockId?: AnyNodeId | null
   ceilingId: string | null
   surfaceItemId: string | null
   /**
@@ -81,6 +85,7 @@ export interface PlacementResult {
   nodeUpdate: Partial<ItemNode> | null
   stopPropagation: boolean
   dirtyNodeId: AnyNode['id'] | null
+  hostFaceId?: string | null
 }
 
 /**
@@ -94,6 +99,7 @@ export interface TransitionResult {
   cursorRotationY: number
   cursorRotation?: [number, number, number]
   stopPropagation: boolean
+  hostFaceId?: string | null
 }
 
 /**

package/src/components/tools/item/test-face-host.ts

@@ -0,0 +1,121 @@
+import {
+  BlockNode,
+  type BlockNode as BlockNodeType,
+  type FaceHostCapability,
+  type ItemNode,
+  nodeRegistry,
+  registerNode,
+} from '@pascal-app/core'
+
+const faceForHit = (object: unknown, faceIndex = 0) => {
+  const geometry = (object as { geometry?: { userData?: Record<string, unknown> } }).geometry
+  const faces = geometry?.userData?.blockFaces
+  if (!Array.isArray(faces)) return null
+  return (
+    faces.find((face) => {
+      if (!face || typeof face !== 'object') return false
+      const entry = face as { start?: number; count?: number }
+      return (
+        typeof entry.start === 'number' &&
+        typeof entry.count === 'number' &&
+        faceIndex * 3 >= entry.start &&
+        faceIndex * 3 < entry.start + entry.count
+      )
+    }) as { faceId?: string } | undefined
+  )?.faceId
+}
+
+const testFaceHost: FaceHostCapability<BlockNodeType> = {
+  currentFaceId: (item) => item?.blockFaceId ?? null,
+  clearItemFields: ['position', 'rotation', 'blockFaceId'],
+  resolvePlacement: ({ asset, currentFaceId, faceIndex, host, localPosition, object }) => {
+    const hitFaceId = faceForHit(object, faceIndex) ?? null
+    const faceId = currentFaceId ?? hitFaceId
+    if (!faceId) return null
+
+    if (faceId === 'f-front') {
+      if (asset.attachTo !== 'wall-side' || localPosition[2] > -0.75) return null
+      return {
+        cursorPosition: [localPosition[0], localPosition[1], -1],
+        position: [localPosition[0], localPosition[1], -1],
+        rotation: [0, 0, 0],
+        cursorRotation: [0, 0, 0],
+        faceId,
+        nodeUpdate: {
+          parentId: host.id,
+          blockFaceId: faceId,
+          position: [localPosition[0], localPosition[1], 0],
+          rotation: [0, 0, 0],
+        },
+      }
+    }
+
+    if (faceId === 'f-bottom') {
+      if (asset.attachTo !== 'ceiling') return null
+      return {
+        cursorPosition: [0, -0.25, 0],
+        position: [0, 0, 0.25],
+        rotation: [-Math.PI / 2, 0, 0],
+        cursorRotation: [-Math.PI / 2, 0, 0],
+        faceId,
+        nodeUpdate: {
+          parentId: host.id,
+          blockFaceId: faceId,
+          position: [0, 0, 0.25],
+          rotation: [-Math.PI / 2, 0, 0],
+        },
+      }
+    }
+
+    if (faceId === 'f-top') {
+      if (asset.attachTo) return null
+      return {
+        cursorPosition: [0, 2.4, 0],
+        position: [0, 2.4, 0],
+        rotation: [Math.PI / 2, 0, 0],
+        cursorRotation: [Math.PI / 2, 0, 0],
+        faceId,
+        nodeUpdate: {
+          parentId: host.id,
+          blockFaceId: faceId,
+          position: [0, 0, 0],
+          rotation: [Math.PI / 2, 0, 0],
+        },
+      }
+    }
+
+    return null
+  },
+  storedPlacementPatch: ({ host, item, position }) => {
+    if (!item.blockFaceId) return null
+    return {
+      parentId: host.id,
+      blockFaceId: item.blockFaceId,
+      position: [position[0], position[1], position[2]],
+      rotation: item.rotation,
+      roofSegmentId: undefined,
+      roofFace: undefined,
+      wallId: undefined,
+      side: 'front',
+    } satisfies Partial<ItemNode>
+  },
+  isStoredPlacementValid: ({ item }) => Boolean(item.blockFaceId),
+}
+
+export function registerTestBlockFaceHost() {
+  // The registry is a module singleton shared across test files, and other
+  // suites register their own minimal `block` (the wall drafting stub is
+  // floor-placed only). Skipping on name alone would leave that capability-less
+  // definition in place, so replace it unless it already hosts faces.
+  if (nodeRegistry.get('block')?.capabilities?.faceHost) return
+  if (nodeRegistry.has('block')) nodeRegistry._reset()
+  registerNode({
+    kind: 'block',
+    schemaVersion: 1,
+    schema: BlockNode,
+    category: 'structure',
+    defaults: () => BlockNode.parse({ id: 'block_test', parentId: null }) as never,
+    capabilities: { faceHost: testFaceHost },
+    renderer: { kind: 'parametric', module: async () => ({ default: () => null }) },
+  } as never)
+}