nodes: improve block mesh editing UX

apps/editor/app/page.tsx

@@ -90,12 +90,15 @@ export default function Home() {
   return (
     <div className="relative h-screen w-screen">
       {PROJECT_ID === 'local-editor' && (
-        <div className="pointer-events-none absolute top-3 left-1/2 z-40 -translate-x-1/2">
-          <div className="pointer-events-auto flex max-w-[min(92vw,42rem)] flex-wrap items-center justify-center gap-x-3 gap-y-1 rounded-full border border-border/60 bg-background/90 px-4 py-1.5 text-xs shadow-sm backdrop-blur">
+        <div className="pointer-events-none absolute top-14 left-1/2 z-40 -translate-x-1/2">
+          <div className="pointer-events-none flex max-w-[min(92vw,42rem)] flex-wrap items-center justify-center gap-x-3 gap-y-1 rounded-full border border-border/60 bg-background/90 px-4 py-1.5 text-xs shadow-sm backdrop-blur">
             <span className="text-muted-foreground">
               Blank canvas — saved scenes are under Scenes (not this page).
             </span>
-            <Link className="font-medium text-foreground hover:underline" href="/scenes">
+            <Link
+              className="pointer-events-auto font-medium text-foreground hover:underline"
+              href="/scenes"
+            >
               Open saved scenes
             </Link>
           </div>

packages/editor/src/components/systems/selection-affordance-manager.tsx

@@ -1,9 +1,18 @@
 '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,
+  SelectionAffordanceProps,
+} from './selection-affordance-services'
 
 /**
  * Editor-mounted dispatcher for a kind's selection-time editing UI.
@@ -19,20 +28,43 @@ 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 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}
+        node={selectedNode}
+        readOnly={readOnly}
+        sceneApi={sceneApi}
+      />
     </Suspense>
   )
 }

packages/editor/src/components/systems/selection-affordance-services.ts

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

packages/editor/src/components/tools/item/block-preview.test.ts → packages/editor/src/components/tools/item/face-host-preview.test.ts

@@ -1,73 +1,73 @@
 import { describe, expect, test } from 'bun:test'
 import { Group } from 'three'
 import {
-  applyBlockPreviewPose,
-  clampBlockFaceCenterPosition,
-  clampBlockFacePosition,
-  resolveBlockFaceSwitch,
-  shouldDetachBlockFaceOnLeave,
-} from './block-preview'
+  applyFaceHostPreviewPose,
+  clampFaceHostCenterPosition,
+  clampFaceHostPosition,
+  resolveFaceHostSwitch,
+  shouldDetachFaceHostOnLeave,
+} from './face-host-preview'
 
-describe('applyBlockPreviewPose', () => {
+describe('applyFaceHostPreviewPose', () => {
   test('moves the rendered draft synchronously with the pointer result', () => {
     const mesh = new Group()
     mesh.position.set(8, 8, 8)
     mesh.rotation.set(1, 1, 1)
 
-    applyBlockPreviewPose(mesh, [1.25, -0.5, 0], [0, 0, 0])
+    applyFaceHostPreviewPose(mesh, [1.25, -0.5, 0], [0, 0, 0])
 
     expect(mesh.position.toArray()).toEqual([1.25, -0.5, 0])
     expect(mesh.rotation.toArray().slice(0, 3)).toEqual([0, 0, 0])
   })
 })
 
-describe('resolveBlockFaceSwitch', () => {
+describe('resolveFaceHostSwitch', () => {
   test('ignores a single adjacent-face hit and accepts a repeated hit', () => {
-    const first = resolveBlockFaceSwitch('face-a', 'face-b', null)
+    const first = resolveFaceHostSwitch('face-a', 'face-b', null)
     expect(first).toEqual({ accept: false, pendingFaceId: 'face-b' })
 
-    const second = resolveBlockFaceSwitch('face-a', 'face-b', first.pendingFaceId)
+    const second = resolveFaceHostSwitch('face-a', 'face-b', first.pendingFaceId)
     expect(second).toEqual({ accept: true, pendingFaceId: null })
   })
 
   test('clears a pending switch when the pointer returns to the current face', () => {
-    expect(resolveBlockFaceSwitch('face-a', 'face-a', 'face-b')).toEqual({
+    expect(resolveFaceHostSwitch('face-a', 'face-a', 'face-b')).toEqual({
       accept: true,
       pendingFaceId: null,
     })
   })
 })
 
-describe('shouldDetachBlockFaceOnLeave', () => {
-  test('keeps attached items on the last valid block face during transient leave events', () => {
-    expect(shouldDetachBlockFaceOnLeave('wall')).toBe(false)
-    expect(shouldDetachBlockFaceOnLeave('wall-side')).toBe(false)
-    expect(shouldDetachBlockFaceOnLeave('ceiling')).toBe(false)
+describe('shouldDetachFaceHostOnLeave', () => {
+  test('detaches attached items when they leave a block face', () => {
+    expect(shouldDetachFaceHostOnLeave('wall')).toBe(true)
+    expect(shouldDetachFaceHostOnLeave('wall-side')).toBe(true)
+    expect(shouldDetachFaceHostOnLeave('ceiling')).toBe(true)
   })
 
   test('allows free floor items to leave a block face', () => {
-    expect(shouldDetachBlockFaceOnLeave(undefined)).toBe(true)
+    expect(shouldDetachFaceHostOnLeave(undefined)).toBe(true)
   })
 })
 
-describe('clampBlockFacePosition', () => {
+describe('clampFaceHostPosition', () => {
   test('keeps the complete wall item inside the face after snapping', () => {
     expect(
-      clampBlockFacePosition([1.9, 2.8, 0], { minU: -2, maxU: 2, minV: 0, maxV: 3 }, [1, 1]),
+      clampFaceHostPosition([1.9, 2.8, 0], { minU: -2, maxU: 2, minV: 0, maxV: 3 }, [1, 1]),
     ).toEqual([1.5, 2, 0])
   })
 
   test('rejects a face that is smaller than the item', () => {
     expect(
-      clampBlockFacePosition([0, 0, 0], { minU: -0.25, maxU: 0.25, minV: 0, maxV: 0.5 }, [1, 1]),
+      clampFaceHostPosition([0, 0, 0], { minU: -0.25, maxU: 0.25, minV: 0, maxV: 0.5 }, [1, 1]),
     ).toBeNull()
   })
 })
 
-describe('clampBlockFaceCenterPosition', () => {
+describe('clampFaceHostCenterPosition', () => {
   test('keeps a ceiling fixture footprint inside the face on both axes', () => {
     expect(
-      clampBlockFaceCenterPosition(
+      clampFaceHostCenterPosition(
         [1.9, 1.9, 0.25],
         { minU: -2, maxU: 2, minV: -2, maxV: 2 },
         [1, 1],

packages/editor/src/components/tools/item/block-preview.ts → packages/editor/src/components/tools/item/face-host-preview.ts

@@ -9,7 +9,7 @@ type FaceBounds = {
   maxV: number
 }
 
-export function applyBlockPreviewPose(
+export function applyFaceHostPreviewPose(
   mesh: Object3D,
   position: Vector3Tuple,
   rotation: Vector3Tuple,
@@ -18,7 +18,7 @@ export function applyBlockPreviewPose(
   mesh.rotation.set(rotation[0], rotation[1], rotation[2])
 }
 
-export function resolveBlockFaceSwitch(
+export function resolveFaceHostSwitch(
   currentFaceId: string | null | undefined,
   nextFaceId: string | null | undefined,
   pendingFaceId: string | null,
@@ -34,11 +34,16 @@ export function resolveBlockFaceSwitch(
   return { accept: false, pendingFaceId: nextFaceId }
 }
 
-export function shouldDetachBlockFaceOnLeave(attachTo: string | undefined): boolean {
-  return !attachTo
+export function shouldDetachFaceHostOnLeave(attachTo: string | undefined): boolean {
+  return (
+    attachTo === undefined ||
+    attachTo === 'wall' ||
+    attachTo === 'wall-side' ||
+    attachTo === 'ceiling'
+  )
 }
 
-export function clampBlockFacePosition(
+export function clampFaceHostPosition(
   position: Vector3Tuple,
   bounds: FaceBounds,
   dimensions: readonly [width: number, height: number],
@@ -57,7 +62,7 @@ export function clampBlockFacePosition(
   ]
 }
 
-export function clampBlockFaceCenterPosition(
+export function clampFaceHostCenterPosition(
   position: Vector3Tuple,
   bounds: FaceBounds,
   dimensions: readonly [width: number, depth: number],

packages/editor/src/components/tools/item/use-placement-coordinator.tsx

@@ -71,13 +71,13 @@ import {
   resolvePointerSupportElevation,
   resolvePointerSupportSurface,
 } from '../shared/pointer-support-cap'
-import {
-  applyBlockPreviewPose,
-  resolveBlockFaceSwitch,
-  shouldDetachBlockFaceOnLeave,
-} from './block-preview'
 import { shouldCreateFloorDraft } from './draft-creation'
 import { commitFaceHostClick, resolveFaceHostPreviewCommit } from './face-host-commit'
+import {
+  applyFaceHostPreviewPose,
+  resolveFaceHostSwitch,
+  shouldDetachFaceHostOnLeave,
+} from './face-host-preview'
 import {
   getDetachedAttachmentPreviewLift,
   getGridAlignedDimensions,
@@ -1569,7 +1569,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       event.stopPropagation()
       const draft = draftNode.current
       const nextFaceId = result.hostFaceId
-      const faceSwitch = resolveBlockFaceSwitch(
+      const faceSwitch = resolveFaceHostSwitch(
         currentFaceHostId(draft),
         nextFaceId,
         pendingFaceHostId,
@@ -1594,7 +1594,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
         Object.assign(draft, result.nodeUpdate)
         const mesh = sceneRegistry.nodes.get(draft.id)
         const rotation = result.nodeUpdate.rotation ?? draft.rotation
-        if (mesh) applyBlockPreviewPose(mesh, result.gridPosition, rotation)
+        if (mesh) applyFaceHostPreviewPose(mesh, result.gridPosition, rotation)
         useLiveNodeOverrides.getState().set(draft.id, {
           position: result.gridPosition,
           rotation,
@@ -1622,7 +1622,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
 
     const onFaceHostLeave = (event: NodeEvent) => {
       pendingFaceHostId = null
-      if (!shouldDetachBlockFaceOnLeave(asset.attachTo)) {
+      if (!shouldDetachFaceHostOnLeave(asset.attachTo)) {
         event.stopPropagation()
         return
       }
@@ -2700,7 +2700,7 @@ export function usePlacementCoordinator(config: PlacementCoordinatorConfig): Rea
       }
     } else if (placementState.current.surface === 'block-face') {
       const rotation = draftNode.current.rotation
-      applyBlockPreviewPose(
+      applyFaceHostPreviewPose(
         mesh,
         [gridPosition.current.x, gridPosition.current.y, gridPosition.current.z],
         rotation,

packages/editor/src/hooks/use-keyboard.test.ts

@@ -8,7 +8,11 @@ import {
 } from '@pascal-app/core'
 import { meshEditScope } from '../lib/interaction/scope'
 import useInteractionScope from '../store/use-interaction-scope'
-import { runHistoryShortcut } from './use-keyboard'
+import {
+  canCycleSnappingModeShortcut,
+  canRunGlobalRotationShortcut,
+  runHistoryShortcut,
+} from './use-keyboard'
 
 type RafFn = (callback: (time: number) => void) => number
 ;(globalThis as unknown as { requestAnimationFrame?: RafFn }).requestAnimationFrame ??= (
@@ -42,6 +46,20 @@ afterEach(() => {
 })
 
 describe('history shortcuts during block editing', () => {
+  test('reserves global rotation shortcuts for the active mesh editor', () => {
+    expect(canRunGlobalRotationShortcut()).toBe(true)
+    useInteractionScope.getState().begin(meshEditScope(NODE_ID))
+    expect(canRunGlobalRotationShortcut()).toBe(false)
+  })
+
+  test('keeps Shift available to cycle snapping while a mesh operation is active', () => {
+    useInteractionScope.getState().begin(meshEditScope(NODE_ID))
+    expect(canCycleSnappingModeShortcut(true)).toBe(true)
+
+    useInteractionScope.getState().begin(meshEditScope(NODE_ID, 'operating', 'translate'))
+    expect(canCycleSnappingModeShortcut(true)).toBe(true)
+  })
+
   test('undoes and redoes mesh changes without leaving component selection mode', () => {
     useInteractionScope.getState().begin(meshEditScope(NODE_ID))