@pascal-app/editor 1.0.1 → 1.0.4

package/src/lib/wall-region-snap.ts

@@ -0,0 +1,110 @@
+import type { AnyNode, WallFace, WallNode } from '@pascal-app/core'
+import { getWallFaceBaseAt } from '@pascal-app/viewer'
+
+// Snapping for the paint tool's wall region gestures, in face coordinates:
+// `u` is metres from the wall start along the reference line (the chord on a
+// curved wall), `v` metres above the face's own base. Modes mirror the 'polygon'
+// snap context: `grid` rounds to the grid step, `lines` catches the face's own
+// features within a tolerance, `off` (or Alt held) leaves the pointer raw.
+
+export type WallRegionSnapMode = 'grid' | 'lines' | 'off'
+
+export type WallRegionSnap = {
+  mode: WallRegionSnapMode
+  /** Grid step (m) used by `grid`. */
+  gridStep: number
+  /** Catch distance (m) used by `lines`. */
+  tolerance: number
+}
+
+/** One face's base runs, as `getWallFinishData(geometry).faceBase[face]` carries them. */
+export type WallFaceBaseRuns = readonly { start: number; end: number; y: number }[] | null
+
+export type WallRegionSnapTargets = { u: number[]; v: number[] }
+
+/** The wainscot height a Horizontal region starts at. */
+export const DEFAULT_WAINSCOT_HEIGHT = 0.9
+/** Regions narrower or shorter than this are a slip, not a gesture. */
+export const MIN_WALL_REGION_SIZE = 0.02
+export const DEFAULT_LINE_SNAP_TOLERANCE = 0.1
+
+export function resolveWallRegionSnapMode(flags: {
+  grid: boolean
+  magnetic: boolean
+  alt?: boolean
+}): WallRegionSnapMode {
+  if (flags.alt) return 'off'
+  if (flags.grid) return 'grid'
+  if (flags.magnetic) return 'lines'
+  return 'off'
+}
+
+/** Base (local y) of a face at station `u`: 0 when the faces share the wall base. */
+export function faceBaseAt(runs: WallFaceBaseRuns, u: number): number {
+  return runs?.length ? getWallFaceBaseAt({ faceBase: { a: [...runs], b: [] } }, 'a', u) : 0
+}
+
+function uniqueSorted(values: number[]): number[] {
+  const out: number[] = []
+  for (const value of values.filter(Number.isFinite).sort((a, b) => a - b))
+    if (out.length === 0 || value - out.at(-1)! > 1e-6) out.push(value)
+  return out
+}
+
+/**
+ * What a region on this face snaps to: the wall ends, openings' jambs, sills
+ * and heads, other regions' bounds on the same face, the face base and the
+ * wainscot height. Opening heights are local y, so each is measured above the
+ * face base under the opening's centre.
+ */
+export function wallRegionSnapTargets(
+  wall: Pick<WallNode, 'start' | 'end' | 'children' | 'faceRegions'>,
+  face: WallFace,
+  nodes: Readonly<Record<string, AnyNode | undefined>>,
+  runs: WallFaceBaseRuns = null,
+  options: { excludeRegionId?: string } = {},
+): WallRegionSnapTargets {
+  const length = Math.hypot(wall.end[0] - wall.start[0], wall.end[1] - wall.start[1])
+  const u = [0, length]
+  const v = [0, DEFAULT_WAINSCOT_HEIGHT]
+  for (const childId of wall.children ?? []) {
+    const child = nodes[childId]
+    if (child?.type !== 'door' && child?.type !== 'window') continue
+    const [x, y] = child.position
+    u.push(x - child.width / 2, x + child.width / 2)
+    const base = faceBaseAt(runs, x)
+    v.push(y - child.height / 2 - base, y + child.height / 2 - base)
+  }
+  for (const region of wall.faceRegions ?? []) {
+    if (region.face !== face || region.id === options.excludeRegionId) continue
+    for (const bound of [region.u0, region.u1]) if (bound !== undefined) u.push(bound)
+    for (const bound of [region.v0, region.v1]) if (bound !== undefined) v.push(bound)
+  }
+  return {
+    u: uniqueSorted(u.filter((value) => value >= -1e-6 && value <= length + 1e-6)),
+    v: uniqueSorted(v.filter((value) => value >= -1e-6)),
+  }
+}
+
+/** Snaps one face coordinate. `target` is the feature it caught in `lines` mode. */
+export function snapWallRegionValue(
+  value: number,
+  targets: readonly number[],
+  snap: WallRegionSnap,
+): { value: number; target: number | null } {
+  if (snap.mode === 'grid' && snap.gridStep > 0) {
+    const stepped = Math.round(value / snap.gridStep) * snap.gridStep
+    return { value: Math.round(stepped * 1e6) / 1e6, target: null }
+  }
+  if (snap.mode === 'lines') {
+    let best: number | null = null
+    for (const target of targets)
+      if (
+        Math.abs(target - value) <= snap.tolerance &&
+        (best === null || Math.abs(target - value) < Math.abs(best - value))
+      )
+        best = target
+    if (best !== null) return { value: best, target: best }
+  }
+  return { value, target: null }
+}

package/src/lib/window-interaction.ts

@@ -84,3 +84,17 @@ export function closeWindowOpenState(windowId: AnyNodeId, options?: WindowOpenAn
   const currentOpenAmount = getDisplayedWindowValue(windowId, node.operationState)
   startWindowOpenAnimation(windowId, 'operationState', currentOpenAmount, 0, options)
 }
+
+export function openWindowOpenState(windowId: AnyNodeId, options?: WindowOpenAnimationOptions) {
+  const node = useScene.getState().nodes[windowId]
+  if (
+    node?.type !== 'window' ||
+    node.openingKind === 'opening' ||
+    !isOperableWindowType(node.windowType)
+  ) {
+    return
+  }
+
+  const currentOpenAmount = getDisplayedWindowValue(windowId, node.operationState)
+  startWindowOpenAnimation(windowId, 'operationState', currentOpenAmount, 1, options)
+}

package/src/lib/world-grid-snap.test.ts

@@ -0,0 +1,48 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import { BuildingNode, LevelNode, useScene } from '@pascal-app/core'
+import { useViewer } from '@pascal-app/viewer'
+import { getActiveBuildingId } from './world-grid-snap'
+
+const originalNodes = useScene.getState().nodes
+const originalSelection = useViewer.getState().selection
+
+afterEach(() => {
+  useScene.setState({ nodes: originalNodes } as never)
+  useViewer.setState({ selection: originalSelection } as never)
+})
+
+describe('getActiveBuildingId', () => {
+  test('prefers the active level owner over a stale selected building', () => {
+    const staleBuilding = BuildingNode.parse({})
+    const activeBuilding = BuildingNode.parse({})
+    const level = LevelNode.parse({ parentId: activeBuilding.id })
+    useScene.setState({
+      nodes: {
+        [staleBuilding.id]: staleBuilding,
+        [activeBuilding.id]: activeBuilding,
+        [level.id]: level,
+      },
+    } as never)
+    useViewer.setState({
+      selection: {
+        buildingId: staleBuilding.id,
+        levelId: level.id,
+        zoneId: null,
+        selectedIds: [],
+      },
+    } as never)
+
+    expect(getActiveBuildingId()).toBe(activeBuilding.id)
+  })
+
+  test('resolves legacy level ownership from the building children list', () => {
+    const level = LevelNode.parse({})
+    const building = BuildingNode.parse({ children: [level.id] })
+    useScene.setState({ nodes: { [building.id]: building, [level.id]: level } } as never)
+    useViewer.setState({
+      selection: { buildingId: null, levelId: level.id, zoneId: null, selectedIds: [] },
+    } as never)
+
+    expect(getActiveBuildingId()).toBe(building.id)
+  })
+})

package/src/lib/world-grid-snap.ts

@@ -15,6 +15,7 @@ import {
   type BuildingPose,
   type ResolveAlignmentInBuildingResult,
   resolveAlignmentInBuildingWorld,
+  resolveBuildingForLevel,
   snapWorldXZToBuildingLocal,
   useLiveTransforms,
   useScene,
@@ -39,7 +40,7 @@ import { useViewer } from '@pascal-app/viewer'
  * guides drift off the visible grid mid-drag (and through any post-drag
  * frame where the live override is still set).
  */
-export function getActiveBuildingPose(): BuildingPose | null {
+export function getActiveBuildingId(): AnyNodeId | null {
   const sel = useViewer.getState().selection
   const nodes = useScene.getState().nodes
   // Match `use-floorplan-scene-data.ts`: prefer the active level's
@@ -48,12 +49,15 @@ export function getActiveBuildingPose(): BuildingPose | null {
   // different level, the level path is the authoritative one.
   let buildingId: AnyNodeId | null = null
   if (sel.levelId) {
-    const level = nodes[sel.levelId]
-    if (level && level.type === 'level' && level.parentId) {
-      buildingId = level.parentId as AnyNodeId
-    }
+    buildingId = resolveBuildingForLevel(sel.levelId as AnyNodeId, nodes)
   }
   if (!buildingId) buildingId = sel.buildingId ?? null
+  return buildingId
+}
+
+export function getActiveBuildingPose(): BuildingPose | null {
+  const buildingId = getActiveBuildingId()
+  const nodes = useScene.getState().nodes
   const building = buildingId ? nodes[buildingId] : null
   if (building?.type !== 'building') return null
   const live = useLiveTransforms.getState().transforms.get(buildingId as string)

package/src/lib/zone-content.ts

@@ -50,7 +50,10 @@ function polygonContainsWithTolerance(
   })
 }
 
-function polygonMatchesZoneFootprint(surfacePolygon: Point2D[], footprint: Point2D[]): boolean {
+export function polygonMatchesZoneFootprint(
+  surfacePolygon: Point2D[],
+  footprint: Point2D[],
+): boolean {
   if (surfacePolygon.length < 3) return false
   return (
     polygonContainsWithTolerance(footprint, surfacePolygon, SURFACE_POLYGON_TOLERANCE) &&

package/src/lib/zone-name.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, test } from 'bun:test'
+import type { AnyNode } from '@pascal-app/core'
+import { nextZoneName } from './zone-name'
+
+const zone = (id: string, name?: string) => ({ id, type: 'zone', name }) as unknown as AnyNode
+
+describe('nextZoneName', () => {
+  test('room zones do not consume zone numbers', () => {
+    expect(nextZoneName({ a: zone('a', 'Room'), b: zone('b', 'Kitchen') })).toBe('Zone 1')
+  })
+
+  test('continues after the highest existing Zone N', () => {
+    expect(nextZoneName({ a: zone('a', 'Zone 1'), b: zone('b', 'Zone 4'), c: zone('c') })).toBe(
+      'Zone 5',
+    )
+  })
+})

package/src/lib/zone-name.ts

@@ -0,0 +1,17 @@
+import type { AnyNode } from '@pascal-app/core'
+
+const ZONE_NAME = /^Zone (\d+)$/
+
+/**
+ * Next free "Zone N" name. Rooms own zones too ("Room", "Kitchen", …), so
+ * counting every zone would skip numbers; only existing "Zone N" names count.
+ */
+export function nextZoneName(nodes: Record<string, AnyNode>): string {
+  let highest = 0
+  for (const node of Object.values(nodes)) {
+    if (node.type !== 'zone') continue
+    const match = ZONE_NAME.exec(node.name ?? '')
+    if (match) highest = Math.max(highest, Number(match[1]))
+  }
+  return `Zone ${highest + 1}`
+}

package/src/store/opens-in-select-mode.test.ts

@@ -0,0 +1,223 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import { createElement } from 'react'
+import type { SidebarTab } from '../components/ui/sidebar/tab-bar'
+import { useShownSidebarPanel } from '../lib/sidebar-panel'
+import { withSelectionHarness } from '../test-utils/selection-harness'
+import useEditor, { DEFAULT_PERSISTED_EDITOR_UI_STATE, editorUiStateOnOpen } from './use-editor'
+import { sceneLayout } from './view-layout'
+
+/**
+ * A project always opens in select mode.
+ *
+ * The armed tool used to ride along in the persisted UI preferences, so whatever
+ * the last session left armed came back on the next load and the first canvas
+ * click drew a wall (or dropped an item) instead of selecting what the user
+ * clicked on. `partialize` no longer writes the tool, and a blob written before
+ * that must not re-arm one either — which is what these cover. Everything else
+ * in the blob is a real preference and still has to come back.
+ */
+describe('opening a project', () => {
+  test('a persisted wall tool is not armed, and the preferences beside it survive', () => {
+    const state = editorUiStateOnOpen({
+      phase: 'building',
+      toolMode: { mode: 'build', tool: 'wall' },
+      mode: 'build',
+      tool: 'wall',
+      viewLayouts: { edit: sceneLayout('split') },
+    })
+
+    expect(state.toolMode).toEqual({ mode: 'select' })
+    expect(state.mode).toBe('select')
+    expect(state.tool).toBeNull()
+    expect(state.phase).toBe('building')
+    expect(state.viewLayouts).toEqual({ edit: sceneLayout('split') })
+  })
+
+  test('the 2D plan opens in select mode as well', () => {
+    const state = editorUiStateOnOpen({
+      phase: 'building',
+      toolMode: { mode: 'build', tool: 'slab' },
+      mode: 'build',
+      tool: 'slab',
+      viewLayouts: { edit: sceneLayout('2d') },
+    })
+
+    expect(state.viewLayouts).toEqual({ edit: sceneLayout('2d') })
+    expect(state.mode).toBe('select')
+    expect(state.tool).toBeNull()
+  })
+
+  test('a persisted item tool leaves no catalog category armed either', () => {
+    const state = editorUiStateOnOpen({
+      phase: 'building',
+      toolMode: { mode: 'build', tool: 'item' },
+      mode: 'build',
+      tool: 'item',
+      catalogCategory: 'kitchen',
+    })
+
+    expect(state.phase).toBe('building')
+    expect(state.mode).toBe('select')
+    expect(state.tool).toBeNull()
+    expect(state.catalogCategory).toBeNull()
+  })
+
+  test('a phase stored before Structure and Furnish merged opens inside the building', () => {
+    // Browsers still hold `structure` / `furnish` from before the merge.
+    for (const stored of ['structure', 'furnish']) {
+      expect(editorUiStateOnOpen({ phase: stored as never }).phase).toBe('building')
+    }
+    expect(editorUiStateOnOpen({ phase: 'site' }).phase).toBe('site')
+    expect(editorUiStateOnOpen({ phase: 'garden' as never }).phase).toBe('site')
+  })
+
+  test('the brush modes do not come back armed', () => {
+    // Paint and sculpt hold an interaction scope for the whole mode, so opening
+    // into one is the same class of surprise as opening into a build tool.
+    expect(editorUiStateOnOpen({ phase: 'site', mode: 'terrain-sculpt' }).mode).toBe('select')
+    expect(editorUiStateOnOpen({ phase: 'building', mode: 'material-paint' }).mode).toBe('select')
+  })
+
+  test('a blob from the Elements/Rooms layer days opens in select mode, its layer dropped', () => {
+    const state = editorUiStateOnOpen({
+      phase: 'building',
+      structureLayer: 'zones',
+      toolMode: { mode: 'build', tool: 'zone' },
+      mode: 'build',
+      tool: 'zone',
+    } as never)
+
+    expect(state).not.toHaveProperty('structureLayer')
+    expect(state.mode).toBe('select')
+    expect(state.tool).toBeNull()
+  })
+
+  test('an empty blob opens on the defaults', () => {
+    expect(editorUiStateOnOpen(null)).toEqual(DEFAULT_PERSISTED_EDITOR_UI_STATE)
+  })
+})
+
+const STORAGE_KEY = 'pascal-editor-ui-preferences'
+const savedWindow = Object.getOwnPropertyDescriptor(globalThis, 'window')
+afterEach(() => {
+  if (savedWindow) Object.defineProperty(globalThis, 'window', savedWindow)
+  else Reflect.deleteProperty(globalThis, 'window')
+})
+
+/** A browser's localStorage, seeded with what an earlier session left behind (a string as is). */
+function stubStorage(stored: Record<string, unknown> = {}) {
+  const values = new Map(
+    Object.entries(stored).map(
+      ([key, value]) => [key, typeof value === 'string' ? value : JSON.stringify(value)] as const,
+    ),
+  )
+  const localStorage: Partial<Storage> = {
+    getItem: (key) => values.get(key) ?? null,
+    setItem: (key, value) => void values.set(key, value),
+    removeItem: (key) => void values.delete(key),
+  }
+  Object.defineProperty(globalThis, 'window', { configurable: true, value: { localStorage } })
+  return { read: (key: string) => JSON.parse(values.get(key) ?? 'null') }
+}
+
+let fresh = 0
+/** The editor store as a page load creates it: not yet rehydrated (`skipHydration`). */
+async function loadEditorStore() {
+  const { default: useEditor } = await import(`./use-editor.tsx?load=${++fresh}`)
+  return useEditor as typeof import('./use-editor').default
+}
+
+describe('reopening the editor', () => {
+  // The editor rehydrates in a mount effect, after the host's own mount effects
+  // have written to the store. Each write saves the whole state, so a write
+  // saved before rehydrate would replace the stored preferences with the
+  // defaults before they are read.
+  test('a write before the store rehydrates leaves the stored panel to come back', async () => {
+    const storage = stubStorage({
+      [STORAGE_KEY]: { state: { sidebarPanels: { edit: 'ai' } }, version: 0 },
+    })
+    const useEditor = await loadEditorStore()
+
+    useEditor.getState().setCanFindNode(true)
+    await useEditor.persist.rehydrate()
+
+    expect(useEditor.getState().activeSidebarPanel).toBe('ai')
+    expect(useEditor.getState().canFindNode).toBe(true)
+    expect(storage.read(STORAGE_KEY).state.sidebarPanels).toEqual({ edit: 'ai' })
+  })
+
+  test('each workspace reopens its own panel, and a reload opens Edit on its own', async () => {
+    stubStorage()
+    const firstSession = await loadEditorStore()
+    await firstSession.persist.rehydrate()
+    const editor = () => firstSession.getState()
+
+    editor().setActiveSidebarPanel('ai')
+    editor().setWorkspaceMode('studio')
+    editor().setActiveSidebarPanel('studio-materials')
+    editor().setWorkspaceMode('edit')
+    expect(editor().activeSidebarPanel).toBe('ai')
+    editor().setWorkspaceMode('studio')
+    expect(editor().activeSidebarPanel).toBe('studio-materials')
+
+    const nextSession = await loadEditorStore()
+    await nextSession.persist.rehydrate()
+    expect(nextSession.getState().workspaceMode).toBe('edit')
+    expect(nextSession.getState().activeSidebarPanel).toBe('ai')
+    nextSession.getState().setWorkspaceMode('studio')
+    expect(nextSession.getState().activeSidebarPanel).toBe('studio-materials')
+  })
+
+  test('an unreadable stored blob opens on the defaults, and the next change replaces it', async () => {
+    const storage = stubStorage({ [STORAGE_KEY]: '{"state":{"sidebarPanels"' })
+    const useEditor = await loadEditorStore()
+    await useEditor.persist.rehydrate()
+
+    expect(useEditor.persist.hasHydrated()).toBe(true)
+    expect(useEditor.getState().activeSidebarPanel).toBe('build')
+    useEditor.getState().setActiveSidebarPanel('ai')
+    expect(storage.read(STORAGE_KEY).state.sidebarPanels).toEqual({ edit: 'ai' })
+  })
+
+  test("a tab whose preferences did not change leaves another tab's panel stored", async () => {
+    const storage = stubStorage()
+    const staleTab = await loadEditorStore()
+    await staleTab.persist.rehydrate()
+    staleTab.getState().setActiveSidebarPanel('build')
+    const otherTab = await loadEditorStore()
+    await otherTab.persist.rehydrate()
+    otherTab.getState().setActiveSidebarPanel('ai')
+
+    staleTab.getState().setCanFindNode(true)
+
+    expect(storage.read(STORAGE_KEY).state.sidebarPanels).toEqual({ edit: 'ai' })
+  })
+})
+
+describe('the rail', () => {
+  test('a remembered panel the rail lacks shows the first tab, keeps the pick, and comes back', async () => {
+    const tab = (id: string): SidebarTab => ({ id, label: id })
+    let shown = ''
+    function Rail({ tabs }: { tabs: SidebarTab[] }) {
+      shown = useShownSidebarPanel(tabs)
+      return null
+    }
+
+    await withSelectionHarness(async ({ render }) => {
+      useEditor.setState({
+        workspaceMode: 'edit',
+        activeSidebarPanel: 'nature',
+        sidebarPanels: { edit: 'nature' },
+      })
+
+      await render(createElement(Rail, { tabs: [tab('build'), tab('paint')] }))
+      expect(shown).toBe('build')
+      expect(useEditor.getState().activeSidebarPanel).toBe('build')
+      expect(useEditor.getState().sidebarPanels).toEqual({ edit: 'nature' })
+
+      await render(createElement(Rail, { tabs: [tab('build'), tab('paint'), tab('nature')] }))
+      expect(shown).toBe('nature')
+      expect(useEditor.getState().activeSidebarPanel).toBe('nature')
+    })
+  })
+})

package/src/store/paint-mode.test.ts

@@ -0,0 +1,188 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { armPaintFromShortcut } from '../hooks/use-keyboard'
+import {
+  bindPaintPickHold,
+  isPaintErasing,
+  paintPickReturnMode,
+  paintRegionModeActive,
+  resetPaintMode,
+  usePaintRegionMode,
+} from '../lib/paint-region-mode'
+import useEditor from './use-editor'
+
+const TILE = { materialPreset: 'library:tile', sourceTarget: 'wall' } as const
+const sub = () => usePaintRegionMode.getState().mode
+const editorMode = () => useEditor.getState().mode
+
+function reset() {
+  useEditor.getState().setPhase('building')
+  useEditor.getState().armToolMode({ mode: 'select' })
+  useEditor.getState().setActivePaintMaterial(null)
+  resetPaintMode()
+}
+beforeEach(reset)
+afterEach(reset)
+
+describe('paint sub-mode state machine', () => {
+  test('the eraser enters paint mode directly from select, with no colour picked', () => {
+    expect(useEditor.getState().activePaintMaterial).toBeNull()
+    useEditor.getState().armMaterialPaint(undefined, 'erase')
+    expect(editorMode()).toBe('material-paint')
+    expect(sub()).toBe('erase')
+    expect(isPaintErasing()).toBe(true)
+    // Erasing is not a region gesture: whole-surface clicks own the pointer.
+    expect(paintRegionModeActive(editorMode())).toBe(false)
+  })
+
+  test('the paint tool enters on the last painting sub-mode, never on erase', () => {
+    useEditor.getState().armMaterialPaint(undefined, 'rectangle')
+    usePaintRegionMode.getState().setMode('erase')
+    useEditor.getState().armToolMode({ mode: 'select' })
+    useEditor.getState().armMaterialPaint()
+    expect(editorMode()).toBe('material-paint')
+    expect(sub()).toBe('rectangle')
+    expect(paintRegionModeActive(editorMode())).toBe(true)
+  })
+
+  test('the P shortcut while erasing switches back to painting', () => {
+    useEditor.getState().armMaterialPaint(undefined, 'polygon')
+    usePaintRegionMode.getState().setMode('erase')
+    armPaintFromShortcut()
+    expect(editorMode()).toBe('material-paint')
+    expect(sub()).toBe('polygon')
+  })
+
+  test('leaving paint mode by any route ends erasing and clears the notice', () => {
+    for (const leave of [
+      () => useEditor.getState().armToolMode({ mode: 'select' }),
+      () => useEditor.getState().setMode('delete'),
+      () => useEditor.getState().armToolMode({ mode: 'build', tool: 'wall' }),
+      () => useEditor.getState().armToolMode({ mode: 'terrain-sculpt' }),
+    ]) {
+      reset()
+      useEditor.getState().armMaterialPaint(undefined, 'rectangle')
+      usePaintRegionMode.getState().setMode('erase')
+      usePaintRegionMode.getState().setNotice('Up to 8 regions per wall face')
+      leave()
+      expect(editorMode()).not.toBe('material-paint')
+      expect(sub()).toBe('rectangle')
+      expect(usePaintRegionMode.getState().notice).toBeNull()
+    }
+  })
+
+  test('picking a colour while erasing paints with it on the last painting sub-mode', () => {
+    useEditor.getState().armMaterialPaint(undefined, 'rectangle')
+    useEditor.getState().armMaterialPaint(undefined, 'erase')
+    useEditor.getState().armMaterialPaint(TILE)
+    expect(sub()).toBe('rectangle')
+    expect(useEditor.getState().activePaintMaterial?.materialPreset).toBe('library:tile')
+
+    usePaintRegionMode.getState().setMode('erase')
+    useEditor.getState().setActivePaintMaterial(TILE)
+    expect(sub()).toBe('rectangle')
+  })
+
+  test('switching sub-mode inside paint mode keeps the mode and remembers the drawing one', () => {
+    useEditor.getState().armMaterialPaint(TILE)
+    for (const mode of ['rectangle', 'erase', 'polygon', 'erase', 'surface'] as const) {
+      usePaintRegionMode.getState().setMode(mode)
+      expect(editorMode()).toBe('material-paint')
+      expect(sub()).toBe(mode)
+    }
+    expect(usePaintRegionMode.getState().drawMode).toBe('surface')
+  })
+
+  test('a new project starts on whole-surface paint', () => {
+    useEditor.getState().armMaterialPaint(undefined, 'polygon')
+    useEditor.getState().armToolMode({ mode: 'select' })
+    resetPaintMode()
+    useEditor.getState().armMaterialPaint()
+    expect(sub()).toBe('surface')
+  })
+})
+
+describe('eyedropper sub-mode', () => {
+  const key = (type: string, init: KeyboardEventInit) => {
+    const event = new Event(type, { cancelable: true }) as KeyboardEvent
+    Object.assign(event, { key: init.key, repeat: init.repeat ?? false })
+    Object.defineProperty(event, 'target', { value: null })
+    return event
+  }
+
+  test('the pick icon enters from select and a pick returns to the sub-mode it came from', () => {
+    useEditor.getState().armMaterialPaint(undefined, 'rectangle')
+    usePaintRegionMode.getState().setMode('pick')
+    expect(sub()).toBe('pick')
+    expect(paintRegionModeActive(editorMode())).toBe(false)
+    expect(paintPickReturnMode()).toBe('rectangle')
+    // What the paint path does with a picked material.
+    useEditor.getState().armMaterialPaint(TILE, paintPickReturnMode())
+    expect(sub()).toBe('rectangle')
+    expect(useEditor.getState().activePaintMaterial?.materialPreset).toBe('library:tile')
+
+    useEditor.getState().armToolMode({ mode: 'select' })
+    useEditor.getState().armMaterialPaint(undefined, 'pick')
+    expect(editorMode()).toBe('material-paint')
+    expect(sub()).toBe('pick')
+  })
+
+  test('picking while erasing returns to painting, not erasing', () => {
+    useEditor.getState().armMaterialPaint(undefined, 'polygon')
+    usePaintRegionMode.getState().setMode('erase')
+    usePaintRegionMode.getState().setMode('pick')
+    expect(paintPickReturnMode()).toBe('polygon')
+  })
+
+  test('Alt held while painting picks; releasing, blur or Escape goes back; never while erasing', () => {
+    const target = new EventTarget()
+    const unbind = bindPaintPickHold(target)
+    try {
+      useEditor.getState().armMaterialPaint(TILE, 'surface')
+      target.dispatchEvent(key('keydown', { key: 'Alt' }))
+      expect(sub()).toBe('pick')
+      target.dispatchEvent(key('keyup', { key: 'Alt' }))
+      expect(sub()).toBe('surface')
+
+      target.dispatchEvent(key('keydown', { key: 'Alt' }))
+      expect(sub()).toBe('pick')
+      target.dispatchEvent(new Event('blur'))
+      expect(sub()).toBe('surface')
+
+      target.dispatchEvent(key('keydown', { key: 'Alt' }))
+      const escapeKey = key('keydown', { key: 'Escape' })
+      target.dispatchEvent(escapeKey)
+      expect(escapeKey.defaultPrevented).toBe(true)
+      expect(sub()).toBe('surface')
+      target.dispatchEvent(key('keyup', { key: 'Alt' }))
+
+      // Erasing picks nothing: Alt does not turn the eyedropper on.
+      usePaintRegionMode.getState().setMode('erase')
+      target.dispatchEvent(key('keydown', { key: 'Alt' }))
+      expect(sub()).toBe('erase')
+      target.dispatchEvent(key('keyup', { key: 'Alt' }))
+
+      // The region sub-modes keep Alt for free placement.
+      usePaintRegionMode.getState().setMode('rectangle')
+      target.dispatchEvent(key('keydown', { key: 'Alt' }))
+      expect(sub()).toBe('rectangle')
+      target.dispatchEvent(key('keyup', { key: 'Alt' }))
+
+      // A pick taken while held is not undone by the release.
+      usePaintRegionMode.getState().setMode('surface')
+      target.dispatchEvent(key('keydown', { key: 'Alt' }))
+      useEditor.getState().armMaterialPaint(TILE, paintPickReturnMode())
+      target.dispatchEvent(key('keyup', { key: 'Alt' }))
+      expect(sub()).toBe('surface')
+    } finally {
+      unbind()
+    }
+  })
+
+  test('leaving paint mode ends the eyedropper', () => {
+    useEditor.getState().armMaterialPaint(undefined, 'pick')
+    usePaintRegionMode.setState({ picked: TILE })
+    useEditor.getState().armToolMode({ mode: 'select' })
+    expect(sub()).toBe('surface')
+    expect(usePaintRegionMode.getState().picked).toBeNull()
+  })
+})