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

package/src/components/ui/command-palette/editor-commands.tsx

@@ -37,7 +37,7 @@ import {
   Video,
 } from 'lucide-react'
 import { useEffect } from 'react'
-import { runRedo, runUndo } from '../../../lib/history'
+import { getHistoryCommandState, runRedo, runUndo } from '../../../lib/history'
 import { deleteLevelWithFallbackSelection } from '../../../lib/level-selection'
 import { useCommandRegistry } from '../../../store/use-command-registry'
 import type { StructureTool } from '../../../store/use-editor'
@@ -49,10 +49,9 @@ export function EditorCommands() {
   const { navigateTo, setInputValue, setOpen } = useCommandPalette()
 
   const setPhase = useEditor((s) => s.setPhase)
-  const setMode = useEditor((s) => s.setMode)
-  const setTool = useEditor((s) => s.setTool)
+  const armToolMode = useEditor((s) => s.armToolMode)
+  const armMaterialPaint = useEditor((s) => s.armMaterialPaint)
   const setStructureLayer = useEditor((s) => s.setStructureLayer)
-  const primeMaterialPaintFromSelection = useEditor((s) => s.primeMaterialPaintFromSelection)
   const isPreviewMode = useEditor((s) => s.isPreviewMode)
   const setPreviewMode = useEditor((s) => s.setPreviewMode)
 
@@ -68,9 +67,9 @@ export function EditorCommands() {
     const activateTool = (tool: StructureTool) => {
       run(() => {
         setPhase('structure')
-        setMode('build')
         if (tool === 'zone') setStructureLayer('zones')
-        setTool(tool)
+        else setStructureLayer('elements')
+        armToolMode({ mode: 'build', tool })
       })
     }
 
@@ -163,10 +162,9 @@ export function EditorCommands() {
         shortcut: ['P'],
         execute: () =>
           run(() => {
-            primeMaterialPaintFromSelection()
             setPhase('structure')
             setStructureLayer('elements')
-            setMode('material-paint')
+            armMaterialPaint()
           }),
       },
       {
@@ -176,9 +174,8 @@ export function EditorCommands() {
         icon: <Mountain className="h-4 w-4" />,
         keywords: ['terrain', 'ground', 'elevation', 'sculpt', 'hill', 'slope', 'grade', 'dig'],
         shortcut: ['G'],
-        // No `setPhase`: `setMode` moves to the site phase itself, and doing it
-        // here would set the phase twice with a mode reset in between.
-        execute: () => run(() => setMode('terrain-sculpt')),
+        // The ToolMode transition moves to the site phase itself.
+        execute: () => run(() => armToolMode({ mode: 'terrain-sculpt' })),
       },
 
       // ── Levels ───────────────────────────────────────────────────────────
@@ -351,6 +348,7 @@ export function EditorCommands() {
         group: 'History',
         icon: <Undo2 className="h-4 w-4" />,
         keywords: ['undo', 'revert', 'back'],
+        when: () => getHistoryCommandState().canUndo,
         execute: () => run(() => runUndo()),
       },
       {
@@ -359,6 +357,7 @@ export function EditorCommands() {
         group: 'History',
         icon: <Redo2 className="h-4 w-4" />,
         keywords: ['redo', 'forward', 'repeat'],
+        when: () => getHistoryCommandState().canRedo,
         execute: () => run(() => runRedo()),
       },
 
@@ -426,8 +425,8 @@ export function EditorCommands() {
     setInputValue,
     setOpen,
     setPhase,
-    setMode,
-    setTool,
+    armToolMode,
+    armMaterialPaint,
     setStructureLayer,
     isPreviewMode,
     setPreviewMode,

package/src/components/ui/command-palette/index.tsx

@@ -2,7 +2,7 @@
 
 import type { AnyNodeId, LevelNode } from '@pascal-app/core'
 import { useScene } from '@pascal-app/core'
-import { useViewer } from '@pascal-app/viewer'
+import { markPerfAction, useViewer } from '@pascal-app/viewer'
 import { Command, useCommandState } from 'cmdk'
 import { ChevronRight, Search } from 'lucide-react'
 import type { ReactNode } from 'react'
@@ -408,7 +408,12 @@ export function CommandPalette({ emptyAction }: { emptyAction?: CommandPaletteEm
                       key={level.id}
                       label={getLevelDisplayName(level)}
                       onSelect={() =>
-                        run(() => useViewer.getState().setSelection({ levelId: level.id }))
+                        run(() => {
+                          if (level.id !== useViewer.getState().selection.levelId) {
+                            markPerfAction('level-switch', level.id)
+                          }
+                          useViewer.getState().setSelection({ levelId: level.id })
+                        })
                       }
                     />
                   ))}

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.
@@ -235,7 +238,7 @@ function LevelRow({
             >
               <SliderControl
                 label="Level height"
-                max={6}
+                max={20}
                 min={1}
                 onChange={(v) => updateNode(level.id, { height: v })}
                 precision={3}
@@ -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))