@pascal-app/editor 1.0.3 → 1.0.4

package/src/hooks/use-keyboard.ts

@@ -5,6 +5,7 @@ import {
   nodeRegistry,
   pauseSpaceDetection,
   resumeSpaceDetection,
+  toggleNodeMechanism,
   useScene,
 } from '@pascal-app/core'
 import { cancelPerfAction, markPerfAction, useViewer } from '@pascal-app/viewer'
@@ -23,16 +24,20 @@ import {
   rotateGroupPatches,
 } from '../components/editor/group-transform-shared'
 import { steppedRotation } from '../components/tools/item/placement-math'
+import { keyCyclableContinuationContext } from '../lib/continuation'
 import { resolveDirectManipulationNode } from '../lib/direct-manipulation'
-import { toggleDoorOpenState } from '../lib/door-interaction'
+import { cancelGestures } from '../lib/gesture-lifecycle'
 import { guideEmitter } from '../lib/guide-events'
 import { isHistoryShortcut, runRedo, runUndo, shouldCancelDraftOnHistoryJump } from '../lib/history'
 import { isActive } from '../lib/interaction/scope'
+import { paintRegionModeActive } from '../lib/paint-region-mode'
+import { popRoomSelection } from '../lib/room-selection-commands'
 import { copySelectedNodesToEditorClipboard } from '../lib/scene-clipboard'
 import { sfxEmitter } from '../lib/sfx-bus'
+import { openSidebarPanel } from '../lib/sidebar-panel'
 import { activeSiteNode, clampBrushRadius } from '../lib/terrain-sculpt'
 import { leaveUnitFocus } from '../lib/units'
-import { toggleWindowOpenState } from '../lib/window-interaction'
+import { selectWallDrawVariant } from '../lib/wall-draw-variant'
 import useDeleteConfirmation from '../store/use-delete-confirmation'
 import useEditor, { getActiveContinuationContext, getActiveSnapContext } from '../store/use-editor'
 import useInteractionScope, {
@@ -108,9 +113,13 @@ export const markToolCancelConsumed = () => {
 // preset/item placement rely on this — they pass no coordinator onCancel, and
 // it is the mode switch unmounting them that destroys the draft.
 const exitToSelectAfterUnconsumedCancel = () => {
-  const currentPhase = useEditor.getState().phase
-  const currentStructureLayer = useEditor.getState().structureLayer
-
+  const editor = useEditor.getState()
+  if (
+    editor.mode === 'select' &&
+    useInteractionScope.getState().scope.kind === 'idle' &&
+    popRoomSelection()
+  )
+    return
   useInteractionScope
     .getState()
     .endIf(
@@ -119,14 +128,8 @@ const exitToSelectAfterUnconsumedCancel = () => {
         (sc.kind === 'reshaping' && sc.reshape === 'hole'),
     )
 
-  // From zone mode, return to structure select
-  if (currentPhase === 'structure' && currentStructureLayer === 'zones') {
-    useEditor.getState().setStructureLayer('elements')
-    useEditor.getState().armToolMode({ mode: 'select' })
-  } else {
-    // Return to the default select tool while keeping the active building/level context.
-    useEditor.getState().armToolMode({ mode: 'select' })
-  }
+  // Back to the select tool, keeping the active building/level context.
+  useEditor.getState().armToolMode({ mode: 'select' })
 
   useEditor.getState().setFloorplanSelectionTool('click')
 
@@ -160,6 +163,11 @@ const cancelInteractionForHistoryShortcut = () => {
     guideEmitter.emit('guide:cancel-reference-scale')
     return true
   }
+  // A live gesture reads ⌘Z as "abort", never as a jump under the pointer.
+  if (cancelGestures('history')) {
+    cancelPerfAction()
+    return true
+  }
   const activeScope = useInteractionScope.getState().scope
   if (shouldCancelDraftOnHistoryJump()) return false
   if (activeScope.kind === 'mesh-editing' && activeScope.phase === 'selecting') return false
@@ -191,8 +199,42 @@ export const runHistoryShortcut = (direction: 'undo' | 'redo') => {
   return true
 }
 
-/** Whether an armed tool owns the rotation key (`R` or `T`) instead of the selection. */
-export const isToolOwnedRotation = (key: 'r' | 't' = 'r') => {
+/**
+ * B: the wall tool on Rectangle — the quickest room — with the Build panel
+ * showing, so the lit tile says what is in hand. The panel's tiles still pick
+ * another shape for the session. The panel opens before the tool is armed: a
+ * host may drop the armed tool when the panel changes.
+ */
+export const armWallToolFromShortcut = () => {
+  selectWallDrawVariant('rectangle')
+  openSidebarPanel(['build'])
+  useEditor.getState().armToolMode({ mode: 'build', tool: 'wall' })
+}
+
+/** 1: site, 2: the building — each back on the select tool. Returns whether `key` was one. */
+export const switchPhaseFromShortcut = (key: string): boolean => {
+  const phase = key === '1' ? 'site' : key === '2' ? 'building' : null
+  if (!phase) return false
+  useEditor.getState().setPhase(phase)
+  useEditor.getState().armToolMode({ mode: 'select' })
+  return true
+}
+
+/** F: the item tool with the items catalog showing, opened first as B's is. */
+export const openItemCatalogFromShortcut = () => {
+  openSidebarPanel(['items'])
+  useEditor.getState().setActiveSidebarPanel('items')
+  useEditor.getState().armToolMode({ mode: 'build', tool: 'item' })
+}
+
+/** P: paint mode, with the Paint panel showing (the Build panel where a host has no Paint tab). */
+export const armPaintFromShortcut = () => {
+  useEditor.getState().armMaterialPaint()
+  openSidebarPanel(['paint', 'build'])
+}
+
+/** Whether an armed tool owns the rotation keys (`R` / `T`) instead of the selection. */
+export const isToolOwnedRotation = () => {
   const editor = useEditor.getState()
   const moving = getMovingNode()
   if (
@@ -212,10 +254,7 @@ export const isToolOwnedRotation = (key: 'r' | 't' = 'r') => {
       // exist. Without this check, selecting an existing item in the 2D plan
       // while the item tool is armed silently drops the global rotate key.
       (editor.tool === 'item' && editor.selectedItem !== null) ||
-      editor.tool === 'lean-to-extension' ||
-      // R toggles the wall tool between line and rectangle drawing; T stays
-      // the selection's.
-      (editor.tool === 'wall' && key === 'r'))
+      editor.tool === 'lean-to-extension')
   )
 }
 
@@ -238,6 +277,16 @@ export function blocksSnappingShortcut(
   return target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.isContentEditable
 }
 
+/** E on one selected node: the kind's own E action, else its mechanism. False when neither applies. */
+export function runNodeInteraction(node: AnyNode): boolean {
+  const action = nodeRegistry.get(node.type)?.keyboardActions?.e
+  if (action?.appliesTo(node)) {
+    action.run(node)
+    return true
+  }
+  return toggleNodeMechanism(node)
+}
+
 export const useKeyboard = ({
   isVersionPreviewMode = false,
   disabled = false,
@@ -309,7 +358,12 @@ export const useKeyboard = ({
         return
       }
 
-      if (e.key === 'Shift' && !e.repeat && useEditor.getState().mode === 'material-paint') {
+      if (
+        e.key === 'Shift' &&
+        !e.repeat &&
+        useEditor.getState().mode === 'material-paint' &&
+        !paintRegionModeActive('material-paint')
+      ) {
         // In paint mode Shift cycles the application scope (this surface →
         // whole item / all matching / room) — the paint-mode analogue of the
         // snapping-mode cycle below. The scope chip mirrors this key.
@@ -361,7 +415,10 @@ export const useKeyboard = ({
           const current = useEditor.getState().getContinuation('fence')
           useEditor
             .getState()
-            .setContinuation('fence', current === 'curved' ? 'continuous' : 'curved')
+            .setContinuation(
+              'fence',
+              current === 'curved' ? 'freehand' : current === 'freehand' ? 'continuous' : 'curved',
+            )
           sfxEmitter.emit('sfx:grid-snap')
           return
         }
@@ -375,12 +432,13 @@ export const useKeyboard = ({
         !e.shiftKey &&
         !e.altKey
       ) {
-        const context = getActiveContinuationContext()
+        // The wall's drawing mode is picked in the Build panel, not cycled here.
+        const context = keyCyclableContinuationContext(getActiveContinuationContext())
         if (context) {
           e.preventDefault()
           if (context === 'fence') {
             const current = useEditor.getState().getContinuation('fence')
-            if (current !== 'curved') {
+            if (current !== 'curved' && current !== 'freehand') {
               useEditor
                 .getState()
                 .setContinuation('fence', current === 'single' ? 'continuous' : 'single')
@@ -407,37 +465,21 @@ export const useKeyboard = ({
         // Only switch to select mode if no tool had an active mid-action to cancel.
         // (e.g. mid-wall draw or mid-slab polygon should only cancel the action, not exit the tool)
         cancelActiveTool()
-      } else if (e.key === '1' && !e.metaKey && !e.ctrlKey) {
-        e.preventDefault()
-        useEditor.getState().setPhase('site')
-        useEditor.getState().armToolMode({ mode: 'select' })
-      } else if (e.key === '2' && !e.metaKey && !e.ctrlKey) {
+      } else if (!e.metaKey && !e.ctrlKey && switchPhaseFromShortcut(e.key)) {
         e.preventDefault()
-        useEditor.getState().setPhase('structure')
-        useEditor.getState().armToolMode({ mode: 'select' })
-      } else if (e.key === '3' && !e.metaKey && !e.ctrlKey) {
-        e.preventDefault()
-        useEditor.getState().setPhase('furnish')
-        useEditor.getState().armToolMode({ mode: 'select' })
       } else if (e.key === 'f' && !e.metaKey && !e.ctrlKey) {
         if (isVersionPreviewMode) return
         if (isToolOwnedCanopyForm()) return
         e.preventDefault()
-        useEditor.getState().setPhase('furnish')
-        useEditor.getState().armToolMode({ mode: 'build', tool: 'item' })
-        useEditor.getState().setActiveSidebarPanel('items')
+        openItemCatalogFromShortcut()
       } else if (e.key === 'z' && !e.metaKey && !e.ctrlKey) {
         if (isVersionPreviewMode) return
         e.preventDefault()
-        useEditor.getState().setPhase('structure')
-        useEditor.getState().setStructureLayer('zones')
         useEditor.getState().armToolMode({ mode: 'build', tool: 'zone' })
       } else if (e.key === 'm' && !e.metaKey && !e.ctrlKey) {
         if (isVersionPreviewMode) return
         e.preventDefault()
         const editor = useEditor.getState()
-        editor.setPhase('structure')
-        editor.setStructureLayer('elements')
         editor.setToolDefaults('measurement', { kind: editor.lastMeasurementKind })
         editor.armToolMode({ mode: 'build', tool: 'measurement' })
       }
@@ -448,9 +490,7 @@ export const useKeyboard = ({
       } else if (e.key === 'b' && !e.metaKey && !e.ctrlKey) {
         if (isVersionPreviewMode) return
         e.preventDefault()
-        useEditor.getState().setPhase('structure')
-        useEditor.getState().setStructureLayer('elements')
-        useEditor.getState().armToolMode({ mode: 'build', tool: 'wall' })
+        armWallToolFromShortcut()
       } else if (e.key === 'x' && !e.metaKey && !e.ctrlKey) {
         if (isVersionPreviewMode) return
         e.preventDefault()
@@ -458,9 +498,7 @@ export const useKeyboard = ({
       } else if (e.key === 'p' && !e.metaKey && !e.ctrlKey) {
         if (isVersionPreviewMode) return
         e.preventDefault()
-        useEditor.getState().setPhase('structure')
-        useEditor.getState().setStructureLayer('elements')
-        useEditor.getState().armMaterialPaint()
+        armPaintFromShortcut()
       } else if (e.key === 'g' && !e.metaKey && !e.ctrlKey) {
         if (isVersionPreviewMode) return
         e.preventDefault()
@@ -632,7 +670,7 @@ export const useKeyboard = ({
       } else if (
         (e.key === 't' || e.key === 'T') &&
         !isVersionPreviewMode &&
-        !isToolOwnedRotation('t') &&
+        !isToolOwnedRotation() &&
         canRunGlobalRotationShortcut()
       ) {
         // Rotate selected node counter-clockwise
@@ -692,34 +730,14 @@ export const useKeyboard = ({
           }
         }
       } else if ((e.key === 'e' || e.key === 'E') && !isVersionPreviewMode) {
-        // Toggle door / operable-window open/closed state. Moved off R,
-        // which now flips the opening (side + π rotation).
+        // E runs the kind's interaction or mechanism (doors and windows open and
+        // close). Moved off R, which now flips the opening (side + π rotation).
         const selectedNodeIds = useViewer.getState().selection.selectedIds as AnyNodeId[]
         if (selectedNodeIds.length === 1) {
           const node = useScene.getState().nodes[selectedNodeIds[0]!]
-          const registryE = node && nodeRegistry.get(node.type)?.keyboardActions?.e
-          if (node && registryE?.appliesTo(node)) {
+          if (node && runNodeInteraction(node)) {
             // Registry-driven E interaction. Same shape as the R/T arms.
             e.preventDefault()
-            registryE.run(node)
-            sfxEmitter.emit('sfx:item-rotate')
-          } else if (node?.type === 'door' && node.openingKind !== 'opening') {
-            e.preventDefault()
-            toggleDoorOpenState(node.id)
-            sfxEmitter.emit('sfx:item-rotate')
-          } else if (
-            node?.type === 'window' &&
-            node.openingKind !== 'opening' &&
-            (node.windowType === 'sliding' ||
-              node.windowType === 'casement' ||
-              node.windowType === 'awning' ||
-              node.windowType === 'hopper' ||
-              node.windowType === 'single-hung' ||
-              node.windowType === 'double-hung' ||
-              node.windowType === 'louvered')
-          ) {
-            e.preventDefault()
-            toggleWindowOpenState(node.id)
             sfxEmitter.emit('sfx:item-rotate')
           }
         }

package/src/hooks/use-open-wall-ends.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, test } from 'bun:test'
+import { type AnyNode, DoorNode, type OpenWallEnd, WallNode } from '@pascal-app/core'
+import { analyseOpenWallEnds } from './use-open-wall-ends'
+
+const wall = (id: string, start: [number, number], end: [number, number]) =>
+  ({
+    id,
+    type: 'wall',
+    object: 'node',
+    parentId: 'level_a',
+    visible: true,
+    children: [],
+    metadata: {},
+    start,
+    end,
+    thickness: 0.1,
+  }) as unknown as WallNode
+
+// A 4 x 4 room whose last corner is left 4 cm open (bodies are 0.1 thick).
+const walls = () => [
+  wall('wall_1', [0, 0], [4, 0]),
+  wall('wall_2', [4, 0], [4, 4]),
+  wall('wall_3', [4, 4], [0, 4]),
+  wall('wall_4', [0, 4], [0, 0.09]),
+]
+
+describe('open wall end analysis shared by the floor plan and 3D view', () => {
+  test('finds the open corner', () => {
+    const ends = analyseOpenWallEnds('level_a', walls())
+    expect(ends.some((end) => end.wallId === 'wall_4' && end.end === 'end')).toBe(true)
+  })
+
+  test('two views reading the same walls get one result', () => {
+    const shared = walls()
+    const first = analyseOpenWallEnds('level_a', [...shared])
+    expect(analyseOpenWallEnds('level_a', [...shared])).toBe(first)
+  })
+
+  test('a changed wall is analysed again', () => {
+    const shared = walls()
+    const first = analyseOpenWallEnds('level_a', shared)
+    const closed = [...shared.slice(0, 3), wall('wall_4', [0, 4], [0, 0])]
+    const next = analyseOpenWallEnds('level_a', closed)
+    expect(next).not.toBe(first)
+    expect(next.some((end) => end.wallId === 'wall_4')).toBe(false)
+  })
+})
+
+describe('the open-end preview reads what the walls host', () => {
+  // An 88° near-miss T: the source wall stops 9 cm short of the long target wall.
+  const level = 'level_t'
+  const tWall = (id: string, start: [number, number], end: [number, number], thickness = 0.1) =>
+    WallNode.parse({ id, parentId: level, start, end, thickness })
+  const scene = () => {
+    const tip: [number, number] = [2 + (3 - 0.09) / Math.tan((88 * Math.PI) / 180), 0.09]
+    const source = tWall('wall_source', [2, 3], tip, 0.01)
+    return {
+      source,
+      walls: [
+        source,
+        tWall('wall_target', [-20, 0], [30, 0], 0.01),
+        tWall('wall_anchor', [2, 3], [-20, 3]),
+        tWall('wall_left', [-20, 3], [-20, 0]),
+      ],
+    }
+  }
+  const sourceEnd = (ends: OpenWallEnd[]) =>
+    ends.find((end) => end.wallId === 'wall_source' && end.end === 'end')
+
+  test('without an opening the preview squares the corner', () => {
+    const point = sourceEnd(analyseOpenWallEnds(level, scene().walls))?.candidate?.point
+    expect(point?.[0]).toBeCloseTo(2, 6)
+    expect(point?.[1]).toBeCloseTo(0, 6)
+  })
+
+  test('a door flush with the anchored end keeps the join straight, and only the door changing re-runs it', () => {
+    const { source, walls } = scene()
+    const door = DoorNode.parse({
+      id: 'door_source',
+      parentId: source.id,
+      wallId: source.id,
+      position: [0.4, 1.05, 0],
+      width: 0.8,
+    })
+    const hosted: AnyNode[] = [
+      { ...source, children: [door.id] } as AnyNode,
+      ...walls.slice(1),
+      door as AnyNode,
+    ]
+    const first = analyseOpenWallEnds(level, hosted)
+    const point = sourceEnd(first)?.candidate?.point
+    expect(point?.[0]).toBeCloseTo(2 + 3 / Math.tan((88 * Math.PI) / 180), 6)
+    expect(point?.[1]).toBeCloseTo(0, 6)
+
+    const narrower = { ...door, width: 0.6 } as AnyNode
+    const next = analyseOpenWallEnds(level, [...hosted.slice(0, -1), narrower])
+    expect(next).not.toBe(first)
+  })
+})

package/src/hooks/use-open-wall-ends.ts

@@ -0,0 +1,238 @@
+'use client'
+
+import { type AnyNode, findOpenWallEnds, type OpenWallEnd, useScene } from '@pascal-app/core'
+import { useViewer } from '@pascal-app/viewer'
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { useShallow } from 'zustand/react/shallow'
+import {
+  collapseMutualOpenWallEnds,
+  joinOpenWallEnd,
+  openWallEndKey,
+  visibleOpenWallEnds,
+} from '../lib/floorplan/open-wall-ends'
+import { sfxEmitter } from '../lib/sfx-bus'
+import useEditor from '../store/use-editor'
+import { useFloorplanDraftPreview } from '../store/use-floorplan-draft-preview'
+import useInteractionScope from '../store/use-interaction-scope'
+
+type Boundary = Extract<AnyNode, { type: 'wall' | 'separator' }>
+
+const NO_ENDS: OpenWallEnd[] = []
+
+const isBoundary = (node: AnyNode): node is Boundary =>
+  node.type === 'wall' || node.type === 'separator'
+
+let lastAnalysis: {
+  levelId: string
+  nodes: readonly AnyNode[]
+  ends: OpenWallEnd[]
+} | null = null
+
+/**
+ * The room-graph pass behind the open-end markers, shared by the floor plan
+ * and the 3D view: split view mounts both, and they must not pay for it twice.
+ * `nodes` is the level's walls and separators plus what the walls host: an
+ * opening can stop core squaring a corner, and the preview must land where
+ * Join walls will. Recomputed only when one of those nodes changes (compared
+ * by reference), never per frame or on unrelated edits.
+ */
+export function analyseOpenWallEnds(levelId: string, nodes: readonly AnyNode[]): OpenWallEnd[] {
+  const last = lastAnalysis
+  if (
+    last &&
+    last.levelId === levelId &&
+    last.nodes.length === nodes.length &&
+    last.nodes.every((node, index) => node === nodes[index])
+  ) {
+    return last.ends
+  }
+  const ends = findOpenWallEnds(Object.fromEntries(nodes.map((node) => [node.id, node])), levelId)
+  lastAnalysis = { levelId, nodes, ends }
+  return ends
+}
+
+/** Moving, placing, reshaping or dragging a handle: the markers step aside. */
+export function useOpenWallEndsSuppressed(): boolean {
+  return useInteractionScope(
+    (state) =>
+      state.scope.kind === 'moving' ||
+      state.scope.kind === 'placing' ||
+      state.scope.kind === 'reshaping' ||
+      state.scope.kind === 'handle-drag',
+  )
+}
+
+export type OpenWallEndsState = {
+  /** The wall tool (any variant) or Divide is active. */
+  drawing: boolean
+  /** A wall or divide segment is mid-draft: markers stay visible but out of the way. */
+  drafting: boolean
+  /** Ends to mark, mutual pairs collapsed to the end that slides straight. */
+  ends: OpenWallEnd[]
+  /** Walls on the active level that bound no room. */
+  roomlessWallIds: string[]
+  /** Whether the overlay is up at all (drawing, or a near miss to show). */
+  shown: boolean
+}
+
+/**
+ * Open wall ends on the active level and when to show them. On while walls or
+ * rooms are being drawn; otherwise only when a wall that bounds no room has a
+ * near miss.
+ */
+export function useOpenWallEnds(): OpenWallEndsState {
+  const levelId = useViewer((state) => state.selection.levelId)
+  const mode = useEditor((state) => state.mode)
+  const tool = useEditor((state) => state.tool)
+  const spaces = useEditor(
+    useShallow((state) => Object.values(state.spaces).filter((space) => space.levelId === levelId)),
+  )
+  const isDividing = useInteractionScope((state) => state.scope.kind === 'room-divide')
+  const dividingDraft = useInteractionScope(
+    (state) => state.scope.kind === 'room-divide' && state.scope.points.length > 0,
+  )
+  const wallDrafting = useFloorplanDraftPreview(
+    (state) =>
+      state.wallDraftStart !== null ||
+      state.wallRectangleDraftStart !== null ||
+      state.wallPolygonDraftPoints.length > 0,
+  )
+  // Walls and separators first, then every node a wall hosts — one flat list,
+  // so a door moving re-runs the analysis but an unrelated item edit does not.
+  const analysisNodes = useScene(
+    useShallow((state) => {
+      const level = levelId ? state.nodes[levelId as AnyNode['id']] : undefined
+      if (level?.type !== 'level') return [] as AnyNode[]
+      const boundaries = level.children
+        .map((id) => state.nodes[id])
+        .filter((node): node is Boundary => !!node && isBoundary(node))
+      const hosted = boundaries.flatMap((node) =>
+        node.type === 'wall'
+          ? node.children
+              .map((id) => state.nodes[id])
+              .filter((child): child is AnyNode => child !== undefined)
+          : [],
+      )
+      return [...boundaries, ...hosted]
+    }),
+  )
+  const boundaries = useMemo(() => analysisNodes.filter(isBoundary), [analysisNodes])
+
+  const drawing = (mode === 'build' && tool === 'wall') || isDividing
+  const roomWallIds = useMemo(() => {
+    const ids = new Set<string>()
+    for (const space of spaces) for (const wallId of space.wallIds) ids.add(wallId)
+    return ids
+  }, [spaces])
+  const roomlessWallIds = useMemo(
+    () =>
+      boundaries
+        .filter((node) => node.type === 'wall' && !roomWallIds.has(node.id))
+        .map((node) => node.id as string),
+    [boundaries, roomWallIds],
+  )
+  const hasWalls = boundaries.some((node) => node.type === 'wall')
+  const shouldAnalyse = !!levelId && hasWalls && (drawing || roomlessWallIds.length > 0)
+  const openEnds = useMemo(
+    () => (shouldAnalyse && levelId ? analyseOpenWallEnds(levelId, analysisNodes) : NO_ENDS),
+    [shouldAnalyse, levelId, analysisNodes],
+  )
+  const ends = useMemo(() => {
+    const walls = new Map(boundaries.map((node) => [node.id as string, node]))
+    return collapseMutualOpenWallEnds(
+      visibleOpenWallEnds(openEnds, roomWallIds, drawing),
+      (wallId) => {
+        const wall = walls.get(wallId)
+        return wall?.type === 'wall'
+          ? [wall.end[0] - wall.start[0], wall.end[1] - wall.start[1]]
+          : null
+      },
+    )
+  }, [openEnds, roomWallIds, drawing, boundaries])
+
+  return {
+    drawing,
+    drafting: wallDrafting || dividingDraft,
+    ends,
+    roomlessWallIds,
+    shown: drawing || ends.length > 0,
+  }
+}
+
+const HOVER_RELEASE_MS = 250
+
+function clearReleaseTimer(timer: { current: ReturnType<typeof setTimeout> | null }) {
+  if (timer.current) clearTimeout(timer.current)
+  timer.current = null
+}
+
+/**
+ * Hover / pin / join for one view's markers — the floor plan and the 3D view
+ * each keep their own, so hovering a dot in one does not pop a pill in the
+ * other. A pinned pill closes on Escape or a press outside any
+ * `[data-open-wall-end]` element.
+ */
+export function useOpenWallEndFocus(ends: readonly OpenWallEnd[], drafting: boolean) {
+  const [hoveredKey, setHoveredKey] = useState<string | null>(null)
+  const [pinnedKey, setPinnedKey] = useState<string | null>(null)
+  const [refusal, setRefusal] = useState<{ key: string; message: string } | null>(null)
+  const releaseTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  const clearTimer = () => clearReleaseTimer(releaseTimer)
+  useEffect(() => () => clearReleaseTimer(releaseTimer), [])
+
+  const activeKey = pinnedKey ?? hoveredKey
+  const activeEnd = drafting
+    ? null
+    : (ends.find((end) => end.candidate && openWallEndKey(end) === activeKey) ?? null)
+
+  useEffect(() => {
+    if (!pinnedKey) return
+    const onPointerDown = (event: PointerEvent) => {
+      const target = event.target instanceof Element ? event.target : null
+      if (target?.closest('[data-open-wall-end]')) return
+      setPinnedKey(null)
+    }
+    window.addEventListener('pointerdown', onPointerDown, true)
+    return () => window.removeEventListener('pointerdown', onPointerDown, true)
+  }, [pinnedKey])
+
+  useEffect(() => {
+    if (!activeEnd) return
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape') return
+      event.stopPropagation()
+      clearReleaseTimer(releaseTimer)
+      setPinnedKey(null)
+      setHoveredKey(null)
+      setRefusal(null)
+    }
+    window.addEventListener('keydown', onKeyDown, true)
+    return () => window.removeEventListener('keydown', onKeyDown, true)
+  }, [activeEnd])
+
+  return {
+    activeKey,
+    activeEnd,
+    refusal: activeEnd && refusal?.key === openWallEndKey(activeEnd) ? refusal.message : null,
+    keepHover: (key: string) => {
+      clearTimer()
+      setHoveredKey(key)
+    },
+    releaseHover: () => {
+      clearTimer()
+      releaseTimer.current = setTimeout(() => setHoveredKey(null), HOVER_RELEASE_MS)
+    },
+    togglePin: (key: string) => setPinnedKey((current) => (current === key ? null : key)),
+    pin: (key: string) => setPinnedKey(key),
+    join: (end: OpenWallEnd) => {
+      const key = openWallEndKey(end)
+      const message = joinOpenWallEnd(end)
+      setRefusal(message ? { key, message } : null)
+      if (message) return
+      sfxEmitter.emit('sfx:structure-build')
+      setPinnedKey(null)
+      setHoveredKey(null)
+    },
+  }
+}

package/src/hooks/use-placement-notice.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from 'bun:test'
+import { type AnyNode, registerNode } from '@pascal-app/core'
+import { placementNoticeOf, transientDraftId } from './use-placement-notice'
+
+// The editor asks a node's definition for its placement notice; it names no kind.
+function registerKind(placementNotice?: unknown): string {
+  const kind = `test:notice-${crypto.randomUUID()}`
+  registerNode({
+    kind,
+    schemaVersion: 1,
+    category: 'furnish',
+    defaults: () => ({}),
+    capabilities: {},
+    ...(placementNotice ? { placementNotice } : {}),
+  } as never)
+  return kind
+}
+
+const nodeOf = (id: string, type: string, metadata?: Record<string, unknown>) =>
+  ({ id, type, parentId: 'level_a', metadata: metadata ?? {} }) as unknown as AnyNode
+
+describe('the placement notice of the node in hand', () => {
+  test("comes from the node's definition, at its live pose", () => {
+    const kind = registerKind((node: AnyNode, ctx: { live?: { position: number[] } }) => ({
+      line: `${node.id} at ${ctx.live?.position.join(',') ?? 'rest'}`,
+    }))
+    const nodes = { a: nodeOf('a', kind) }
+    expect(placementNoticeOf(nodes, 'a')).toEqual({ line: 'a at rest' })
+    expect(placementNoticeOf(nodes, 'a', { position: [1, 0, 2], rotation: 0 })).toEqual({
+      line: 'a at 1,0,2',
+    })
+  })
+
+  test('is null for a kind that declares none, and for a node not in the scene', () => {
+    const nodes = { b: nodeOf('b', registerKind()) }
+    expect(placementNoticeOf(nodes, 'b')).toBeNull()
+    expect(placementNoticeOf(nodes, 'missing')).toBeNull()
+  })
+
+  test("a tool's transient draft is found whatever its kind", () => {
+    const nodes = {
+      kept: nodeOf('kept', registerKind()),
+      draft: nodeOf('draft', registerKind(), { isTransient: true }),
+    }
+    expect(transientDraftId(nodes) as string | null).toBe('draft')
+    expect(transientDraftId({ kept: nodes.kept })).toBeNull()
+  })
+})