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

package/src/components/ui/controls/material-paint-panel.tsx

@@ -35,7 +35,7 @@ export type MaterialPaintPanelProps = {
 export function MaterialPaintPanel({ onCreateMaterialRequest }: MaterialPaintPanelProps) {
   const activePaintMaterial = useEditor((state) => state.activePaintMaterial)
   const activePaintTarget = useEditor((state) => state.activePaintTarget)
-  const setActivePaintMaterial = useEditor((state) => state.setActivePaintMaterial)
+  const armMaterialPaint = useEditor((state) => state.armMaterialPaint)
   const setActivePaintTarget = useEditor((state) => state.setActivePaintTarget)
   const paintEraser = useEditor((state) => state.paintEraser)
   const setPaintEraser = useEditor((state) => state.setPaintEraser)
@@ -81,7 +81,7 @@ export function MaterialPaintPanel({ onCreateMaterialRequest }: MaterialPaintPan
         },
       },
     })
-    setActivePaintMaterial({ materialPreset: toSceneMaterialRef(id), sourceTarget: activePaintTarget })
+    armMaterialPaint({ materialPreset: toSceneMaterialRef(id), sourceTarget: activePaintTarget })
     setAutoEditMaterialId(id)
   }
 
@@ -112,11 +112,13 @@ export function MaterialPaintPanel({ onCreateMaterialRequest }: MaterialPaintPan
       </div>
 
       {/* Scrolls: category tabs (fixed inside) + catalog grid (the scroll). */}
-      <div className="min-h-0 flex-1">
+      {/* A stable hook for host-app onboarding to point at. Static, and read
+          only from outside: nothing here depends on it. */}
+      <div className="min-h-0 flex-1" data-guide-target="paint-material">
         <MaterialPicker
           onCreateMaterialRequest={onCreateMaterialRequest}
           onSelectMaterialPreset={(materialPreset) => {
-            setActivePaintMaterial({ materialPreset, sourceTarget: activePaintTarget })
+            armMaterialPaint({ materialPreset, sourceTarget: activePaintTarget })
           }}
           selectedMaterialPreset={activePaintMaterial?.materialPreset}
         />

package/src/components/ui/controls/material-picker.tsx

@@ -17,7 +17,7 @@ import { Plus } from 'lucide-react'
 import { useEffect, useMemo, useState, useSyncExternalStore } from 'react'
 import { triggerSFX } from '../../../lib/sfx-bus'
 
-export type MaterialSourceFilter = 'all' | MaterialSource
+export type MaterialSourceFilter = MaterialSource
 
 export type MaterialPickerProps = {
   selectedMaterialPreset?: string
@@ -28,8 +28,9 @@ export type MaterialPickerProps = {
   onCreateMaterialRequest?: () => void
 }
 
+// No 'All': the browse surfaces (Items / Rooms / Build) dropped it and default
+// to the Pascal library — the combined list buried the curated set.
 const SOURCE_FILTERS: { id: MaterialSourceFilter; label: string }[] = [
-  { id: 'all', label: 'All' },
   { id: 'pascal', label: 'Pascal' },
   { id: 'mine', label: 'Mine' },
   { id: 'workspace', label: 'Workspace' },
@@ -41,7 +42,6 @@ function getCategoryLabel(category: (typeof MATERIAL_CATEGORIES)[number]) {
 }
 
 function filterBySource(items: MaterialCatalogItem[], filter: MaterialSourceFilter) {
-  if (filter === 'all') return items
   return items.filter((item) => (item.source ?? 'pascal') === filter)
 }
 
@@ -60,7 +60,7 @@ export function MaterialPicker({
   const [selectedCategory, setSelectedCategory] = useState<(typeof MATERIAL_CATEGORIES)[number]>(
     MATERIAL_CATEGORIES[0],
   )
-  const [sourceFilter, setSourceFilter] = useState<MaterialSourceFilter>('all')
+  const [sourceFilter, setSourceFilter] = useState<MaterialSourceFilter>('pascal')
   // Version counter so host registrations/unregistrations re-render the picker.
   const libraryVersion = useSyncExternalStore(
     subscribeLibraryMaterials,

package/src/components/ui/controls/scene-material-list.tsx

@@ -33,7 +33,7 @@ export function SceneMaterialList({ autoEditId }: { autoEditId?: SceneMaterialId
   const removeSceneMaterial = useScene((state) => state.removeSceneMaterial)
   const activePaintTarget = useEditor((state) => state.activePaintTarget)
   const activePaintRef = useEditor((state) => state.activePaintMaterial?.materialPreset)
-  const setActivePaintMaterial = useEditor((state) => state.setActivePaintMaterial)
+  const armMaterialPaint = useEditor((state) => state.armMaterialPaint)
 
   const materialEntries = useMemo(
     () => Object.entries(materials) as [SceneMaterialId, SceneMaterial][],
@@ -76,7 +76,7 @@ export function SceneMaterialList({ autoEditId }: { autoEditId?: SceneMaterialId
           key={id}
           removeSceneMaterial={removeSceneMaterial}
           sceneMaterial={sceneMaterial}
-          setActivePaintMaterial={setActivePaintMaterial}
+          armMaterialPaint={armMaterialPaint}
           updateSceneMaterial={updateSceneMaterial}
           usageCount={usageCounts.get(id) ?? 0}
         />
@@ -95,7 +95,7 @@ function SceneMaterialRow({
   addSceneMaterial,
   updateSceneMaterial,
   removeSceneMaterial,
-  setActivePaintMaterial,
+  armMaterialPaint,
 }: {
   id: SceneMaterialId
   sceneMaterial: SceneMaterial
@@ -106,7 +106,7 @@ function SceneMaterialRow({
   addSceneMaterial: ReturnType<typeof useScene.getState>['addSceneMaterial']
   updateSceneMaterial: ReturnType<typeof useScene.getState>['updateSceneMaterial']
   removeSceneMaterial: ReturnType<typeof useScene.getState>['removeSceneMaterial']
-  setActivePaintMaterial: ReturnType<typeof useEditor.getState>['setActivePaintMaterial']
+  armMaterialPaint: ReturnType<typeof useEditor.getState>['armMaterialPaint']
 }) {
   // A freshly-created material (via "+ Custom") mounts with its editor open.
   const [isEditingMaterial, setIsEditingMaterial] = useState(autoEdit)
@@ -141,6 +141,7 @@ function SceneMaterialRow({
       className={`rounded-md border border-border/60 bg-background/40 p-2 ${
         isActive ? 'ring-1 ring-primary ring-inset' : ''
       }`}
+      data-testid={`scene-material-row-${id}`}
     >
       <div className="flex items-center gap-2">
         <span
@@ -174,7 +175,7 @@ function SceneMaterialRow({
               <Button
                 aria-label="Paint with"
                 onClick={() =>
-                  setActivePaintMaterial({
+                  armMaterialPaint({
                     materialPreset: toSceneMaterialRef(id),
                     sourceTarget: activePaintTarget,
                   })

package/src/components/ui/controls/segmented-control.tsx

@@ -7,6 +7,8 @@ interface SegmentedControlProps<T extends string> {
   onChange: (value: T) => void
   options: { label: React.ReactNode; value: T }[]
   className?: string
+  disabled?: boolean
+  mixed?: boolean
 }
 
 export function SegmentedControl<T extends string>({
@@ -14,16 +16,19 @@ export function SegmentedControl<T extends string>({
   onChange,
   options,
   className,
+  disabled = false,
+  mixed = false,
 }: SegmentedControlProps<T>) {
   return (
     <div
       className={cn(
         'flex h-9 w-full items-center rounded-lg border border-border/50 bg-[#2C2C2E] p-[3px]',
+        disabled && 'opacity-60',
         className,
       )}
     >
       {options.map((option) => {
-        const isSelected = value === option.value
+        const isSelected = !mixed && value === option.value
         return (
           <button
             className={cn(
@@ -31,7 +36,9 @@ export function SegmentedControl<T extends string>({
               isSelected
                 ? 'bg-[#3e3e3e] text-foreground shadow-sm ring-1 ring-border/50'
                 : 'text-muted-foreground hover:bg-white/5 hover:text-foreground',
+              disabled && 'cursor-not-allowed hover:bg-transparent hover:text-muted-foreground',
             )}
+            disabled={disabled}
             key={option.value}
             onClick={() => onChange(option.value)}
             type="button"

package/src/components/ui/controls/slider-control.tsx

@@ -22,6 +22,7 @@ interface SliderControlProps {
   className?: string
   unit?: string
   restoreOnCommit?: boolean
+  mixed?: boolean
 }
 
 function stepPrecision(s: number): number {
@@ -64,6 +65,7 @@ export function SliderControl({
   className,
   unit = '',
   restoreOnCommit = true,
+  mixed = false,
 }: SliderControlProps) {
   // Display/storage conversion so the value honors the metric/imperial toggle.
   // `value`, `onChange`, `onCommit`, `min`/`max`/`clamp` are always in the
@@ -76,6 +78,10 @@ export function SliderControl({
   const [isDragging, setIsDragging] = useState(false)
   const [isHovered, setIsHovered] = useState(false)
   const [inputValue, setInputValue] = useState(toDisplay(value).toFixed(precision))
+  // Live readout while dragging. Multi-edit previews write live overrides
+  // instead of the scene, so `value` would otherwise stay frozen even though
+  // the meshes are moving.
+  const [dragDisplay, setDragDisplay] = useState<number | null>(null)
 
   const dragRef = useRef<{
     // Original value at drag start — preserved across modifier re-anchors so
@@ -89,8 +95,9 @@ export function SliderControl({
     stepMultiplier: number
   } | null>(null)
   const labelRef = useRef<HTMLDivElement>(null)
-  const valueRef = useRef(value)
-  valueRef.current = value
+  const shown = dragDisplay ?? value
+  const valueRef = useRef(shown)
+  valueRef.current = shown
 
   const clamp = useCallback((val: number) => Math.min(Math.max(val, min), max), [min, max])
   // Apply a signed display-unit delta to a stored value, rounding in the
@@ -185,6 +192,7 @@ export function SliderControl({
       const newValue = applyDisplayDelta(anchorValue, (dx / 4) * s, s)
       if (newValue !== valueRef.current) {
         valueRef.current = newValue
+        setDragDisplay(newValue)
         onChange(newValue)
       }
     },
@@ -209,6 +217,7 @@ export function SliderControl({
         useScene.temporal.getState().resume()
         onCommit?.(finalVal)
       }
+      setDragDisplay(null)
     },
     [onChange, onCommit, restoreOnCommit],
   )
@@ -272,7 +281,7 @@ export function SliderControl({
     [submitValue, value, precision, step, applyDisplayDelta, onChange, toDisplay],
   )
 
-  const displayValue = toDisplay(value)
+  const displayValue = toDisplay(shown)
 
   return (
     <div
@@ -340,6 +349,13 @@ export function SliderControl({
               </span>
             )}
           </>
+        ) : mixed && !isDragging ? (
+          <div
+            className="flex cursor-text items-center text-muted-foreground transition-colors hover:text-foreground"
+            onClick={handleValueClick}
+          >
+            <span className="font-mono tracking-tight">Mixed</span>
+          </div>
         ) : (
           <div
             className="flex cursor-text items-center text-foreground/60 transition-colors hover:text-foreground"

package/src/components/ui/controls/toggle-control.tsx

@@ -8,9 +8,16 @@ interface ToggleControlProps {
   checked: boolean
   onChange: (checked: boolean) => void
   className?: string
+  mixed?: boolean
 }
 
-export function ToggleControl({ label, checked, onChange, className }: ToggleControlProps) {
+export function ToggleControl({
+  label,
+  checked,
+  onChange,
+  className,
+  mixed = false,
+}: ToggleControlProps) {
   return (
     <div
       className={cn(
@@ -26,12 +33,18 @@ export function ToggleControl({ label, checked, onChange, className }: ToggleCon
       <div
         className={cn(
           'flex h-5 w-5 items-center justify-center rounded-[4px] border transition-all duration-200',
-          checked
-            ? 'border-primary bg-primary text-primary-foreground'
-            : 'border-border bg-black/20 text-transparent group-hover:border-muted-foreground',
+          mixed
+            ? 'border-muted-foreground/70 bg-black/20 text-muted-foreground'
+            : checked
+              ? 'border-primary bg-primary text-primary-foreground'
+              : 'border-border bg-black/20 text-transparent group-hover:border-muted-foreground',
         )}
       >
-        <Check className="h-3.5 w-3.5" strokeWidth={3} />
+        {mixed ? (
+          <div className="h-0.5 w-2.5 rounded-full bg-current" />
+        ) : (
+          <Check className="h-3.5 w-3.5" strokeWidth={3} />
+        )}
       </div>
     </div>
   )

package/src/components/ui/controls/tool-options-panel.tsx

@@ -0,0 +1,126 @@
+'use client'
+
+import { nodeRegistry, type ToolOption } from '@pascal-app/core'
+import Image from 'next/image'
+import { useSyncExternalStore } from 'react'
+import { cn } from '../../../lib/utils'
+import { triggerSFX } from '../../../lib/sfx-bus'
+
+const ALWAYS_VISIBLE = {
+  subscribe: () => () => {},
+  value: () => true,
+}
+
+function ToolOptionRow({
+  option,
+  onSelect,
+  getChoiceThumbnail,
+  active = true,
+}: {
+  option: ToolOption
+  onSelect?: (option: ToolOption, value: string) => void
+  getChoiceThumbnail?: (option: ToolOption, value: string) => string | undefined
+  active?: boolean
+}) {
+  const visibility = option.visible ?? ALWAYS_VISIBLE
+  const visible = useSyncExternalStore(visibility.subscribe, visibility.value, visibility.value)
+  const value = useSyncExternalStore(option.subscribe, option.value, option.value)
+  if (
+    !visible ||
+    (!active && !option.choices.some((choice) => getChoiceThumbnail?.(option, choice.value)))
+  ) return null
+
+  const activeChoice = active && option.choices.find((choice) => choice.value === value)
+  return (
+    <div className="flex flex-col gap-2">
+      <div className="px-0.5 font-medium text-muted-foreground text-xs">{option.label}</div>
+      <div
+        className="grid gap-1.5"
+        style={{
+          gridTemplateColumns: `repeat(${Math.min(option.choices.length, 3)}, minmax(0, 1fr))`,
+        }}
+      >
+        {option.choices.map((choice) => {
+          const selected = active && choice.value === value
+          const thumbnail = getChoiceThumbnail?.(option, choice.value)
+          return (
+            <button
+              aria-pressed={selected}
+              className={cn(
+                'rounded-lg px-2 py-2 text-center font-medium text-xs transition-colors',
+                selected
+                  ? 'bg-primary/10 text-primary ring-1 ring-primary/50'
+                  : 'bg-muted/40 text-muted-foreground hover:bg-muted hover:text-foreground',
+              )}
+              key={choice.value}
+              onClick={() => {
+                triggerSFX('sfx:menu-click')
+                option.set(choice.value)
+                onSelect?.(option, choice.value)
+              }}
+              onMouseEnter={() => triggerSFX('sfx:menu-hover')}
+              type="button"
+            >
+              {thumbnail && (
+                <Image
+                  alt=""
+                  className={cn(
+                    'mx-auto mb-1 size-14 object-contain',
+                    !selected && 'opacity-70 grayscale',
+                  )}
+                  height={56}
+                  src={thumbnail}
+                  width={56}
+                />
+              )}
+              {choice.label}
+            </button>
+          )
+        })}
+      </div>
+      {activeChoice && activeChoice.description ? (
+        <p className="px-0.5 text-[11px] text-muted-foreground leading-relaxed">
+          {activeChoice.description}
+        </p>
+      ) : null}
+    </div>
+  )
+}
+
+/**
+ * The pick-one option rows a kind declares via `def.toolOptions` (e.g. the
+ * roof's 'Create from: Draw / Room'), for whichever sidebar the host mounts
+ * it in — the standalone Build tab and the community Build sidebar both get
+ * every kind's options with no per-kind wiring. Renders nothing for kinds
+ * without options. Selecting a choice only writes the kind's own state;
+ * hosts that want selection to also arm the tool pass `onSelect`.
+ */
+export function ToolOptionsPanel({
+  kind,
+  className,
+  onSelect,
+  getChoiceThumbnail,
+  active = true,
+}: {
+  kind: string | null | undefined
+  className?: string
+  onSelect?: (option: ToolOption, value: string) => void
+  getChoiceThumbnail?: (option: ToolOption, value: string) => string | undefined
+  active?: boolean
+}) {
+  const options = (kind ? nodeRegistry.get(kind)?.toolOptions : undefined) ?? []
+  if (options.length === 0) return null
+  return (
+    <div className={cn('flex flex-col gap-3', className)}>
+      {options.map((option) => (
+        <ToolOptionRow
+          active={active}
+          getChoiceThumbnail={getChoiceThumbnail}
+          key={option.id}
+          onSelect={onSelect}
+          option={option}
+        />
+      ))}
+    </div>
+  )
+}

package/src/components/ui/floating-level-selector.tsx

@@ -27,7 +27,7 @@ import {
   LevelNode,
   useScene,
 } from '@pascal-app/core'
-import { useViewer } from '@pascal-app/viewer'
+import { markPerfAction, useViewer } from '@pascal-app/viewer'
 import { ClipboardPaste, Copy, GripVertical, MoreVertical, Plus, Trash2 } from 'lucide-react'
 import {
   type ButtonHTMLAttributes,
@@ -150,6 +150,9 @@ function LevelRow({
   const storeyHeight = getStoredLevelHeight(level)
   // toFixed(2) + strip one trailing zero: "2.50" → "2.5", "2.75" stays.
   const storeyHeightLabel = `${toDisplay(storeyHeight).toFixed(2).replace(/0$/, '')} ${displayUnit}`
+  // Same rule as the site panel and command palette: the ordinal-0 ground
+  // floor is the vertical model's zero anchor and must never be deletable.
+  const canDeleteLevel = level.level !== 0
 
   // Clean preset values per display system; imperial stores exact meters
   // for whole-foot storey heights.
@@ -304,11 +307,13 @@ function LevelRow({
                 </button>
               )}
               <button
-                className="flex w-full items-center gap-2 rounded-md px-2.5 py-1.5 text-left text-muted-foreground text-xs transition-colors hover:bg-white/10 hover:text-red-400"
+                className="flex w-full items-center gap-2 rounded-md px-2.5 py-1.5 text-left text-muted-foreground text-xs transition-colors enabled:hover:bg-white/10 enabled:hover:text-red-400 disabled:cursor-not-allowed disabled:opacity-50"
+                disabled={!canDeleteLevel}
                 onClick={(e) => {
                   e.stopPropagation()
                   onRequestDelete()
                 }}
+                title={canDeleteLevel ? 'Delete level' : 'The ground level cannot be deleted'}
                 type="button"
               >
                 <Trash2 className="h-3 w-3" />
@@ -572,6 +577,9 @@ export function FloatingLevelSelector() {
           {!draggingLevelId && (
             <button
               className={cn(addButtonClass, 'top-0 -translate-y-1/2')}
+              // A stable hook for host-app onboarding to point at. Static, and
+              // read only from outside: nothing here depends on it.
+              data-guide-target="level-add"
               onClick={handleAddAbove}
               title="Add level above"
               type="button"
@@ -608,20 +616,29 @@ export function FloatingLevelSelector() {
                   const showGapBelow = i < reversedLevels.length - 1
 
                   return (
-                    <div className="relative" key={level.id}>
+                    <div
+                      className="relative"
+                      // A stable hook for host-app onboarding to point at, on
+                      // the ground floor only — the one level a guide can name
+                      // without knowing the building. Static, and read only
+                      // from outside: nothing here depends on it.
+                      data-guide-target={level.level === 0 ? 'level-ground' : undefined}
+                      key={level.id}
+                    >
                       <SortableLevelRow
                         isSelected={isSelected}
                         level={level}
                         onDuplicate={(preset) => handleDuplicateLevel(level, preset)}
                         onPaste={() => handlePasteToLevel(level)}
                         onRequestDelete={() => setDeletingLevel(level)}
-                        onSelect={() =>
+                        onSelect={() => {
+                          if (!isSelected) markPerfAction('level-switch', level.id)
                           setSelection(
                             resolvedBuildingId
                               ? { buildingId: resolvedBuildingId, levelId: level.id }
                               : { levelId: level.id },
                           )
-                        }
+                        }}
                       />
 
                       {showGapBelow && !draggingLevelId && (

package/src/components/ui/helpers/contextual-helper-panel.tsx

@@ -90,6 +90,7 @@ function ShortcutSequence({
 function ChipRow({
   ariaLabel,
   disabled = false,
+  guideTarget,
   icon,
   label,
   onClick,
@@ -98,6 +99,11 @@ function ChipRow({
 }: {
   ariaLabel?: string
   disabled?: boolean
+  /**
+   * A static hook for a host app's first-run tour to point at, written to
+   * `data-guide-target`. Nothing here reads it.
+   */
+  guideTarget?: string
   icon?: string
   label: string
   onClick?: () => void
@@ -130,6 +136,7 @@ function ChipRow({
         'pointer-events-auto cursor-pointer items-center rounded-md text-left transition-colors hover:bg-muted/60',
         disabled && 'opacity-45 saturate-0',
       )}
+      data-guide-target={guideTarget}
       onClick={onClick}
       type="button"
     >
@@ -181,6 +188,7 @@ function SnappingChips({ context }: { context: SnapContext }) {
     <>
       <ChipRow
         ariaLabel={`Snapping: ${SNAPPING_MODE_LABELS[snappingMode]}`}
+        guideTarget="snap-mode"
         icon={SNAPPING_MODE_ICONS[snappingMode]}
         label={`Snapping: ${SNAPPING_MODE_LABELS[snappingMode]}`}
         onClick={() => {
@@ -193,6 +201,7 @@ function SnappingChips({ context }: { context: SnapContext }) {
       {gridActive ? (
         <ChipRow
           ariaLabel={`Grid step: ${gridSnapStep.toFixed(2)} m`}
+          guideTarget="snap-grid-step"
           label={`Grid: ${gridSnapStep.toFixed(2)} m`}
           onClick={() => {
             setGridSnapStep(nextGridSnapStep(gridSnapStep))

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

@@ -8,7 +8,7 @@ import {
   useScene,
 } from '@pascal-app/core'
 import { useViewer } from '@pascal-app/viewer'
-import { useEffect, useMemo, useState } from 'react'
+import { useEffect, useMemo, useState, useSyncExternalStore } from 'react'
 import { useShallow } from 'zustand/react/shallow'
 import { useIsMobile } from '../../../hooks/use-mobile'
 import {
@@ -19,6 +19,7 @@ import {
   resolveRotateHandleHelpHints,
   resolveSelectModeHelpHints,
 } from '../../../lib/contextual-help'
+import { getContextualHelpNodeExtension } from '../../../lib/contextual-help-extension'
 import { continuationContextOf } from '../../../lib/continuation'
 import { canDirectMoveNode, canDirectRotateNode } from '../../../lib/direct-manipulation'
 import type { ReshapeKind } from '../../../lib/interaction/scope'
@@ -33,7 +34,6 @@ import { BuildingHelper } from './building-helper'
 import { ContextualHelperPanel } from './contextual-helper-panel'
 import { ItemHelper } from './item-helper'
 import { RegisteredToolHelper } from './registered-tool-helper'
-import { RoofHelper } from './roof-helper'
 
 // Reshaping a selected node's geometry (endpoint / curve / polygon corner). The
 // snapping chip is the main control; these just name the gesture + Esc.
@@ -88,6 +88,9 @@ type ActiveModifierKeys = {
   shift: boolean
 }
 
+const EMPTY_CONTEXTUAL_HINTS: ContextualShortcutHint[] = []
+const NO_CONTEXTUAL_HELP_SUBSCRIPTION = () => () => {}
+
 function useActiveModifierKeys(): ActiveModifierKeys {
   const [modifiers, setModifiers] = useState<ActiveModifierKeys>({
     command: false,
@@ -143,6 +146,21 @@ export function HelperManager() {
         .filter((node): node is AnyNode => node !== undefined),
     ),
   )
+  const contextualHelpNode =
+    scope.kind === 'mesh-editing'
+      ? selectedNodes.find((node) => node.id === scope.nodeId) ?? null
+      : null
+  const contextualHelpExtension = contextualHelpNode
+    ? getContextualHelpNodeExtension(nodeRegistry.get(contextualHelpNode.type))
+    : undefined
+  const contextualEditHints = useSyncExternalStore(
+    contextualHelpExtension?.subscribe ?? NO_CONTEXTUAL_HELP_SUBSCRIPTION,
+    () =>
+      contextualHelpNode
+        ? (contextualHelpExtension?.getHints(contextualHelpNode.id) ?? EMPTY_CONTEXTUAL_HINTS)
+        : EMPTY_CONTEXTUAL_HINTS,
+    () => EMPTY_CONTEXTUAL_HINTS,
+  )
   // The snapping context for whatever's active (wall / item / polygon) — drives
   // which snapping chips the HUD shows, derived once and shared by every branch.
   const snapContext = useMemo(
@@ -152,6 +170,10 @@ export function HelperManager() {
         mode,
         tool,
         profileOf: (typeOrTool) => nodeRegistry.get(typeOrTool)?.snapProfile,
+        profileOfNode: (nodeId) => {
+          const node = useScene.getState().nodes[nodeId as AnyNodeId]
+          return node ? nodeRegistry.get(node.type)?.snapProfile : undefined
+        },
         draftDirectionalOf: (typeOrTool) => nodeRegistry.get(typeOrTool)?.snapDraftDirectional ?? true,
       }),
     [scope, mode, tool],
@@ -212,6 +234,22 @@ export function HelperManager() {
     )
   }
 
+  // A single-node resize arrow is still an active snapping interaction. Roof
+  // width/depth handles opt into grid snapping, so keep the mode and grid-step
+  // controls visible for the whole drag instead of falling through to idle
+  // selection hints.
+  if (activeHandleDrag) {
+    return (
+      <ContextualHelperPanel
+        hints={[
+          { keys: ['Drag'], label: 'Resize' },
+          { keys: ['Esc'], label: 'Cancel' },
+        ]}
+        snapContext={snapContext}
+      />
+    )
+  }
+
   // Reshaping a node's geometry (endpoint / curve / polygon corner). Checked
   // 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.
@@ -227,13 +265,13 @@ export function HelperManager() {
     const movingContinuationContext = isFreshPlacementMetadata(movingNode.metadata)
       ? continuationContextOf(movingNode.type)
       : null
-    // Force-place only makes sense for kinds that collision-validate their drop;
-    // structural kinds (wall/slab/…) never reject, so don't advertise Alt.
+    const collisionValidatesDrop =
+      nodeRegistry.get(movingNode.type)?.capabilities.floorPlaced?.collides === true
     return (
       <ItemHelper
         continuationContext={movingContinuationContext}
         showEsc
-        showForce={nodeRegistry.get(movingNode.type)?.snapProfile !== 'structural'}
+        showForce={collisionValidatesDrop}
         snapContext={snapContext}
       />
     )
@@ -255,6 +293,10 @@ export function HelperManager() {
     return <ContextualHelperPanel hints={terrainSculptHints(terrainVerb, terrainSampling)} />
   }
 
+  if (scope.kind === 'mesh-editing') {
+    return <ContextualHelperPanel hints={contextualEditHints} snapContext={snapContext} />
+  }
+
   // Idle select only — an active scope (handle-drag, box-select, …) must not show
   // the idle selection hints.
   if (mode === 'select' && scope.kind === 'idle') {
@@ -273,12 +315,6 @@ export function HelperManager() {
     )
   }
 
-  // Legacy fallback — only `roof` remains because it hasn't migrated to
-  // `def.tool` / `def.toolHints` yet (no Stage D port). Checked before the
-  // generic tool branch so the snap-context fallback below doesn't capture it
-  // and drop its bespoke `RoofHelper` hints. When roof migrates, this deletes.
-  if (tool === 'roof') return <RoofHelper snapContext={snapContext} />
-
   // Registry-first: a kind renders the generic `RegisteredToolHelper` when it
   // declares `def.toolHints`, OR whenever its draft resolves to a snap /
   // continuation context — so a snappable tool with NO hand-written hints (e.g.

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

@@ -6,7 +6,7 @@ interface ItemHelperProps {
   showEsc?: boolean
   snapContext?: SnapContext | null
   // Whether to advertise Alt = force-place. Only meaningful for kinds that
-  // collision-validate their drop (structural kinds never reject, so it's hidden).
+  // collision-validate their drop.
   showForce?: boolean
   // 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.