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

package/src/lib/ground-surface.ts

@@ -0,0 +1,95 @@
+// The one place that answers "where is the ground under this pointer ray?".
+//
+// Before terrain there was no question to answer: the ground was `y = 0` and
+// every consumer intersected its own horizontal plane. Terrain makes those
+// planes wrong in a way that is invisible on flat ground and badly wrong on a
+// slope — a ray intersected at the datum instead of at the surface reports an XZ
+// that slides along the ray, further the more oblique the camera. Item placement
+// already repairs this locally (`resolvePointerSupportSurface`); this module
+// exists so the repair is shared instead of copied into column, wall, fence, and
+// the sculpt tool.
+//
+// It lives in `editor` rather than `core` because the decision needs one piece of
+// editor knowledge — which plane a consumer is asking about — while the geometry
+// it delegates to (`raycastTerrain`, `heightAt`) is pure core.
+
+import {
+  heightAt,
+  isSiteDatum,
+  raycastTerrain,
+  type SiteNode,
+  type TerrainField,
+  type TerrainHit,
+  terrainFieldOf,
+  useScene,
+} from '@pascal-app/core'
+
+/** The active site's terrain field, or null when the scene has no sculpted ground. */
+export function siteTerrainField(): TerrainField | null {
+  const { nodes, rootNodeIds } = useScene.getState()
+  const siteId = rootNodeIds[0]
+  const site = siteId ? nodes[siteId] : null
+  if (site?.type !== 'site') return null
+  return terrainFieldOf(site as SiteNode)
+}
+
+/**
+ * True when a horizontal query plane at `planeY` is the *site ground*, as opposed
+ * to a built flat surface that happens to be horizontal.
+ *
+ * This is the whole scoping rule, and getting it wrong in either direction is
+ * worse than not having terrain at all:
+ *
+ * - Treat every horizontal plane as ground and a second-storey wall draft snaps
+ *   to the hillside under the building.
+ * - Treat none of them as ground and every ground tool keeps the perspective skew
+ *   terrain was supposed to remove.
+ *
+ * The datum is exactly the right discriminator because terrain *is* the surface at
+ * the datum: the site renderer removes the flat ground fill when terrain mounts,
+ * so at the datum there is nothing else to hit. Every other horizontal plane —
+ * a storey base, a slab top, a shelf — is a real flat surface built by the user,
+ * and a plane is the correct model for it.
+ *
+ * `isSiteDatum` comes from core so this rule and the one the support resolver
+ * applies (`terrain-support.ts`) cannot drift into disagreeing about which
+ * surfaces are ground.
+ */
+export function isSiteGroundPlane(planeY: number): boolean {
+  return isSiteDatum(planeY)
+}
+
+/**
+ * Where a pointer ray meets the sculpted ground, or null when the flat-plane path
+ * should be used instead — no terrain, the ray misses the field, or the query
+ * plane is a built surface rather than the ground.
+ *
+ * Returning null rather than a fallback hit is deliberate: the caller already owns
+ * a correct plane intersection for its own frame (world for grid events,
+ * level-local for support election), and duplicating that here would mean two
+ * definitions of the fallback to keep in sync.
+ */
+export function resolveTerrainGroundHit(
+  origin: readonly [number, number, number],
+  direction: readonly [number, number, number],
+  planeY: number,
+): TerrainHit | null {
+  if (!isSiteGroundPlane(planeY)) return null
+  const field = siteTerrainField()
+  if (!field) return null
+  return raycastTerrain(field, origin, direction)
+}
+
+/**
+ * Ground height at a world XZ, for consumers with no ray to march.
+ *
+ * The 2D plan view is the case this exists for: an orthographic top-down camera
+ * makes the pointer ray vertical, so the march degenerates to a single sample and
+ * there is no XZ skew to correct — only a Y to report.
+ */
+export function groundHeightAt(x: number, z: number, planeY: number): number | null {
+  if (!isSiteGroundPlane(planeY)) return null
+  const field = siteTerrainField()
+  if (!field) return null
+  return heightAt(field, x, z)
+}

package/src/lib/history.test.ts

@@ -0,0 +1,96 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test'
+import {
+  type AnyNode,
+  type AnyNodeId,
+  BuildingNode,
+  clearSceneHistory,
+  LevelNode,
+  useScene,
+} from '@pascal-app/core'
+import { installHistoryCommandDelegate, runRedo, runUndo } from './history'
+
+type RafFn = (cb: (time: number) => void) => number
+;(globalThis as unknown as { requestAnimationFrame?: RafFn }).requestAnimationFrame ??= (cb) => {
+  cb(0)
+  return 0
+}
+;(globalThis as unknown as { cancelAnimationFrame?: (id: number) => void }).cancelAnimationFrame ??=
+  () => {}
+
+const BUILDING_ID = 'building_history_controller' as AnyNodeId
+const LEVEL_ID = 'level_history_controller' as AnyNodeId
+let disposeController = () => {}
+
+function levelNumber(): number {
+  return (useScene.getState().nodes[LEVEL_ID] as { level: number }).level
+}
+
+describe('editor history controller', () => {
+  beforeEach(() => {
+    disposeController()
+    disposeController = () => {}
+    const level = LevelNode.parse({
+      id: LEVEL_ID,
+      parentId: BUILDING_ID,
+      children: [],
+      level: 0,
+    })
+    const building = BuildingNode.parse({
+      id: BUILDING_ID,
+      parentId: null,
+      children: [LEVEL_ID],
+    })
+    useScene.setState({
+      nodes: { [BUILDING_ID]: building, [LEVEL_ID]: level },
+      rootNodeIds: [BUILDING_ID],
+      dirtyNodes: new Set<AnyNodeId>(),
+      collections: {},
+      materials: {},
+      readOnly: false,
+    } as never)
+    clearSceneHistory()
+    useScene.getState().updateNode(LEVEL_ID, { level: 1 } as Partial<AnyNode>)
+  })
+
+  afterEach(() => {
+    disposeController()
+    disposeController = () => {}
+  })
+
+  test('delegates undo and redo while a host delegate is installed', () => {
+    const undo = mock(() => {})
+    const redo = mock(() => {})
+    disposeController = installHistoryCommandDelegate({ undo, redo })
+
+    runUndo()
+    runRedo()
+
+    expect(undo).toHaveBeenCalledTimes(1)
+    expect(redo).toHaveBeenCalledTimes(1)
+    expect(levelNumber()).toBe(1)
+    expect(useScene.temporal.getState().pastStates).toHaveLength(1)
+  })
+
+  test('falls back to standalone Zundo undo and redo when no controller is installed', () => {
+    runUndo()
+    expect(levelNumber()).toBe(0)
+    expect(useScene.temporal.getState().futureStates).toHaveLength(1)
+
+    runRedo()
+    expect(levelNumber()).toBe(1)
+    expect(useScene.temporal.getState().pastStates).toHaveLength(1)
+  })
+
+  test('an older cleanup cannot uninstall a newer controller', () => {
+    const firstUndo = mock(() => {})
+    const stopFirst = installHistoryCommandDelegate({ undo: firstUndo, redo: () => {} })
+    const secondUndo = mock(() => {})
+    disposeController = installHistoryCommandDelegate({ undo: secondUndo, redo: () => {} })
+
+    stopFirst()
+    runUndo()
+
+    expect(firstUndo).toHaveBeenCalledTimes(0)
+    expect(secondUndo).toHaveBeenCalledTimes(1)
+  })
+})

package/src/lib/history.ts

@@ -1,5 +1,19 @@
 import { useLiveNodeOverrides, useLiveTransforms, useScene } from '@pascal-app/core'
 
+export type HistoryCommandDelegate = {
+  undo: () => void
+  redo: () => void
+}
+
+let historyCommandDelegate: HistoryCommandDelegate | null = null
+
+export function installHistoryCommandDelegate(delegate: HistoryCommandDelegate): () => void {
+  historyCommandDelegate = delegate
+  return () => {
+    if (historyCommandDelegate === delegate) historyCommandDelegate = null
+  }
+}
+
 function refreshSceneAfterHistoryJump() {
   useLiveNodeOverrides.getState().clearAll()
   useLiveTransforms.getState().clearAll()
@@ -11,11 +25,28 @@ function refreshSceneAfterHistoryJump() {
 }
 
 export function runUndo() {
+  if (historyCommandDelegate) {
+    historyCommandDelegate.undo()
+    return
+  }
   useScene.temporal.getState().undo()
   refreshSceneAfterHistoryJump()
 }
 
 export function runRedo() {
+  if (historyCommandDelegate) {
+    historyCommandDelegate.redo()
+    return
+  }
   useScene.temporal.getState().redo()
   refreshSceneAfterHistoryJump()
 }
+
+/**
+ * ⌘Z / ⌘⇧Z (undo/redo). Pointer-drag sessions intercept these in the capture
+ * phase and cancel the gesture instead — mid-drag, "undo" means "abort what my
+ * mouse is doing", never a history jump under a live pointer.
+ */
+export function isHistoryShortcut(e: KeyboardEvent) {
+  return (e.metaKey || e.ctrlKey) && (e.key === 'z' || e.key === 'Z')
+}

package/src/lib/interaction/hot-set.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, test } from 'bun:test'
+import type { AnyNode } from '@pascal-app/core'
+import {
+  type AttachClass,
+  attachClassOf,
+  type HotSetCandidate,
+  isCandidateInHotSet,
+  isPickableForAttach,
+} from './hot-set'
+
+const mockNode = (id: string, type: string): AnyNode => ({ id, type }) as unknown as AnyNode
+
+const floor: HotSetCandidate = {
+  type: 'level',
+  isFloorLike: true,
+  exposesTop: false,
+  attachClass: 'surface',
+}
+const wall: HotSetCandidate = {
+  type: 'wall',
+  isFloorLike: false,
+  exposesTop: false,
+  attachClass: 'surface',
+}
+const ceiling: HotSetCandidate = {
+  type: 'ceiling',
+  isFloorLike: false,
+  exposesTop: false,
+  attachClass: 'surface',
+}
+const table: HotSetCandidate = {
+  type: 'item',
+  isFloorLike: false,
+  exposesTop: true,
+  attachClass: 'surface',
+}
+const wallShelf: HotSetCandidate = {
+  type: 'shelf',
+  isFloorLike: false,
+  exposesTop: true,
+  attachClass: 'wall',
+}
+const ceilingFan: HotSetCandidate = {
+  type: 'item',
+  isFloorLike: false,
+  exposesTop: true,
+  attachClass: 'ceiling',
+}
+
+describe('attachClassOf', () => {
+  test('wall and wall-side collapse to wall', () => {
+    expect(attachClassOf('wall')).toBe('wall')
+    expect(attachClassOf('wall-side')).toBe('wall')
+  })
+  test('ceiling maps to ceiling', () => {
+    expect(attachClassOf('ceiling')).toBe('ceiling')
+  })
+  test('undefined/null/unknown is surface-resting', () => {
+    expect(attachClassOf(undefined)).toBe('surface')
+    expect(attachClassOf(null)).toBe('surface')
+    expect(attachClassOf('')).toBe('surface')
+  })
+})
+
+describe('isPickableForAttach — wall-mounted (window)', () => {
+  test('only walls are eligible; floor/ceiling/tops are not', () => {
+    expect(isPickableForAttach('wall', wall)).toBe(true)
+    expect(isPickableForAttach('wall', floor)).toBe(false)
+    expect(isPickableForAttach('wall', ceiling)).toBe(false)
+    expect(isPickableForAttach('wall', table)).toBe(false)
+    expect(isPickableForAttach('wall', wallShelf)).toBe(false)
+  })
+})
+
+describe('isPickableForAttach — ceiling-mounted', () => {
+  test('only ceilings are eligible', () => {
+    expect(isPickableForAttach('ceiling', ceiling)).toBe(true)
+    expect(isPickableForAttach('ceiling', wall)).toBe(false)
+    expect(isPickableForAttach('ceiling', floor)).toBe(false)
+  })
+})
+
+describe('isPickableForAttach — surface-resting (sofa / cactus)', () => {
+  test('floor is always eligible', () => {
+    expect(isPickableForAttach('surface', floor)).toBe(true)
+  })
+  test('host tops (table, wall-shelf top) are eligible', () => {
+    expect(isPickableForAttach('surface', table)).toBe(true)
+    expect(isPickableForAttach('surface', wallShelf)).toBe(true)
+  })
+  test('a wall (no top surface) is not eligible', () => {
+    expect(isPickableForAttach('surface', wall)).toBe(false)
+  })
+  test('a ceiling-mounted host (ceiling fan) is never eligible — Track E', () => {
+    expect(isPickableForAttach('surface', ceilingFan)).toBe(false)
+  })
+})
+
+describe('isCandidateInHotSet — by scope', () => {
+  const surfaceClass: AttachClass = 'surface'
+  test('idle: everything is in the hot-set (selection filtering lives elsewhere)', () => {
+    expect(isCandidateInHotSet({ kind: 'idle' }, null, ceilingFan)).toBe(true)
+  })
+  test('placing a surface item: derives from attach class', () => {
+    const scope = {
+      kind: 'placing' as const,
+      node: mockNode('i1', 'item'),
+      nodeId: 'i1',
+      nodeType: 'item',
+      view: '3d' as const,
+      pressDrag: false,
+    }
+    expect(isCandidateInHotSet(scope, surfaceClass, floor)).toBe(true)
+    expect(isCandidateInHotSet(scope, surfaceClass, ceilingFan)).toBe(false)
+  })
+  test('moving a wall-mounted item: only walls', () => {
+    const scope = {
+      kind: 'moving' as const,
+      node: mockNode('w1', 'window'),
+      nodeId: 'w1',
+      nodeType: 'window',
+      view: '2d' as const,
+    }
+    expect(isCandidateInHotSet(scope, 'wall', wall)).toBe(true)
+    expect(isCandidateInHotSet(scope, 'wall', table)).toBe(false)
+  })
+  test('non-placement active scopes target nothing in the scene', () => {
+    expect(isCandidateInHotSet({ kind: 'box-select' }, null, floor)).toBe(false)
+    expect(
+      isCandidateInHotSet({ kind: 'handle-drag', nodeId: 'x', handle: 'h' }, null, floor),
+    ).toBe(false)
+  })
+})

package/src/lib/interaction/hot-set.ts

@@ -0,0 +1,67 @@
+// The hot-set: which scene objects are raycast-eligible during an interaction.
+//
+// It is never hand-authored per interaction. It falls out of the node's
+// `asset.attachTo` plus whether a candidate exposes a top surface. "Floor item"
+// really means surface-resting: it rests on the floor *or* any host's top
+// surface. Walls and ceilings are the special attach modes. Adding a node kind
+// = set `attachTo` (or leave blank); the hot-set follows with zero per-kind
+// wiring.
+
+import type { InteractionScope } from './scope'
+
+// What a node attaches to, collapsed to the three classes the hot-set cares
+// about. `wall-side` is a wall attachment; everything without an explicit
+// `attachTo` is surface-resting.
+export type AttachClass = 'wall' | 'ceiling' | 'surface'
+
+export function attachClassOf(attachTo: string | undefined | null): AttachClass {
+  if (attachTo === 'wall' || attachTo === 'wall-side') return 'wall'
+  if (attachTo === 'ceiling') return 'ceiling'
+  return 'surface'
+}
+
+// The metadata the hot-set needs about a candidate host/surface. Derived from
+// the candidate node + its registry definition by the caller, so this module
+// stays pure and unit-testable without the scene or registry.
+export type HotSetCandidate = {
+  type: string
+  // The level floor plane / ground a surface-resting node can always rest on.
+  isFloorLike: boolean
+  // The candidate exposes a usable top surface (registry
+  // `capabilities.surfaces.top`) — a table, a shelf, a slab.
+  exposesTop: boolean
+  // The candidate's own attach class. A ceiling fan is `ceiling`: it hangs from
+  // the ceiling and must never act as a host top (Track E).
+  attachClass: AttachClass
+}
+
+// For a node whose attach class is `placed`, is `candidate` a valid
+// host/surface to pick during placement or move?
+export function isPickableForAttach(placed: AttachClass, candidate: HotSetCandidate): boolean {
+  if (placed === 'wall') return candidate.type === 'wall'
+  if (placed === 'ceiling') return candidate.type === 'ceiling'
+  // Surface-resting: the floor, or any host that exposes a top surface — but
+  // never a ceiling-mounted host (a floor lamp must not land on a ceiling fan).
+  if (candidate.isFloorLike) return true
+  if (!candidate.exposesTop) return false
+  if (candidate.attachClass === 'ceiling') return false
+  return true
+}
+
+// The hot-set predicate for a whole scope. For placing/moving it derives from
+// the moving node's attach class; for every other active scope nothing in the
+// scene is a placement target, so the body's own raycast owns the pointer.
+// `idle` returns true here — selection/phase filtering stays in the selection
+// manager; this only narrows what an *active* interaction can target.
+export function isCandidateInHotSet(
+  scope: InteractionScope,
+  placedAttachClass: AttachClass | null,
+  candidate: HotSetCandidate,
+): boolean {
+  if (scope.kind === 'idle') return true
+  if (scope.kind === 'placing' || scope.kind === 'moving') {
+    if (placedAttachClass === null) return true
+    return isPickableForAttach(placedAttachClass, candidate)
+  }
+  return false
+}

package/src/lib/interaction/overlay-policy.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, test } from 'bun:test'
+import type { AnyNode } from '@pascal-app/core'
+import { resolveOverlayPolicy } from './overlay-policy'
+import type { ActiveInteractionScope } from './scope'
+
+const mockNode = (id: string, type: string): AnyNode => ({ id, type }) as unknown as AnyNode
+
+const ACTIVE_SCOPES: ActiveInteractionScope[] = [
+  {
+    kind: 'placing',
+    node: mockNode('i1', 'item'),
+    nodeId: 'i1',
+    nodeType: 'item',
+    view: '3d',
+    pressDrag: false,
+  },
+  { kind: 'moving', node: mockNode('i1', 'item'), nodeId: 'i1', nodeType: 'item', view: '2d' },
+  { kind: 'handle-drag', nodeId: 'w1', handle: 'height' },
+  { kind: 'drafting', tool: 'wall' },
+  { kind: 'reshaping', nodeId: 's1', reshape: 'hole', driver: 'tool', holeIndex: 0 },
+  { kind: 'box-select' },
+  { kind: 'painting' },
+  { kind: 'sculpting' },
+]
+
+describe('resolveOverlayPolicy', () => {
+  test('idle keeps everything shown and pickable', () => {
+    const p = resolveOverlayPolicy({ kind: 'idle' })
+    expect(p.zoneLabels).toBe('shown')
+    expect(p.contextBadges).toBe('shown')
+    expect(p.conflictingControls).toBe('shown')
+    expect(p.sceneObjectsPickable).toBe(true)
+  })
+
+  test('every active scope hides zone labels, fades badges, hides conflicting controls', () => {
+    for (const scope of ACTIVE_SCOPES) {
+      const p = resolveOverlayPolicy(scope)
+      expect(p.zoneLabels).toBe('hidden')
+      expect(p.contextBadges).toBe('faded')
+      expect(p.conflictingControls).toBe('hidden')
+      expect(p.sceneObjectsPickable).toBe(false)
+    }
+  })
+
+  test('active affordances and the contextual HUD always stay interactive', () => {
+    for (const scope of [{ kind: 'idle' } as const, ...ACTIVE_SCOPES]) {
+      const p = resolveOverlayPolicy(scope)
+      expect(p.activeAffordances).toBe('shown')
+      expect(p.contextualHudInteractive).toBe(true)
+    }
+  })
+})

package/src/lib/interaction/overlay-policy.ts

@@ -0,0 +1,59 @@
+// The overlay scope matrix — the "Sims-light" feel. During any non-idle
+// interaction, two layers behave differently:
+//
+//  - 3D scene objects stay VISIBLE but become NON-pickable (the hot-set owns
+//    what the active interaction can target). Context is preserved; you just
+//    can't grab the wrong thing.
+//  - DOM/HUD overlays step back, differentiated by how distracting they are:
+//      zone labels      -> hidden (not a primary editing concern)
+//      context badges   -> faded + pointer-events:none (hover name pills)
+//      other controls   -> hard-hidden (other objects' handles, the floating
+//                          action menu, conflicting controls)
+//
+// The active interaction's own affordances (ghost, snap guides, dimension
+// labels, the active handle) always stay — "default-off, opt-in for the active
+// action". The contextual control HUD is exempt from the pointer-events
+// step-back because it *is* the active interaction's own controls.
+
+import { type InteractionScope, isActive } from './scope'
+
+export type OverlayVisibility = 'shown' | 'faded' | 'hidden'
+
+export type OverlayPolicy = {
+  zoneLabels: OverlayVisibility
+  // Hover name pills / context badges.
+  contextBadges: OverlayVisibility
+  // Other objects' handles + the floating action menu — anything whose action
+  // would conflict with the active interaction.
+  conflictingControls: OverlayVisibility
+  // Non-active scene objects: visible always, pickable only when idle.
+  sceneObjectsPickable: boolean
+  // The active interaction's own ghost/guides/dimension labels/handle. Always
+  // shown; this field exists so consumers can assert the contract.
+  activeAffordances: 'shown'
+  // The contextual control HUD keeps pointer events even while everything else
+  // steps back, because it is the active interaction's own controls.
+  contextualHudInteractive: boolean
+}
+
+const IDLE_POLICY: OverlayPolicy = {
+  zoneLabels: 'shown',
+  contextBadges: 'shown',
+  conflictingControls: 'shown',
+  sceneObjectsPickable: true,
+  activeAffordances: 'shown',
+  contextualHudInteractive: true,
+}
+
+const ACTIVE_POLICY: OverlayPolicy = {
+  zoneLabels: 'hidden',
+  contextBadges: 'faded',
+  conflictingControls: 'hidden',
+  sceneObjectsPickable: false,
+  activeAffordances: 'shown',
+  contextualHudInteractive: true,
+}
+
+export function resolveOverlayPolicy(scope: InteractionScope): OverlayPolicy {
+  return isActive(scope) ? ACTIVE_POLICY : IDLE_POLICY
+}