@pascal-app/editor 1.0.1 → 1.0.4

package/src/components/ui/helpers/helper-manager.tsx

@@ -3,6 +3,7 @@
 import {
   type AnyNode,
   type AnyNodeId,
+  floorPlacedCollides,
   nodeRegistry,
   type TerrainVerb,
   useScene,
@@ -20,18 +21,60 @@ import {
   resolveSelectModeHelpHints,
 } from '../../../lib/contextual-help'
 import { getContextualHelpNodeExtension } from '../../../lib/contextual-help-extension'
-import { continuationContextOf } from '../../../lib/continuation'
+import { continuationContextOf, keyCyclableContinuationContext } from '../../../lib/continuation'
 import { canDirectMoveNode, canDirectRotateNode } from '../../../lib/direct-manipulation'
+import {
+  DIVIDE_ROOM_HUD_TITLE,
+  MEZZANINE_HUD_TITLE,
+  OPENING_HUD_TITLE,
+  TERRACE_HUD_TITLE,
+  MOVE_ROOM_HUD_TITLE,
+  MOVE_SELECTION_HUD_TITLE,
+  nodeKindHudTitle,
+  ERASE_HUD_TITLE,
+  PAINT_HUD_TITLE,
+  PICK_MATERIAL_HUD_TITLE,
+  paintRegionHudTitle,
+  RESIZE_HUD_TITLE,
+  ROTATE_HUD_TITLE,
+  SELECT_HUD_TITLE,
+  SMART_MEASURE_HUD_TITLE,
+  terrainHudTitle,
+  toolHudTitle,
+} from '../../../lib/hud-title'
 import type { ReshapeKind } from '../../../lib/interaction/scope'
+import {
+  type MezzanineShape,
+  useMezzanineDraft,
+} from '../../../lib/mezzanine-draft'
+import {
+  TERRACE_SHAPE_HINT,
+  type TerraceShape,
+  useTerraceDraft,
+} from '../../../lib/terrace-draft'
+import {
+  type OpeningShape,
+  useOpeningDraft,
+} from '../../../lib/floor-opening-draft'
 import { isFreshPlacementMetadata } from '../../../lib/placement-metadata'
+import { MEZZANINE_EDGE_DRAG_LABEL, ROOM_ELEVATION_DRAG_LABEL } from '../../../lib/room-handle-drag'
+import { ROOM_MOVE_DRAG_LABEL } from '../../../lib/room-transform-session'
+import { usePaintRegionHovering } from '../../../lib/paint-region-hover'
+import {
+  type PaintMode,
+  paintRegionHoverHint,
+  usePaintRegionMode,
+} from '../../../lib/paint-region-mode'
 import { snapContextOf } from '../../../lib/snapping-mode'
 import useEditor, { getActiveContinuationContext } from '../../../store/use-editor'
 import useInteractionScope, {
   useActiveHandleDrag,
   useMovingNode,
+  useReshapingNode,
 } from '../../../store/use-interaction-scope'
 import { BuildingHelper } from './building-helper'
 import { ContextualHelperPanel } from './contextual-helper-panel'
+import { transientDraftId, usePlacementNotice } from '../../../hooks/use-placement-notice'
 import { ItemHelper } from './item-helper'
 import { RegisteredToolHelper } from './registered-tool-helper'
 
@@ -84,15 +127,100 @@ function terrainSculptHints(verb: TerrainVerb, sampling: boolean): ContextualSho
 }
 
 type ActiveModifierKeys = {
+  alt: boolean
   command: boolean
   shift: boolean
 }
 
 const EMPTY_CONTEXTUAL_HINTS: ContextualShortcutHint[] = []
+
+// The paint tool's region sub-modes: what one gesture draws, then Esc. A
+// refused gesture (the per-face cap) shows as the first row.
+/** What a click does in each whole-surface sub-mode; only painting teaches the held eyedropper. */
+export function paintHints(mode: PaintMode): ContextualShortcutHint[] {
+  if (mode === 'pick')
+    return [
+      { keys: ['Left click'], label: 'Paint with this material' },
+      { keys: ['Esc'], label: 'Cancel' },
+    ]
+  if (mode === 'erase')
+    return [{ keys: ['Left click'], label: 'Remove a painted part, or reset a surface' }]
+  if (mode === 'surface') return [{ keys: [['Alt', 'Option']], label: 'Hold to pick a material' }]
+  return []
+}
+
+export function paintRegionHints(
+  mode: 'rectangle' | 'polygon',
+  notice: string | null,
+  hovering = true,
+): ContextualShortcutHint[] {
+  const gesture: Record<typeof mode, ContextualShortcutHint> = {
+    rectangle: { keys: ['Drag'], label: 'Press anywhere, drag to the opposite corner' },
+    polygon: { keys: ['Left click'], label: 'Add point · click the first to close' },
+  }
+  // Off anything the sub-mode draws on, the HUD says where to go instead.
+  if (!hovering)
+    return [
+      ...(notice ? [{ keys: ['!'], label: notice, active: true }] : []),
+      { keys: ['Hover'], label: paintRegionHoverHint(mode), active: true },
+      { keys: ['Esc'], label: 'Cancel' },
+    ]
+  return [
+    ...(notice ? [{ keys: ['!'], label: notice, active: true }] : []),
+    gesture[mode],
+    ...(mode === 'polygon' ? [{ keys: ['Backspace'], label: 'Remove last point' }] : []),
+    { keys: ['Esc'], label: 'Cancel' },
+  ]
+}
+// "Add mezzanine": the outline gesture for the shape picked in the room panel,
+// then Esc; the snapping chip sits below.
+export function mezzanineHints(shape: MezzanineShape): ContextualShortcutHint[] {
+  return shape === 'rectangle'
+    ? [
+        { keys: ['Left click'], label: 'Set one corner, then the opposite' },
+        { keys: ['Drag'], label: 'Draw the mezzanine' },
+        { keys: ['Esc'], label: 'Cancel' },
+      ]
+    : [
+        { keys: ['Left click'], label: 'Add point · click the first to close' },
+        { keys: ['Backspace'], label: 'Remove last point' },
+        { keys: ['Enter'], label: 'Finish' },
+        { keys: ['Esc'], label: 'Cancel' },
+      ]
+}
+/** "Cut opening": the outline gesture for the chosen shape, then Esc. */
+export function openingHints(shape: OpeningShape): ContextualShortcutHint[] {
+  return mezzanineHints(shape).map((hint) =>
+    hint.label === 'Draw the mezzanine' ? { ...hint, label: 'Draw the opening' } : hint,
+  )
+}
+const TERRACE_CHIP_HINTS = [TERRACE_SHAPE_HINT]
+// The terrace tool: the outline gesture for the chosen shape, then Esc.
+export function terraceHints(shape: TerraceShape): ContextualShortcutHint[] {
+  return shape === 'rectangle'
+    ? [
+        { keys: ['Left click'], label: 'Set one corner, then the opposite' },
+        { keys: ['Drag'], label: 'Draw the terrace' },
+        { keys: ['Esc'], label: 'Done' },
+      ]
+    : [
+        { keys: ['Left click'], label: 'Add point · click the first to close' },
+        { keys: ['Backspace'], label: 'Remove last point' },
+        { keys: ['Enter'], label: 'Finish' },
+        { keys: ['Esc'], label: 'Done' },
+      ]
+}
+export const ROOM_DIVIDE_HINTS: ContextualShortcutHint[] = [
+  { keys: ['Left click'], label: 'Add point' },
+  { keys: ['Backspace'], label: 'Remove last point' },
+  { keys: ['Enter'], label: 'Finish at the edge' },
+  { keys: ['Esc'], label: 'Cancel' },
+]
 const NO_CONTEXTUAL_HELP_SUBSCRIPTION = () => () => {}
 
 function useActiveModifierKeys(): ActiveModifierKeys {
   const [modifiers, setModifiers] = useState<ActiveModifierKeys>({
+    alt: false,
     command: false,
     shift: false,
   })
@@ -101,6 +229,7 @@ function useActiveModifierKeys(): ActiveModifierKeys {
     const updateModifiers = (event: KeyboardEvent) => {
       const isKeyDown = event.type === 'keydown'
       setModifiers({
+        alt: event.altKey || (isKeyDown && event.key === 'Alt'),
         command:
           event.metaKey ||
           event.ctrlKey ||
@@ -109,7 +238,7 @@ function useActiveModifierKeys(): ActiveModifierKeys {
       })
     }
     const clearModifiers = () => {
-      setModifiers({ command: false, shift: false })
+      setModifiers({ alt: false, command: false, shift: false })
     }
 
     window.addEventListener('keydown', updateModifiers)
@@ -125,6 +254,43 @@ function useActiveModifierKeys(): ActiveModifierKeys {
   return modifiers
 }
 
+export type MezzanineGesture = 'raise' | 'resize' | 'move'
+
+/**
+ * A handle drag on a mezzanine — its floor handle, an edge arrow, or its pick-up
+ * (Move / Duplicate) — or null. Its HUD names the mezzanine, not "Resize" or
+ * "Move room".
+ */
+export function mezzanineGesture(
+  drag: { nodeId: string; label: string } | null,
+  nodes: Readonly<Record<string, AnyNode>>,
+): MezzanineGesture | null {
+  if (!drag) return null
+  const zone = nodes[drag.nodeId]
+  if (zone?.type !== 'zone' || zone.floor?.support !== 'open') return null
+  if (drag.label === ROOM_ELEVATION_DRAG_LABEL) return 'raise'
+  if (drag.label === MEZZANINE_EDGE_DRAG_LABEL) return 'resize'
+  if (drag.label === ROOM_MOVE_DRAG_LABEL) return 'move'
+  return null
+}
+
+export const MEZZANINE_GESTURE_HINTS: Record<MezzanineGesture, ContextualShortcutHint[]> = {
+  raise: [
+    { keys: ['Drag'], label: 'Raise or lower' },
+    { keys: ['Esc'], label: 'Cancel' },
+  ],
+  resize: [
+    { keys: ['Drag'], label: 'Resize' },
+    { keys: ['Esc'], label: 'Cancel' },
+  ],
+  move: [
+    { keys: ['Left click'], label: 'Place inside the room' },
+    { keys: [['R', 'T']], label: 'Rotate ±45°' },
+    { keys: ['Alt'], label: 'Free move' },
+    { keys: ['Esc'], label: 'Cancel' },
+  ],
+}
+
 export function HelperManager() {
   const mode = useEditor((s) => s.mode)
   const tool = useEditor((s) => s.tool)
@@ -132,10 +298,24 @@ export function HelperManager() {
   const terrainSampling = useEditor((s) => s.terrainSampling)
   const isFirstPersonMode = useEditor((s) => s.isFirstPersonMode)
   const measurementToolKind = useEditor((s) => s.toolDefaults.measurement?.kind)
+  const wallMode = useEditor((s) => s.continuationByContext.wall)
   const workspaceMode = useEditor((s) => s.workspaceMode)
   const scope = useInteractionScope((s) => s.scope)
+  const paintRegionMode = usePaintRegionMode((s) => s.mode)
+  const paintRegionDrawing = paintRegionMode === 'rectangle' || paintRegionMode === 'polygon'
+  const paintRegionNotice = usePaintRegionMode((s) => s.notice)
+  const paintRegionHovering = usePaintRegionHovering()
+  const mezzanineShape = useMezzanineDraft((s) => (s.host ? s.shape : null))
+  const openingShape = useOpeningDraft((s) => (s.host ? s.shape : null))
+  const terraceShape = useTerraceDraft((s) => (s.host ? s.shape : null))
   const movingNode = useMovingNode()
+  // A tool whose kind gives placement notices: its transient draft is the node in hand.
+  const toolNotices = !!(tool && nodeRegistry.get(tool)?.placementNotice)
+  const toolDraftId = useScene((s) => (toolNotices ? transientDraftId(s.nodes) : null))
+  const placementNotice = usePlacementNotice(movingNode?.id ?? toolDraftId)
+  const reshapingNode = useReshapingNode()
   const activeHandleDrag = useActiveHandleDrag()
+  const mezzanineHandle = useScene((s) => mezzanineGesture(activeHandleDrag, s.nodes))
   const selectedIds = useViewer((s) => s.selection.selectedIds)
   const isMobile = useIsMobile()
   const modifiers = useActiveModifierKeys()
@@ -175,11 +355,14 @@ export function HelperManager() {
           return node ? nodeRegistry.get(node.type)?.snapProfile : undefined
         },
         draftDirectionalOf: (typeOrTool) => nodeRegistry.get(typeOrTool)?.snapDraftDirectional ?? true,
+        paintRegion: mode === 'material-paint' && paintRegionDrawing,
       }),
-    [scope, mode, tool],
+    [scope, mode, tool, paintRegionDrawing],
   )
+  // Contexts whose mode is picked in the Build panel (the wall's Rooms variant)
+  // get no HUD chip: the header names the variant instead.
   const continuationContext = useMemo(
-    () => getActiveContinuationContext(),
+    () => keyCyclableContinuationContext(getActiveContinuationContext()),
     [scope, mode, tool],
   )
   const selectModeHints = useMemo(() => {
@@ -190,10 +373,12 @@ export function HelperManager() {
         : single?.type === 'duct-fitting' || single?.type === 'pipe-fitting'
           ? 'fitting'
           : null
+    const hasOpeningRadiusSelection = single?.type === 'door' || single?.type === 'window'
     return resolveSelectModeHelpHints({
       selectedCount: selectedNodes.length,
       hasMovableSelection: selectedNodes.some((node) => canDirectMoveNode(node)),
       hasRotatableSelection: selectedNodes.some((node) => canDirectRotateNode(node)),
+      hasOpeningRadiusSelection,
       commandPressed: modifiers.command,
       shiftPressed: modifiers.shift,
       mepSelection,
@@ -211,15 +396,17 @@ export function HelperManager() {
   // tools — editor shortcut hints would only mislead there.
   if (workspaceMode === 'studio') return null
 
-  // Rotating a node (or a multi-selection group) via its in-world gizmo:
-  // advertise Shift = free rotation, the same angle-step bypass wall drafting
-  // exposes. Takes priority over the idle select-mode hints since a handle
-  // drag is the active interaction.
   if (
     activeHandleDrag?.label === ROTATE_HANDLE_DRAG_LABEL ||
     activeHandleDrag?.label === GROUP_ROTATE_DRAG_LABEL
   ) {
-    return <ContextualHelperPanel hints={resolveRotateHandleHelpHints(modifiers.shift)} />
+    return (
+      <ContextualHelperPanel
+        hints={resolveRotateHandleHelpHints(modifiers.alt)}
+        snapContext={snapContext}
+        title={ROTATE_HUD_TITLE}
+      />
+    )
   }
 
   // Group-move drag / pick-up: the drag resolves to the 'item' snap context
@@ -230,6 +417,79 @@ export function HelperManager() {
       <ContextualHelperPanel
         hints={[{ keys: ['R / T'], label: 'Rotate the selection ±45°' }]}
         snapContext={snapContext}
+        title={MOVE_SELECTION_HUD_TITLE}
+      />
+    )
+  }
+
+  if (mezzanineHandle) {
+    return (
+      <ContextualHelperPanel
+        hints={MEZZANINE_GESTURE_HINTS[mezzanineHandle]}
+        snapContext={snapContext}
+        title={MEZZANINE_HUD_TITLE}
+      />
+    )
+  }
+
+  // A picked-up room (Move / Duplicate / Rotate from its pill): the same keys
+  // as a group pick-up.
+  if (activeHandleDrag?.label === ROOM_MOVE_DRAG_LABEL) {
+    return (
+      <ContextualHelperPanel
+        hints={[
+          { keys: ['Left click'], label: 'Place' },
+          { keys: [['R', 'T']], label: 'Rotate ±45°' },
+          { keys: ['Alt'], label: 'Free move · slide doors and windows' },
+          { keys: ['Esc'], label: 'Cancel' },
+        ]}
+        snapContext={snapContext}
+        title={MOVE_ROOM_HUD_TITLE}
+      />
+    )
+  }
+  // A paint region gesture holds a handle-drag scope while it draws; its HUD
+  // stays the region one (Backspace / close hints for a polygon mid-draft).
+  if (mode === 'material-paint' && paintRegionDrawing) {
+    return (
+      <ContextualHelperPanel
+        hints={paintRegionHints(paintRegionMode, paintRegionNotice, paintRegionHovering)}
+        snapContext={snapContext}
+        title={paintRegionHudTitle(paintRegionMode)}
+      />
+    )
+  }
+
+  // The terrace tool draws like "Add mezzanine": same outline gestures and chip.
+  if (terraceShape) {
+    return (
+      <ContextualHelperPanel
+        chipHints={TERRACE_CHIP_HINTS}
+        hints={terraceHints(terraceShape)}
+        snapContext={snapContext}
+        title={TERRACE_HUD_TITLE}
+      />
+    )
+  }
+
+  if (openingShape) {
+    return (
+      <ContextualHelperPanel
+        hints={openingHints(openingShape)}
+        snapContext={snapContext}
+        title={OPENING_HUD_TITLE}
+      />
+    )
+  }
+
+  // "Add mezzanine" holds a handle-drag scope on its host room for the whole
+  // tool, so it must win over the generic resize HUD below.
+  if (mezzanineShape) {
+    return (
+      <ContextualHelperPanel
+        hints={mezzanineHints(mezzanineShape)}
+        snapContext={snapContext}
+        title={MEZZANINE_HUD_TITLE}
       />
     )
   }
@@ -246,6 +506,7 @@ export function HelperManager() {
           { keys: ['Esc'], label: 'Cancel' },
         ]}
         snapContext={snapContext}
+        title={RESIZE_HUD_TITLE}
       />
     )
   }
@@ -254,25 +515,54 @@ export function HelperManager() {
   // before the select branch so the idle "drag selected / add objects" hints
   // never leak over an in-progress reshape — and it gets its own snapping chip.
   if (scope.kind === 'reshaping') {
-    return <ContextualHelperPanel hints={reshapingHints(scope.reshape)} snapContext={snapContext} />
+    // A kind's own reshape brings its hints (`def.affordanceHints[reshape]`).
+    const hints = reshapingNode
+      ? nodeRegistry.get(reshapingNode.type)?.affordanceHints?.[scope.reshape]
+      : undefined
+    const title = reshapingNode
+      ? nodeKindHudTitle(reshapingNode.type, scope.reshape === 'split' ? 'Split' : 'Edit')
+      : null
+    if (hints) {
+      return (
+        <RegisteredToolHelper
+          hints={hints}
+          shiftPressed={modifiers.shift}
+          snapContext={snapContext}
+          title={title}
+        />
+      )
+    }
+    return (
+      <ContextualHelperPanel
+        hints={reshapingHints(scope.reshape)}
+        snapContext={snapContext}
+        title={title}
+      />
+    )
   }
 
   if (movingNode) {
-    if (movingNode.type === 'building') return <BuildingHelper showRotate />
     // A fresh placement (e.g. a positioned preset like a shelf) advertises its
     // once/repeat continuation, exactly like the GLB item tool — but an existing
     // node being *moved* is not a placement, so it gets no continuation chip.
-    const movingContinuationContext = isFreshPlacementMetadata(movingNode.metadata)
-      ? continuationContextOf(movingNode.type)
+    const isFreshPlacement = isFreshPlacementMetadata(movingNode.metadata)
+    const movingTitle = nodeKindHudTitle(movingNode.type, isFreshPlacement ? undefined : 'Move')
+    if (movingNode.type === 'building') return <BuildingHelper showRotate title={movingTitle} />
+    const movingContinuationContext = isFreshPlacement
+      ? keyCyclableContinuationContext(continuationContextOf(movingNode.type))
       : null
-    const collisionValidatesDrop =
-      nodeRegistry.get(movingNode.type)?.capabilities.floorPlaced?.collides === true
+    const collisionValidatesDrop = floorPlacedCollides(
+      nodeRegistry.get(movingNode.type)?.capabilities.floorPlaced,
+      movingNode,
+    )
     return (
       <ItemHelper
         continuationContext={movingContinuationContext}
+        notice={placementNotice?.line}
         showEsc
         showForce={collisionValidatesDrop}
         snapContext={snapContext}
+        title={movingTitle}
       />
     )
   }
@@ -281,7 +571,19 @@ export function HelperManager() {
   // only contextual control here. The chip hides itself for targets that only
   // paint one surface, so this renders nothing until a scoped target is active.
   if (mode === 'material-paint') {
-    return <ContextualHelperPanel hints={[]} showPaintScope />
+    return (
+      <ContextualHelperPanel
+        hints={paintHints(paintRegionMode)}
+        showPaintScope
+        title={
+          paintRegionMode === 'pick'
+            ? PICK_MATERIAL_HUD_TITLE
+            : paintRegionMode === 'erase'
+              ? ERASE_HUD_TITLE
+              : PAINT_HUD_TITLE
+        }
+      />
+    )
   }
 
   // Sculpt mode. The HUD is what makes a sustained brush mode legible: it names
@@ -290,17 +592,41 @@ export function HelperManager() {
   // mode-specific — bracket resize, and an Esc that abandons the stroke rather
   // than exiting the mode.
   if (mode === 'terrain-sculpt') {
-    return <ContextualHelperPanel hints={terrainSculptHints(terrainVerb, terrainSampling)} />
+    return (
+      <ContextualHelperPanel
+        hints={terrainSculptHints(terrainVerb, terrainSampling)}
+        title={terrainHudTitle(terrainVerb)}
+      />
+    )
   }
 
   if (scope.kind === 'mesh-editing') {
-    return <ContextualHelperPanel hints={contextualEditHints} snapContext={snapContext} />
+    return (
+      <ContextualHelperPanel
+        hints={contextualEditHints}
+        snapContext={snapContext}
+        title={contextualHelpNode ? nodeKindHudTitle(contextualHelpNode.type, 'Edit') : null}
+      />
+    )
+  }
+
+
+  // Divide draws a separator path across the selected room — it reads as a
+  // wall draft: the wall's snapping chips (Shift / Ctrl) plus the path keys.
+  if (scope.kind === 'room-divide') {
+    return (
+      <ContextualHelperPanel
+        hints={ROOM_DIVIDE_HINTS}
+        snapContext={snapContext}
+        title={DIVIDE_ROOM_HUD_TITLE}
+      />
+    )
   }
 
   // Idle select only — an active scope (handle-drag, box-select, …) must not show
   // the idle selection hints.
   if (mode === 'select' && scope.kind === 'idle') {
-    return <ContextualHelperPanel hints={selectModeHints} />
+    return <ContextualHelperPanel hints={selectModeHints} title={SELECT_HUD_TITLE} />
   }
 
   if (tool === 'measurement' && measurementToolKind === 'smart') {
@@ -311,6 +637,7 @@ export function HelperManager() {
           { keys: ['Click'], label: 'Pin measurement lens' },
           { keys: ['Esc'], label: 'Exit smart measure' },
         ]}
+        title={SMART_MEASURE_HUD_TITLE}
       />
     )
   }
@@ -328,8 +655,10 @@ export function HelperManager() {
         <RegisteredToolHelper
           continuationContext={continuationContext}
           hints={hints}
+          notice={placementNotice?.line ?? null}
           shiftPressed={modifiers.shift}
           snapContext={snapContext}
+          title={toolHudTitle(tool, wallMode)}
         />
       )
     }

package/src/components/ui/helpers/item-helper.tsx

@@ -1,4 +1,5 @@
 import type { ContinuationContext } from '../../../lib/continuation'
+import type { HudTitle } from '../../../lib/hud-title'
 import type { SnapContext } from '../../../lib/snapping-mode'
 import { ContextualHelperPanel } from './contextual-helper-panel'
 
@@ -11,6 +12,9 @@ interface ItemHelperProps {
   // Set for a fresh point-kind placement (e.g. a positioned preset) so the
   // once/repeat continuation chip shows; null for an existing-node move.
   continuationContext?: ContinuationContext | null
+  title?: HudTitle | null
+  // Why the item would not fit where it is (a door's way, a room too small): a warning, not a block.
+  notice?: string | null
 }
 
 // Snapping mode is the chip on the right (Shift cycles it), so it's not repeated
@@ -20,10 +24,13 @@ export function ItemHelper({
   snapContext,
   showForce,
   continuationContext = null,
+  title = null,
+  notice = null,
 }: ItemHelperProps) {
   return (
     <ContextualHelperPanel
       continuationContext={continuationContext}
+      notice={notice}
       hints={[
         { keys: ['Left click'], label: 'Place' },
         { keys: ['R', 'T'], label: 'Rotate' },
@@ -31,6 +38,7 @@ export function ItemHelper({
         { keys: [showEsc ? 'Esc' : 'Right click'], label: 'Cancel' },
       ]}
       snapContext={snapContext}
+      title={title}
     />
   )
 }

package/src/components/ui/helpers/registered-tool-helper.tsx

@@ -1,8 +1,8 @@
 import type { ToolHint } from '@pascal-app/core'
-import { useMemo, useSyncExternalStore } from 'react'
 import type { ContinuationContext } from '../../../lib/continuation'
+import type { HudTitle } from '../../../lib/hud-title'
 import type { SnapContext } from '../../../lib/snapping-mode'
-import useEditor from '../../../store/use-editor'
+import { useVisibleToolHints } from '../../../lib/panel-tool-options'
 import { ContextualHelperPanel } from './contextual-helper-panel'
 
 /**
@@ -19,43 +19,18 @@ export function RegisteredToolHelper({
   shiftPressed = false,
   snapContext = null,
   continuationContext = null,
+  title = null,
+  notice = null,
 }: {
   hints: ToolHint[]
   shiftPressed?: boolean
   snapContext?: SnapContext | null
   continuationContext?: ContinuationContext | null
+  title?: HudTitle | null
+  notice?: string | null
 }) {
-  // Live vertex count of an in-progress polygon draft, so hints gated on a
-  // minimum (e.g. "Finish" at ≥ 3) only appear once they're actually possible.
-  const draftVertexCount = useEditor((s) => s.draftVertexCount)
-  const visibilityStore = useMemo(
-    () => ({
-      subscribe: (onChange: () => void) => {
-        const unsubscribers = hints.flatMap((hint) =>
-          hint.visible ? [hint.visible.subscribe(onChange)] : [],
-        )
-        return () => {
-          for (const unsubscribe of unsubscribers) unsubscribe()
-        }
-      },
-      getSnapshot: () => hints.map((hint) => (hint.visible?.value() === false ? '0' : '1')).join(''),
-    }),
-    [hints],
-  )
-  useSyncExternalStore(
-    visibilityStore.subscribe,
-    visibilityStore.getSnapshot,
-    visibilityStore.getSnapshot,
-  )
-  // Some hints are replaced by live contextual chips, so keep the generic
-  // registry renderer from duplicating stale/static versions.
-  const visible = hints.filter(
-    (hint) =>
-      !(hint.key === 'Shift' && hint.label === 'Cycle snapping mode') &&
-      hint.visible?.value() !== false &&
-      (hint.minDraftVertices == null || draftVertexCount >= hint.minDraftVertices),
-  )
-  if (visible.length === 0 && !snapContext && !continuationContext) return null
+  const visible = useVisibleToolHints(hints)
+  if (visible.length === 0 && !snapContext && !continuationContext && !notice) return null
   // Hints carrying a live-state `chip` render as mode chips next to the
   // snapping / continuation rows; the rest stay static key rows.
   const chipHints = visible.filter((hint) => hint.chip)
@@ -74,7 +49,9 @@ export function RegisteredToolHelper({
         }
       })}
       continuationContext={continuationContext}
+      notice={notice}
       snapContext={snapContext}
+      title={title}
     />
   )
 }