@pascal-app/editor 1.0.1 → 1.0.4

package/src/lib/session-writes.test.ts

@@ -0,0 +1,120 @@
+import { beforeEach, describe, expect, test } from 'bun:test'
+import {
+  type AnyNode,
+  type AnyNodeId,
+  applySceneOperationPatch,
+  BuildingNode,
+  clearSceneHistory,
+  LevelNode,
+  useScene,
+  WallNode,
+} from '@pascal-app/core'
+import { createSessionWrites } from './session-writes'
+
+// A live session (a floor-plan drag, a height scrub) takes back only what it
+// wrote itself: an edit a collaborator lands on the same node mid-drag survives
+// the cancel and the commit.
+
+globalThis.requestAnimationFrame ??= (callback) => {
+  callback(0)
+  return 0
+}
+globalThis.cancelAnimationFrame ??= () => {}
+
+const level = LevelNode.parse({ id: 'level_writes', parentId: 'building_writes' })
+const building = BuildingNode.parse({ id: 'building_writes', children: [level.id] })
+const wall = WallNode.parse({ id: 'wall_writes', parentId: level.id, start: [0, 0], end: [4, 0] })
+const nodes = () => useScene.getState().nodes as Record<string, AnyNode>
+const data = () => JSON.parse(JSON.stringify(nodes()))
+const id = wall.id as AnyNodeId
+
+beforeEach(() => {
+  useScene.setState({
+    nodes: {
+      [building.id]: building,
+      [level.id]: { ...level, children: [wall.id] },
+      [wall.id]: wall,
+    },
+    rootNodeIds: [building.id],
+    dirtyNodes: new Set(),
+    collections: {},
+    materials: {},
+    readOnly: false,
+  })
+  clearSceneHistory()
+})
+
+/** A collaborator's change, applied outside the session like a remote operation. */
+const remote = (patch: Partial<WallNode>) =>
+  useScene.setState({ nodes: { ...nodes(), [id]: { ...nodes()[id]!, ...patch } as AnyNode } })
+
+describe('session writes', () => {
+  test('cancel takes back the session’s fields and keeps a collaborator’s edit', () => {
+    const writes = createSessionWrites()
+    writes.record(() => useScene.getState().updateNodes([{ id, data: { end: [6, 0] } }]))
+    remote({ name: 'Kitchen wall' })
+    writes.record(() => useScene.getState().updateNodes([{ id, data: { end: [7, 0] } }]))
+    writes.revert()
+    expect(nodes()[id]).toMatchObject({ end: [4, 0], name: 'Kitchen wall' })
+  })
+
+  test('commit re-applies only the session’s fields', () => {
+    const writes = createSessionWrites()
+    writes.record(() => useScene.getState().updateNodes([{ id, data: { end: [6, 0] } }]))
+    remote({ name: 'Kitchen wall' })
+    const changes = writes.changes()
+    expect(changes.update).toEqual([{ id, data: { end: [6, 0] } }])
+    writes.revert()
+    useScene.getState().applyNodeChanges(changes)
+    expect(nodes()[id]).toMatchObject({ end: [6, 0], name: 'Kitchen wall' })
+  })
+
+  test('a session that previews through overrides writes nothing back', () => {
+    const writes = createSessionWrites()
+    writes.record(() => {})
+    remote({ name: 'Kitchen wall' })
+    const before = data()
+    writes.revert()
+    expect(data()).toEqual(before)
+    expect(writes.changes()).toEqual({ create: [], update: [], delete: [] })
+  })
+
+  test('nodes the session created go, nodes it deleted come back, outside history', () => {
+    const writes = createSessionWrites()
+    const extra = WallNode.parse({
+      id: 'wall_extra',
+      parentId: level.id,
+      start: [4, 0],
+      end: [4, 4],
+    })
+    const before = data()
+    writes.record(() => {
+      useScene.getState().createNode(extra, level.id as AnyNodeId)
+      useScene.getState().deleteNode(id)
+    })
+    const past = useScene.temporal.getState().pastStates.length
+    writes.revert()
+    expect(data()).toEqual(before)
+    expect(useScene.temporal.getState().pastStates).toHaveLength(past)
+  })
+
+  test('a watched node: another local writer’s draft goes back, a collaborator’s change stays', () => {
+    const writes = createSessionWrites()
+    writes.watch([id])
+    // The 3D tool mounted beside the plan drafts the same node…
+    useScene.getState().updateNodes([{ id, data: { metadata: { isTransient: true } } }])
+    // …while a collaborator's rename arrives from the host.
+    applySceneOperationPatch({
+      materialChanges: [],
+      nodeUpdates: [{ id, data: { name: 'Kitchen wall' }, removeFields: [] }],
+      nodeCreates: [],
+      nodeDeletes: [],
+    })
+    writes.revert()
+    expect(nodes()[id]).toMatchObject({ metadata: {}, name: 'Kitchen wall' })
+    // The revert ended the watch: later writes are no longer the session's.
+    useScene.getState().updateNodes([{ id, data: { end: [5, 0] } }])
+    writes.revert()
+    expect(nodes()[id]).toMatchObject({ end: [5, 0] })
+  })
+})

package/src/lib/session-writes.ts

@@ -0,0 +1,205 @@
+import {
+  type AnyNode,
+  type AnyNodeId,
+  isApplyingRemoteSceneChange,
+  pauseSceneHistory,
+  resumeSceneHistory,
+  useScene,
+} from '@pascal-app/core'
+
+type NodeMap = Record<string, AnyNode>
+
+/**
+ * What a live session wrote to the scene: for each node it touched, the value
+ * before its first write and the value it last wrote (`undefined` for
+ * "absent"). Only writes made inside `record` count, so a collaborator's change
+ * applied between two pointer moves is never mistaken for the session's.
+ */
+export type SessionWrites = {
+  /** Runs one step of the session and records what it wrote. */
+  record: <T>(run: () => T) => T
+  /**
+   * Also records every local write to `ids` until the session ends, whoever
+   * makes it (the 3D tool mounted beside a plan session in split view drafts
+   * the same node) — never a collaborator's change applied from the host.
+   */
+  watch: (ids: readonly string[]) => void
+  /** Stops watching (the revert stops too). */
+  stop: () => void
+  /**
+   * Takes back what the session wrote, outside history. A node changed again
+   * since by someone else keeps that change: only the session's own fields go
+   * back. A session that never wrote the scene touches nothing.
+   */
+  revert: () => void
+  /** The session's writes as one change batch from the originals (the commit a legacy session makes). */
+  changes: () => {
+    create: { node: AnyNode; parentId?: AnyNodeId }[]
+    update: { id: AnyNodeId; data: Partial<AnyNode> }[]
+    delete: AnyNodeId[]
+  }
+  readonly size: number
+}
+
+/** The value a field had before the session first wrote it, and the value it last wrote. */
+type FieldWrite = { had: boolean; from: unknown; to: unknown }
+
+type Entry = {
+  original: AnyNode | undefined
+  wrote: AnyNode | undefined
+  /** Fields the session changed on a node that existed before and after its write. */
+  fields: Map<string, FieldWrite>
+}
+
+export function createSessionWrites(): SessionWrites {
+  const writes = new Map<string, Entry>()
+  let unwatch: (() => void) | null = null
+
+  const note = (before: NodeMap, after: NodeMap, only?: ReadonlySet<string>) => {
+    if (before === after) return
+    const ids = only ?? new Set([...Object.keys(before), ...Object.keys(after)])
+    for (const id of ids) {
+      const prev = before[id]
+      const next = after[id]
+      if (prev === next) continue
+      let entry = writes.get(id)
+      if (!entry) {
+        entry = { original: prev, wrote: next, fields: new Map() }
+        writes.set(id, entry)
+      } else entry.wrote = next
+      if (!(prev && next)) continue
+      const from = prev as Record<string, unknown>
+      const to = next as Record<string, unknown>
+      for (const key of new Set([...Object.keys(from), ...Object.keys(to)])) {
+        if (Object.is(from[key], to[key])) continue
+        const field = entry.fields.get(key)
+        if (field) field.to = to[key]
+        else entry.fields.set(key, { had: Object.hasOwn(from, key), from: from[key], to: to[key] })
+      }
+    }
+  }
+
+  const created = (id: string) => {
+    const entry = writes.get(id)
+    return !!entry && !entry.original && !!entry.wrote
+  }
+  const deleted = (id: string) => {
+    const entry = writes.get(id)
+    return !!entry && !!entry.original && !entry.wrote
+  }
+
+  // Field by field: a field the session wrote goes back unless someone else
+  // has written it since; every other field keeps its current value. A child
+  // list drops the session's creations and gets back what it deleted.
+  const revertFields = (current: AnyNode, entry: Entry): AnyNode | null => {
+    const merged: Record<string, unknown> = { ...current }
+    const cur = current as Record<string, unknown>
+    let changed = false
+    for (const [key, { had, from, to }] of entry.fields) {
+      if (key === 'children' && Array.isArray(cur[key]) && Array.isArray(from)) {
+        const children = (cur[key] as string[]).filter((id) => !created(id))
+        for (const id of from as string[])
+          if (deleted(id) && !children.includes(id)) children.push(id)
+        if (children.join('|') !== (cur[key] as string[]).join('|')) {
+          merged[key] = children
+          changed = true
+        }
+        continue
+      }
+      if (!Object.is(cur[key], to)) continue
+      if (had) merged[key] = from
+      else delete merged[key]
+      changed = true
+    }
+    if (!changed) return null
+    // Nothing else moved: the node the session found, as it was (same object).
+    const original = entry.original as Record<string, unknown> | undefined
+    if (
+      original &&
+      Object.keys(merged).length === Object.keys(original).length &&
+      Object.keys(merged).every((key) => Object.is(merged[key], original[key]))
+    )
+      return entry.original!
+    return merged as AnyNode
+  }
+
+  const stop = () => {
+    unwatch?.()
+    unwatch = null
+  }
+
+  return {
+    watch(ids) {
+      stop()
+      const scope = new Set(ids)
+      unwatch = useScene.subscribe((state, previous) => {
+        if (isApplyingRemoteSceneChange()) return
+        note(previous.nodes as NodeMap, state.nodes as NodeMap, scope)
+      })
+    },
+    stop,
+    record(run) {
+      const before = useScene.getState().nodes as NodeMap
+      try {
+        return run()
+      } finally {
+        note(before, useScene.getState().nodes as NodeMap)
+      }
+    },
+    revert() {
+      stop()
+      if (writes.size === 0) return
+      const nodes = useScene.getState().nodes as NodeMap
+      const next: NodeMap = { ...nodes }
+      const touched: AnyNode[] = []
+      for (const [id, entry] of writes) {
+        const current = nodes[id]
+        if (!entry.original) {
+          if (!current) continue
+          delete next[id]
+        } else if (!current) {
+          next[id] = entry.original
+        } else {
+          const reverted = revertFields(current, entry)
+          if (!reverted) continue
+          next[id] = reverted
+        }
+        touched.push(entry.original ?? current!)
+      }
+      writes.clear()
+      if (touched.length === 0) return
+      pauseSceneHistory(useScene)
+      try {
+        useScene.setState({ nodes: next as ReturnType<typeof useScene.getState>['nodes'] })
+      } finally {
+        resumeSceneHistory(useScene)
+      }
+      const { markDirty } = useScene.getState()
+      for (const node of touched) {
+        if (next[node.id]) markDirty(node.id as AnyNodeId)
+        if (node.parentId && next[node.parentId]) markDirty(node.parentId as AnyNodeId)
+      }
+    },
+    changes() {
+      const batch: ReturnType<SessionWrites['changes']> = { create: [], update: [], delete: [] }
+      for (const [id, { original, wrote, fields }] of writes) {
+        if (!original && wrote) {
+          batch.create.push({ node: wrote, parentId: (wrote.parentId ?? undefined) as AnyNodeId })
+        } else if (original && !wrote) {
+          batch.delete.push(id as AnyNodeId)
+        } else if (original && wrote) {
+          const data: Record<string, unknown> = {}
+          // Child lists follow the creates and deletes.
+          for (const [key, { from, to }] of fields)
+            if (key !== 'children' && JSON.stringify(from) !== JSON.stringify(to)) data[key] = to
+          if (Object.keys(data).length)
+            batch.update.push({ id: id as AnyNodeId, data: data as Partial<AnyNode> })
+        }
+      }
+      return batch
+    },
+    get size() {
+      return writes.size
+    },
+  }
+}

package/src/lib/sidebar-panel.ts

@@ -0,0 +1,62 @@
+import { useEffect } from 'react'
+import { useSidebarStore } from '../components/ui/primitives/sidebar'
+import type { SidebarTab } from '../components/ui/sidebar/tab-bar'
+import useEditor from '../store/use-editor'
+
+/** The narrowest a reopened sidebar panel may be (the layout's resize floor). */
+export const SIDEBAR_MIN_WIDTH = 300
+
+// The desktop layout's rail tabs, published while it is mounted. Hosts pick
+// their own tabs, so a shortcut names the panels it would like, in order, and
+// gets the first one the host has.
+let sidebarTabIds: readonly string[] = []
+
+export function setSidebarTabIds(ids: readonly string[]): void {
+  sidebarTabIds = ids
+}
+
+/**
+ * Pick panel `id` and expand a collapsed sidebar onto it, at a usable width.
+ * The pick goes first: expanding first would reopen the panel left open for a
+ * moment, and a host may arm that panel's tool as it opens (Paint).
+ */
+export function showSidebarPanel(id: string): void {
+  useEditor.getState().setActiveSidebarPanel(id)
+  const sidebar = useSidebarStore.getState()
+  if (!sidebar.isCollapsed) return
+  sidebar.setIsCollapsed(false)
+  if (sidebar.width < SIDEBAR_MIN_WIDTH) sidebar.setWidth(SIDEBAR_MIN_WIDTH)
+}
+
+/**
+ * Show the first of `preferred` the host provides (`showSidebarPanel`).
+ * Returns the panel shown, or null when the host has none of them (e.g. on
+ * mobile).
+ */
+export function openSidebarPanel(preferred: readonly string[]): string | null {
+  const id = preferred.find((candidate) => sidebarTabIds.includes(candidate))
+  if (!id) return null
+  showSidebarPanel(id)
+  return id
+}
+
+/**
+ * The rail tab on screen: the panel picked in this workspace when the rail has
+ * it, else the first tab with a panel. `activeSidebarPanel` follows what shows,
+ * so every reader agrees with the screen, while the pick (`sidebarPanels`)
+ * stays: a plugin's panel joins the rail only once the scene's plugins load,
+ * so a panel restored on reload is missing for a moment and comes back then.
+ */
+export function useShownSidebarPanel(tabs: readonly SidebarTab[]): string {
+  const activePanel = useEditor((s) => s.activeSidebarPanel)
+  const pickedPanel = useEditor((s) => s.sidebarPanels[s.workspaceMode] ?? s.activeSidebarPanel)
+  const shownPanel = tabs.some((tab) => tab.id === pickedPanel)
+    ? pickedPanel
+    : ((tabs.find((tab) => !tab.noPanel) ?? tabs[0])?.id ?? pickedPanel)
+
+  useEffect(() => {
+    if (shownPanel !== activePanel) useEditor.setState({ activeSidebarPanel: shownPanel })
+  }, [shownPanel, activePanel])
+
+  return shownPanel
+}

package/src/lib/site-boundary.test.ts

@@ -9,7 +9,7 @@ import { siteBoundaryHandlesEnabled } from './site-boundary'
  */
 
 const MODES: Mode[] = ['select', 'edit', 'delete', 'build', 'material-paint', 'terrain-sculpt']
-const PHASES: Phase[] = ['site', 'structure', 'furnish']
+const PHASES: Phase[] = ['site', 'building']
 
 describe('siteBoundaryHandlesEnabled', () => {
   test('sculpt hides the handles in every phase', () => {
@@ -29,15 +29,13 @@ describe('siteBoundaryHandlesEnabled', () => {
 
   test('select mode offers them outside the site phase', () => {
     // The flags double as the affordance that *enters* site editing, so select mode
-    // has to show them from structure/furnish or the lot becomes unreachable.
-    expect(siteBoundaryHandlesEnabled({ mode: 'select', phase: 'structure' })).toBe(true)
-    expect(siteBoundaryHandlesEnabled({ mode: 'select', phase: 'furnish' })).toBe(true)
+    // has to show them from the building or the lot becomes unreachable.
+    expect(siteBoundaryHandlesEnabled({ mode: 'select', phase: 'building' })).toBe(true)
   })
 
   test('a drafting or painting mode outside the site phase hides them', () => {
     for (const mode of ['edit', 'delete', 'build', 'material-paint'] as Mode[]) {
-      expect(siteBoundaryHandlesEnabled({ mode, phase: 'structure' })).toBe(false)
-      expect(siteBoundaryHandlesEnabled({ mode, phase: 'furnish' })).toBe(false)
+      expect(siteBoundaryHandlesEnabled({ mode, phase: 'building' })).toBe(false)
     }
   })
 

package/src/lib/site-boundary.ts

@@ -11,7 +11,7 @@ export const SITE_BOUNDARY_DRAG_LABEL = 'site-boundary'
  * clause was added to only one of them.
  *
  * The disagreement was reachable in exactly one configuration, which is why it was
- * easy to miss: arming sculpt from the 2D view promotes `viewMode` to `split` *and*
+ * easy to miss: arming sculpt from the 2D view opens 3D beside the plan *and*
  * the phase to `site`, so the floorplan's `phase === 'site'` term went true at the
  * same moment the 3D editor's `!sculpting` term went false — handles gone in one
  * pane, live in the other. Grabbing one then calls `begin({kind: 'handle-drag'})`,

package/src/lib/snapping-mode.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it } from 'bun:test'
-import { GROUP_MOVE_DRAG_LABEL, ROTATE_HANDLE_DRAG_LABEL } from './contextual-help'
+import {
+  GROUP_MOVE_DRAG_LABEL,
+  GROUP_ROTATE_DRAG_LABEL,
+  ROTATE_HANDLE_DRAG_LABEL,
+} from './contextual-help'
 import {
   cycleSnappingModeIn,
   DEFAULT_SNAPPING_MODE,
@@ -49,6 +53,12 @@ describe('resolveSnapFlags', () => {
 })
 
 describe('per-context snapping', () => {
+  it('rotation defaults to angles and cycles independently to free rotation', () => {
+    expect(defaultSnappingModeFor('rotation')).toBe('angles')
+    expect(snappingModesFor('rotation')).toEqual(['angles', 'off'])
+    expect(cycleSnappingModeIn('rotation', 'angles')).toBe('off')
+    expect(cycleSnappingModeIn('rotation', 'off')).toBe('angles')
+  })
   it('items default to magnetic alignment with no angle lock', () => {
     expect(defaultSnappingModeFor('item')).toBe('lines')
     expect(snappingModesFor('item')).toEqual(['lines', 'grid', 'off'])
@@ -120,6 +130,10 @@ describe('snapContextOf (profile-driven, node-declared)', () => {
     tool: string | null = null,
   ) => snapContextOf({ scope, mode, tool, profileOf, profileOfNode })
 
+  it('dividing a room draws like a wall draft (wall, with angles)', () => {
+    expect(ctx({ kind: 'room-divide' })).toBe('wall')
+  })
+
   it('translating a whole structural node has no angle (polygon, not wall)', () => {
     expect(ctx({ kind: 'moving', nodeType: 'wall' })).toBe('polygon')
     expect(ctx({ kind: 'moving', nodeType: 'slab' })).toBe('polygon')
@@ -132,7 +146,8 @@ describe('snapContextOf (profile-driven, node-declared)', () => {
     expect(ctx({ kind: 'handle-drag', nodeId: 'unknown_1' })).toBeNull()
     expect(
       ctx({ kind: 'handle-drag', nodeId: 'cabinet-module_1', handle: ROTATE_HANDLE_DRAG_LABEL }),
-    ).toBeNull()
+    ).toBe('rotation')
+    expect(ctx({ kind: 'handle-drag', handle: GROUP_ROTATE_DRAG_LABEL })).toBe('rotation')
   })
 
   it('gives mesh rotation the angle context and other edit operations polygon snapping', () => {

package/src/lib/snapping-mode.ts

@@ -1,5 +1,9 @@
 import type { SnapProfile } from '@pascal-app/core'
-import { GROUP_MOVE_DRAG_LABEL, ROTATE_HANDLE_DRAG_LABEL } from './contextual-help'
+import {
+  GROUP_MOVE_DRAG_LABEL,
+  GROUP_ROTATE_DRAG_LABEL,
+  ROTATE_HANDLE_DRAG_LABEL,
+} from './contextual-help'
 
 /**
  * Snapping mode is a single global, user-cyclable control that maps onto the
@@ -68,14 +72,13 @@ export function nextSnappingMode(mode: SnappingMode): SnappingMode {
 // alignment lines). The mode is remembered per context and shown live, so it's
 // never a silent surprise — it just matches what you're doing.
 
-export type SnapContext = 'wall' | 'item' | 'polygon'
+export type SnapContext = 'wall' | 'item' | 'polygon' | 'rotation'
 
 // The cyclable mode-set for a context (distinct from the node's `SnapProfile`).
 type SnapModeSet = { modes: SnappingMode[]; default: SnappingMode }
 
 // `modes[0]` is the cycle's first entry; `default` is what a context starts at.
-// The 'wall' set is the ONLY one with an angle lock — it applies solely when
-// you're setting a segment's DIRECTION (wall/fence drafting + endpoint drag).
+// The 'wall' set includes angle lock when setting a segment's direction.
 // Translating a whole wall, curving it, or drawing/moving a slab can't change an
 // angle, so those use the no-angle 'polygon' set.
 const SNAP_PROFILES: Record<SnapContext, SnapModeSet> = {
@@ -88,9 +91,10 @@ const SNAP_PROFILES: Record<SnapContext, SnapModeSet> = {
   // whole wall/fence translate, curve reshape, polygon boundary edit. Grid by
   // default, NO angle lock.
   polygon: { modes: ['grid', 'lines', 'off'], default: 'grid' },
+  rotation: { modes: ['angles', 'off'], default: 'angles' },
 }
 
-export const SNAP_CONTEXTS: SnapContext[] = ['wall', 'item', 'polygon']
+export const SNAP_CONTEXTS: SnapContext[] = ['wall', 'item', 'polygon', 'rotation']
 
 export function snappingModesFor(context: SnapContext): SnappingMode[] {
   return SNAP_PROFILES[context].modes
@@ -157,8 +161,12 @@ export function snapContextOf(args: {
   // like `profileOf` so `snapping-mode` need not import the registry; defaults
   // to `true` (the structural draw default) when not supplied.
   draftDirectionalOf?: (typeOrTool: string) => boolean
+  // The paint tool's region sub-mode draws lines and boxes on a surface: the
+  // no-angle 'polygon' set (grid / lines / off), idle or mid-gesture.
+  paintRegion?: boolean
 }): SnapContext | null {
-  const { scope, mode, tool, profileOf, profileOfNode, draftDirectionalOf } = args
+  const { scope, mode, tool, profileOf, profileOfNode, draftDirectionalOf, paintRegion } = args
+  if (paintRegion && mode === 'material-paint') return 'polygon'
   // The group-move gizmo translates the whole selection — same no-angle
   // treatment as a single-node move, so Shift cycles the 'item' modes and the
   // HUD shows the item snapping chips for the drag.
@@ -166,12 +174,16 @@ export function snapContextOf(args: {
     return 'item'
   }
   switch (scope.kind) {
+    // Dividing a room draws a segment like a wall draft: same modes, same keys.
+    case 'room-divide':
+      return 'wall'
     case 'mesh-editing':
       return scope.nodeId
         ? contextForProfile(profileOfNode?.(scope.nodeId), scope.operator === 'rotate')
         : null
     case 'handle-drag':
-      if (scope.handle === ROTATE_HANDLE_DRAG_LABEL) return null
+      if (scope.handle === ROTATE_HANDLE_DRAG_LABEL || scope.handle === GROUP_ROTATE_DRAG_LABEL)
+        return 'rotation'
       return scope.nodeId ? contextForProfile(profileOfNode?.(scope.nodeId), false) : null
     case 'placing':
     case 'moving':

package/src/lib/spatial-drag-plane.test.ts

@@ -0,0 +1,53 @@
+import { expect, test } from 'bun:test'
+import { Matrix4, Ray, Vector3 } from 'three'
+import {
+  createSpatialDragPlane,
+  intersectSpatialDragPlane,
+  spatialDragLocalY,
+} from './spatial-drag-plane'
+
+test('controller translation gives continuous motion at the grabbed height', () => {
+  const start = new Vector3(2, 2.4, 1)
+  const ray = new Ray(new Vector3(2, 3.4, 2), new Vector3(0, -1, -1).normalize())
+  const plane = createSpatialDragPlane(start, ray)
+  for (let step = 0; step <= 10; step++) {
+    const moved = ray.clone()
+    moved.origin.z += step / 10
+    const hit = intersectSpatialDragPlane(moved, plane, new Vector3())!
+    expect(hit.x).toBeCloseTo(2)
+    expect(hit.y).toBeCloseTo(2.4)
+    expect(hit.z).toBeCloseTo(1 + step / 10)
+  }
+})
+
+test('horizontal rays use a stable facing plane and grazing rays are ignored', () => {
+  const ray = new Ray(new Vector3(0, 1, 2), new Vector3(0, 0, -1))
+  const plane = createSpatialDragPlane(new Vector3(0, 1, 0), ray)
+  ray.origin.x = 0.1
+  expect(intersectSpatialDragPlane(ray, plane, new Vector3())?.x).toBeCloseTo(0.1)
+  ray.direction.set(1, 0, -0.001).normalize()
+  expect(intersectSpatialDragPlane(ray, plane, new Vector3())).toBeNull()
+})
+
+test('drag plane follows a rotated, scaled building frame', () => {
+  const transform = new Matrix4().makeRotationZ(Math.PI / 4).scale(new Vector3(0.2, 0.2, 0.2))
+  const point = new Vector3(0, 2, 0).applyMatrix4(transform)
+  const up = new Vector3(0, 1, 0).transformDirection(transform)
+  const ray = new Ray(point.clone().add(up), up.clone().negate())
+  const plane = createSpatialDragPlane(point, ray, transform)
+  expect(intersectSpatialDragPlane(ray, plane, new Vector3())?.distanceTo(point)).toBeLessThan(1e-8)
+})
+
+test('height drag uses model metres at human and miniature scales without an initial jump', () => {
+  for (const scale of [1, 0.2, 2]) {
+    const frame = new Matrix4().makeRotationY(0.7).scale(new Vector3(scale, scale, scale))
+    frame.setPosition(2, 4, -3)
+    const inverse = frame.clone().invert()
+    const start = new Vector3(1, 2.5, 3).applyMatrix4(frame)
+    const initialY = spatialDragLocalY(start, inverse)
+    for (let step = 0; step <= 10; step++) {
+      const moved = start.clone().add(new Vector3(0, (scale * step) / 10, 0))
+      expect(2.5 + spatialDragLocalY(moved, inverse) - initialY).toBeCloseTo(2.5 + step / 10)
+    }
+  }
+})

package/src/lib/spatial-drag-plane.ts

@@ -0,0 +1,19 @@
+import { type Matrix4, Plane, type Ray, Vector3 } from 'three'
+
+export function createSpatialDragPlane(point: Vector3, ray: Ray, localToWorld?: Matrix4) {
+  const normal = new Vector3(0, 1, 0)
+  if (localToWorld) normal.transformDirection(localToWorld)
+  // A nearly horizontal controller ray cannot reliably intersect a floor plane.
+  if (Math.abs(normal.dot(ray.direction)) < 0.2) normal.copy(ray.direction)
+  return new Plane().setFromNormalAndCoplanarPoint(normal, point)
+}
+
+export function intersectSpatialDragPlane(ray: Ray, plane: Plane, target: Vector3) {
+  if (Math.abs(plane.normal.dot(ray.direction)) < 0.05) return null
+  return ray.intersectPlane(plane, target)
+}
+
+// Freeze this frame at grab time; world metres differ from model metres in God view.
+export function spatialDragLocalY(worldPoint: Vector3, worldToLocal: Matrix4) {
+  return worldPoint.clone().applyMatrix4(worldToLocal).y
+}