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

package/src/components/systems/roof/roof-edit-system.test.tsx

@@ -0,0 +1,120 @@
+import { expect, test } from 'bun:test'
+import { RoofSegmentNode, sceneRegistry, useLiveNodeOverrides, useScene } from '@pascal-app/core'
+import { hideFromScene, showInScene, useViewer } from '@pascal-app/viewer'
+import { _roots, act, createRoot, extend, type Instance, type ThreeEvent } from '@react-three/fiber'
+import { createElement } from 'react'
+import * as THREE from 'three'
+import useInteractionScope from '../../../store/use-interaction-scope'
+import { RoofEditSystem } from './roof-edit-system'
+
+extend({ Group: THREE.Group, Mesh: THREE.Mesh, LineSegments: THREE.LineSegments })
+
+test('roof trim drag keeps its plane hit over a surface joining and leaving a batch', async () => {
+  const previousViewer = useViewer.getState()
+  const previousScene = useScene.getState()
+  const previousScope = useInteractionScope.getState().scope
+  const previousOverrides = useLiveNodeOverrides.getState()
+  const previousWindow = Object.getOwnPropertyDescriptor(globalThis, 'window')
+  const previousDocument = Object.getOwnPropertyDescriptor(globalThis, 'document')
+  const events = Object.assign(new EventTarget(), { setTimeout, clearTimeout })
+  Object.defineProperty(globalThis, 'window', { configurable: true, value: events })
+  Object.defineProperty(globalThis, 'document', {
+    configurable: true,
+    value: { body: { style: { cursor: '' } } },
+  })
+  const actGlobal = globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }
+  const previousAct = actGlobal.IS_REACT_ACT_ENVIRONMENT
+  actGlobal.IS_REACT_ACT_ENVIRONMENT = true
+  const canvas = Object.assign(new EventTarget(), {
+    getBoundingClientRect: () => ({ left: 0, top: 0, width: 100, height: 100 }),
+  }) as unknown as HTMLCanvasElement
+  const root = createRoot(canvas)
+  const camera = new THREE.PerspectiveCamera(60, 1, 0.1, 100)
+  camera.position.set(0, 15, 10)
+  camera.lookAt(0, 3, 0)
+  camera.updateMatrixWorld()
+  const scene = new THREE.Scene()
+  const segment = RoofSegmentNode.parse({
+    id: 'rseg_batch_drag',
+    width: 10,
+    depth: 10,
+    metadata: { showTrimPlanes: true },
+  })
+  const source = new THREE.Group()
+  const surface = new THREE.Mesh(new THREE.BoxGeometry(30, 0.25, 30), new THREE.MeshBasicMaterial())
+  surface.position.y = 2
+  scene.add(surface)
+  scene.updateMatrixWorld(true)
+  try {
+    sceneRegistry.nodes.set(segment.id, source)
+    useScene.setState({ nodes: { [segment.id]: segment }, readOnly: false })
+    useViewer.setState({
+      hoveredId: null,
+      selection: { buildingId: null, levelId: null, zoneId: null, selectedIds: [segment.id] },
+    })
+    await root.configure({
+      gl: {
+        domElement: canvas,
+        render() {},
+        setSize() {},
+        setPixelRatio() {},
+      } as unknown as THREE.WebGLRenderer,
+      camera,
+      scene,
+      frameloop: 'never',
+      dpr: 1,
+      size: { width: 100, height: 100, top: 0, left: 0 },
+    })
+    await act(async () => {
+      root.render(createElement(RoofEditSystem))
+    })
+    let pointerDown: ((event: ThreeEvent<PointerEvent>) => void) | undefined
+    scene.traverse((object) => {
+      const instance = (object as THREE.Object3D & { __r3f?: Instance }).__r3f
+      pointerDown ??= instance?.handlers.onPointerDown
+    })
+    expect(pointerDown).toBeDefined()
+    await act(async () => {
+      pointerDown!({
+        button: 0,
+        clientX: 50,
+        clientY: 50,
+        stopPropagation() {},
+      } as ThreeEvent<PointerEvent>)
+    })
+    const move = async () => {
+      await act(async () => {
+        events.dispatchEvent(Object.assign(new Event('pointermove'), { clientX: 60, clientY: 60 }))
+      })
+      return useLiveNodeOverrides.getState().overrides.get(segment.id)?.trim
+    }
+    const before = await move()
+    expect(before).toBeDefined()
+    expect(Object.values(before!).some((value) => (value as number) > 0)).toBe(true)
+    hideFromScene(surface, 'batched')
+    expect(await move()).toEqual(before)
+    showInScene(surface, 'batched')
+    expect(await move()).toEqual(before)
+    await act(async () => {
+      events.dispatchEvent(new Event('pointercancel'))
+    })
+    expect(useLiveNodeOverrides.getState().overrides.has(segment.id)).toBe(false)
+  } finally {
+    await act(async () => {
+      root.render(null)
+    })
+    _roots.delete(canvas)
+    sceneRegistry.nodes.delete(segment.id)
+    surface.geometry.dispose()
+    surface.material.dispose()
+    useScene.setState(previousScene)
+    useViewer.setState(previousViewer)
+    useInteractionScope.setState({ scope: previousScope })
+    useLiveNodeOverrides.setState(previousOverrides)
+    actGlobal.IS_REACT_ACT_ENVIRONMENT = previousAct
+    if (previousWindow) Object.defineProperty(globalThis, 'window', previousWindow)
+    else Reflect.deleteProperty(globalThis, 'window')
+    if (previousDocument) Object.defineProperty(globalThis, 'document', previousDocument)
+    else Reflect.deleteProperty(globalThis, 'document')
+  }
+})

package/src/components/systems/roof/roof-edit-system.tsx

@@ -22,6 +22,7 @@ import {
   csgEvaluator,
   generateRoofSegmentGeometry,
   INTERSECTION,
+  markPureRaycast,
   prepareBrushForCSG,
   useViewer,
 } from '@pascal-app/viewer'
@@ -707,7 +708,7 @@ function makeExpandedTrimRaycast(
   const halfX = Math.max(0.5, hitScale[0] / Math.max(visualScale[0], 1e-6) / 2)
   const halfY = Math.max(0.5, hitScale[1] / Math.max(visualScale[1], 1e-6) / 2)
   const halfZ = Math.max(0.5, hitScale[2] / Math.max(visualScale[2], 1e-6) / 2)
-  return function expandedTrimRaycast(
+  return markPureRaycast(function expandedTrimRaycast(
     this: THREE.Mesh,
     raycaster: THREE.Raycaster,
     intersects: THREE.Intersection[],
@@ -722,7 +723,7 @@ function makeExpandedTrimRaycast(
     const distance = raycaster.ray.origin.distanceTo(point)
     if (distance < raycaster.near || distance > raycaster.far) return
     intersects.push({ distance, point, object: this })
-  }
+  })
 }
 
 function trimEquals(a: RoofSegmentTrim, b: RoofSegmentTrim): boolean {
@@ -1788,16 +1789,14 @@ export const RoofEditSystem = () => {
   useEffect(() => {
     const nodes = useScene.getState().nodes
 
-    // Roofs where a segment itself is selected -> full edit mode (hide
-    // merged, show wrapper).
+    // Roofs where a segment itself is selected enter full edit mode.
     const activeRoofIds = new Set<string>()
     // Roofs where an accessory (dormer/chimney/etc.) is selected -> only
     // reveal the wrapper so handle portals into the segment mesh become
     // visible. Merged stays on.
     const revealRoofIds = new Set<string>()
-    // Roofs whose selected segment is currently being moved in 3D. During this
-    // transient state we reveal the wrapper so the moving segment mesh is
-    // visible and hide the merged roof to avoid the duplicate shell fighting it.
+    // Roofs whose selected segment is currently being moved in 3D. The merged
+    // roof remains the visual source and rebuilds from the live move override.
     const movingRoofIds = new Set<string>()
 
     for (const id of selectedIds) {
@@ -1842,14 +1841,8 @@ export const RoofEditSystem = () => {
       const isMoving = movingRoofIds.has(roofId)
       const isReveal = revealRoofIds.has(roofId)
 
-      // Keep the clean merged shell visible during trim editing too (not just
-      // when deselected). The merged shell rebuilds live from each segment's
-      // trim override (RoofSystem reads getEffectiveNode), so the dragged
-      // cutaway matches the commit. Showing the individual per-segment meshes
-      // instead would expose their abutting end-cap faces (the white planes the
-      // merged union removes) — exactly what the commit doesn't show.
-      if (mergedMesh) mergedMesh.visible = !isMoving
-      if (segmentsWrapper) segmentsWrapper.visible = isReveal || isMoving
+      if (mergedMesh) mergedMesh.visible = true
+      if (segmentsWrapper) segmentsWrapper.visible = isReveal
 
       const roofNode = nodes[roofId as AnyNodeId] as RoofNode | undefined
       if (roofNode?.children?.length) {
@@ -1857,10 +1850,8 @@ export const RoofEditSystem = () => {
         const wasMoving = prevMovingRoofIds.current.has(roofId)
         const wasReveal = prevRevealRoofIds.current.has(roofId)
         if (isActive !== wasActive || isMoving !== wasMoving) {
-          // Entering / exiting full edit mode: rebuild segment / merged
-          // geometries. Segment-move reveal uses the same rebuild so any
-          // wrapper mesh previously stripped to an empty placeholder is
-          // restored before the drag begins.
+          // Entering or exiting edit and move modes rebuilds the merged shell
+          // from the current segment values.
           const { markDirty } = useScene.getState()
           for (const childId of roofNode.children) {
             markDirty(childId as AnyNodeId)

package/src/components/systems/selection-affordance-manager.tsx

@@ -1,9 +1,19 @@
 'use client'
 
-import { type AnyNodeId, useScene } from '@pascal-app/core'
+import {
+  type AnyNodeId,
+  createSceneApi,
+  runAsSingleSceneHistoryStep,
+  useScene,
+} from '@pascal-app/core'
 import { useViewer } from '@pascal-app/viewer'
 import { type ComponentType, Suspense, useMemo } from 'react'
 import { getRegistryAffordanceTool } from '../tools/shared/affordance-dispatch'
+import type {
+  SelectionAffordanceHistoryApi,
+  SelectionAffordanceInteractionApi,
+  SelectionAffordanceProps,
+} from './selection-affordance-services'
 
 /**
  * Editor-mounted dispatcher for a kind's selection-time editing UI.
@@ -19,20 +29,60 @@ import { getRegistryAffordanceTool } from '../tools/shared/affordance-dispatch'
  */
 export function SelectionAffordanceManager() {
   const selectedIds = useViewer((s) => s.selection.selectedIds)
-  const selectedKind = useScene((s) => {
+  const selectedNode = useScene((s) => {
     if (selectedIds.length !== 1) return null
-    return s.nodes[selectedIds[0] as AnyNodeId]?.type ?? null
+    return s.nodes[selectedIds[0] as AnyNodeId] ?? null
   })
+  const readOnly = useScene((s) => s.readOnly)
+  const sceneApi = useMemo(() => createSceneApi(useScene), [])
+  const historyApi = useMemo<SelectionAffordanceHistoryApi>(
+    () => ({
+      depth: () => useScene.temporal.getState().pastStates.length,
+      replaceLatest: (expectedDepth, replace) => {
+        if (useScene.temporal.getState().pastStates.length !== expectedDepth) return false
+        let replaced = false
+        runAsSingleSceneHistoryStep(useScene, () => {
+          useScene.temporal.getState().undo()
+          replaced = replace()
+          if (!replaced) useScene.temporal.getState().redo()
+        })
+        return replaced
+      },
+    }),
+    [],
+  )
+  const interactionApi = useMemo<SelectionAffordanceInteractionApi>(
+    () => ({
+      beginInputDrag: () => {
+        const previous = useViewer.getState().inputDragging
+        let restored = false
+        useViewer.getState().setInputDragging(true)
+        return () => {
+          if (restored) return
+          restored = true
+          useViewer.getState().setInputDragging(previous)
+        }
+      },
+      clearSelection: () => useViewer.getState().setSelection({ selectedIds: [] }),
+    }),
+    [],
+  )
 
-  const Component = useMemo<ComponentType | null>(() => {
-    if (!selectedKind) return null
-    return getRegistryAffordanceTool(selectedKind, 'selection')
-  }, [selectedKind])
+  const Component = useMemo<ComponentType<SelectionAffordanceProps> | null>(() => {
+    if (!selectedNode) return null
+    return getRegistryAffordanceTool(selectedNode.type, 'selection')
+  }, [selectedNode])
 
-  if (!Component) return null
+  if (!(Component && selectedNode)) return null
   return (
     <Suspense fallback={null}>
-      <Component />
+      <Component
+        historyApi={historyApi}
+        interactionApi={interactionApi}
+        node={selectedNode}
+        readOnly={readOnly}
+        sceneApi={sceneApi}
+      />
     </Suspense>
   )
 }

package/src/components/systems/selection-affordance-services.ts

@@ -0,0 +1,19 @@
+import type { AnyNode, SceneApi } from '@pascal-app/core'
+
+export type SelectionAffordanceHistoryApi = {
+  depth: () => number
+  replaceLatest: (expectedDepth: number, replace: () => boolean) => boolean
+}
+
+export type SelectionAffordanceInteractionApi = {
+  beginInputDrag: () => () => void
+  clearSelection: () => void
+}
+
+export type SelectionAffordanceProps = {
+  historyApi: SelectionAffordanceHistoryApi
+  interactionApi: SelectionAffordanceInteractionApi
+  node: AnyNode
+  readOnly: boolean
+  sceneApi: SceneApi
+}

package/src/components/systems/stair/stair-edit-system.tsx

@@ -67,9 +67,12 @@ export const StairEditSystem = () => {
       const mergedMesh = group.getObjectByName('merged-stair')
       const segmentsWrapper = group.getObjectByName('segments-wrapper')
       const isActive = activeStairIds.has(stairId)
+      // A straight stair with no segment children has an empty wrapper, so
+      // edit mode would hide the merged body and leave nothing on screen.
+      const isEditable = !isCurved && (stairNode?.children?.length ?? 0) > 0
 
-      if (mergedMesh) mergedMesh.visible = !(isActive || isCurved)
-      if (segmentsWrapper) segmentsWrapper.visible = isActive && !isCurved
+      if (mergedMesh) mergedMesh.visible = !((isActive && isEditable) || isCurved)
+      if (segmentsWrapper) segmentsWrapper.visible = isActive && isEditable
 
       if (stairNode?.children?.length) {
         const wasActive = prevActiveStairIds.current.has(stairId)

package/src/components/tools/fence/fence-drafting.test.ts

@@ -0,0 +1,100 @@
+import { beforeEach, describe, expect, test } from 'bun:test'
+import {
+  type AnyNode,
+  type AnyNodeId,
+  GROUND_SUPPORT_ID,
+  type SlabNode,
+  spatialGridManager,
+  useScene,
+} from '@pascal-app/core'
+import { useViewer } from '@pascal-app/viewer'
+import useEditor from '../../../store/use-editor'
+import { createFenceOnCurrentLevel } from './fence-drafting'
+
+const LEVEL_ID = 'level_test' as AnyNodeId
+
+function seedLevel(extraNodes: AnyNode[] = []) {
+  useScene.setState({
+    nodes: Object.fromEntries([
+      [
+        LEVEL_ID,
+        {
+          id: LEVEL_ID,
+          type: 'level',
+          object: 'node',
+          parentId: null,
+          visible: true,
+          metadata: {},
+          children: extraNodes.map((node) => node.id),
+          level: 0,
+        } as AnyNode,
+      ],
+      ...extraNodes.map((node) => [node.id, node] as const),
+    ]),
+    rootNodeIds: [LEVEL_ID],
+    dirtyNodes: new Set(),
+    collections: {},
+  } as never)
+}
+
+describe('createFenceOnCurrentLevel', () => {
+  beforeEach(() => {
+    spatialGridManager.clear()
+    useViewer.setState({
+      selection: {
+        buildingId: null,
+        levelId: LEVEL_ID,
+        zoneId: null,
+        selectedIds: [],
+      },
+    } as never)
+    useEditor.getState().setToolDefaults('fence', null)
+    seedLevel()
+  })
+
+  test('freezes a block top above its underlying slab', () => {
+    const slab = {
+      id: 'slab_low',
+      type: 'slab',
+      object: 'node',
+      parentId: LEVEL_ID,
+      visible: true,
+      metadata: {},
+      children: [],
+      polygon: [
+        [-2, -2],
+        [2, -2],
+        [2, 2],
+        [-2, 2],
+      ],
+      holes: [],
+      holeMetadata: [],
+      elevation: 0.25,
+      thickness: 0.25,
+      recessed: false,
+      autoFromWalls: false,
+    } as SlabNode
+    seedLevel([slab as AnyNode])
+    spatialGridManager.handleNodeCreated(slab as AnyNode, LEVEL_ID)
+
+    const fence = createFenceOnCurrentLevel([-1, 0], [1, 0], {
+      supportCap: 2,
+      preferredSupportSlabId: slab.id,
+      constructionElevation: 2,
+    })
+
+    expect(fence?.supportSlabId).toBe(slab.id)
+    expect(fence?.supportOffset).toBeCloseTo(1.75)
+  })
+
+  test('pins ground beneath a block top when no slab exists', () => {
+    const fence = createFenceOnCurrentLevel([-1, 0], [1, 0], {
+      supportCap: 2,
+      preferredSupportSlabId: null,
+      constructionElevation: 2,
+    })
+
+    expect(fence?.supportSlabId).toBe(GROUND_SUPPORT_ID)
+    expect(fence?.supportOffset).toBeCloseTo(2)
+  })
+})

package/src/components/tools/fence/fence-drafting.ts

@@ -1,11 +1,12 @@
 import {
   DEFAULT_ANGLE_STEP,
+  type FenceConstructionOptions as FenceCommitOptions,
   FenceNode,
   getTwoPointFenceCurveTangents,
   getWallCurveFrameAt,
   getWallCurveLength,
   isCurvedWall,
-  resolveFenceSupportSlabPatch,
+  resolveFenceConstructionSupport,
   snapPointAlongAngleRay,
   useScene,
   type WallNode,
@@ -188,18 +189,6 @@ export function snapFenceDraftPoint(args: {
   return fenceSnapTarget ?? findWallSnapTarget(basePoint, walls) ?? basePoint
 }
 
-export type FenceCommitOptions = {
-  /**
-   * Pointer-decided support cap (level-local Y) from
-   * `resolvePointerSupportSurface` — the 3D tool passes the elevation of
-   * the surface the commit click actually aimed at, so a fence drawn on a
-   * deck top persists the deck as its lift host while one drawn at the
-   * floor underneath stays grounded. Omitted by 2D floor-plan commits (no
-   * camera ray): those keep the uncapped max election.
-   */
-  supportCap?: number | null
-}
-
 export function createFenceOnCurrentLevel(
   start: FencePlanPoint,
   end: FencePlanPoint,
@@ -217,7 +206,7 @@ export function createFenceOnCurrentLevel(
   // spacing, …) merge in first; `name`/`start`/`end` always win. The
   // schema parse validates and drops anything unexpected.
   const defaults = useEditor.getState().toolDefaults.fence ?? {}
-  const fence = FenceNode.parse({
+  const authoredFence = FenceNode.parse({
     ...defaults,
     name: `Fence ${fenceCount + 1}`,
     start,
@@ -225,11 +214,7 @@ export function createFenceOnCurrentLevel(
   })
   // Fences run no per-frame support election — the persisted host IS the
   // lift (absent = level floor), so elect it at commit, pointer-capped.
-  fence.supportSlabId = resolveFenceSupportSlabPatch(
-    { ...fence, parentId: currentLevelId },
-    nodes,
-    { maxElevation: options?.supportCap ?? null },
-  ).supportSlabId
+  const fence = resolveFenceConstructionSupport(authoredFence, currentLevelId, nodes, options)
 
   createNode(fence, currentLevelId)
   sfxEmitter.emit('sfx:structure-build')
@@ -264,7 +249,7 @@ export function createSplineFenceOnCurrentLevel(
 
   const fenceCount = Object.values(nodes).filter((node) => node.type === 'fence').length
   const defaults = useEditor.getState().toolDefaults.fence ?? {}
-  const fence = FenceNode.parse({
+  const authoredFence = FenceNode.parse({
     ...defaults,
     name: `Fence ${fenceCount + 1}`,
     start,
@@ -272,11 +257,7 @@ export function createSplineFenceOnCurrentLevel(
     path,
     tangents,
   })
-  fence.supportSlabId = resolveFenceSupportSlabPatch(
-    { ...fence, parentId: currentLevelId },
-    nodes,
-    { maxElevation: options?.supportCap ?? null },
-  ).supportSlabId
+  const fence = resolveFenceConstructionSupport(authoredFence, currentLevelId, nodes, options)
 
   createNode(fence, currentLevelId)
   sfxEmitter.emit('sfx:structure-build')

package/src/components/tools/item/draft-creation.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, test } from 'bun:test'
+import { shouldCreateFloorDraft } from './draft-creation'
+
+describe('shouldCreateFloorDraft', () => {
+  test('does not create a level-hosted draft while block-face placement is active', () => {
+    expect(shouldCreateFloorDraft(null, undefined, 'block-face')).toBe(false)
+  })
+
+  test('creates a draft for an unmounted floor placement', () => {
+    expect(shouldCreateFloorDraft(null, undefined, 'floor')).toBe(true)
+  })
+})

package/src/components/tools/item/draft-creation.ts

@@ -0,0 +1,10 @@
+import type { AssetInput, ItemNode } from '@pascal-app/core'
+import type { PlacementState } from './placement-types'
+
+export function shouldCreateFloorDraft(
+  draft: ItemNode | null,
+  attachTo: AssetInput['attachTo'],
+  surface: PlacementState['surface'],
+): boolean {
+  return draft === null && attachTo === undefined && surface === 'floor'
+}

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

@@ -0,0 +1,65 @@
+import { beforeEach, describe, expect, test } from 'bun:test'
+import { BlockNode, ItemNode, type LevelNode, useScene } from '@pascal-app/core'
+import { Vector3 } from 'three'
+import { resolveFaceHostPreviewCommit } from './face-host-commit'
+import type { PlacementContext } from './placement-types'
+import { registerTestBlockFaceHost } from './test-face-host'
+
+const BLOCK_ID = 'block_self-click'
+const LEVEL_ID = 'level_self-click' as LevelNode['id']
+
+beforeEach(() => {
+  registerTestBlockFaceHost()
+  useScene.setState((state) => ({
+    ...state,
+    nodes: {
+      ...state.nodes,
+      [BLOCK_ID]: BlockNode.parse({ id: BLOCK_ID, parentId: LEVEL_ID }),
+    },
+  }))
+})
+
+describe('resolveFaceHostPreviewCommit', () => {
+  test('commits an intercepted draft click to its active block face', () => {
+    const asset = {
+      id: 'cactus',
+      category: 'decor',
+      name: 'Cactus',
+      thumbnail: '/cactus.png',
+      src: '/cactus.glb',
+      dimensions: [0.5, 0.39, 0.5] as [number, number, number],
+    }
+    const context: PlacementContext = {
+      asset,
+      levelId: LEVEL_ID,
+      draftItem: ItemNode.parse({
+        id: 'item_self-click',
+        asset,
+        parentId: BLOCK_ID,
+        position: [0.5, -0.5, 0],
+        rotation: [Math.PI / 2, 0, 0],
+        blockFaceId: 'face-top',
+        metadata: { isTransient: true },
+      }),
+      gridPosition: new Vector3(0.5, -0.5, 0),
+      state: {
+        surface: 'block-face',
+        blockId: BLOCK_ID,
+        wallId: null,
+        roofSegmentId: null,
+        ceilingId: null,
+        surfaceItemId: null,
+        shelfId: null,
+      },
+      currentCursorRotationY: 0,
+    }
+
+    expect(resolveFaceHostPreviewCommit(context)?.nodeUpdate).toMatchObject({
+      parentId: BLOCK_ID,
+      position: [0.5, -0.5, 0],
+      rotation: [Math.PI / 2, 0, 0],
+      blockFaceId: 'face-top',
+      metadata: {},
+    })
+  })
+})

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

@@ -0,0 +1,56 @@
+import type { ItemNode, NodeEvent } from '@pascal-app/core'
+import { nodeRegistry, useScene } from '@pascal-app/core'
+import { stripTransient } from './placement-math'
+import { faceHostStrategy } from './placement-strategies'
+import type { CommitResult, PlacementContext } from './placement-types'
+
+export type FaceHostClickCommitOutcome = {
+  committedId: string | null
+  wasAdopted: boolean
+}
+
+export function commitFaceHostClick({
+  commitDraft,
+  enterFaceHost,
+  event,
+  getContext,
+}: {
+  commitDraft: (nodeUpdate: Partial<ItemNode>) => FaceHostClickCommitOutcome
+  enterFaceHost: (event: NodeEvent) => boolean
+  event: NodeEvent
+  getContext: () => PlacementContext
+}): FaceHostClickCommitOutcome | null {
+  let result = faceHostStrategy.click(getContext(), event)
+  if (!result && enterFaceHost(event)) {
+    result = faceHostStrategy.click(getContext(), event)
+  }
+  if (!result) return null
+  const outcome = commitDraft(result.nodeUpdate)
+  event.stopPropagation()
+  return outcome
+}
+
+export function resolveFaceHostPreviewCommit(context: PlacementContext): CommitResult | null {
+  const { draftItem, gridPosition, state } = context
+  if (state.surface !== 'block-face' || !state.blockId || !draftItem) {
+    return null
+  }
+  const host = useScene.getState().nodes[state.blockId]
+  const faceHost = host ? nodeRegistry.get(host.type)?.capabilities.faceHost : undefined
+  if (!(host && faceHost)) return null
+  const nodeUpdate = faceHost?.storedPlacementPatch({
+    host,
+    item: draftItem,
+    position: [gridPosition.x, gridPosition.y, gridPosition.z],
+  })
+  if (!nodeUpdate) return null
+
+  return {
+    nodeUpdate: {
+      ...nodeUpdate,
+      metadata: stripTransient(draftItem.metadata),
+    },
+    stopPropagation: true,
+    dirtyNodeId: null,
+  }
+}