@pascal-app/editor 0.8.0 → 0.9.2

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

@@ -1,45 +1,257 @@
 'use client'
 
+import {
+  type AnyNode,
+  type AnyNodeId,
+  nodeRegistry,
+  useScene,
+} from '@pascal-app/core'
+import { useViewer } from '@pascal-app/viewer'
+import { useEffect, useMemo, useState } from 'react'
+import { useShallow } from 'zustand/react/shallow'
 import { useIsMobile } from '../../../hooks/use-mobile'
-import useEditor from '../../../store/use-editor'
+import {
+  type ContextualShortcutHint,
+  GROUP_MOVE_DRAG_LABEL,
+  GROUP_ROTATE_DRAG_LABEL,
+  ROTATE_HANDLE_DRAG_LABEL,
+  resolveRotateHandleHelpHints,
+  resolveSelectModeHelpHints,
+} from '../../../lib/contextual-help'
+import { continuationContextOf } from '../../../lib/continuation'
+import { canDirectMoveNode, canDirectRotateNode } from '../../../lib/direct-manipulation'
+import type { ReshapeKind } from '../../../lib/interaction/scope'
+import { isFreshPlacementMetadata } from '../../../lib/placement-metadata'
+import { snapContextOf } from '../../../lib/snapping-mode'
+import useEditor, { getActiveContinuationContext } from '../../../store/use-editor'
+import useInteractionScope, {
+  useActiveHandleDrag,
+  useMovingNode,
+} from '../../../store/use-interaction-scope'
 import { BuildingHelper } from './building-helper'
-import { CeilingHelper } from './ceiling-helper'
+import { ContextualHelperPanel } from './contextual-helper-panel'
 import { ItemHelper } from './item-helper'
+import { RegisteredToolHelper } from './registered-tool-helper'
 import { RoofHelper } from './roof-helper'
-import { SlabHelper } from './slab-helper'
-import { WallHelper } from './wall-helper'
+
+// Reshaping a selected node's geometry (endpoint / curve / polygon corner). The
+// snapping chip is the main control; these just name the gesture + Esc.
+function reshapingHints(reshape: ReshapeKind): ContextualShortcutHint[] {
+  const action =
+    reshape === 'curve'
+      ? 'Curve'
+      : reshape === 'control-point'
+        ? 'Move control point'
+        : reshape === 'tangent'
+          ? 'Move tangent'
+      : reshape === 'endpoint'
+        ? 'Move endpoint'
+        : 'Move corner'
+  return [
+    { keys: ['Drag'], label: action },
+    { keys: ['Esc'], label: 'Cancel' },
+  ]
+}
+
+type ActiveModifierKeys = {
+  command: boolean
+  shift: boolean
+}
+
+function useActiveModifierKeys(): ActiveModifierKeys {
+  const [modifiers, setModifiers] = useState<ActiveModifierKeys>({
+    command: false,
+    shift: false,
+  })
+
+  useEffect(() => {
+    const updateModifiers = (event: KeyboardEvent) => {
+      const isKeyDown = event.type === 'keydown'
+      setModifiers({
+        command:
+          event.metaKey ||
+          event.ctrlKey ||
+          (isKeyDown && (event.key === 'Meta' || event.key === 'Control')),
+        shift: event.shiftKey || (isKeyDown && event.key === 'Shift'),
+      })
+    }
+    const clearModifiers = () => {
+      setModifiers({ command: false, shift: false })
+    }
+
+    window.addEventListener('keydown', updateModifiers)
+    window.addEventListener('keyup', updateModifiers)
+    window.addEventListener('blur', clearModifiers)
+    return () => {
+      window.removeEventListener('keydown', updateModifiers)
+      window.removeEventListener('keyup', updateModifiers)
+      window.removeEventListener('blur', clearModifiers)
+    }
+  }, [])
+
+  return modifiers
+}
 
 export function HelperManager() {
   const mode = useEditor((s) => s.mode)
   const tool = useEditor((s) => s.tool)
-  const movingNode = useEditor((state) => state.movingNode)
+  const measurementToolKind = useEditor((s) => s.toolDefaults.measurement?.kind)
+  const workspaceMode = useEditor((s) => s.workspaceMode)
+  const scope = useInteractionScope((s) => s.scope)
+  const movingNode = useMovingNode()
+  const activeHandleDrag = useActiveHandleDrag()
+  const selectedIds = useViewer((s) => s.selection.selectedIds)
   const isMobile = useIsMobile()
+  const modifiers = useActiveModifierKeys()
+  const selectedNodes = useScene(
+    useShallow((s) =>
+      selectedIds
+        .map((id) => s.nodes[id as AnyNodeId])
+        .filter((node): node is AnyNode => node !== undefined),
+    ),
+  )
+  // 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(
+    () =>
+      snapContextOf({
+        scope,
+        mode,
+        tool,
+        profileOf: (typeOrTool) => nodeRegistry.get(typeOrTool)?.snapProfile,
+        draftDirectionalOf: (typeOrTool) => nodeRegistry.get(typeOrTool)?.snapDraftDirectional ?? true,
+      }),
+    [scope, mode, tool],
+  )
+  const continuationContext = useMemo(
+    () => getActiveContinuationContext(),
+    [scope, mode, tool],
+  )
+  const selectModeHints = useMemo(() => {
+    const single = selectedNodes.length === 1 ? selectedNodes[0] : null
+    const mepSelection =
+      single?.type === 'duct-segment' || single?.type === 'pipe-segment'
+        ? 'run'
+        : single?.type === 'duct-fitting' || single?.type === 'pipe-fitting'
+          ? 'fitting'
+          : null
+    return resolveSelectModeHelpHints({
+      selectedCount: selectedNodes.length,
+      hasMovableSelection: selectedNodes.some((node) => canDirectMoveNode(node)),
+      hasRotatableSelection: selectedNodes.some((node) => canDirectRotateNode(node)),
+      commandPressed: modifiers.command,
+      shiftPressed: modifiers.shift,
+      mepSelection,
+    })
+  }, [modifiers.command, modifiers.shift, selectedNodes])
 
   // Helpers are keyboard-driven hints (Esc, R, etc.) — irrelevant on touch.
   if (isMobile) return null
 
+  // The studio workspace (compose panel / gallery) has no scene selection or
+  // 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)} />
+  }
+
+  // Group-move drag / pick-up: the drag resolves to the 'item' snap context
+  // (see `snapContextOf`), so surface the snapping chips — mode + grid step,
+  // with their Shift / Ctrl cycle shortcuts — plus the mid-move R/T rotate.
+  if (activeHandleDrag?.label === GROUP_MOVE_DRAG_LABEL) {
+    return (
+      <ContextualHelperPanel
+        hints={[{ keys: ['R / T'], label: 'Rotate the selection ±45°' }]}
+        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.
+  if (scope.kind === 'reshaping') {
+    return <ContextualHelperPanel hints={reshapingHints(scope.reshape)} snapContext={snapContext} />
+  }
+
   if (movingNode) {
     if (movingNode.type === 'building') return <BuildingHelper showRotate />
-    return <ItemHelper showEsc />
+    // 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)
+      : null
+    // Force-place only makes sense for kinds that collision-validate their drop;
+    // structural kinds (wall/slab/…) never reject, so don't advertise Alt.
+    return (
+      <ItemHelper
+        continuationContext={movingContinuationContext}
+        showEsc
+        showForce={nodeRegistry.get(movingNode.type)?.snapProfile !== 'structural'}
+        snapContext={snapContext}
+      />
+    )
   }
 
+  // Paint mode advertises (and cycles, via Shift) the application scope — the
+  // 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 null
-  }
-
-  // Show appropriate helper based on current tool
-  switch (tool) {
-    case 'wall':
-      return <WallHelper />
-    case 'item':
-      return <ItemHelper />
-    case 'slab':
-      return <SlabHelper />
-    case 'ceiling':
-      return <CeilingHelper />
-    case 'roof':
-      return <RoofHelper />
-    default:
-      return null
+    return <ContextualHelperPanel hints={[]} showPaintScope />
+  }
+
+  // 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} />
   }
+
+  if (tool === 'measurement' && measurementToolKind === 'smart') {
+    return (
+      <ContextualHelperPanel
+        hints={[
+          { keys: ['Hover'], label: 'Inspect surface dimensions' },
+          { keys: ['Click'], label: 'Pin measurement lens' },
+          { keys: ['Esc'], label: 'Exit smart measure' },
+        ]}
+      />
+    )
+  }
+
+  // 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.
+  // `zone`) still advertises the snapping chip it already honors (Shift = cycle).
+  // `RegisteredToolHelper` self-hides when there's genuinely nothing to show.
+  if (tool) {
+    const def = nodeRegistry.get(tool)
+    const hints = def?.toolHints ?? []
+    if (hints.length > 0 || snapContext || continuationContext) {
+      return (
+        <RegisteredToolHelper
+          continuationContext={continuationContext}
+          hints={hints}
+          shiftPressed={modifiers.shift}
+          snapContext={snapContext}
+        />
+      )
+    }
+  }
+
+  return null
 }

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

@@ -1,40 +1,36 @@
-import { ShortcutToken } from '../primitives/shortcut-token'
+import type { ContinuationContext } from '../../../lib/continuation'
+import type { SnapContext } from '../../../lib/snapping-mode'
+import { ContextualHelperPanel } from './contextual-helper-panel'
 
 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).
+  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.
+  continuationContext?: ContinuationContext | null
 }
 
-export function ItemHelper({ showEsc }: ItemHelperProps) {
+// Snapping mode is the chip on the right (Shift cycles it), so it's not repeated
+// as a key hint. Rotate is the two keys; Alt forces an invalid (red) drop.
+export function ItemHelper({
+  showEsc,
+  snapContext,
+  showForce,
+  continuationContext = null,
+}: ItemHelperProps) {
   return (
-    <div className="pointer-events-none fixed top-1/2 right-4 z-40 flex -translate-y-1/2 flex-col gap-2 rounded-lg border border-border bg-background/95 px-4 py-3 shadow-lg backdrop-blur-md">
-      <div className="flex items-center gap-2 text-sm">
-        <ShortcutToken value="Left click" />
-        <span className="text-muted-foreground">Place item</span>
-      </div>
-      <div className="flex items-center gap-2 text-sm">
-        <ShortcutToken value="R" />
-        <span className="text-muted-foreground">Rotate counterclockwise</span>
-      </div>
-      <div className="flex items-center gap-2 text-sm">
-        <ShortcutToken value="T" />
-        <span className="text-muted-foreground">Rotate clockwise</span>
-      </div>
-      <div className="flex items-center gap-2 text-sm">
-        <ShortcutToken value="Shift" />
-        <span className="text-muted-foreground">Free place</span>
-      </div>
-      {showEsc && (
-        <div className="flex items-center gap-2 text-sm">
-          <ShortcutToken value="Esc" />
-          <span className="text-muted-foreground">Cancel</span>
-        </div>
-      )}
-      {!showEsc && (
-        <div className="flex items-center gap-2 text-sm">
-          <ShortcutToken value="Right click" />
-          <span className="text-muted-foreground">Cancel</span>
-        </div>
-      )}
-    </div>
+    <ContextualHelperPanel
+      continuationContext={continuationContext}
+      hints={[
+        { keys: ['Left click'], label: 'Place' },
+        { keys: ['R', 'T'], label: 'Rotate' },
+        ...(showForce ? [{ keys: ['Alt'], label: 'Force place' }] : []),
+        { keys: [showEsc ? 'Esc' : 'Right click'], label: 'Cancel' },
+      ]}
+      snapContext={snapContext}
+    />
   )
 }

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

@@ -0,0 +1,59 @@
+import type { ToolHint } from '@pascal-app/core'
+import type { ContinuationContext } from '../../../lib/continuation'
+import type { SnapContext } from '../../../lib/snapping-mode'
+import useEditor from '../../../store/use-editor'
+import { ContextualHelperPanel } from './contextual-helper-panel'
+
+/**
+ * Generic helper panel rendered from `def.toolHints` data. Matches the
+ * visual styling of the hand-written `<WallHelper>` / `<ItemHelper>` /
+ * etc. so registry-driven kinds get a consistent look without each kind
+ * writing its own component.
+ *
+ * Drops the need for per-kind helper files entirely — kinds declare
+ * their hints as static data in their `NodeDefinition`.
+ */
+export function RegisteredToolHelper({
+  hints,
+  shiftPressed = false,
+  snapContext = null,
+  continuationContext = null,
+}: {
+  hints: ToolHint[]
+  shiftPressed?: boolean
+  snapContext?: SnapContext | null
+  continuationContext?: ContinuationContext | 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)
+  // 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.minDraftVertices == null || draftVertexCount >= hint.minDraftVertices),
+  )
+  if (visible.length === 0 && !snapContext && !continuationContext) 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)
+  const staticHints = visible.filter((hint) => !hint.chip)
+  return (
+    <ContextualHelperPanel
+      chipHints={chipHints}
+      hints={staticHints.map((hint) => {
+        // Shift is a per-kind bypass for opening / zone / duct placement ("Free
+        // place", "Free angle", …) — those flip to a bypassed state while held.
+        const isBypassHint = hint.key === 'Shift'
+        return {
+          keys: [hint.key],
+          label: shiftPressed && isBypassHint ? 'Guided constraints bypassed' : hint.label,
+          active: shiftPressed && isBypassHint,
+        }
+      })}
+      continuationContext={continuationContext}
+      snapContext={snapContext}
+    />
+  )
+}

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

@@ -1,16 +1,14 @@
-import { ShortcutToken } from '../primitives/shortcut-token'
+import type { SnapContext } from '../../../lib/snapping-mode'
+import { ContextualHelperPanel } from './contextual-helper-panel'
 
-export function RoofHelper() {
+export function RoofHelper({ snapContext }: { snapContext?: SnapContext | null }) {
   return (
-    <div className="pointer-events-none fixed top-1/2 right-4 z-40 flex -translate-y-1/2 flex-col gap-2 rounded-lg border border-border bg-background/95 px-4 py-3 shadow-lg backdrop-blur-md">
-      <div className="flex items-center gap-2 text-sm">
-        <ShortcutToken value="Left click" />
-        <span className="text-muted-foreground">Set corner</span>
-      </div>
-      <div className="flex items-center gap-2 text-sm">
-        <ShortcutToken value="Esc" />
-        <span className="text-muted-foreground">Cancel</span>
-      </div>
-    </div>
+    <ContextualHelperPanel
+      hints={[
+        { keys: ['Left click'], label: 'Set corner' },
+        { keys: ['Esc'], label: 'Cancel' },
+      ]}
+      snapContext={snapContext}
+    />
   )
 }

package/src/components/ui/icon-ref.tsx

@@ -0,0 +1,47 @@
+'use client'
+
+import { Icon } from '@iconify/react'
+import type { IconRef } from '@pascal-app/core'
+import { type ComponentType, lazy, Suspense } from 'react'
+
+// `React.lazy` must be called once per loader so the resolved component keeps
+// a stable identity across renders (otherwise every parent re-render remounts
+// the icon). Cache by the loader function — same pattern as the plugin-panel
+// component cache.
+const lazyIconCache = new WeakMap<() => Promise<{ default: ComponentType }>, ComponentType>()
+
+function resolveLazyIcon(module: () => Promise<{ default: ComponentType }>): ComponentType {
+  const cached = lazyIconCache.get(module)
+  if (cached) return cached
+  const Lazy = lazy(module)
+  lazyIconCache.set(module, Lazy)
+  return Lazy
+}
+
+/**
+ * Generic renderer for a registry {@link IconRef} — url / iconify / inline-svg
+ * marks are sized by `size` (px); `component`-kind icons size themselves.
+ * Shared by the quick-action menus; the icon rail and inspector keep their
+ * own copies with bespoke wrappers for now.
+ */
+export function IconRefGlyph({ icon, size = 16 }: { icon: IconRef; size?: number }) {
+  if (icon.kind === 'url') {
+    return <img alt="" className="shrink-0 object-contain" height={size} src={icon.src} width={size} />
+  }
+  if (icon.kind === 'iconify') {
+    return <Icon height={size} icon={icon.name} width={size} />
+  }
+  if (icon.kind === 'svg') {
+    return (
+      <svg height={size} viewBox={icon.viewBox} width={size}>
+        <path d={icon.path} fill="currentColor" />
+      </svg>
+    )
+  }
+  const LazyIcon = resolveLazyIcon(icon.module)
+  return (
+    <Suspense fallback={null}>
+      <LazyIcon />
+    </Suspense>
+  )
+}

package/src/components/ui/item-catalog/catalog-items.tsx

@@ -1,6 +1,14 @@
 import type { AssetInput } from '@pascal-app/core'
 
-export const CATALOG_ITEMS: AssetInput[] = [
+/**
+ * A catalog tile: the asset plus optional editor placement metadata.
+ * `tool` names the placement tool the tile arms (defaults to the generic
+ * `'item'` drop tool) — kinds drawn by their own registry tool (e.g. the
+ * modular cabinet) point at that tool id instead.
+ */
+export type CatalogItem = AssetInput & { tool?: string }
+
+export const CATALOG_ITEMS: CatalogItem[] = [
   {
     id: 'cactus',
     category: 'furniture',
@@ -437,6 +445,36 @@ export const CATALOG_ITEMS: AssetInput[] = [
     scale: [1, 1, 1],
     surface: { height: 0.48 },
   },
+  {
+    id: 'cabinet',
+    tool: 'cabinet',
+    category: 'furniture',
+    name: 'Modular Cabinet',
+    tags: [
+      'cabinet',
+      'cupboard',
+      'storage',
+      'kitchen',
+      'pantry',
+      'wood',
+      'timber',
+      'modern',
+      'contemporary',
+      'minimalist',
+      'organization',
+      'furniture',
+    ],
+    thumbnail:
+      'https://byrpxoiotywskoojsrzd.supabase.co/storage/v1/object/public/items/system/kitchen-cabinet/thumbnail.png',
+    src: 'https://byrpxoiotywskoojsrzd.supabase.co/storage/v1/object/public/items/system/kitchen-cabinet/model.glb',
+    floorPlanUrl:
+      'https://byrpxoiotywskoojsrzd.supabase.co/storage/v1/object/public/items/system/kitchen-cabinet/floor-plan.png',
+    dimensions: [1.65, 1.09, 0.77],
+    offset: [0, 0.0004, 0],
+    rotation: [0, 0, 0],
+    scale: [1, 1, 1],
+    surface: { height: 1.09 },
+  },
   {
     id: 'sofa',
     category: 'furniture',
@@ -628,6 +666,7 @@ export const CATALOG_ITEMS: AssetInput[] = [
     rotation: [0, 0, 0],
     scale: [1, 1, 1],
     attachTo: 'ceiling',
+    recessed: true,
     interactive: {
       controls: [
         { kind: 'toggle' },

package/src/components/ui/item-catalog/item-catalog.tsx

@@ -1,17 +1,13 @@
 'use client'
 
 import type { AssetInput } from '@pascal-app/core'
-import { resolveCdnUrl } from '@pascal-app/viewer'
-import Image from 'next/image'
+import { resolveCdnUrl, useViewer } from '@pascal-app/viewer'
 import { useEffect } from 'react'
-import {
-  Tooltip,
-  TooltipContent,
-  TooltipTrigger,
-} from './../../../components/ui/primitives/tooltip'
+import { triggerSFX } from './../../../lib/sfx-bus'
 import { cn } from './../../../lib/utils'
 import useEditor, { type CatalogCategory } from './../../../store/use-editor'
-import { CATALOG_ITEMS } from './catalog-items'
+import { resolveAssetSnapTarget, SnapTargetBadge } from '../snap-target-badge'
+import { CATALOG_ITEMS, type CatalogItem } from './catalog-items'
 
 export function ItemCatalog({
   category,
@@ -40,9 +36,9 @@ export function ItemCatalog({
   const setMode = useEditor((state) => state.setMode)
   const setTool = useEditor((state) => state.setTool)
 
-  const sourceItems = itemsOverride ?? CATALOG_ITEMS
+  const sourceItems: CatalogItem[] = itemsOverride ?? CATALOG_ITEMS
   // Server-provided results bypass all local filtering; otherwise filter by category/search/tags
-  const filteredItems =
+  const filteredItems: CatalogItem[] =
     overrideItems ??
     (() => {
       const categoryItems = search
@@ -57,22 +53,6 @@ export function ItemCatalog({
       })
     })()
 
-  const categoryItems = filteredItems
-
-  // Auto-select first item if current selection is not in the filtered list
-  useEffect(() => {
-    const isCurrentItemInCategory = categoryItems.some((item) => item.src === selectedItem?.src)
-    if (!isCurrentItemInCategory && categoryItems.length > 0) {
-      setSelectedItem(categoryItems[0] as AssetInput)
-    }
-  }, [categoryItems, selectedItem?.src, setSelectedItem])
-
-  const getAttachmentIcon = (attachTo: AssetInput['attachTo']) => {
-    if (attachTo === 'wall' || attachTo === 'wall-side') return '/icons/wall.png'
-    if (attachTo === 'ceiling') return '/icons/ceiling.png'
-    return null
-  }
-
   if (filteredItems.length === 0 && emptyState) {
     return <>{emptyState}</>
   }
@@ -85,7 +65,7 @@ export function ItemCatalog({
       {leadingTile}
       {filteredItems.map((item, index) => {
         const isSelected = selectedItem?.src === item?.src
-        const attachmentIcon = getAttachmentIcon(item?.attachTo)
+        const snapTarget = resolveAssetSnapTarget(item?.attachTo)
         return (
           <button
             className={cn(
@@ -94,10 +74,16 @@ export function ItemCatalog({
             )}
             key={index}
             onClick={() => {
+              triggerSFX('sfx:menu-click')
+              // Drop the current selection before arming placement — keeping
+              // it would route shortcuts (rotate & co) to both the ghost and
+              // the selected node.
+              useViewer.getState().setSelection({ selectedIds: [], zoneId: null })
               setSelectedItem(item)
-              setTool('item')
+              setTool(item.tool ?? 'item')
               setMode('build')
             }}
+            onMouseEnter={() => triggerSFX('sfx:menu-hover')}
             type="button"
           >
             <div className="relative aspect-square w-full overflow-hidden rounded-lg">
@@ -107,14 +93,8 @@ export function ItemCatalog({
                 loading="eager"
                 src={resolveCdnUrl(item.thumbnail) || ''}
               />
-              {attachmentIcon && (
-                <div className="absolute right-1 bottom-1 flex h-4 w-4 items-center justify-center rounded bg-black/60">
-                  <img
-                    alt={item.attachTo === 'ceiling' ? 'Ceiling attachment' : 'Wall attachment'}
-                    className="h-4 w-4"
-                    src={attachmentIcon}
-                  />
-                </div>
+              {snapTarget && (
+                <SnapTargetBadge className="absolute right-1 bottom-1" target={snapTarget} />
               )}
             </div>
             <span className="truncate px-0.5 text-left font-medium text-[11px] text-muted-foreground group-hover:text-foreground">

package/src/components/ui/level-duplicate-dialog.tsx

@@ -3,6 +3,7 @@
 import type { LevelNode } from '@pascal-app/core'
 import { useEffect, useState } from 'react'
 import type { LevelDuplicatePreset } from '../../lib/level-duplication'
+import { getLevelDisplayName } from '@pascal-app/core'
 import { cn } from '../../lib/utils'
 import {
   Dialog,
@@ -42,7 +43,7 @@ const DUPLICATE_PRESETS: Array<{
 
 function getLevelLabel(level: LevelNode | null) {
   if (!level) return 'this level'
-  return level.name || `Level ${level.level}`
+  return getLevelDisplayName(level)
 }
 
 export function LevelDuplicateDialog({