@pascal-app/editor 1.0.4 → 1.0.6

package/src/lib/follow-pascal.ts

@@ -0,0 +1,284 @@
+import { type CameraPose, criticallyDamped } from '@pascal-app/core'
+
+/**
+ * Follow Pascal: the camera follows what the agent is building (the owner, 2026-10-08). It eases to
+ * what the current step works on, at the distance its scale needs; stays about 1.5 s on each target at
+ * least; frames what lands together as one; keeps the horizon level (it moves as an orbit about the
+ * thing it looks at, never as a free flight); and moves like a critically damped spring.
+ *
+ * Everything here is arithmetic on boxes and angles, so it is tested without a canvas; the component
+ * that feeds it the reveal's events and writes its poses to the camera is `FollowPascal`.
+ */
+
+export type Vec3 = [number, number, number]
+export type Box = { min: Vec3; max: Vec3 }
+
+/** What kind of thing a step works on decides how far and from how high it is looked at. */
+export type FollowKind = 'floor' | 'detail' | 'roof' | 'furnish' | 'group'
+
+export type FollowWant = {
+  box: Box
+  kind: FollowKind
+  levelId?: string
+  nodeIds?: readonly string[]
+  /** The outward direction of the wall it is on, in the plan (x, z), for what is looked at square on. */
+  normal?: [number, number]
+  /** The eye must stand above this height (metres): a roof lifted out of the way is looked down through, not from within. */
+  eyeAbove?: number
+  /**
+   * What it works on is seen from outside (an exterior wall bent, a window moved on one, a roof, the
+   * ground): the view is from outdoors with no cutaway, whatever hides the target.
+   */
+  exterior?: boolean
+  /** When it was asked for, in seconds on the follower's clock. */
+  at: number
+}
+
+/** The camera stays on a target at least this long. */
+export const FOLLOW_DWELL_S = 1.5
+/** What lands within this of the first is framed with it. */
+export const FOLLOW_GATHER_S = 0.35
+/** How long a flight takes: a spring's response, not a duration. */
+export const FOLLOW_RESPONSE_S = 1.1
+
+/** The eye's elevation above the horizon for each kind, in radians. */
+export const FOLLOW_ELEVATION: Record<FollowKind, number> = {
+  floor: 0.5,
+  detail: 0.27,
+  roof: 0.61,
+  furnish: 0.92,
+  group: 0.45,
+}
+
+const centreOf = ({ min, max }: Box): Vec3 => [
+  (min[0] + max[0]) / 2,
+  (min[1] + max[1]) / 2,
+  (min[2] + max[2]) / 2,
+]
+const sizeOf = ({ min, max }: Box): Vec3 => [max[0] - min[0], max[1] - min[1], max[2] - min[2]]
+
+/** What lands together, as one target: the union of their boxes, a common direction if they share one. */
+export function mergeWants(wants: readonly FollowWant[]): FollowWant {
+  const first = wants[0]!
+  const min: Vec3 = [...first.box.min]
+  const max: Vec3 = [...first.box.max]
+  for (const { box } of wants) {
+    for (let axis = 0; axis < 3; axis += 1) {
+      min[axis] = Math.min(min[axis]!, box.min[axis]!)
+      max[axis] = Math.max(max[axis]!, box.max[axis]!)
+    }
+  }
+  const kind = wants.every((want) => want.kind === first.kind) ? first.kind : 'group'
+  let normal: [number, number] | undefined
+  if (wants.every((want) => want.normal)) {
+    const sum: [number, number] = [0, 0]
+    for (const want of wants) {
+      sum[0] += want.normal![0]
+      sum[1] += want.normal![1]
+    }
+    const length = Math.hypot(sum[0], sum[1])
+    // They share a direction only when they mostly agree: the length of the sum over their count.
+    if (length / wants.length > 0.6) normal = [sum[0] / length, sum[1] / length]
+  }
+  const eyes = wants.flatMap((want) => (want.eyeAbove === undefined ? [] : [want.eyeAbove]))
+  const nodeIds = [...new Set(wants.flatMap((want) => want.nodeIds ?? []))]
+  return {
+    box: { min, max },
+    kind,
+    ...(first.levelId ? { levelId: first.levelId } : {}),
+    ...(nodeIds.length ? { nodeIds } : {}),
+    ...(normal ? { normal } : {}),
+    ...(eyes.length ? { eyeAbove: Math.max(...eyes) } : {}),
+    // Seen from outside when any of what lands together is: a mixed step takes the outside view.
+    ...(wants.some((want) => want.exterior) ? { exterior: true } : {}),
+    at: Math.max(...wants.map((want) => want.at)),
+  }
+}
+
+/**
+ * Decides when the camera changes target. Wants are gathered for a moment so things landing together
+ * are framed as one, and the camera never leaves a target before its dwell is over.
+ */
+export class Follower {
+  private pending: FollowWant[] = []
+  private last = Number.NEGATIVE_INFINITY
+
+  want(want: FollowWant): void {
+    this.pending.push(want)
+  }
+
+  /** The target to fly to now, if one is due. `blocked` holds it (the person is pointing at something). */
+  due(now: number, blocked = false): FollowWant | null {
+    const oldest = this.pending[0]
+    if (!oldest || blocked) return null
+    if (now - this.last < FOLLOW_DWELL_S || now - oldest.at < FOLLOW_GATHER_S) return null
+    const nextFloor = this.pending.findIndex((want) => want.levelId !== oldest.levelId)
+    const count = nextFloor < 0 ? this.pending.length : nextFloor
+    const merged = mergeWants(this.pending.splice(0, count))
+    this.last = now
+    return merged
+  }
+
+  /** Forgets what waits and starts its dwell over (a new build; the person took the camera back). */
+  reset(): void {
+    this.pending = []
+    this.last = Number.NEGATIVE_INFINITY
+  }
+}
+
+export type OrbitValue = { x: number; y: number; z: number; r: number; az: number; el: number }
+
+export type FollowView = {
+  /** The camera's vertical field of view, in degrees. */
+  fov: number
+  /** The canvas' width over its height. */
+  aspect: number
+  /** Where the camera looks from now, so a flight takes the nearest way round. */
+  azimuth: number
+}
+
+const clamp = (value: number, low: number, high: number) => Math.min(high, Math.max(low, value))
+const TAU = Math.PI * 2
+
+/** The angle `to` written as the nearest equivalent of `from`, so it never goes the long way round. */
+export function nearestTurn(to: number, from: number): number {
+  let angle = to
+  while (angle - from > Math.PI) angle -= TAU
+  while (angle - from < -Math.PI) angle += TAU
+  return angle
+}
+
+/**
+ * Where the camera stands to see `want`: the box's centre, its scale decides how far (a window up
+ * close, a floor whole, a group between) at the elevation of its kind, from the side nearest the way
+ * it already looks, or square to the wall it is on.
+ */
+export function frameOf(want: FollowWant, view: FollowView): OrbitValue {
+  const [cx, cy, cz] = centreOf(want.box)
+  const [sx, sy, sz] = sizeOf(want.box)
+  const detail = want.kind === 'detail'
+  const extent = Math.max(sx, sz, sy * 1.4, detail ? 1.2 : 3)
+  const halfVertical = (view.fov * Math.PI) / 360
+  const halfHorizontal = Math.atan(Math.tan(halfVertical) * Math.max(0.5, view.aspect))
+  const fits = (extent * 0.5) / Math.tan(Math.min(halfVertical, halfHorizontal))
+  let r = clamp(fits * 1.25 + sy * 0.3, detail ? 2.8 : 6, 90)
+  const el = FOLLOW_ELEVATION[want.kind]
+  const eyeY = Math.max(cy, 0.9) + r * Math.sin(el)
+  if (want.eyeAbove !== undefined && eyeY < want.eyeAbove) {
+    // Further back along the same line of sight, until the eye is above what it must clear.
+    r = (want.eyeAbove - Math.max(cy, 0.9)) / Math.sin(el)
+  }
+  let az = view.azimuth
+  if (want.normal) {
+    const facing = Math.atan2(want.normal[0], want.normal[1])
+    // A little off square, to the side it is already seen from.
+    const [left, right] = [facing + 0.5, facing - 0.5]
+    az =
+      Math.abs(nearestTurn(left, view.azimuth) - view.azimuth) <=
+      Math.abs(nearestTurn(right, view.azimuth) - view.azimuth)
+        ? left
+        : right
+  }
+  return {
+    x: cx,
+    y: want.kind === 'roof' ? cy - 0.6 : Math.max(cy, 0.9),
+    z: cz,
+    r,
+    az: nearestTurn(az, view.azimuth),
+    el,
+  }
+}
+
+const KEYS = ['x', 'y', 'z', 'r', 'az', 'el'] as const
+
+function orbitPose({ x, y, z, r, az, el }: OrbitValue): CameraPose {
+  const flat = Math.cos(el)
+  return {
+    position: [x + r * flat * Math.sin(az), y + r * Math.sin(el), z + r * flat * Math.cos(az)],
+    target: [x, y, z],
+    projection: 'perspective',
+  }
+}
+
+/** Try a higher eye before turning away; never reorient an already clear view. */
+export function clearFrame(
+  goal: OrbitValue,
+  sees: (pose: CameraPose) => boolean,
+): OrbitValue | null {
+  for (const offset of [
+    0,
+    Math.PI / 6,
+    -Math.PI / 6,
+    Math.PI / 3,
+    -Math.PI / 3,
+    Math.PI / 2,
+    -Math.PI / 2,
+  ]) {
+    for (const elevation of [goal.el, 0.9, 1.2, (75 * Math.PI) / 180]) {
+      const candidate = { ...goal, az: goal.az + offset, el: Math.max(goal.el, elevation) }
+      if (sees(orbitPose(candidate))) return candidate
+    }
+  }
+  return null
+}
+
+/** The camera as six springs on an orbit: the point it looks at, how far, and which way round. */
+export class OrbitSpring {
+  private states = Object.fromEntries(KEYS.map((key) => [key, { x: 0, v: 0 }])) as Record<
+    (typeof KEYS)[number],
+    { x: number; v: number }
+  >
+  private goal: OrbitValue
+
+  constructor(
+    start: OrbitValue,
+    private response = FOLLOW_RESPONSE_S,
+  ) {
+    this.goal = { ...start }
+    this.snap(start)
+  }
+
+  snap(value: OrbitValue): void {
+    this.goal = { ...value }
+    for (const key of KEYS) this.states[key] = { x: value[key], v: 0 }
+  }
+
+  /** Flies to `value`, from where it is, carrying its speed. */
+  to(value: OrbitValue): void {
+    this.goal = { ...value, az: nearestTurn(value.az, this.states.az.x) }
+  }
+
+  step(dt: number): void {
+    for (const key of KEYS) criticallyDamped(this.states[key], this.goal[key], this.response, dt)
+  }
+
+  value(): OrbitValue {
+    return Object.fromEntries(KEYS.map((key) => [key, this.states[key].x])) as OrbitValue
+  }
+
+  /** The orbit read off a camera that is already somewhere. */
+  fromPose(pose: CameraPose): void {
+    const dx = pose.position[0] - pose.target[0]
+    const dy = pose.position[1] - pose.target[1]
+    const dz = pose.position[2] - pose.target[2]
+    const r = Math.hypot(dx, dy, dz) || 1
+    this.snap({
+      x: pose.target[0],
+      y: pose.target[1],
+      z: pose.target[2],
+      r,
+      az: Math.atan2(dx, dz),
+      el: Math.asin(clamp(dy / r, -1, 1)),
+    })
+  }
+
+  /** Where the camera is now: at the radius and angles about its centre, always looking at it, level. */
+  pose(): CameraPose {
+    return orbitPose(this.value())
+  }
+
+  /** The goal it is flying to. */
+  destination(): OrbitValue {
+    return { ...this.goal }
+  }
+}

package/src/lib/fresh-planar-placement.test.ts

@@ -3,18 +3,24 @@ import {
   type AnyNode,
   type AnyNodeDefinition,
   type AnyNodeId,
+  BuildingNode,
   beginSceneHistoryPauseSession,
   CabinetModuleNode,
   CabinetNode,
   findLevelAncestorId,
   getSceneHistoryPauseDepth,
+  type LevelNode,
   nodeRegistry,
   pauseSceneHistory,
+  RoofNode,
+  RoofSegmentNode,
   registerNode,
   resumeSceneHistory,
   type SceneCommit,
   subscribeSceneCommits,
   useScene,
+  WallNode,
+  WindowNode,
 } from '@pascal-app/core'
 import { z } from 'zod'
 import {
@@ -223,6 +229,102 @@ describe('commitFreshPlacementSubtree', () => {
     expect((useScene.getState().nodes[LEVEL_ID] as { children: AnyNodeId[] }).children).toEqual([])
   })
 
+  // A roof lives on the level above the walls that carry it: one dropped onto them (a duplicate
+  // in hand) goes there in the placement's one step.
+  test('a roof dropped onto the walls that carry it lands on a new Roof level, in the one step', () => {
+    const corners: [number, number][] = [
+      [0, 0],
+      [8, 0],
+      [8, 6],
+      [0, 6],
+    ]
+    const walls = corners.map((start, i) =>
+      WallNode.parse({ parentId: LEVEL_ID, start, end: corners[(i + 1) % 4], height: 2.5 }),
+    )
+    const segment = RoofSegmentNode.parse({ width: 8, depth: 6, wallHeight: 0 })
+    const draft = RoofNode.parse({
+      parentId: LEVEL_ID,
+      visible: false,
+      metadata: { isNew: true },
+      children: [segment.id],
+    })
+    const building = BuildingNode.parse({ children: [LEVEL_ID] })
+    useScene.setState({
+      nodes: {
+        [building.id]: building,
+        [LEVEL_ID]: {
+          ...level([...walls.map((wall) => wall.id), draft.id]),
+          parentId: building.id,
+          height: 2.5,
+        },
+        ...Object.fromEntries(walls.map((wall) => [wall.id, wall])),
+        [draft.id]: draft,
+        [segment.id]: { ...segment, parentId: draft.id },
+      },
+      rootNodeIds: [building.id],
+      collections: {},
+      dirtyNodes: new Set(),
+    } as never)
+    useScene.temporal.getState().clear()
+
+    const committedId = commitFreshPlacementSubtree(draft.id, {
+      position: [4, 2.5, 3],
+      visible: true,
+    } as Partial<AnyNode>)!
+    const nodes = useScene.getState().nodes
+    const roofLevel = nodes[nodes[committedId]!.parentId as AnyNodeId] as LevelNode
+    expect(roofLevel).toMatchObject({ type: 'level', metadata: { role: 'roof' } })
+    expect(roofLevel.children as string[]).toEqual([committedId])
+    expect((nodes[LEVEL_ID] as LevelNode).children as string[]).not.toContain(committedId)
+    expect(useScene.getState().rootNodeIds).toEqual([building.id])
+
+    useScene.temporal.getState().undo()
+    expect(useScene.getState().nodes[committedId]).toBeUndefined()
+    expect(useScene.getState().nodes[roofLevel.id]).toBeUndefined()
+  })
+
+  test('a window joined at a corner while in hand stays joined: its partner names the committed window', () => {
+    const wall = WallNode.parse({ id: 'wall_a', parentId: LEVEL_ID, start: [4, 0], end: [0, 0] })
+    const other = WallNode.parse({ id: 'wall_b', parentId: LEVEL_ID, start: [0, 0], end: [0, 3] })
+    const draft = WindowNode.parse({
+      id: 'window_draft',
+      parentId: wall.id,
+      wallId: wall.id,
+      position: [3.5, 1.5, 0],
+      width: 1,
+      visible: false,
+      metadata: { isNew: true },
+      corner: { end: 'end', partnerId: 'window_partner', post: 'none' },
+    })
+    const partner = WindowNode.parse({
+      id: 'window_partner',
+      parentId: other.id,
+      wallId: other.id,
+      position: [0.5, 1.5, 0],
+      width: 1,
+      corner: { end: 'start', partnerId: draft.id, post: 'none' },
+    })
+    useScene.setState({
+      nodes: {
+        [LEVEL_ID]: level([wall.id as AnyNodeId, other.id as AnyNodeId]),
+        [wall.id]: { ...wall, children: [draft.id] } as AnyNode,
+        [other.id]: { ...other, children: [partner.id] } as AnyNode,
+        [draft.id]: draft as AnyNode,
+        [partner.id]: partner as AnyNode,
+      },
+      rootNodeIds: [LEVEL_ID],
+      collections: {},
+      dirtyNodes: new Set(),
+    } as never)
+
+    const committedId = commitFreshPlacementSubtree(draft.id as AnyNodeId, { visible: true })
+
+    const nodes = useScene.getState().nodes as Record<string, AnyNode>
+    expect(committedId).toBeTruthy()
+    expect((nodes[committedId!] as WindowNode).corner?.partnerId).toBe(partner.id)
+    expect((nodes[partner.id] as WindowNode).corner?.partnerId).toBe(committedId!)
+  })
+
   test("never records inside another owner's pause", () => {
     pauseSceneHistory(useScene)
     try {
@@ -280,6 +382,16 @@ describe('commitFreshPlacementSubtree', () => {
     expect((source as AnyNode & { children: AnyNodeId[] }).children).toEqual(['item_original'])
   })
 
+  // A copy of one side of a corner window kept naming the original's partner, which never named it
+  // back: a link that made the copy refuse to join another window.
+  test('a copy of one side of a corner window is a plain window', () => {
+    const side = WindowNode.parse({
+      corner: { end: 'end', partnerId: 'window_partner', post: 'none' },
+    })
+    expect((prepareFreshPlacementRootDuplicate(side) as WindowNode).corner).toBeUndefined()
+    expect(side.corner?.partnerId).toBe('window_partner')
+  })
+
   test('commits a duplicated cabinet draft without deleting the original modules', () => {
     seedCabinetRun()
     useScene.temporal.getState().clear()

package/src/lib/fresh-planar-placement.ts

@@ -8,14 +8,17 @@ import {
   collectSubtree,
   createSceneApi,
   type DuplicableConfig,
+  getEffectiveNode,
   getSceneHistoryPauseDepth,
   getSurfaceProvider,
   nodeRegistry,
   resolveSurfacePlacement,
   runSceneHistoryDraftWrite,
   type SurfaceRejectReason,
+  seatRoofs,
   useScene,
 } from '@pascal-app/core'
+import { remapNodeReferences } from '@pascal-app/core/clone-scene-graph'
 import { evaluateRecipe, isProceduralItem } from '@pascal-app/core/procedural-items'
 import useInteractionScope from '../store/use-interaction-scope'
 import usePlacementPreview from '../store/use-placement-preview'
@@ -39,6 +42,47 @@ function parentIdOf(node: AnyNode): AnyNodeId | undefined {
   return parentId ?? undefined
 }
 
+/**
+ * The nodes the draft root names, outside its subtree and other than its parent, that name it
+ * back (a corner window's partner, joined while the draft was in hand). The commit gives the
+ * root a new id, so they are rewritten to name the committed node, never the deleted draft.
+ */
+function peerReferenceUpdates(
+  nodes: Readonly<Record<string, AnyNode>>,
+  root: AnyNode,
+  subtreeIds: ReadonlySet<string>,
+  committedId: AnyNodeId,
+): { id: AnyNodeId; data: Partial<AnyNode> }[] {
+  const named = new Set<string>()
+  const visit = (value: unknown) => {
+    if (typeof value === 'string') {
+      if (nodes[value] && !subtreeIds.has(value) && value !== root.parentId) named.add(value)
+    } else if (Array.isArray(value)) value.forEach(visit)
+    else if (value && typeof value === 'object') Object.values(value).forEach(visit)
+  }
+  const {
+    id: _id,
+    parentId: _parentId,
+    children: _children,
+    ...fields
+  } = root as AnyNode & {
+    children?: unknown
+  }
+  visit(fields)
+  const ids = new Map([[root.id, committedId as string]])
+  return [...named].flatMap((id) => {
+    const peer = nodes[id]!
+    const remapped = remapNodeReferences(peer, ids) as Record<string, unknown>
+    const data = Object.fromEntries(
+      Object.entries(remapped).filter(
+        ([key, value]) =>
+          JSON.stringify(value) !== JSON.stringify((peer as Record<string, unknown>)[key]),
+      ),
+    )
+    return Object.keys(data).length ? [{ id: id as AnyNodeId, data: data as Partial<AnyNode> }] : []
+  })
+}
+
 /**
  * Create ops for a clone of scene nodes: each copy joins the collections its
  * source is in, whatever its kind.
@@ -80,6 +124,8 @@ export function prepareFreshPlacementRootDuplicate(node: AnyNode): AnyNode {
     metadata?: unknown
   }
   delete duplicate.id
+  // A copy of one side of a corner window is a plain window: its partner stays with the original.
+  delete duplicate.corner
   if (Array.isArray(duplicate.children)) duplicate.children = []
   duplicate.metadata = {
     ...getPlacementMetadataRecord(stripPlacementMetadataFlags(duplicate.metadata)),
@@ -255,7 +301,9 @@ export function commitFreshPlacementSubtree(
     onReject?.(rejection)
     return null
   }
-  const descendants = subtree.descendants.map((node) => cleanPlacementMetadata(node))
+  const descendants = subtree.descendants.map((node) =>
+    cleanPlacementMetadata(getEffectiveNode(node)),
+  )
   const parentId = parentIdOf(root)
   const cloned = cloneNodesInto([root, ...descendants], { rootId, parentId })
   // The drafts' memberships, read before they are deleted.
@@ -269,6 +317,12 @@ export function commitFreshPlacementSubtree(
     if (previous === -1) updates.push(merged)
     else updates[previous] = merged
   }
+  const subtreeIds = new Set([rootId, ...descendants.map((node) => node.id)])
+  for (const update of peerReferenceUpdates(scene.nodes, root, subtreeIds, cloned.rootId))
+    if (!updates.some((entry) => entry.id === update.id)) updates.push(update)
+
+  // A roof dropped onto the walls that carry it goes to the level above them, in the same step.
+  const seated = seatRoofs(scene.nodes, { create, update: updates, delete: [rootId] }).changes
 
   const scope = useInteractionScope.getState()
   const factoryCreated =
@@ -282,13 +336,13 @@ export function commitFreshPlacementSubtree(
       useScene.getState().deleteNode(rootId)
     })
     recordPlacementStep(rootId, wasTracking, () =>
-      useScene.getState().applyNodeChanges({ create, update: updates }),
+      useScene.getState().applyNodeChanges({ create: seated.create, update: seated.update }),
     )
   } else {
     recordPlacementStep(rootId, wasTracking, () => {
       try {
         // applyNodeChanges validates the complete proposed graph before publishing any part of it.
-        scene.applyNodeChanges({ delete: [rootId], create, update: updates })
+        scene.applyNodeChanges(seated)
         for (const node of [subtree.root, ...subtree.descendants]) scene.clearDirty(node.id)
       } catch (error) {
         // Zustand publishes before notifying subscribers. A subscriber error must restore

package/src/lib/geometry-script/author.ts

@@ -54,6 +54,7 @@ export async function compileAndStoreGeometryScript(input: {
   nodeId?: string
   params?: Record<string, GeometryScriptParamValue>
   kind?: 'item' | 'door' | 'window' | 'column'
+  inputs?: Record<string, unknown>
   name?: string
   description?: string
   category?: string
@@ -80,7 +81,11 @@ export async function compileAndStoreGeometryScript(input: {
     if (!blenderBuilder) throw new Error('This editor cannot run Blender (bpy) scripts')
     return { ...(await blenderBuilder({ code, params, nodeId, metadata })), nodeId }
   }
-  const { glb, ...compiled } = await compileGeometryScriptInWorker({ code, params })
+  const { glb, ...compiled } = await compileGeometryScriptInWorker({
+    code,
+    params,
+    inputs: input.inputs,
+  })
   const context = { nodeId, metadata: { ...metadata, mount: compiled.mount } }
   const store = getArtifactStore()
   const [sha256] = await Promise.all([

package/src/lib/geometry-script/client.ts

@@ -138,10 +138,17 @@ function startSandbox(): Promise<Window> {
 export async function compileGeometryScriptInWorker(input: {
   code: string
   params?: Record<string, GeometryScriptParamValue>
+  /** What the host builds it for (a room's floor), in the host's frame. */
+  inputs?: Record<string, unknown>
 }): Promise<GeometryScriptCompileOutput> {
   const target = await startSandbox()
   const id = nextId++
-  const request: GeometryScriptWorkerRequest = { id, code: input.code, params: input.params }
+  const request: GeometryScriptWorkerRequest = {
+    id,
+    code: input.code,
+    params: input.params,
+    inputs: input.inputs,
+  }
   return new Promise((resolve, reject) => {
     const timeout = setTimeout(() => {
       reset(new Error(`The script ran longer than ${COMPILE_TIMEOUT_MS / 1000} s and was stopped`))