@pascal-app/editor 1.0.1 → 1.0.4

package/src/lib/orbit-floor-clearance.test.ts

@@ -0,0 +1,165 @@
+import { expect, test } from 'bun:test'
+import {
+  floorLimitAt,
+  glideFloorLimit,
+  LOOK_UP_PITCH_GAIN,
+  LOOK_UP_PUSH_HALF_ANGLE,
+  MAX_ORBIT_POLAR_ANGLE,
+  ORBIT_FLOOR_CLEARANCE,
+  ORBIT_TARGET_HEIGHT,
+  orbitAngleBelowFloor,
+  orbitCameraAboveFloor,
+} from './orbit-floor-clearance'
+
+type Vec3 = { x: number; y: number; z: number }
+
+const FLOOR_Y = 3
+const MIN_Y = FLOOR_Y + ORBIT_FLOOR_CLEARANCE
+const target: Vec3 = { x: 1, y: FLOOR_Y, z: -2 }
+
+// camera-controls' orbit: polar 0 looks straight down, PI/2 is level with the target.
+function orbit(distance: number, polar: number, azimuth = 0.4): Vec3 {
+  return {
+    x: target.x + distance * Math.sin(polar) * Math.sin(azimuth),
+    y: target.y + distance * Math.cos(polar),
+    z: target.z + distance * Math.sin(polar) * Math.cos(azimuth),
+  }
+}
+
+function present(position: Vec3) {
+  const out = { x: Number.NaN, y: Number.NaN, z: Number.NaN }
+  const polar = orbitCameraAboveFloor(out, position, target, MIN_Y)
+  return { grounded: out.y === MIN_Y && position.y < MIN_Y, out, polar }
+}
+
+const horizontalDistance = (p: Vec3) => Math.hypot(p.x - target.x, p.z - target.z)
+const DEGREE = Math.PI / 180
+
+test('an orbit above the clearance is drawn exactly where it is', () => {
+  const position = orbit(10, Math.PI / 3)
+  const { grounded, out, polar } = present(position)
+  expect(grounded).toBe(false)
+  expect(out).toEqual(position)
+  expect(polar).toBeCloseTo(Math.PI / 3, 9)
+})
+
+test('tilting past the horizon keeps the camera on the floor clearance', () => {
+  for (const distance of [2, 8, 40]) {
+    for (const polar of [Math.PI / 2, 0.6 * Math.PI, 0.75 * Math.PI, Math.PI - 0.05]) {
+      const position = orbit(distance, polar)
+      const { grounded, out } = present(position)
+      expect(grounded).toBe(true)
+      expect(out.y).toBeCloseTo(MIN_Y, 9)
+    }
+  }
+})
+
+test('past the clearance the view pitches up faster than the drag and stops at straight up', () => {
+  for (const distance of [2.2, 8, 40]) {
+    const contactPolar = Math.acos(ORBIT_FLOOR_CLEARANCE / distance)
+    for (let past = 0; past <= 60 * DEGREE; past += DEGREE) {
+      const { polar } = present(orbit(distance, contactPolar + past))
+      expect(polar).toBeCloseTo(
+        Math.min(contactPolar + past * LOOK_UP_PITCH_GAIN, MAX_ORBIT_POLAR_ANGLE),
+        9,
+      )
+    }
+    // From level to (almost) straight up within ~40° of drag.
+    const straightUp = (MAX_ORBIT_POLAR_ANGLE - contactPolar) / LOOK_UP_PITCH_GAIN
+    expect(straightUp).toBeLessThan(95 * DEGREE)
+    // And stops there: more drag changes nothing.
+    const atTop = present(orbit(distance, contactPolar + straightUp))
+    const beyond = present(orbit(distance, contactPolar + straightUp + 5 * DEGREE))
+    expect(beyond.polar).toBeCloseTo(MAX_ORBIT_POLAR_ANGLE, 9)
+    expect(horizontalDistance(beyond.out)).toBeCloseTo(horizontalDistance(atTop.out), 9)
+  }
+})
+
+test('past the clearance the camera closes on its target gently, at the half-angle rate', () => {
+  for (const distance of [2.2, 8, 40]) {
+    const contactPolar = Math.acos(ORBIT_FLOOR_CLEARANCE / distance)
+    const contactReach = horizontalDistance(present(orbit(distance, contactPolar)).out)
+    let previous = contactReach
+    const straightUp = (MAX_ORBIT_POLAR_ANGLE - contactPolar) / LOOK_UP_PITCH_GAIN
+    for (let polar = contactPolar + 0.01; polar <= contactPolar + straightUp; polar += 0.01) {
+      const position = orbit(distance, polar)
+      expect(orbitAngleBelowFloor(position, target, MIN_Y)).toBeCloseTo(polar - contactPolar, 9)
+      const reach = horizontalDistance(present(position).out)
+      expect(reach).toBeCloseTo(
+        contactReach * 0.5 ** ((polar - contactPolar) / LOOK_UP_PUSH_HALF_ANGLE),
+        9,
+      )
+      expect(reach).toBeLessThan(previous)
+      previous = reach
+    }
+    // By the time the view looks straight up it has closed at most ~25% of the way.
+    const there = horizontalDistance(present(orbit(distance, contactPolar + straightUp)).out)
+    expect(1 - there / contactReach).toBeLessThan(0.75)
+    expect(1 - there / contactReach).toBeGreaterThan(0.35)
+  }
+})
+
+test('crossing the clearance is continuous, so orbiting back up has no jump', () => {
+  const distance = 6
+  // The polar angle at which the orbit itself touches the clearance.
+  const contact = Math.acos(ORBIT_FLOOR_CLEARANCE / distance)
+  const before = present(orbit(distance, contact - 1e-6)).out
+  const after = present(orbit(distance, contact + 1e-6)).out
+  expect(Math.hypot(after.x - before.x, after.y - before.y, after.z - before.z)).toBeLessThan(1e-4)
+})
+
+test('zooming in while grounded still moves the camera toward the target', () => {
+  const polar = 0.8 * Math.PI
+  let previous = Number.POSITIVE_INFINITY
+  for (let distance = 40; distance >= 2; distance -= 2) {
+    const reach = horizontalDistance(present(orbit(distance, polar)).out)
+    expect(reach).toBeLessThan(previous)
+    previous = reach
+  }
+})
+
+test('with the pivot at standing height, a close orbit looks around before the floor stops it', () => {
+  const pivot = { x: 0, y: FLOOR_Y + ORBIT_TARGET_HEIGHT, z: 0 }
+  const distance = 2
+  const at = (polar: number) => ({
+    x: distance * Math.sin(polar),
+    y: pivot.y + distance * Math.cos(polar),
+    z: 0,
+  })
+  // Level with the pivot and a little past it: a free orbit at about eye
+  // height, already looking up, nothing pushed.
+  for (const polar of [Math.PI / 2, 100 * DEGREE, 105 * DEGREE]) {
+    const out = { x: 0, y: 0, z: 0 }
+    expect(orbitCameraAboveFloor(out, at(polar), pivot, MIN_Y)).toBeCloseTo(polar, 9)
+    expect(out).toEqual(at(polar))
+  }
+  // The clearance takes over only where the orbit would reach it.
+  const contact = Math.acos((MIN_Y - pivot.y) / distance)
+  expect(contact).toBeGreaterThan(105 * DEGREE)
+  const out = { x: 0, y: 0, z: 0 }
+  orbitCameraAboveFloor(out, at(contact + 5 * DEGREE), pivot, MIN_Y)
+  expect(out.y).toBeCloseTo(MIN_Y, 9)
+})
+
+test('the floor limit sits the clearance above the surface under the camera, or the level floor', () => {
+  // A raised platform 0.45 m above a level at 2.71.
+  expect(floorLimitAt(3.16, 2.71)).toBeCloseTo(3.16 + ORBIT_FLOOR_CLEARANCE, 9)
+  // A sunken floor below the level's own floor.
+  expect(floorLimitAt(2.21, 2.71)).toBeCloseTo(2.21 + ORBIT_FLOOR_CLEARANCE, 9)
+  // Nothing under the camera (outside, no terrain): the level floor, never 0.
+  expect(floorLimitAt(null, 2.71)).toBeCloseTo(2.71 + ORBIT_FLOOR_CLEARANCE, 9)
+  expect(floorLimitAt(null, 0)).toBe(ORBIT_FLOOR_CLEARANCE)
+})
+
+test('a change in floor height is glided over, never popped', () => {
+  expect(glideFloorLimit(null, 1, 1 / 60)).toBe(1)
+  let limit = 0.3
+  let previous = limit
+  for (let frame = 0; frame < 120; frame++) {
+    limit = glideFloorLimit(limit, 0.75, 1 / 60)
+    expect(limit).toBeGreaterThan(previous)
+    expect(limit - previous).toBeLessThan(0.07)
+    previous = limit
+  }
+  expect(limit).toBeCloseTo(0.75, 6)
+})

package/src/lib/orbit-floor-clearance.ts

@@ -0,0 +1,106 @@
+type Vec3 = { x: number; y: number; z: number }
+
+/** The lowest an orbiting camera sits above the active level's floor. */
+export const ORBIT_FLOOR_CLEARANCE = 0.45
+
+/**
+ * How high above the active level's floor the orbit's pivot rests when the
+ * editor aims it at the ground (level switch, panning, framing, focusing a
+ * floor or room): about standing eye height, so zoomed all the way in the
+ * camera looks around the room the way a walkthrough does.
+ */
+export const ORBIT_TARGET_HEIGHT = 1.1
+
+const DEGREE = Math.PI / 180
+
+/** The steepest an orbit camera looks: straight down is 0, straight up π. */
+export const MAX_ORBIT_POLAR_ANGLE = Math.PI - 0.05
+
+/**
+ * Past the point where the camera reached the floor clearance, the view
+ * pitches up this many times faster than the orbit drag: about 80° more drag
+ * takes it from level to straight up.
+ */
+export const LOOK_UP_PITCH_GAIN = 1.1
+
+/**
+ * The look-up push: every this many degrees of drag past the clearance, the
+ * camera's horizontal distance to its target halves. Over the ~80° it takes
+ * to look straight up, the camera closes about two thirds of the way in.
+ */
+export const LOOK_UP_PUSH_HALF_ANGLE = 55 * DEGREE
+
+/**
+ * How far the orbit has tilted past the point where its camera reaches
+ * `minY` (radians, negative while it is still above). Zero exactly when the
+ * orbit camera sits at `minY`.
+ */
+export function orbitAngleBelowFloor(position: Vec3, target: Vec3, minY: number): number {
+  const horizontal = Math.hypot(position.x - target.x, position.z - target.z)
+  const height = position.y - target.y
+  const distance = Math.hypot(horizontal, height)
+  if (distance < 1e-9) return 0
+  const polar = Math.atan2(horizontal, height)
+  const contactPolar = Math.acos(Math.max(-1, Math.min(1, (minY - target.y) / distance)))
+  return polar - contactPolar
+}
+
+/**
+ * Where to draw an orbit camera so it never drops below `minY`. Above it the
+ * orbit pose stands. An orbit that would take it lower keeps the camera on
+ * `minY`, pitches the view up `LOOK_UP_PITCH_GAIN` times faster than the
+ * drag (stopping at straight up), and pushes the camera gently toward its
+ * target at the `LOOK_UP_PUSH_HALF_ANGLE` rate. A pure function of the orbit
+ * state, so orbiting back up returns the exact orbit pose.
+ *
+ * Writes the drawn position into `out` and returns the drawn polar angle.
+ */
+export function orbitCameraAboveFloor(
+  out: Vec3,
+  position: Vec3,
+  target: Vec3,
+  minY: number,
+): number {
+  const dx = position.x - target.x
+  const dz = position.z - target.z
+  const horizontal = Math.hypot(dx, dz)
+  const height = position.y - target.y
+  if (!(position.y < minY)) {
+    out.x = position.x
+    out.y = position.y
+    out.z = position.z
+    return Math.atan2(horizontal, height)
+  }
+
+  const rise = minY - target.y
+  const distance = Math.hypot(horizontal, height)
+  const contactRadius = Math.sqrt(Math.max(0, distance * distance - rise * rise))
+  const below = Math.max(0, orbitAngleBelowFloor(position, target, minY))
+  const contactPolar = Math.atan2(horizontal, height) - below
+  // Nothing moves once the view looks straight up.
+  const pastContact = Math.min(below, (MAX_ORBIT_POLAR_ANGLE - contactPolar) / LOOK_UP_PITCH_GAIN)
+  const reach = contactRadius * 0.5 ** (pastContact / LOOK_UP_PUSH_HALF_ANGLE)
+  const scale = horizontal > 1e-9 ? reach / horizontal : 0
+  out.x = target.x + dx * scale
+  out.y = minY
+  out.z = target.z + dz * scale
+  return contactPolar + pastContact * LOOK_UP_PITCH_GAIN
+}
+
+// How quickly the floor limit follows a change in the floor under the camera
+// (stepping over a raised platform's edge): about this many seconds per e-fold.
+const FLOOR_GLIDE_SECONDS = 0.12
+
+/**
+ * The lowest the camera may sit: the clearance above the floor surface under
+ * it, or above the level's own floor when there is none (outside, no terrain).
+ */
+export function floorLimitAt(surfaceTop: number | null, levelFloorY: number): number {
+  return (surfaceTop ?? levelFloorY) + ORBIT_FLOOR_CLEARANCE
+}
+
+/** Eases a floor limit toward `target` over `delta` seconds, so it never pops. */
+export function glideFloorLimit(current: number | null, target: number, delta: number): number {
+  if (current === null || !(delta > 0)) return current ?? target
+  return target + (current - target) * Math.exp(-delta / FLOOR_GLIDE_SECONDS)
+}

package/src/lib/overlay-transform.test.ts

@@ -0,0 +1,28 @@
+import { test } from 'bun:test'
+import assert from 'node:assert/strict'
+import { Group } from 'three'
+import { copyOverlayWorldTransform } from './overlay-transform'
+
+test('opening overlays retain the source transform through God-mode zoom and rotation', () => {
+  const model = new Group()
+  const wall = new Group()
+  const opening = new Group()
+  model.add(wall)
+  wall.add(opening)
+  wall.rotation.y = 0.8
+  opening.position.set(2, 1.5, 0.1)
+  const portal = new Group()
+  portal.position.set(4, 1, -2)
+  portal.rotation.y = -0.4
+  const overlay = new Group()
+  portal.add(overlay)
+  for (const scale of [0.01, 0.2, 1, 4, 0.05]) {
+    model.scale.set(scale, scale * 2, scale)
+    model.rotation.y += 0.2
+    copyOverlayWorldTransform(opening, overlay)
+    overlay.updateWorldMatrix(true, false)
+    overlay.matrixWorld.elements.forEach((value, i) => {
+      assert.ok(Math.abs(value - opening.matrixWorld.elements[i]!) < 1e-8)
+    })
+  }
+})

package/src/lib/overlay-transform.ts

@@ -0,0 +1,12 @@
+import type { Object3D } from 'three'
+
+/** Preserve scale and shear when an overlay is portalled outside its source hierarchy. */
+export function copyOverlayWorldTransform(source: Object3D, overlay: Object3D) {
+  source.updateWorldMatrix(true, false)
+  overlay.parent?.updateWorldMatrix(true, false)
+  overlay.matrixAutoUpdate = false
+  if (overlay.parent)
+    overlay.matrix.copy(overlay.parent.matrixWorld).invert().multiply(source.matrixWorld)
+  else overlay.matrix.copy(source.matrixWorld)
+  overlay.matrixWorldNeedsUpdate = true
+}

package/src/lib/paint-commit-route.test.ts

@@ -0,0 +1,37 @@
+import { expect, test } from 'bun:test'
+import { paintCommitRoute } from './paint-commit-route'
+
+test('only the hovered surface itself keeps the kind commit', () => {
+  expect(paintCommitRoute([], 'wall_a', 'a')).toBe('own')
+  expect(paintCommitRoute([{ nodeId: 'wall_a', role: 'a' }], 'wall_a', 'a')).toBe('own')
+  // A one-wall room: one target, but on the room role.
+  expect(paintCommitRoute([{ nodeId: 'wall_a', role: 'room:zone_1' }], 'wall_a', 'a')).toBe(
+    'fanout',
+  )
+  expect(paintCommitRoute([{ nodeId: 'wall_b', role: 'a' }], 'wall_a', 'a')).toBe('fanout')
+  expect(
+    paintCommitRoute(
+      [
+        { nodeId: 'wall_a', role: 'a' },
+        { nodeId: 'wall_b', role: 'a' },
+      ],
+      'wall_a',
+      'a',
+    ),
+  ).toBe('fanout')
+})
+
+for (const role of ['step:zone_upper', 'edge:zone_upper'])
+  test(`${role} retains the room side role through paint routing`, () => {
+    expect(paintCommitRoute([{ nodeId: 'slab_platform', role }], 'slab_platform', role)).toBe('own')
+    expect(
+      paintCommitRoute(
+        [
+          { nodeId: 'slab_platform', role },
+          { nodeId: 'slab_component', role },
+        ],
+        'slab_platform',
+        role,
+      ),
+    ).toBe('fanout')
+  })

package/src/lib/paint-commit-route.ts

@@ -0,0 +1,17 @@
+/**
+ * How a paint click commits its resolved spread. Only a spread that is exactly
+ * the hovered surface keeps the kind's own commit; anything else — several
+ * targets, or one target on another role such as a whole room's
+ * `room:<zoneId>` role — goes through the fan-out, which routes each role to
+ * the kind that owns it. A one-wall room therefore needs no second target to
+ * reach its room role.
+ */
+export function paintCommitRoute(
+  targets: ReadonlyArray<{ nodeId: string; role: string }>,
+  nodeId: string,
+  role: string,
+): 'own' | 'fanout' {
+  if (targets.length === 0) return 'own'
+  const [only] = targets
+  return targets.length === 1 && only!.nodeId === nodeId && only!.role === role ? 'own' : 'fanout'
+}

package/src/lib/paint-eyedropper.test.tsx

@@ -0,0 +1,165 @@
+import { expect, test } from 'bun:test'
+import {
+  type AnyNode,
+  nodeRegistry,
+  registerNode,
+  SlabNode,
+  useScene,
+  WallNode,
+} from '@pascal-app/core'
+import { useNodeEvents, useViewer } from '@pascal-app/viewer'
+import { _roots, act, events } from '@react-three/fiber'
+import type { OrthographicCamera } from 'three'
+import { z } from 'zod'
+import { SelectionManager, useEditor } from '../index'
+import { withSelectionHarness } from '../test-utils/selection-harness'
+import { resetPaintMode, usePaintRegionMode } from './paint-region-mode'
+
+const picked = { materialPreset: 'library:wall-red', sourceTarget: 'wall' } as const
+
+function Surface({ node }: { node: AnyNode }) {
+  const wall = node.type === 'wall'
+  return (
+    <mesh
+      {...useNodeEvents(node, node.type)}
+      name={node.id}
+      position={wall ? [0, 1.5, 0] : [0, 0, 0]}
+      rotation={wall ? [0, 0, 0] : [-Math.PI / 2, 0, 0]}
+    >
+      <planeGeometry args={wall ? [20, 3] : [20, 20]} />
+      <meshBasicMaterial />
+    </mesh>
+  )
+}
+
+for (const activation of ['icon', 'Alt'] as const) {
+  test(`${activation} eyedrop consumes the front wall click; only the next click paints the slab behind`, async () => {
+    const restoreRegistry = nodeRegistry._snapshot()
+    const previousPaint = usePaintRegionMode.getState()
+    const previousDocument = globalThis.document
+    const previousCancel = globalThis.cancelAnimationFrame
+    globalThis.cancelAnimationFrame = () => {}
+    globalThis.document = { body: { style: { cursor: '' } } } as unknown as Document
+    nodeRegistry._reset()
+    const writes: string[] = []
+    try {
+      for (const kind of ['wall', 'slab']) {
+        registerNode({
+          kind,
+          schemaVersion: 1,
+          schema: z.object({ type: z.literal(kind) }) as never,
+          category: 'structure',
+          defaults: () => ({}),
+          capabilities: {
+            slots: () => [{ slotId: 'default', label: 'Surface' }],
+            paint: {
+              resolveRole: () => 'default',
+              getEffectiveMaterial: () => ({
+                material: undefined,
+                materialPreset: picked.materialPreset,
+              }),
+              buildPatch: ({ materialPreset }) => ({ materialPreset }) as Partial<AnyNode>,
+              commit: ({ node, materialPreset }) => {
+                writes.push(node.id)
+                useScene.getState().updateNode(node.id, { materialPreset } as Partial<AnyNode>)
+              },
+              applyPreview: () => () => {},
+            },
+          },
+        })
+      }
+      await withSelectionHarness(async ({ canvas, render }) => {
+        const wall = WallNode.parse({ id: 'wall_front', start: [-10, 0], end: [10, 0] })
+        const slab = SlabNode.parse({
+          id: 'slab_behind',
+          polygon: [
+            [-10, -10],
+            [10, -10],
+            [10, 10],
+            [-10, 10],
+          ],
+        })
+        useScene.setState({ nodes: { [wall.id]: wall, [slab.id]: slab }, readOnly: false })
+        useViewer.getState().resetSelection()
+        useViewer.setState({ cameraDragging: false, inputDragging: false })
+        resetPaintMode()
+        useEditor.getState().armMaterialPaint(undefined, activation === 'icon' ? 'pick' : 'surface')
+        await render(
+          <>
+            <SelectionManager />
+            <Surface node={wall} />
+            <Surface node={slab} />
+          </>,
+        )
+        if (activation === 'Alt') {
+          await act(async () => {
+            window.dispatchEvent(Object.assign(new Event('keydown'), { key: 'Alt', repeat: false }))
+          })
+        }
+        expect(usePaintRegionMode.getState().mode).toBe('pick')
+        const store = _roots.get(canvas)!.store
+        const state = store.getState()
+        const camera = state.camera as OrthographicCamera
+        Object.assign(camera, { left: -5, right: 5, top: 5, bottom: -5 })
+        camera.position.set(0, 5, 10)
+        camera.up.set(0, 1, 0)
+        camera.lookAt(0, 1, 0)
+        camera.updateProjectionMatrix()
+        camera.updateMatrixWorld(true)
+        state.setEvents(events(store))
+        state.scene.updateMatrixWorld(true)
+        const send = async (type: 'onPointerMove' | 'onPointerDown' | 'onPointerUp') => {
+          await act(async () => {
+            store.getState().events.handlers![type]({
+              offsetX: 500,
+              offsetY: 500,
+              clientX: 500,
+              clientY: 500,
+              button: 0,
+              pointerId: 1,
+              target: canvas,
+              type,
+            } as unknown as PointerEvent)
+          })
+        }
+        // Hover first: sampling synchronously replays this event when it returns to paint.
+        await send('onPointerMove')
+        expect(useViewer.getState().hoveredId).toBe(wall.id)
+        const hits = state.raycaster.intersectObjects(state.internal.interaction, true)
+        expect([...new Set(hits.map((hit) => hit.object.name))]).toEqual([wall.id, slab.id])
+        const before = useScene.getState().nodes
+        await send('onPointerDown')
+        await send('onPointerUp')
+        expect(useEditor.getState().activePaintMaterial).toEqual(picked)
+        expect(usePaintRegionMode.getState().mode).toBe('surface')
+        expect(writes).toEqual([])
+        expect(useScene.getState().nodes).toBe(before)
+        if (activation === 'Alt') {
+          await act(async () =>
+            window.dispatchEvent(Object.assign(new Event('keyup'), { key: 'Alt' })),
+          )
+        }
+        // Expose the slab at the same cursor, then prove the next gesture paints once.
+        await render(
+          <>
+            <SelectionManager />
+            <Surface node={slab} />
+          </>,
+        )
+        state.scene.updateMatrixWorld(true)
+        await send('onPointerMove')
+        await send('onPointerDown')
+        await send('onPointerUp')
+        expect(writes).toEqual([slab.id])
+        expect((useScene.getState().nodes[slab.id] as SlabNode).materialPreset).toBe(
+          picked.materialPreset,
+        )
+      })
+    } finally {
+      restoreRegistry()
+      usePaintRegionMode.setState(previousPaint)
+      globalThis.document = previousDocument
+      globalThis.cancelAnimationFrame = previousCancel
+    }
+  })
+}

package/src/lib/paint-eyedropper.ts

@@ -0,0 +1,99 @@
+import {
+  type AnyNode,
+  type AnyNodeId,
+  type MaterialSchema,
+  nodeRegistry,
+  type SceneMaterial,
+  type SceneMaterialId,
+  slotDefaultPaintMaterial,
+} from '@pascal-app/core'
+import type { Material, Object3D } from 'three'
+import {
+  type ActivePaintMaterial,
+  hasActivePaintMaterial,
+  type PaintableMaterialTarget,
+  resolveActivePaintMaterialFromSelection,
+} from './material-paint'
+
+type RenderedMaterial = Material & {
+  color?: { getHexString: () => string }
+  roughness?: number
+  metalness?: number
+}
+
+/** The drawn material of a mesh hit, for a slot that carries no finish of its own (an item's GLB). */
+function drawnMaterial(hitObject: Object3D | undefined, materialIndex: number | null) {
+  const material = (hitObject as { material?: Material | Material[] } | undefined)?.material
+  const drawn = (Array.isArray(material) ? material[materialIndex ?? 0] : material) as
+    | RenderedMaterial
+    | undefined
+  if (!drawn?.color) return null
+  return {
+    preset: 'custom',
+    properties: {
+      color: `#${drawn.color.getHexString()}`,
+      roughness: drawn.roughness ?? 0.5,
+      metalness: drawn.metalness ?? 0,
+      opacity: drawn.opacity ?? 1,
+      transparent: drawn.transparent ?? false,
+      side: 'front',
+    },
+  } satisfies MaterialSchema
+}
+
+/**
+ * The material the eyedropper takes from `role` of `node`: what the surface
+ * shows, read through the paint path — the kind's `getEffectiveMaterial` (the
+ * finish a room, region or override gives it, with derived roles falling to
+ * what they draw), the legacy per-kind arms, then the slot's declared default
+ * (`node.slots[slot]` → `default`, the renderer's own chain). A slot with none
+ * of those (an item's GLB material) is read off the drawn mesh.
+ */
+export function eyedropperMaterial(args: {
+  node: AnyNode
+  role: string
+  nodes: Record<string, AnyNode>
+  materials?: Record<SceneMaterialId, SceneMaterial>
+  hitObject?: Object3D
+  materialIndex?: number | null
+}): ActivePaintMaterial | null {
+  const { node, role, nodes } = args
+  const definition = nodeRegistry.get(node.type)
+  const paint = definition?.capabilities?.paint
+  const sourceTarget = (paint?.materialTarget ?? node.type) as PaintableMaterialTarget
+  const valid = (value: { material?: MaterialSchema; materialPreset?: string } | null) =>
+    value && hasActivePaintMaterial({ ...value, sourceTarget })
+      ? { material: value.material, materialPreset: value.materialPreset, sourceTarget }
+      : null
+
+  const effective =
+    valid(
+      paint?.getEffectiveMaterial?.({
+        node,
+        role,
+        nodes: nodes as Record<AnyNodeId, AnyNode>,
+        rendered: true,
+        materials: args.materials,
+      }) ?? null,
+    ) ??
+    resolveActivePaintMaterialFromSelection({
+      nodes,
+      selectedId: node.id,
+      materials: args.materials,
+      selectedMaterialTarget: { nodeId: node.id, role },
+    })
+  if (effective) return effective
+
+  const declared = definition?.capabilities?.slots?.(node).find((slot) => slot.slotId === role)
+  const fallback = valid(slotDefaultPaintMaterial(declared?.default))
+  if (fallback) return fallback
+
+  const drawn = drawnMaterial(args.hitObject, args.materialIndex ?? null)
+  return drawn ? { material: drawn, sourceTarget } : null
+}
+
+/** A stable key for a picked material, so an unchanged pick is not re-announced. */
+export function paintMaterialKey(material: ActivePaintMaterial | null): string {
+  if (!material) return ''
+  return material.materialPreset ?? JSON.stringify(material.material ?? null)
+}