@pascal-app/editor 1.0.3 → 1.0.5

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

@@ -3,6 +3,7 @@
 import {
   type AnyNode,
   type AnyNodeId,
+  floorPlacedCollides,
   nodeRegistry,
   type TerrainVerb,
   useScene,
@@ -20,11 +21,52 @@ import {
   resolveSelectModeHelpHints,
 } from '../../../lib/contextual-help'
 import { getContextualHelpNodeExtension } from '../../../lib/contextual-help-extension'
-import { continuationContextOf } from '../../../lib/continuation'
+import { continuationContextOf, keyCyclableContinuationContext } from '../../../lib/continuation'
 import { canDirectMoveNode, canDirectRotateNode } from '../../../lib/direct-manipulation'
+import {
+  DIVIDE_ROOM_HUD_TITLE,
+  MEZZANINE_HUD_TITLE,
+  OPENING_HUD_TITLE,
+  TERRACE_HUD_TITLE,
+  MOVE_ROOM_HUD_TITLE,
+  MOVE_SELECTION_HUD_TITLE,
+  nodeKindHudTitle,
+  ERASE_HUD_TITLE,
+  PAINT_HUD_TITLE,
+  PICK_MATERIAL_HUD_TITLE,
+  paintRegionHudTitle,
+  RESIZE_HUD_TITLE,
+  ROTATE_HUD_TITLE,
+  SELECT_HUD_TITLE,
+  SMART_MEASURE_HUD_TITLE,
+  terrainHudTitle,
+  toolHudTitle,
+} from '../../../lib/hud-title'
 import type { ReshapeKind } from '../../../lib/interaction/scope'
+import {
+  type MezzanineShape,
+  useMezzanineDraft,
+} from '../../../lib/mezzanine-draft'
+import {
+  TERRACE_SHAPE_HINT,
+  type TerraceShape,
+  useTerraceDraft,
+} from '../../../lib/terrace-draft'
+import {
+  type OpeningShape,
+  useOpeningDraft,
+} from '../../../lib/floor-opening-draft'
 import { isFreshPlacementMetadata } from '../../../lib/placement-metadata'
+import { MEZZANINE_EDGE_DRAG_LABEL, ROOM_ELEVATION_DRAG_LABEL } from '../../../lib/room-handle-drag'
+import { ROOM_MOVE_DRAG_LABEL } from '../../../lib/room-transform-session'
+import { usePaintRegionHovering } from '../../../lib/paint-region-hover'
+import {
+  type PaintMode,
+  paintRegionHoverHint,
+  usePaintRegionMode,
+} from '../../../lib/paint-region-mode'
 import { snapContextOf } from '../../../lib/snapping-mode'
+import { cornerHintRows, useCornerSnapHint } from '../../../store/use-corner-snap-hint'
 import useEditor, { getActiveContinuationContext } from '../../../store/use-editor'
 import useInteractionScope, {
   useActiveHandleDrag,
@@ -33,6 +75,7 @@ import useInteractionScope, {
 } from '../../../store/use-interaction-scope'
 import { BuildingHelper } from './building-helper'
 import { ContextualHelperPanel } from './contextual-helper-panel'
+import { transientDraftId, usePlacementNotice } from '../../../hooks/use-placement-notice'
 import { ItemHelper } from './item-helper'
 import { RegisteredToolHelper } from './registered-tool-helper'
 
@@ -91,6 +134,89 @@ type ActiveModifierKeys = {
 }
 
 const EMPTY_CONTEXTUAL_HINTS: ContextualShortcutHint[] = []
+
+// The paint tool's region sub-modes: what one gesture draws, then Esc. A
+// refused gesture (the per-face cap) shows as the first row.
+/** What a click does in each whole-surface sub-mode; only painting teaches the held eyedropper. */
+export function paintHints(mode: PaintMode): ContextualShortcutHint[] {
+  if (mode === 'pick')
+    return [
+      { keys: ['Left click'], label: 'Paint with this material' },
+      { keys: ['Esc'], label: 'Cancel' },
+    ]
+  if (mode === 'erase')
+    return [{ keys: ['Left click'], label: 'Remove a painted part, or reset a surface' }]
+  if (mode === 'surface') return [{ keys: [['Alt', 'Option']], label: 'Hold to pick a material' }]
+  return []
+}
+
+export function paintRegionHints(
+  mode: 'rectangle' | 'polygon',
+  notice: string | null,
+  hovering = true,
+): ContextualShortcutHint[] {
+  const gesture: Record<typeof mode, ContextualShortcutHint> = {
+    rectangle: { keys: ['Drag'], label: 'Press anywhere, drag to the opposite corner' },
+    polygon: { keys: ['Left click'], label: 'Add point · click the first to close' },
+  }
+  // Off anything the sub-mode draws on, the HUD says where to go instead.
+  if (!hovering)
+    return [
+      ...(notice ? [{ keys: ['!'], label: notice, active: true }] : []),
+      { keys: ['Hover'], label: paintRegionHoverHint(mode), active: true },
+      { keys: ['Esc'], label: 'Cancel' },
+    ]
+  return [
+    ...(notice ? [{ keys: ['!'], label: notice, active: true }] : []),
+    gesture[mode],
+    ...(mode === 'polygon' ? [{ keys: ['Backspace'], label: 'Remove last point' }] : []),
+    { keys: ['Esc'], label: 'Cancel' },
+  ]
+}
+// "Add mezzanine": the outline gesture for the shape picked in the room panel,
+// then Esc; the snapping chip sits below.
+export function mezzanineHints(shape: MezzanineShape): ContextualShortcutHint[] {
+  return shape === 'rectangle'
+    ? [
+        { keys: ['Left click'], label: 'Set one corner, then the opposite' },
+        { keys: ['Drag'], label: 'Draw the mezzanine' },
+        { keys: ['Esc'], label: 'Cancel' },
+      ]
+    : [
+        { keys: ['Left click'], label: 'Add point · click the first to close' },
+        { keys: ['Backspace'], label: 'Remove last point' },
+        { keys: ['Enter'], label: 'Finish' },
+        { keys: ['Esc'], label: 'Cancel' },
+      ]
+}
+/** "Cut opening": the outline gesture for the chosen shape, then Esc. */
+export function openingHints(shape: OpeningShape): ContextualShortcutHint[] {
+  return mezzanineHints(shape).map((hint) =>
+    hint.label === 'Draw the mezzanine' ? { ...hint, label: 'Draw the opening' } : hint,
+  )
+}
+const TERRACE_CHIP_HINTS = [TERRACE_SHAPE_HINT]
+// The terrace tool: the outline gesture for the chosen shape, then Esc.
+export function terraceHints(shape: TerraceShape): ContextualShortcutHint[] {
+  return shape === 'rectangle'
+    ? [
+        { keys: ['Left click'], label: 'Set one corner, then the opposite' },
+        { keys: ['Drag'], label: 'Draw the terrace' },
+        { keys: ['Esc'], label: 'Done' },
+      ]
+    : [
+        { keys: ['Left click'], label: 'Add point · click the first to close' },
+        { keys: ['Backspace'], label: 'Remove last point' },
+        { keys: ['Enter'], label: 'Finish' },
+        { keys: ['Esc'], label: 'Done' },
+      ]
+}
+export const ROOM_DIVIDE_HINTS: ContextualShortcutHint[] = [
+  { keys: ['Left click'], label: 'Add point' },
+  { keys: ['Backspace'], label: 'Remove last point' },
+  { keys: ['Enter'], label: 'Finish at the edge' },
+  { keys: ['Esc'], label: 'Cancel' },
+]
 const NO_CONTEXTUAL_HELP_SUBSCRIPTION = () => () => {}
 
 function useActiveModifierKeys(): ActiveModifierKeys {
@@ -129,6 +255,43 @@ function useActiveModifierKeys(): ActiveModifierKeys {
   return modifiers
 }
 
+export type MezzanineGesture = 'raise' | 'resize' | 'move'
+
+/**
+ * A handle drag on a mezzanine — its floor handle, an edge arrow, or its pick-up
+ * (Move / Duplicate) — or null. Its HUD names the mezzanine, not "Resize" or
+ * "Move room".
+ */
+export function mezzanineGesture(
+  drag: { nodeId: string; label: string } | null,
+  nodes: Readonly<Record<string, AnyNode>>,
+): MezzanineGesture | null {
+  if (!drag) return null
+  const zone = nodes[drag.nodeId]
+  if (zone?.type !== 'zone' || zone.floor?.support !== 'open') return null
+  if (drag.label === ROOM_ELEVATION_DRAG_LABEL) return 'raise'
+  if (drag.label === MEZZANINE_EDGE_DRAG_LABEL) return 'resize'
+  if (drag.label === ROOM_MOVE_DRAG_LABEL) return 'move'
+  return null
+}
+
+export const MEZZANINE_GESTURE_HINTS: Record<MezzanineGesture, ContextualShortcutHint[]> = {
+  raise: [
+    { keys: ['Drag'], label: 'Raise or lower' },
+    { keys: ['Esc'], label: 'Cancel' },
+  ],
+  resize: [
+    { keys: ['Drag'], label: 'Resize' },
+    { keys: ['Esc'], label: 'Cancel' },
+  ],
+  move: [
+    { keys: ['Left click'], label: 'Place inside the room' },
+    { keys: [['R', 'T']], label: 'Rotate ±45°' },
+    { keys: ['Alt'], label: 'Free move' },
+    { keys: ['Esc'], label: 'Cancel' },
+  ],
+}
+
 export function HelperManager() {
   const mode = useEditor((s) => s.mode)
   const tool = useEditor((s) => s.tool)
@@ -136,11 +299,25 @@ export function HelperManager() {
   const terrainSampling = useEditor((s) => s.terrainSampling)
   const isFirstPersonMode = useEditor((s) => s.isFirstPersonMode)
   const measurementToolKind = useEditor((s) => s.toolDefaults.measurement?.kind)
+  const wallMode = useEditor((s) => s.continuationByContext.wall)
   const workspaceMode = useEditor((s) => s.workspaceMode)
   const scope = useInteractionScope((s) => s.scope)
+  const paintRegionMode = usePaintRegionMode((s) => s.mode)
+  const paintRegionDrawing = paintRegionMode === 'rectangle' || paintRegionMode === 'polygon'
+  const paintRegionNotice = usePaintRegionMode((s) => s.notice)
+  const paintRegionHovering = usePaintRegionHovering()
+  const mezzanineShape = useMezzanineDraft((s) => (s.host ? s.shape : null))
+  const openingShape = useOpeningDraft((s) => (s.host ? s.shape : null))
+  const terraceShape = useTerraceDraft((s) => (s.host ? s.shape : null))
   const movingNode = useMovingNode()
+  const cornerHint = useCornerSnapHint((s) => s.hint)
+  // A tool whose kind gives placement notices: its transient draft is the node in hand.
+  const toolNotices = !!(tool && nodeRegistry.get(tool)?.placementNotice)
+  const toolDraftId = useScene((s) => (toolNotices ? transientDraftId(s.nodes) : null))
+  const placementNotice = usePlacementNotice(movingNode?.id ?? toolDraftId, toolNotices)
   const reshapingNode = useReshapingNode()
   const activeHandleDrag = useActiveHandleDrag()
+  const mezzanineHandle = useScene((s) => mezzanineGesture(activeHandleDrag, s.nodes))
   const selectedIds = useViewer((s) => s.selection.selectedIds)
   const isMobile = useIsMobile()
   const modifiers = useActiveModifierKeys()
@@ -180,11 +357,14 @@ export function HelperManager() {
           return node ? nodeRegistry.get(node.type)?.snapProfile : undefined
         },
         draftDirectionalOf: (typeOrTool) => nodeRegistry.get(typeOrTool)?.snapDraftDirectional ?? true,
+        paintRegion: mode === 'material-paint' && paintRegionDrawing,
       }),
-    [scope, mode, tool],
+    [scope, mode, tool, paintRegionDrawing],
   )
+  // Contexts whose mode is picked in the Build panel (the wall's Rooms variant)
+  // get no HUD chip: the header names the variant instead.
   const continuationContext = useMemo(
-    () => getActiveContinuationContext(),
+    () => keyCyclableContinuationContext(getActiveContinuationContext()),
     [scope, mode, tool],
   )
   const selectModeHints = useMemo(() => {
@@ -226,6 +406,7 @@ export function HelperManager() {
       <ContextualHelperPanel
         hints={resolveRotateHandleHelpHints(modifiers.alt)}
         snapContext={snapContext}
+        title={ROTATE_HUD_TITLE}
       />
     )
   }
@@ -238,6 +419,79 @@ export function HelperManager() {
       <ContextualHelperPanel
         hints={[{ keys: ['R / T'], label: 'Rotate the selection ±45°' }]}
         snapContext={snapContext}
+        title={MOVE_SELECTION_HUD_TITLE}
+      />
+    )
+  }
+
+  if (mezzanineHandle) {
+    return (
+      <ContextualHelperPanel
+        hints={MEZZANINE_GESTURE_HINTS[mezzanineHandle]}
+        snapContext={snapContext}
+        title={MEZZANINE_HUD_TITLE}
+      />
+    )
+  }
+
+  // A picked-up room (Move / Duplicate / Rotate from its pill): the same keys
+  // as a group pick-up.
+  if (activeHandleDrag?.label === ROOM_MOVE_DRAG_LABEL) {
+    return (
+      <ContextualHelperPanel
+        hints={[
+          { keys: ['Left click'], label: 'Place' },
+          { keys: [['R', 'T']], label: 'Rotate ±45°' },
+          { keys: ['Alt'], label: 'Free move · slide doors and windows' },
+          { keys: ['Esc'], label: 'Cancel' },
+        ]}
+        snapContext={snapContext}
+        title={MOVE_ROOM_HUD_TITLE}
+      />
+    )
+  }
+  // A paint region gesture holds a handle-drag scope while it draws; its HUD
+  // stays the region one (Backspace / close hints for a polygon mid-draft).
+  if (mode === 'material-paint' && paintRegionDrawing) {
+    return (
+      <ContextualHelperPanel
+        hints={paintRegionHints(paintRegionMode, paintRegionNotice, paintRegionHovering)}
+        snapContext={snapContext}
+        title={paintRegionHudTitle(paintRegionMode)}
+      />
+    )
+  }
+
+  // The terrace tool draws like "Add mezzanine": same outline gestures and chip.
+  if (terraceShape) {
+    return (
+      <ContextualHelperPanel
+        chipHints={TERRACE_CHIP_HINTS}
+        hints={terraceHints(terraceShape)}
+        snapContext={snapContext}
+        title={TERRACE_HUD_TITLE}
+      />
+    )
+  }
+
+  if (openingShape) {
+    return (
+      <ContextualHelperPanel
+        hints={openingHints(openingShape)}
+        snapContext={snapContext}
+        title={OPENING_HUD_TITLE}
+      />
+    )
+  }
+
+  // "Add mezzanine" holds a handle-drag scope on its host room for the whole
+  // tool, so it must win over the generic resize HUD below.
+  if (mezzanineShape) {
+    return (
+      <ContextualHelperPanel
+        hints={mezzanineHints(mezzanineShape)}
+        snapContext={snapContext}
+        title={MEZZANINE_HUD_TITLE}
       />
     )
   }
@@ -254,6 +508,7 @@ export function HelperManager() {
           { keys: ['Esc'], label: 'Cancel' },
         ]}
         snapContext={snapContext}
+        title={RESIZE_HUD_TITLE}
       />
     )
   }
@@ -266,30 +521,54 @@ export function HelperManager() {
     const hints = reshapingNode
       ? nodeRegistry.get(reshapingNode.type)?.affordanceHints?.[scope.reshape]
       : undefined
+    const title = reshapingNode
+      ? nodeKindHudTitle(reshapingNode.type, scope.reshape === 'split' ? 'Split' : 'Edit')
+      : null
     if (hints) {
       return (
-        <RegisteredToolHelper hints={hints} shiftPressed={modifiers.shift} snapContext={snapContext} />
+        <RegisteredToolHelper
+          hints={hints}
+          shiftPressed={modifiers.shift}
+          snapContext={snapContext}
+          title={title}
+        />
       )
     }
-    return <ContextualHelperPanel hints={reshapingHints(scope.reshape)} snapContext={snapContext} />
+    return (
+      <ContextualHelperPanel
+        hints={reshapingHints(scope.reshape)}
+        snapContext={snapContext}
+        title={title}
+      />
+    )
   }
 
   if (movingNode) {
-    if (movingNode.type === 'building') return <BuildingHelper showRotate />
     // A fresh placement (e.g. a positioned preset like a shelf) advertises its
     // once/repeat continuation, exactly like the GLB item tool — but an existing
     // node being *moved* is not a placement, so it gets no continuation chip.
-    const movingContinuationContext = isFreshPlacementMetadata(movingNode.metadata)
-      ? continuationContextOf(movingNode.type)
+    const isFreshPlacement = isFreshPlacementMetadata(movingNode.metadata)
+    const movingTitle = nodeKindHudTitle(movingNode.type, isFreshPlacement ? undefined : 'Move')
+    if (movingNode.type === 'building') return <BuildingHelper showRotate title={movingTitle} />
+    const movingContinuationContext = isFreshPlacement
+      ? keyCyclableContinuationContext(continuationContextOf(movingNode.type))
       : null
-    const collisionValidatesDrop =
-      nodeRegistry.get(movingNode.type)?.capabilities.floorPlaced?.collides === true
+    const collisionValidatesDrop = floorPlacedCollides(
+      nodeRegistry.get(movingNode.type)?.capabilities.floorPlaced,
+      movingNode,
+    )
     return (
       <ItemHelper
         continuationContext={movingContinuationContext}
+        notice={placementNotice?.line}
         showEsc
+        extraHints={movingNode.type === 'window' ? cornerHintRows(cornerHint) : []}
+        replacesPlace={
+          movingNode.type === 'window' && (cornerHint === 'join' || cornerHint === 'new')
+        }
         showForce={collisionValidatesDrop}
         snapContext={snapContext}
+        title={movingTitle}
       />
     )
   }
@@ -298,7 +577,19 @@ export function HelperManager() {
   // only contextual control here. The chip hides itself for targets that only
   // paint one surface, so this renders nothing until a scoped target is active.
   if (mode === 'material-paint') {
-    return <ContextualHelperPanel hints={[]} showPaintScope />
+    return (
+      <ContextualHelperPanel
+        hints={paintHints(paintRegionMode)}
+        showPaintScope
+        title={
+          paintRegionMode === 'pick'
+            ? PICK_MATERIAL_HUD_TITLE
+            : paintRegionMode === 'erase'
+              ? ERASE_HUD_TITLE
+              : PAINT_HUD_TITLE
+        }
+      />
+    )
   }
 
   // Sculpt mode. The HUD is what makes a sustained brush mode legible: it names
@@ -307,18 +598,41 @@ export function HelperManager() {
   // mode-specific — bracket resize, and an Esc that abandons the stroke rather
   // than exiting the mode.
   if (mode === 'terrain-sculpt') {
-    return <ContextualHelperPanel hints={terrainSculptHints(terrainVerb, terrainSampling)} />
+    return (
+      <ContextualHelperPanel
+        hints={terrainSculptHints(terrainVerb, terrainSampling)}
+        title={terrainHudTitle(terrainVerb)}
+      />
+    )
   }
 
   if (scope.kind === 'mesh-editing') {
-    return <ContextualHelperPanel hints={contextualEditHints} snapContext={snapContext} />
+    return (
+      <ContextualHelperPanel
+        hints={contextualEditHints}
+        snapContext={snapContext}
+        title={contextualHelpNode ? nodeKindHudTitle(contextualHelpNode.type, 'Edit') : null}
+      />
+    )
   }
 
 
+  // Divide draws a separator path across the selected room — it reads as a
+  // wall draft: the wall's snapping chips (Shift / Ctrl) plus the path keys.
+  if (scope.kind === 'room-divide') {
+    return (
+      <ContextualHelperPanel
+        hints={ROOM_DIVIDE_HINTS}
+        snapContext={snapContext}
+        title={DIVIDE_ROOM_HUD_TITLE}
+      />
+    )
+  }
+
   // Idle select only — an active scope (handle-drag, box-select, …) must not show
   // the idle selection hints.
   if (mode === 'select' && scope.kind === 'idle') {
-    return <ContextualHelperPanel hints={selectModeHints} />
+    return <ContextualHelperPanel hints={selectModeHints} title={SELECT_HUD_TITLE} />
   }
 
   if (tool === 'measurement' && measurementToolKind === 'smart') {
@@ -329,6 +643,7 @@ export function HelperManager() {
           { keys: ['Click'], label: 'Pin measurement lens' },
           { keys: ['Esc'], label: 'Exit smart measure' },
         ]}
+        title={SMART_MEASURE_HUD_TITLE}
       />
     )
   }
@@ -346,8 +661,10 @@ export function HelperManager() {
         <RegisteredToolHelper
           continuationContext={continuationContext}
           hints={hints}
+          notice={placementNotice?.line ?? null}
           shiftPressed={modifiers.shift}
           snapContext={snapContext}
+          title={toolHudTitle(tool, wallMode)}
         />
       )
     }

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

@@ -1,4 +1,5 @@
 import type { ContinuationContext } from '../../../lib/continuation'
+import type { HudTitle } from '../../../lib/hud-title'
 import type { SnapContext } from '../../../lib/snapping-mode'
 import { ContextualHelperPanel } from './contextual-helper-panel'
 
@@ -11,6 +12,13 @@ interface ItemHelperProps {
   // Set for a fresh point-kind placement (e.g. a positioned preset) so the
   // once/repeat continuation chip shows; null for an existing-node move.
   continuationContext?: ContinuationContext | null
+  title?: HudTitle | null
+  // Why the item would not fit where it is (a door's way, a room too small): a warning, not a block.
+  notice?: string | null
+  // Rows a kind adds while it is in hand (a window near a corner says what dropping it does).
+  extraHints?: { keys: string[]; label: string }[]
+  // The extra rows say what a click does, so the plain Place row is left out.
+  replacesPlace?: boolean
 }
 
 // Snapping mode is the chip on the right (Shift cycles it), so it's not repeated
@@ -20,17 +28,25 @@ export function ItemHelper({
   snapContext,
   showForce,
   continuationContext = null,
+  title = null,
+  notice = null,
+  extraHints = [],
+  replacesPlace = false,
 }: ItemHelperProps) {
   return (
     <ContextualHelperPanel
       continuationContext={continuationContext}
+      notice={notice}
       hints={[
-        { keys: ['Left click'], label: 'Place' },
+        // Where a click does something else (joining a corner), that row says so instead.
+        ...(replacesPlace ? [] : [{ keys: ['Left click'], label: 'Place' }]),
+        ...extraHints,
         { keys: ['R', 'T'], label: 'Rotate' },
         ...(showForce ? [{ keys: ['Alt'], label: 'Force place' }] : []),
         { keys: [showEsc ? 'Esc' : 'Right click'], label: 'Cancel' },
       ]}
       snapContext={snapContext}
+      title={title}
     />
   )
 }

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

@@ -1,5 +1,6 @@
 import type { ToolHint } from '@pascal-app/core'
 import type { ContinuationContext } from '../../../lib/continuation'
+import type { HudTitle } from '../../../lib/hud-title'
 import type { SnapContext } from '../../../lib/snapping-mode'
 import { useVisibleToolHints } from '../../../lib/panel-tool-options'
 import { ContextualHelperPanel } from './contextual-helper-panel'
@@ -18,14 +19,18 @@ export function RegisteredToolHelper({
   shiftPressed = false,
   snapContext = null,
   continuationContext = null,
+  title = null,
+  notice = null,
 }: {
   hints: ToolHint[]
   shiftPressed?: boolean
   snapContext?: SnapContext | null
   continuationContext?: ContinuationContext | null
+  title?: HudTitle | null
+  notice?: string | null
 }) {
   const visible = useVisibleToolHints(hints)
-  if (visible.length === 0 && !snapContext && !continuationContext) return null
+  if (visible.length === 0 && !snapContext && !continuationContext && !notice) return null
   // Hints carrying a live-state `chip` render as mode chips next to the
   // snapping / continuation rows; the rest stay static key rows.
   const chipHints = visible.filter((hint) => hint.chip)
@@ -44,7 +49,9 @@ export function RegisteredToolHelper({
         }
       })}
       continuationContext={continuationContext}
+      notice={notice}
       snapContext={snapContext}
+      title={title}
     />
   )
 }

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

@@ -3,6 +3,50 @@
 import { Icon } from '@iconify/react'
 import type { IconRef } from '@pascal-app/core'
 import { type ComponentType, lazy, Suspense } from 'react'
+import { cn } from '../../lib/utils'
+
+const SVG_DATA_URI = /^data:image\/svg\+xml[^,]*,/
+
+/** Whether a `data:image/svg+xml` URI's markup paints with `currentColor`. */
+function isCurrentColorSvg(src: string): boolean {
+  const head = SVG_DATA_URI.exec(src)
+  if (!head) return false
+  const body = src.slice(head[0].length)
+  try {
+    const markup = head[0].includes(';base64') ? atob(body) : decodeURIComponent(body)
+    return markup.includes('currentColor')
+  } catch {
+    return false
+  }
+}
+
+/**
+ * A `url`-kind icon. An SVG behind an `<img>` renders in its own document, so
+ * `currentColor` in the markup resolves to black rather than the surrounding
+ * text colour — a monochrome plugin glyph then disappears against the dark
+ * sidebar. Such an SVG becomes a CSS mask over the text colour instead. Plugin
+ * manifests are third-party, so the markup is never inlined into the page.
+ */
+export function IconRefImage({
+  className,
+  size,
+  src,
+}: {
+  className?: string
+  size?: number
+  src: string
+}) {
+  const style = size === undefined ? undefined : { height: size, width: size }
+  if (!isCurrentColorSvg(src)) return <img alt="" className={className} src={src} style={style} />
+  const mask = `url("${src.replace(/["\\\n\r]/g, encodeURIComponent)}") center / contain no-repeat`
+  return (
+    <span
+      aria-hidden
+      className={cn('inline-block bg-current', className)}
+      style={{ ...style, mask, WebkitMask: mask }}
+    />
+  )
+}
 
 // `React.lazy` must be called once per loader so the resolved component keeps
 // a stable identity across renders (otherwise every parent re-render remounts
@@ -26,7 +70,7 @@ function resolveLazyIcon(module: () => Promise<{ default: ComponentType }>): Com
  */
 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} />
+    return <IconRefImage className="shrink-0" size={size} src={icon.src} />
   }
   if (icon.kind === 'iconify') {
     return <Icon height={size} icon={icon.name} width={size} />

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

@@ -2,7 +2,7 @@
 
 import type { LevelNode } from '@pascal-app/core'
 import { useEffect, useState } from 'react'
-import type { LevelDuplicatePreset } from '../../lib/level-duplication'
+import type { LevelDuplicatePreset } from '@pascal-app/core/building'
 import { getLevelDisplayName } from '@pascal-app/core'
 import { cn } from '../../lib/utils'
 import {

package/src/components/ui/node-icon-image.tsx

@@ -0,0 +1,16 @@
+'use client'
+
+import { ARTIFACT_URL_PREFIX, resolveArtifactUrl } from '@pascal-app/core'
+import Image, { type ImageProps } from 'next/image'
+
+/**
+ * A node's icon or thumbnail. A scripted object's thumbnail is an
+ * `artifact://` image: it resolves through the project's artifact store and
+ * skips image optimization, whose server-side fetch has no session to read a
+ * private project's artifact with.
+ */
+export function NodeIconImage({ src, ...props }: Omit<ImageProps, 'src'> & { src: string }) {
+  if (!src.startsWith(ARTIFACT_URL_PREFIX)) return <Image src={src} {...props} />
+  const url = resolveArtifactUrl(src)
+  return url ? <Image src={url} unoptimized {...props} /> : null
+}