@pascal-app/editor 0.9.1 → 1.0.0-beta.1

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

@@ -1,44 +1,303 @@
 'use client'
 
-import { nodeRegistry } from '@pascal-app/core'
+import {
+  type AnyNode,
+  type AnyNodeId,
+  nodeRegistry,
+  type TerrainVerb,
+  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 { 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.
+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' },
+  ]
+}
+
+// Sculpt mode's HUD. The verb is named rather than described because it is the one
+// piece of state a user loses track of between strokes. This stays even though the
+// brush ring now carries the verb in colour (`brushRingColor`): the ring says
+// *which* verb only to someone who already knows the mapping, and the HUD is what
+// teaches it.
+function terrainSculptHints(verb: TerrainVerb, sampling: boolean): ContextualShortcutHint[] {
+  if (sampling) {
+    return [
+      { keys: ['Click'], label: 'Pick target height' },
+      { keys: ['Esc'], label: 'Cancel picking' },
+    ]
+  }
+  const action =
+    verb === 'raise'
+      ? 'Raise ground'
+      : verb === 'lower'
+        ? 'Lower ground'
+        : verb === 'flatten'
+          ? 'Level ground'
+          : 'Smooth ground'
+  return [
+    { keys: ['Drag'], label: action },
+    // Nested, so the two render as alternatives ("[ / ]") rather than a chord —
+    // a flat `['[', ']']` joins with "+" and would read as "press both".
+    { keys: [['[', ']']], label: 'Brush size' },
+    { keys: ['Esc'], label: 'Cancel stroke' },
+  ]
+}
+
+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 terrainVerb = useEditor((s) => s.terrainVerb)
+  const terrainSampling = useEditor((s) => s.terrainSampling)
+  const isFirstPersonMode = useEditor((s) => s.isFirstPersonMode)
+  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
 
+  // First-person walkthrough has its own HUD; editor shortcut hints (e.g. the
+  // Ctrl multi-select hint — Ctrl is crouch there) don't apply while walking.
+  if (isFirstPersonMode) 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
+    return <ContextualHelperPanel hints={[]} showPaintScope />
+  }
+
+  // Sculpt mode. The HUD is what makes a sustained brush mode legible: it names
+  // the active verb (the same word the panel's segmented control shows, so the
+  // two never disagree), and it advertises the two keys whose behaviour is
+  // 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)} />
+  }
+
+  // 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' },
+        ]}
+      />
+    )
   }
 
-  // Registry-first: kinds with `def.toolHints` render through the generic
-  // `RegisteredToolHelper`. Today that covers ceiling / door / fence /
-  // item / shelf / slab / spawn / wall / window.
+  // 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)
-    if (def?.toolHints && def.toolHints.length > 0) {
-      return <RegisteredToolHelper hints={def.toolHints} />
+    const hints = def?.toolHints ?? []
+    if (hints.length > 0 || snapContext || continuationContext) {
+      return (
+        <RegisteredToolHelper
+          continuationContext={continuationContext}
+          hints={hints}
+          shiftPressed={modifiers.shift}
+          snapContext={snapContext}
+        />
+      )
     }
   }
 
-  // Legacy fallback — only `roof` remains because it hasn't migrated to
-  // `def.tool` / `def.toolHints` yet (no Stage D port). When roof
-  // migrates, this switch deletes outright.
-  if (tool === 'roof') return <RoofHelper />
   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

@@ -1,5 +1,8 @@
 import type { ToolHint } from '@pascal-app/core'
-import { ShortcutToken } from '../primitives/shortcut-token'
+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
@@ -10,16 +13,47 @@ import { ShortcutToken } from '../primitives/shortcut-token'
  * Drops the need for per-kind helper files entirely — kinds declare
  * their hints as static data in their `NodeDefinition`.
  */
-export function RegisteredToolHelper({ hints }: { hints: ToolHint[] }) {
-  if (hints.length === 0) return null
+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 (
-    <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">
-      {hints.map((hint) => (
-        <div className="flex items-center gap-2 text-sm" key={`${hint.key}:${hint.label}`}>
-          <ShortcutToken value={hint.key} />
-          <span className="text-muted-foreground">{hint.label}</span>
-        </div>
-      ))}
-    </div>
+    <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',