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

package/src/lib/terrain-sculpt.ts

@@ -0,0 +1,301 @@
+// Sculpt-mode helpers that are pure enough to test without a canvas: sizing the
+// field to a site, resolving the flatten target, and the commit.
+//
+// The tool component owns pointer plumbing; everything here is a function of
+// data, which is what lets the interesting decisions (grid extent, undo
+// granularity, when a stroke is worth persisting) be asserted in unit tests
+// instead of e2e.
+
+import {
+  type BrushSettings,
+  commitTerrainField,
+  createTerrainField,
+  DEFAULT_TERRAIN_SPACING,
+  type HeightPatch,
+  isDatumField,
+  minBrushRadius,
+  pointInPolygon2D,
+  quantize,
+  runAsSingleSceneHistoryStep,
+  type SiteNode,
+  sampleTarget,
+  type TerrainField,
+  type TerrainVerb,
+  terrainFieldOf,
+  useLiveTerrain,
+  useScene,
+} from '@pascal-app/core'
+
+/**
+ * Field sizes we allow, all `2ⁿ+1` so a future LOD halving lands on existing
+ * samples instead of interpolating a seam.
+ */
+const FIELD_SIZES = [33, 65, 129, 257] as const
+
+/**
+ * Sample count a fresh field gets, chosen to cover the site polygon at roughly
+ * `DEFAULT_TERRAIN_SPACING` and never exceeding 257² (66 049 samples — about
+ * four furnished rooms' worth of vertices).
+ *
+ * Sizing from the polygon rather than a fixed extent matters because the extent
+ * is baked at creation: the field is the ground for the whole session, and a
+ * grid that stops short of the lot line leaves a visible cliff where the terrain
+ * mesh ends and the flat fill resumes. Padding by one spacing keeps the boundary
+ * line itself on interpolated ground rather than on the clamped edge row.
+ */
+export function fieldExtentForSite(site: Pick<SiteNode, 'polygon'> | null | undefined): {
+  origin: [number, number]
+  cols: number
+  rows: number
+  spacing: number
+} {
+  const points = site?.polygon?.points ?? []
+  if (points.length < 3) {
+    const half = ((65 - 1) / 2) * DEFAULT_TERRAIN_SPACING
+    return { origin: [-half, -half], cols: 65, rows: 65, spacing: DEFAULT_TERRAIN_SPACING }
+  }
+
+  let minX = Number.POSITIVE_INFINITY
+  let minZ = Number.POSITIVE_INFINITY
+  let maxX = Number.NEGATIVE_INFINITY
+  let maxZ = Number.NEGATIVE_INFINITY
+  for (const [x, z] of points) {
+    if (x < minX) minX = x
+    if (x > maxX) maxX = x
+    if (z < minZ) minZ = z
+    if (z > maxZ) maxZ = z
+  }
+
+  // The grid is square: a rectangular field would need two spacings or two
+  // sample counts, and both make every downstream index calculation branchier
+  // for no visual gain.
+  const pad = DEFAULT_TERRAIN_SPACING * 2
+  const span = Math.max(maxX - minX, maxZ - minZ) + pad * 2
+  const centerX = (minX + maxX) / 2
+  const centerZ = (minZ + maxZ) / 2
+
+  const wanted = Math.ceil(span / DEFAULT_TERRAIN_SPACING) + 1
+  const size = FIELD_SIZES.find((candidate) => candidate >= wanted) ?? FIELD_SIZES.at(-1)!
+  // Spacing stretches when the lot is bigger than 257 samples can cover at the
+  // default: coarser ground beats ground that stops at the property line.
+  const spacing = Math.max(DEFAULT_TERRAIN_SPACING, span / (size - 1))
+  const half = ((size - 1) / 2) * spacing
+
+  return {
+    origin: [centerX - half, centerZ - half],
+    cols: size,
+    rows: size,
+    spacing,
+  }
+}
+
+/**
+ * The field a sculpt stroke on `site` should start from: its existing terrain,
+ * or a fresh flat one sized to the lot.
+ *
+ * Not `terrainFieldForEdit` — that takes explicit options, and the whole point
+ * here is that the tool must not have to know how to size a grid.
+ */
+export function sculptFieldForSite(site: SiteNode): TerrainField {
+  return terrainFieldOf(site) ?? createTerrainField(fieldExtentForSite(site))
+}
+
+/** Whether an XZ point belongs to the editable property footprint. */
+export function terrainPointInsideSite(
+  site: Pick<SiteNode, 'polygon'>,
+  x: number,
+  z: number,
+): boolean {
+  const polygon = site.polygon?.points ?? []
+  return polygon.length >= 3 && pointInPolygon2D([x, z], polygon, { includeBoundary: true })
+}
+
+/**
+ * Keep a rectangular brush patch inside the property footprint.
+ *
+ * The heightfield stays padded and square for compact storage and predictable
+ * partial uploads, but that implementation extent is not editable land. Samples
+ * outside the polygon retain their current values even when a brush overlaps the
+ * property line.
+ */
+export function clipTerrainPatchToSite(
+  field: TerrainField,
+  patch: HeightPatch,
+  site: Pick<SiteNode, 'polygon'>,
+): HeightPatch {
+  let heights: Int16Array | null = null
+
+  for (let row = 0; row < patch.rows; row += 1) {
+    for (let col = 0; col < patch.cols; col += 1) {
+      const fieldCol = patch.col0 + col
+      const fieldRow = patch.row0 + row
+      const x = field.origin[0] + fieldCol * field.spacing
+      const z = field.origin[1] + fieldRow * field.spacing
+      if (terrainPointInsideSite(site, x, z)) continue
+
+      const patchIndex = row * patch.cols + col
+      const previous = field.heights[fieldRow * field.cols + fieldCol] ?? 0
+      if ((patch.heights[patchIndex] ?? 0) === previous) continue
+      heights ??= patch.heights.slice()
+      heights[patchIndex] = previous
+    }
+  }
+
+  return heights ? { ...patch, heights } : patch
+}
+
+/**
+ * The site node the sculpt tool acts on, read straight from the scene.
+ *
+ * The tool and panel get this from a subscribed selector; the keyboard handler
+ * cannot (it is one imperative listener, not a component), and open-coding
+ * "root[0], is it a site?" a third time is how the three drift apart.
+ */
+export function activeSiteNode(): SiteNode | null {
+  const { nodes, rootNodeIds } = useScene.getState()
+  const root = rootNodeIds[0]
+  const node = root ? nodes[root] : undefined
+  return node?.type === 'site' ? (node as SiteNode) : null
+}
+
+/**
+ * Largest brush radius offered, in metres.
+ *
+ * A taste call, unlike the minimum: 20 m covers a building pad in one pass and is
+ * about where a bigger brush stops being aimable and starts being `flattenSite`.
+ */
+export const MAX_BRUSH_RADIUS = 20
+
+/**
+ * The legal brush-radius range for `site`, low end first.
+ *
+ * Exists because two controls set this value — the panel's Size slider and the
+ * `[`/`]` keys — and both used to carry their own hardcoded `0.5`/`20`, with a
+ * comment in the keyboard handler asserting they matched. They did, but nothing
+ * held them to it, and the shared minimum was wrong anyway: it was a flat 0.5 m
+ * while the real floor scales with the field's spacing, which
+ * `fieldExtentForSite` stretches on large lots. Below that floor a drag paints
+ * nothing at all (see `MIN_BRUSH_RADIUS_IN_SPACINGS`).
+ *
+ * The max is clamped to stay above the min so the range never inverts on a lot
+ * big enough that the minimum passes 20 m — the brush ends up pinned to one
+ * usable size, which is honest, rather than to an empty range.
+ */
+export function brushRadiusRange(site: SiteNode | null | undefined): [number, number] {
+  // Spacing, not the field: this runs on every render of the panel, and
+  // `sculptFieldForSite` would decode or allocate up to 257² samples to read one
+  // number off the result. An existing field's spacing is on the node; a lot with
+  // no terrain yet gets the spacing it *would* be given.
+  const spacing = site
+    ? (site.terrain?.spacing ?? fieldExtentForSite(site).spacing)
+    : DEFAULT_TERRAIN_SPACING
+  const min = minBrushRadius({ spacing })
+  return [min, Math.max(min, MAX_BRUSH_RADIUS)]
+}
+
+/** `radius` clamped into `brushRadiusRange(site)`. */
+export function clampBrushRadius(site: SiteNode | null | undefined, radius: number): number {
+  const [min, max] = brushRadiusRange(site)
+  return Math.min(max, Math.max(min, radius))
+}
+
+/**
+ * The absolute height a `flatten` stroke aims at.
+ *
+ * `null` target means the user never picked one, so the first click samples the
+ * ground under the cursor — flatten stays usable without ever opening a number
+ * field, and "flatten this pad to match that corner" is a two-step gesture.
+ */
+export function resolveFlattenTarget(
+  field: TerrainField,
+  explicitTarget: number | null,
+  x: number,
+  z: number,
+): number {
+  return explicitTarget ?? sampleTarget(field, x, z)
+}
+
+export type SculptCommit = {
+  verb: TerrainVerb
+  settings: BrushSettings
+}
+
+/**
+ * Drop any stroke in flight on `site` before a write that replaces the whole field.
+ *
+ * Every reader prefers the live stroke over the persisted terrain (that is what
+ * makes a drag consistent), so a lot-wide write landing *under* a live stroke is
+ * invisible: the ground keeps showing the stroke, and the stroke's own commit —
+ * computed from a snapshot taken before the write — then overwrites it. The user
+ * sees a button that did nothing, with no error and nothing in history to undo.
+ *
+ * Reachable because the brush and these controls are usable at the same moment.
+ * On touch it takes no timing at all: one finger holds a stroke while the other
+ * taps the panel. With a mouse a stroke stays live across a wheel zoom's 500 ms
+ * `cameraDragging` window, and a held pointer that leaves the canvas keeps its
+ * capture until release.
+ *
+ * Abandoning rather than committing first: the pending dabs are the thing the
+ * user is replacing, so keeping them would mean "level the lot, except where I
+ * happened to be mid-drag". Ending the live stroke without committing reverts it
+ * exactly, the same as Escape.
+ */
+function abandonLiveStroke(site: Pick<SiteNode, 'id'>): void {
+  useLiveTerrain.getState().end(site.id)
+}
+
+/**
+ * Flatten the whole site to one height in a single step.
+ *
+ * The brush cannot do this well and should not have to: covering a lot with dabs
+ * is dozens of strokes, and any sample the brush misses leaves a ridge that is
+ * invisible until a slab lands on it. Sizing from `fieldExtentForSite` means the
+ * result covers the padded extent, so the property line stays on flat ground too.
+ */
+export function flattenSite(site: SiteNode, metres: number): void {
+  abandonLiveStroke(site)
+  const field = sculptFieldForSite(site)
+  const value = quantize(field, metres)
+  const heights = new Int16Array(field.heights.length)
+  heights.fill(value)
+  commitStroke(site.id, { ...field, heights })
+}
+
+/**
+ * Drop a site's terrain entirely, back to the implicit flat ground.
+ *
+ * Distinct from flattening to 0: this removes the `terrain` field, so the scene
+ * returns to the exact state it had before terrain was ever touched rather than
+ * carrying a field of zeroes. Undo-able like any other sculpt.
+ */
+export function resetSiteTerrain(site: SiteNode): void {
+  // Before the `site.terrain` guard, not after: a stroke on a site that has no
+  // persisted terrain yet is exactly the case that reaches the early return, and
+  // leaving it live would keep showing sculpted ground the scene graph has none of.
+  abandonLiveStroke(site)
+  if (!site.terrain) return
+  runAsSingleSceneHistoryStep(useScene, () => {
+    useScene.getState().updateNode(site.id, { terrain: undefined })
+  })
+}
+
+/**
+ * Persist a finished stroke as exactly one undo step.
+ *
+ * `runAsSingleSceneHistoryStep` collapses the write, which matters because a
+ * stroke is one user action even though it produced dozens of dabs — without it,
+ * undo would walk back through the stroke dab by dab, which is both surprising
+ * and unbounded in length.
+ *
+ * A stroke that leaves the field at the datum writes `undefined` rather than
+ * ~11 KB of base64 zeroes: sculpting up and then flattening back down should
+ * return the scene to the state it would have had if terrain were never touched,
+ * not merely to a visually identical one.
+ */
+export function commitStroke(siteId: SiteNode['id'], field: TerrainField): void {
+  runAsSingleSceneHistoryStep(useScene, () => {
+    useScene.getState().updateNode(siteId, {
+      terrain: isDatumField(field) ? undefined : commitTerrainField(field),
+    })
+  })
+}

package/src/lib/terrain-verb-color.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from 'bun:test'
+import type { TerrainVerb } from '@pascal-app/core'
+import { brushRingColor } from './terrain-verb-color'
+
+/**
+ * The brush ring is the only thing at the point of action that can say what the
+ * next drag will do. Sculpt is a *sustained* mode, so the verb a user armed a
+ * minute ago is still armed — and the ring's geometry is identical for all four
+ * verbs, which leaves colour as the only channel carrying that state.
+ *
+ * These assert the property rather than the palette: which hex is taste, but "no
+ * two states look alike" is correctness, and it is the thing that silently breaks
+ * when a fifth verb is added (terrace is planned).
+ */
+
+const VERBS: TerrainVerb[] = ['raise', 'lower', 'flatten', 'smooth']
+
+describe('brushRingColor', () => {
+  test('no two verbs share a colour', () => {
+    const colors = VERBS.map((verb) => brushRingColor(verb, false))
+    expect(new Set(colors).size).toBe(VERBS.length)
+  })
+
+  test('raise and lower are the pair that must never be confused', () => {
+    // The original bug: one amber ring for both, so the only way to know which way
+    // the ground would move was to look away from the cursor at the panel.
+    expect(brushRingColor('raise', false)).not.toBe(brushRingColor('lower', false))
+  })
+
+  test('flatten and smooth differ too', () => {
+    // Both are "neither up nor down", but one drives ground to a target height you
+    // can set wrongly and the other only softens what is there.
+    expect(brushRingColor('flatten', false)).not.toBe(brushRingColor('smooth', false))
+  })
+
+  test('sampling overrides every verb with one distinct colour', () => {
+    // While the eyedropper is armed the click does not apply the verb at all, so
+    // the ring must not read as any of them.
+    const sampled = VERBS.map((verb) => brushRingColor(verb, true))
+    expect(new Set(sampled).size).toBe(1)
+    for (const verb of VERBS) {
+      expect(brushRingColor(verb, true)).not.toBe(brushRingColor(verb, false))
+    }
+  })
+
+  test('every verb resolves to a colour, so a new verb cannot fall through', () => {
+    for (const verb of VERBS) {
+      expect(brushRingColor(verb, false)).toMatch(/^#[0-9a-f]{6}$/)
+    }
+  })
+})

package/src/lib/terrain-verb-color.ts

@@ -0,0 +1,58 @@
+// The verb→colour mapping, shared by the brush ring on the canvas and the verb
+// picker in the panel.
+//
+// Its own module because the two consumers cannot import each other: the ring is an
+// R3F component (`useFrame`, `three`) and the panel is a plain sidebar surface that
+// must not drag a render loop into its module graph. Duplicating four hex strings
+// across them would be the version that silently drifts — and drift here is not
+// cosmetic, since the whole point is that the two surfaces agree.
+
+import type { TerrainVerb } from '@pascal-app/core'
+
+/**
+ * One colour per verb, because the brush ring's geometry is identical for all four.
+ *
+ * A single colour made raise and lower visually indistinguishable: same circle, same
+ * amber, opposite effect — so the only way to know which way the next drag moves the
+ * ground was to look away from the cursor at the panel. The verb is also the one piece
+ * of sculpt state a user loses track of between strokes, since the mode is sustained
+ * and an intent set a minute ago is still armed.
+ *
+ * Values are the repo's existing palette (`ui/primitives/color-dot.tsx`) used with its
+ * established meanings — green for additive, red for destructive (`#ef4444` is already
+ * the delete cursor badge and the 2D delete stroke), blue and violet for the two
+ * operations that move ground neither up nor down. Amber is deliberately retired rather
+ * than kept for one verb: reusing the old colour for `raise` alone would leave every
+ * existing screenshot ambiguous.
+ *
+ * All four differ, including flatten vs smooth. Giving those two the same blue would
+ * reproduce the gap this closes, one pair over: both are "neither up nor down", but one
+ * drives ground to a *target height* you can set wrongly and the other only softens
+ * what is already there — confusing them costs a stroke.
+ */
+export const TERRAIN_VERB_COLOR: Record<TerrainVerb, string> = {
+  raise: '#22c55e',
+  lower: '#ef4444',
+  flatten: '#3b82f6',
+  smooth: '#a855f7',
+}
+
+/**
+ * Picking a height, not applying a verb — so the ring must not read as any of them.
+ * The eyedropper is a one-shot arm whose UI lives in the panel; the cursor is the only
+ * thing at the point of action that can say "this click samples rather than sculpts".
+ */
+export const TERRAIN_SAMPLING_COLOR = '#f59e0b'
+
+/**
+ * The brush ring's colour for a given brush state.
+ *
+ * A function rather than a lookup at the call site because sampling *outranks* the
+ * verb — while the eyedropper is armed the click does not apply the verb at all, so
+ * showing the verb's colour would promise the wrong action. Keeping that precedence in
+ * one place also makes it assertable: "no two states look alike" is a property, and one
+ * worth checking rather than re-eyeballing every time a verb is added.
+ */
+export function brushRingColor(verb: TerrainVerb, sampling: boolean): string {
+  return sampling ? TERRAIN_SAMPLING_COLOR : TERRAIN_VERB_COLOR[verb]
+}

package/src/lib/touch-gesture-priority.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from 'bun:test'
+import type { Mode } from '../store/use-editor'
+import { editorOwnsOneFingerDrag } from './touch-gesture-priority'
+
+/**
+ * One finger on a touch screen is one pointer, so the camera and the editor
+ * cannot both have it. These lock which side wins, because the failure is silent:
+ * the loser's handlers simply never fire.
+ */
+describe('editorOwnsOneFingerDrag', () => {
+  const ALL_MODES: Mode[] = [
+    'select',
+    'edit',
+    'delete',
+    'build',
+    'material-paint',
+    'terrain-sculpt',
+  ]
+
+  test('the camera keeps one finger when nothing is going on', () => {
+    expect(editorOwnsOneFingerDrag({ mode: 'select', activeGesture: false })).toBe(false)
+  })
+
+  test('both brush modes claim it with no transient gesture at all', () => {
+    // The regression: a brush mode arms nothing that the transient terms can see,
+    // so before this the camera orbited under a one-finger sculpt or paint drag.
+    expect(editorOwnsOneFingerDrag({ mode: 'terrain-sculpt', activeGesture: false })).toBe(true)
+    expect(editorOwnsOneFingerDrag({ mode: 'material-paint', activeGesture: false })).toBe(true)
+  })
+
+  test('a live gesture claims it in every mode', () => {
+    for (const mode of ALL_MODES) {
+      expect(editorOwnsOneFingerDrag({ mode, activeGesture: true })).toBe(true)
+    }
+  })
+
+  test('the non-brush modes leave it to the camera when idle', () => {
+    // Asserted as the complement of the brush set rather than a list, so adding a
+    // third brush mode cannot quietly land here as "camera wins".
+    const idle = ALL_MODES.filter(
+      (mode) => !editorOwnsOneFingerDrag({ mode, activeGesture: false }),
+    )
+    expect(idle).toEqual(['select', 'edit', 'delete', 'build'])
+  })
+})

package/src/lib/touch-gesture-priority.ts

@@ -0,0 +1,30 @@
+import type { Mode } from '../store/use-editor'
+import { isBrushMode } from '../store/use-editor'
+
+/**
+ * Whether the editor — rather than the camera — owns a one-finger touch drag.
+ *
+ * On touch there is exactly one pointer, so the camera and the editor cannot both
+ * have it: `custom-camera-controls` maps one finger to `TOUCH_ROTATE` by default
+ * (orbiting a phone with one thumb is the common case) and to `NONE` while an
+ * editor gesture is live, which lets the tool's own pointer handlers through.
+ * Two fingers always pinch and three always orbit, so the camera is never
+ * unreachable — that is what makes yielding one finger safe.
+ *
+ * Extracted from the component because the terms are not obviously exhaustive and
+ * one was missing. A *brush mode* owns the drag exactly the way an armed tool
+ * does, but none of the other terms notice it: entering paint or sculpt **clears**
+ * `tool`, and the scope it holds is `painting`/`sculpting`, not `handle-drag`. So
+ * on a tablet a one-finger drag over the ground orbited the camera instead of
+ * sculpting — and set `cameraDragging`, which the sculpt tool gates pointer-down
+ * on, so the stroke could not start either. The brush was simply inert on touch,
+ * in both brush modes.
+ *
+ * `activeGesture` is the OR of the transient signals the component already reads
+ * (an armed tool, a moving node, an endpoint reshape, a handle drag, marquee
+ * box-select); they stay in the component because each is its own subscription,
+ * while what is worth pinning down here is that a sustained *mode* counts too.
+ */
+export function editorOwnsOneFingerDrag(args: { mode: Mode; activeGesture: boolean }): boolean {
+  return args.activeGesture || isBrushMode(args.mode)
+}

package/src/lib/window-interaction.ts

@@ -23,7 +23,7 @@ export function isOperableWindowType(windowType: string | undefined) {
   )
 }
 
-function getDisplayedWindowValue(windowId: AnyNodeId, nodeValue: number | undefined) {
+export function getDisplayedWindowValue(windowId: AnyNodeId, nodeValue: number | undefined) {
   const interactive = useInteractive.getState()
   const runtimeValue = interactive.windows[windowId]?.operationState
   if (runtimeValue !== undefined) return runtimeValue

package/src/store/camera-pose-store.test.ts

@@ -0,0 +1,29 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import type { CameraPose } from '@pascal-app/core'
+import { cameraPoseStore, publishCameraPose, subscribeCameraPose } from './camera-pose-store'
+
+const pose: CameraPose = {
+  position: [3, 4, 5],
+  projection: 'perspective',
+  target: [0, 1, 0],
+  viewWidth: 12,
+}
+
+afterEach(() => {
+  cameraPoseStore.setState({ pose: null })
+})
+
+describe('camera pose store', () => {
+  test('replays the latest pose and streams later poses to focused subscribers', () => {
+    publishCameraPose(pose)
+    const received: CameraPose[] = []
+    const unsubscribe = subscribeCameraPose((nextPose) => received.push(nextPose))
+    const nextPose = { ...pose, viewWidth: 8 }
+
+    publishCameraPose(nextPose)
+    unsubscribe()
+    publishCameraPose({ ...pose, viewWidth: 4 })
+
+    expect(received).toEqual([pose, nextPose])
+  })
+})

package/src/store/camera-pose-store.ts

@@ -0,0 +1,27 @@
+import type { CameraPose } from '@pascal-app/core'
+import { subscribeWithSelector } from 'zustand/middleware'
+import { createStore } from 'zustand/vanilla'
+
+type CameraPoseState = {
+  pose: CameraPose | null
+}
+
+export const cameraPoseStore = createStore<CameraPoseState>()(
+  subscribeWithSelector<CameraPoseState>(() => ({ pose: null })),
+)
+
+export function publishCameraPose(pose: CameraPose) {
+  cameraPoseStore.setState({ pose })
+}
+
+export function subscribeCameraPose(listener: (pose: CameraPose) => void) {
+  const currentPose = cameraPoseStore.getState().pose
+  if (currentPose) listener(currentPose)
+
+  return cameraPoseStore.subscribe(
+    (state) => state.pose,
+    (pose) => {
+      if (pose) listener(pose)
+    },
+  )
+}