@pascal-app/editor 1.0.6 → 1.0.7

package/src/lib/glb-export.test.ts

@@ -15,11 +15,14 @@ import {
   SiteNode,
   sceneRegistry,
   useScene,
+  WindowNode,
 } from '@pascal-app/core'
 import { evaluateRecipe, ProceduralItemNode, parseRecipe } from '@pascal-app/core/procedural-items'
 import {
   buildDoorPreviewMesh,
+  buildWindowPreviewMesh,
   markViewerPresentationTextureBorrowed,
+  poseWindowMovingParts,
   type ViewerPresentationContribution,
   viewerPresentationRegistry,
 } from '@pascal-app/viewer'
@@ -1164,6 +1167,210 @@ describe('prepareSceneForExport', () => {
     expect(hasMesh).toBe(false)
   })
 
+  test.each(['tilt', 'turn'] as const)(
+    'bakes tilt-turn %s with attached hardware and grids at 0, 0.5 and 1',
+    (tiltTurnMode) => {
+      const node = WindowNode.parse({
+        windowType: 'tilt-turn',
+        tiltTurnMode,
+        hingesSide: 'right',
+        operationState: 0.6,
+        sill: false,
+        sashGrid: true,
+        columnRatios: [1, 1],
+        rollerShutter: 'box',
+        rollerShutterOpen: 0.5,
+      })
+      const mesh = buildWindowPreviewMesh(node)
+      const original = mesh.getObjectByName('tilt-turn-window-sash')!.quaternion.clone()
+      const root = new THREE.Group().add(mesh)
+      sceneRegistry.nodes.set(node.id, mesh)
+      const prepared = prepareSceneForExport(root, { [node.id]: node })
+      expect(prepared.animations).toHaveLength(2)
+      const clip = prepared.animations.find((clip) => clip.name === `${node.id}: open`)!
+      expect(clip.tracks).toHaveLength(1)
+      const target = prepared.scene.getObjectByProperty(
+        'uuid',
+        clip.tracks[0]!.name.replace('.quaternion', ''),
+      )!
+      expect(target.getObjectByName('window-handle')).toBeDefined()
+      expect(target.getObjectByName('window-sash-grid')).toBeDefined()
+      const mixer = new THREE.AnimationMixer(prepared.scene)
+      const action = mixer.clipAction(clip)
+      action.setLoop(THREE.LoopOnce, 1)
+      action.clampWhenFinished = true
+      action.play()
+      for (const value of [0, 0.5, 1]) {
+        mixer.setTime(value)
+        const live = buildWindowPreviewMesh({ ...node, operationState: value })
+        const liveSash = live.getObjectByName('tilt-turn-window-sash')!
+        expect(target.quaternion.clone().normalize().angleTo(liveSash.quaternion)).toBeLessThan(
+          1e-6,
+        )
+      }
+      expect(
+        mesh.getObjectByName('tilt-turn-window-sash')!.quaternion.angleTo(original),
+      ).toBeCloseTo(0)
+      mixer.stopAllAction()
+      prepared.dispose()
+    },
+  )
+
+  test.each(
+    (['box', 'concealed'] as const).flatMap((rollerShutter) =>
+      [0, 0.5, 1].map((shutterOpen) => ({ rollerShutter, shutterOpen })),
+    ),
+  )(
+    'bakes saved bifold shutters and $rollerShutter roller at $shutterOpen without changing live previews',
+    ({ shutterOpen, rollerShutter }) => {
+      const node = WindowNode.parse({
+        windowType: 'casement',
+        shutters: 'panel',
+        shutterOpen,
+        width: 2,
+        rollerShutter,
+        rollerShutterOpen: shutterOpen,
+      })
+      const mesh = buildWindowPreviewMesh(node)
+      const saved = mesh.getObjectByName('shutter-left')!.quaternion.clone()
+      poseWindowMovingParts(node, mesh, 0, 1 - shutterOpen)
+      const preview = mesh.getObjectByName('shutter-left')!.quaternion.clone()
+      // Simulate a live roller preview whose topology differs from the saved node.
+      mesh.getObjectByName('window-roller-curtain')!.clear()
+      sceneRegistry.nodes.set(node.id, mesh)
+      const prepared = prepareSceneForExport(new THREE.Group().add(mesh), { [node.id]: node })
+      expect(prepared.animations.map((clip) => clip.name)).toEqual([
+        `${node.id}: open`,
+        `${node.id}: shutters`,
+      ])
+      expect(prepared.animations[0]!.tracks).toHaveLength(1)
+      const extras = prepared.scene.getObjectByName(node.id)!.userData
+      expect(extras.shutters).toBe(true)
+      expect(extras.shuttersOpen).toBe(shutterOpen)
+      expect(extras.openable).toBe(true)
+      expect(extras.clips).toEqual(prepared.animations.map((clip) => clip.name))
+      const shutters = prepared.animations[1]!
+      expect(shutters.duration).toBe(1)
+      const leaves: THREE.Object3D[] = []
+      prepared.scene.traverse((part) => {
+        if (['shutter-left', 'shutter-right', 'shutter-outer'].includes(part.name))
+          leaves.push(part)
+      })
+      for (const leaf of leaves)
+        expect(shutters.tracks.some((track) => track.name === `${leaf.uuid}.quaternion`)).toBe(true)
+      const baked = prepared.scene.getObjectByName('shutter-left')!
+      const outer = baked.getObjectByName('shutter-outer')!
+      const expectedOuter = buildWindowPreviewMesh(node).getObjectByName('shutter-outer')!
+      expect(outer.quaternion.angleTo(expectedOuter.quaternion)).toBeCloseTo(0)
+      expect(baked.quaternion.angleTo(saved)).toBeCloseTo(0)
+      expect(mesh.getObjectByName('shutter-left')!.quaternion.angleTo(preview)).toBeCloseTo(0)
+      const curtain = prepared.scene.getObjectByName('window-roller-curtain')!
+      expect(curtain.children).toHaveLength(1)
+      expect(curtain.position.y).toBe(node.height / 2)
+      expect(curtain.scale.y).toBeCloseTo(1 - 0.98 * shutterOpen)
+      const panel = curtain.children[0] as THREE.Mesh
+      expect(panel.geometry.index!.count).toBe(Math.floor(node.height / 0.04) * 36)
+      const track = shutters.tracks.find((track) => track.name === `${curtain.uuid}.scale`)!
+      expect(Array.from(track.values)).toEqual([1, 1, 1, 1, expect.closeTo(0.02), 1])
+      expect(extras.rollerShutterAnimation).toBe('top-pivot-scale-y')
+      const mixer = new THREE.AnimationMixer(prepared.scene)
+      const action = mixer.clipAction(shutters).setLoop(THREE.LoopOnce, 1)
+      action.clampWhenFinished = true
+      action.play()
+      for (const fraction of [0, 0.25, 0.5, 0.75, 1]) {
+        mixer.setTime(fraction)
+        const expected = buildWindowPreviewMesh({ ...node, shutterOpen: fraction })
+        expect(
+          baked.quaternion
+            .clone()
+            .normalize()
+            .angleTo(expected.getObjectByName('shutter-left')!.quaternion),
+        ).toBeLessThan(1e-6)
+        expect(
+          outer.quaternion
+            .clone()
+            .normalize()
+            .angleTo(expected.getObjectByName('shutter-outer')!.quaternion),
+        ).toBeLessThan(1e-6)
+      }
+      mixer.stopAllAction()
+      prepared.dispose()
+    },
+  )
+
+  test('a shuttered casement exports independent sash and leaf rotations at its saved pose', () => {
+    const node = WindowNode.parse({
+      windowType: 'casement',
+      width: 1,
+      shutters: 'panel',
+      shutterOpen: 0.25,
+      rollerShutter: 'box',
+      rollerShutterOpen: 0.75,
+    })
+    const mesh = buildWindowPreviewMesh(node)
+    sceneRegistry.nodes.set(node.id, mesh)
+    const prepared = prepareSceneForExport(new THREE.Group().add(mesh), { [node.id]: node })
+    expect(prepared.animations.map((clip) => clip.name)).toEqual([
+      `${node.id}: open`,
+      `${node.id}: shutters`,
+    ])
+    const window = prepared.scene.getObjectByName(node.id)!
+    expect(window.userData.shuttersOpen).toBe(0.25)
+    expect(window.userData.rollerShutterOpen).toBe(0.75)
+    const curtain = window.getObjectByName('window-roller-curtain')!
+    expect(curtain.scale.y).toBeCloseTo(1 - 0.98 * 0.75)
+    const top = new THREE.Box3().setFromObject(curtain).max.y
+    const leaves = ['shutter-left', 'shutter-right'].map((name) => window.getObjectByName(name)!)
+    const clip = prepared.animations[1]!
+    expect(clip.tracks.map((track) => track.name)).toEqual([
+      ...leaves.map((leaf) => `${leaf.uuid}.quaternion`),
+      `${curtain.uuid}.scale`,
+    ])
+    for (const leaf of leaves)
+      expect(leaf.quaternion.angleTo(mesh.getObjectByName(leaf.name)!.quaternion)).toBeCloseTo(0)
+    const mixer = new THREE.AnimationMixer(prepared.scene)
+    const action = mixer.clipAction(clip).setLoop(THREE.LoopOnce, 1)
+    action.clampWhenFinished = true
+    action.play()
+    for (const fraction of [0, 0.25, 0.5, 0.75, 1]) {
+      mixer.setTime(fraction)
+      const expected = buildWindowPreviewMesh({ ...node, shutterOpen: fraction })
+      for (const leaf of leaves)
+        expect(
+          leaf.quaternion
+            .clone()
+            .normalize()
+            .angleTo(expected.getObjectByName(leaf.name)!.quaternion),
+        ).toBeLessThan(1e-6)
+      expect(new THREE.Box3().setFromObject(curtain).max.y).toBeCloseTo(top)
+    }
+    mixer.stopAllAction()
+    prepared.dispose()
+  })
+
+  test.each(['panel', 'roller'] as const)(
+    'a fixed window with %s shutters exports only its shutters clip',
+    (kind) => {
+      const node = WindowNode.parse({
+        windowType: 'fixed',
+        ...(kind === 'panel'
+          ? { shutters: 'panel', shutterOpen: 0.3 }
+          : { rollerShutter: 'box', rollerShutterOpen: 0.3 }),
+      })
+      const mesh = buildWindowPreviewMesh(node)
+      sceneRegistry.nodes.set(node.id, mesh)
+      const prepared = prepareSceneForExport(new THREE.Group().add(mesh), { [node.id]: node })
+      expect(prepared.animations.map((clip) => clip.name)).toEqual([`${node.id}: shutters`])
+      expect(mesh.userData.openable).toBeUndefined()
+      const extras = prepared.scene.getObjectByName(node.id)!.userData
+      expect(extras.openable).toBeUndefined()
+      expect(extras.shutters).toBe(true)
+      expect(extras.shuttersOpen).toBe(0.3)
+      expect(extras.clips).toEqual([`${node.id}: shutters`])
+      prepared.dispose()
+    },
+  )
+
   test('bakes a swing door into an open quaternion clip', () => {
     const root = new THREE.Group()
     const doorGroup = new THREE.Group()
@@ -1203,6 +1410,64 @@ describe('prepareSceneForExport', () => {
     expect(closed.angleTo(new THREE.Quaternion())).toBeCloseTo(0)
   })
 
+  for (const doorType of ['hinged', 'double', 'french'] as const) {
+    test(`bakes ${doorType} hardware with the leaf through closed/45/90° poses`, () => {
+      const node = DoorNode.parse({
+        id: `door_hardware_${doorType}`,
+        doorType,
+        swingAngle: Math.PI / 3,
+        position: [2, 1.05, 3],
+        rotation: [0, 0.4, 0],
+      })
+      const mesh = buildDoorPreviewMesh(node)
+      const root = new THREE.Group()
+      root.add(mesh)
+      sceneRegistry.nodes.set(node.id, mesh)
+      const { scene, animations } = prepareSceneForExport(root, { [node.id]: node })
+      expect(animations).toHaveLength(1)
+      const clip = animations[0]!
+      expect(clip.tracks).toHaveLength(doorType === 'hinged' ? 1 : 2)
+      const mixer = new THREE.AnimationMixer(scene)
+      const action = mixer.clipAction(clip)
+      action.setLoop(THREE.LoopOnce, 1)
+      action.clampWhenFinished = true
+      action.play()
+      for (const amount of [0, 0.5, 1]) {
+        mixer.setTime(amount)
+        scene.updateMatrixWorld(true)
+        const live = buildDoorPreviewMesh({ ...node, swingAngle: (amount * Math.PI) / 2 })
+        live.updateMatrixWorld(true)
+        const leaves = live.children.filter((part) => part.userData.pascalSwingLeaf)
+        for (const [i, track] of clip.tracks.entries()) {
+          const target = scene.getObjectByProperty('uuid', track.name.replace('.quaternion', ''))!
+          const exportedHardware = target.children.filter(
+            (part) => part.userData.slotId === 'hardware',
+          )
+          const liveHardware = leaves[i]!.children.filter(
+            (part) => part.userData.slotId === 'hardware',
+          )
+          expect(exportedHardware).toHaveLength(2)
+          for (const [j, part] of exportedHardware.entries()) {
+            const source = liveHardware[j]!
+            expect(
+              part
+                .getWorldPosition(new THREE.Vector3())
+                .distanceTo(source.getWorldPosition(new THREE.Vector3())),
+            ).toBeLessThan(1e-6)
+            expect(
+              part
+                .getWorldQuaternion(new THREE.Quaternion())
+                .angleTo(source.getWorldQuaternion(new THREE.Quaternion())),
+            ).toBeLessThan(1e-6)
+            expect((part as THREE.Mesh).geometry).not.toBe((source as THREE.Mesh).geometry)
+            expect((part as THREE.Mesh).geometry.userData.shared).toBeUndefined()
+          }
+        }
+      }
+      mixer.stopAllAction()
+    })
+  }
+
   test('bakes registry-owned open clips and stamps the node openable', () => {
     const root = new THREE.Group()
     const nodeGroup = new THREE.Group()
@@ -2461,3 +2726,65 @@ test('exports a plugin LOD once without invoking its argument-requiring construc
   expect(meshes[0]!.geometry).not.toBe(mesh.geometry)
   expect(lod.levels).toHaveLength(2)
 })
+
+for (const config of [
+  { doorType: 'sliding', leafCount: 3, slidingStyle: 'patio', tracks: 1 },
+  { doorType: 'sliding', leafCount: 4, slidingStyle: 'patio', tracks: 2 },
+  { doorType: 'sliding', leafCount: 4, slidingStyle: 'bypass', tracks: 2 },
+  { doorType: 'folding', leafCount: 6, tracks: 6 },
+  { doorType: 'folding', leafCount: 8, tracks: 8 },
+]) {
+  test(`GLB samples ${config.slidingStyle ?? ''} ${config.doorType} with ${config.leafCount} panels`, () => {
+    const node = DoorNode.parse({
+      ...config,
+      width: 4,
+      slideDirection: 'right',
+      operationState: 0.5,
+    })
+    const mesh = buildDoorPreviewMesh(node)
+    const root = new THREE.Group()
+    root.add(mesh)
+    sceneRegistry.nodes.set(node.id, mesh)
+    try {
+      const { animations } = prepareSceneForExport(root, { [node.id]: node })
+      expect(animations).toHaveLength(1)
+      expect(animations[0]!.tracks).toHaveLength(config.tracks)
+      for (const track of animations[0]!.tracks) {
+        expect(track.times[0]).toBe(0)
+        expect(track.times[8]).toBe(0.5)
+        expect(track.times[16]).toBe(1)
+      }
+    } finally {
+      sceneRegistry.nodes.delete(node.id)
+    }
+  })
+}
+
+test('GLB entry-door clip moves its leaf and keeps sidelights and transom static', () => {
+  const node = DoorNode.parse({
+    width: 1,
+    height: 2.1,
+    sidelightLeft: 0.3,
+    sidelightRight: 0.5,
+    transomHeight: 0.4,
+    swingAngle: 0.6,
+  })
+  const mesh = buildDoorPreviewMesh(node)
+  const root = new THREE.Group()
+  root.add(mesh)
+  sceneRegistry.nodes.set(node.id, mesh)
+  try {
+    const { scene, animations } = prepareSceneForExport(root, { [node.id]: node })
+    expect(animations).toHaveLength(1)
+    const fixed = scene.getObjectByName('door-fixed-lights')!
+    expect(fixed).toBeDefined()
+    const staticIds = new Set<string>()
+    fixed.traverse((part) => staticIds.add(part.uuid))
+    expect(animations[0]!.tracks.length).toBeGreaterThan(0)
+    expect(animations[0]!.tracks.some((track) => staticIds.has(track.name.split('.')[0]!))).toBe(
+      false,
+    )
+  } finally {
+    sceneRegistry.nodes.delete(node.id)
+  }
+})

package/src/lib/glb-export.ts

@@ -26,6 +26,7 @@ import {
   isViewerPresentationTextureBorrowed,
   poseDoorMovingParts,
   poseWindowMovingParts,
+  restoreWindowRollerShutter,
   SCENE_LAYER,
   snapLevelsToTruePositions,
   type ViewerPresentationContribution,
@@ -914,6 +915,8 @@ function cloneSceneForExport(
     let geometry = cache.geometries.get(renderable.geometry)
     if (!geometry) {
       geometry = renderable.geometry.clone()
+      // Export owns its clones even when the live geometry belongs to a shared cache.
+      delete geometry.userData.shared
       cache.geometries.set(renderable.geometry, geometry)
     }
     renderableClone.geometry = geometry
@@ -1710,14 +1713,68 @@ function openClip(id: string, tracks: THREE.KeyframeTrack[]): THREE.AnimationCli
   return clip
 }
 
+/** Shutters share a toggle, independently of the sash's open clip. */
+function bakeWindowClip(
+  id: string,
+  node: WindowNode,
+  windowObject: THREE.Object3D,
+): THREE.AnimationClip[] {
+  const clips: THREE.AnimationClip[] = []
+  restoreWindowRollerShutter(node, windowObject)
+  const sash = bakeWindowOpenClip(id, node, windowObject)
+  if (sash) clips.push(sash)
+  const hinged = Boolean(node.shutters && node.shutters !== 'none')
+  const roller = node.rollerShutter === 'box' || node.rollerShutter === 'concealed'
+  if (!hinged && !roller) return clips
+
+  const leaves: THREE.Object3D[] = []
+  windowObject.traverse((part) => {
+    if (['shutter-left', 'shutter-right', 'shutter-outer'].includes(part.name)) leaves.push(part)
+  })
+  const rotations = new Map(leaves.map((leaf) => [leaf, [] as number[]]))
+  // A midpoint disambiguates the direction of a half-turn for quaternion interpolation.
+  for (const value of [0, 0.5, 1]) {
+    poseWindowMovingParts(node, windowObject, 0, value)
+    for (const leaf of leaves) rotations.get(leaf)!.push(...leaf.quaternion.toArray())
+  }
+  poseWindowMovingParts(node, windowObject, 0)
+  const tracks: THREE.KeyframeTrack[] = leaves.map(
+    (leaf) =>
+      new THREE.QuaternionKeyframeTrack(
+        `${leaf.uuid}.quaternion`,
+        [0, 0.5, 1],
+        rotations.get(leaf)!,
+      ),
+  )
+  if (roller) {
+    restoreWindowRollerShutter({ ...node, rollerShutterOpen: 0 }, windowObject)
+    const curtain = windowObject.getObjectByName('window-roller-curtain')
+    if (curtain) {
+      // Fixed topology: compress the full curtain towards its top, inside the lintel/box.
+      curtain.position.y = node.height / 2
+      for (const child of curtain.children) child.position.y -= node.height / 2
+      curtain.scale.y = 1 - 0.98 * (node.rollerShutterOpen ?? 1)
+      tracks.push(
+        new THREE.VectorKeyframeTrack(`${curtain.uuid}.scale`, [0, 1], [1, 1, 1, 1, 0.02, 1]),
+      )
+    }
+  }
+  if (tracks.length) {
+    const clip = new THREE.AnimationClip(`${id}: shutters`, 1, tracks)
+    clip.userData = { loop: false }
+    clips.push(clip)
+  }
+  return clips
+}
+
 /**
  * Bake a window's open motion generically: snapshot every part's pose closed,
  * pose the subtree open, and emit a track for whichever parts actually moved
  * (translation for sliding/hung sashes, rotation for casement/awning/louvre).
  * Reusing the live `poseWindowMovingParts` keeps one source of truth for window
- * kinematics. The subtree is left posed closed as the GLB's rest state.
+ * kinematics. The sash is left closed; shutters keep their saved rest pose.
  */
-function bakeWindowClip(
+function bakeWindowOpenClip(
   id: string,
   node: WindowNode,
   windowObject: THREE.Object3D,
@@ -1855,6 +1912,17 @@ function stampIdentity(
     const clipNames = clipNamesByNode.get(id)
     if (clipNames?.length) {
       if (clipNames.some((name) => name.endsWith(': open'))) extras.openable = true
+      if (node.type === 'window' && clipNames.includes(`${id}: shutters`)) {
+        extras.shutters = true
+        extras.shuttersOpen =
+          node.shutters && node.shutters !== 'none'
+            ? (node.shutterOpen ?? 1)
+            : (node.rollerShutterOpen ?? 1)
+        if (node.rollerShutter === 'box' || node.rollerShutter === 'concealed') {
+          extras.rollerShutterOpen = node.rollerShutterOpen ?? 1
+          extras.rollerShutterAnimation = 'top-pivot-scale-y'
+        }
+      }
       extras.clips = clipNames
     }
     if (node.type === 'zone') {

package/src/lib/grid-frame.test.ts

@@ -1,6 +1,11 @@
-import { expect, test } from 'bun:test'
-import { Group, Vector3 } from 'three'
-import { gridLocalNormal, gridLocalPoint } from './grid-frame'
+import { describe, expect, test } from 'bun:test'
+import { Group, Quaternion, Vector3 } from 'three'
+import {
+  gridLocalNormal,
+  gridLocalPoint,
+  HORIZONTAL_GRID_QUATERNION,
+  layHorizontalGrid,
+} from './grid-frame'
 
 test('grid floor and cursor stay in model coordinates after God-view pan, scale and yaw', () => {
   const root = new Group()
@@ -17,3 +22,51 @@ test('grid floor and cursor stay in model coordinates after God-view pan, scale
   ).toBeLessThan(1e-8)
   expect(world.distanceTo(local)).toBeGreaterThan(1)
 })
+
+// The grid plane's lattice lines run at multiples of the cell size in its own
+// XY, from its origin: where does plane-local (u, v) land?
+function planePoint(position: Vector3, quaternion: Quaternion, u: number, v: number) {
+  return new Vector3(u, v, 0).applyQuaternion(quaternion).add(position)
+}
+
+describe('layHorizontalGrid', () => {
+  test("lays the lattice on a turned, offset building's own frame", () => {
+    const yaw = (17 * Math.PI) / 180
+    const position = new Vector3()
+    const quaternion = new Quaternion()
+    layHorizontalGrid({ position: [12.37, 0, -8.91], rotationY: yaw }, 0.301, position, quaternion)
+
+    expect(position.toArray()).toEqual([12.37, 0.301, -8.91])
+    // Flat…
+    expect(new Vector3(0, 0, 1).applyQuaternion(quaternion).y).toBeCloseTo(1, 12)
+    // …and each lattice point is a building-local lattice point: plane (1, -1.5)
+    // is building-local (1, 1.5), wherever the building's yaw puts it.
+    const point = planePoint(position, quaternion, 1, -1.5)
+    const cos = Math.cos(yaw)
+    const sin = Math.sin(yaw)
+    expect(point.x).toBeCloseTo(12.37 + cos + 1.5 * sin, 12)
+    expect(point.y).toBeCloseTo(0.301, 12)
+    expect(point.z).toBeCloseTo(-8.91 - sin + 1.5 * cos, 12)
+  })
+
+  test('with no building the world grid stays anchored at the origin, as before', () => {
+    const position = new Vector3(5, 5, 5)
+    const quaternion = new Quaternion()
+    layHorizontalGrid(null, 0.001, position, quaternion)
+
+    expect(position.toArray()).toEqual([0, 0.001, 0])
+    expect(Math.abs(quaternion.dot(HORIZONTAL_GRID_QUATERNION))).toBeCloseTo(1, 12)
+    const point = planePoint(position, quaternion, 2, -3)
+    expect(point.x).toBeCloseTo(2, 12)
+    expect(point.z).toBeCloseTo(3, 12)
+  })
+
+  test('an unturned building at the origin draws the same grid as no building', () => {
+    const position = new Vector3()
+    const quaternion = new Quaternion()
+    layHorizontalGrid({ position: [0, 0, 0], rotationY: 0 }, 0.001, position, quaternion)
+
+    expect(position.toArray()).toEqual([0, 0.001, 0])
+    expect(Math.abs(quaternion.dot(HORIZONTAL_GRID_QUATERNION))).toBeCloseTo(1, 12)
+  })
+})

package/src/lib/grid-frame.ts

@@ -1,4 +1,5 @@
-import type { Object3D, Vector3 } from 'three'
+import type { BuildingPose } from '@pascal-app/core'
+import { type Object3D, Quaternion, Vector3 } from 'three'
 
 // Placement surfaces are world-space; the grid lives under the scalable XR
 // scene root. Keep its lattice and reveal in that root's model coordinates.
@@ -16,3 +17,29 @@ export function gridLocalNormal(parent: Object3D | null, normal: Vector3, target
   if (parent) target.transformDirection(parent.matrixWorld.clone().invert())
   return target
 }
+
+const UP = new Vector3(0, 1, 0)
+
+/** Lays the grid's PlaneGeometry (which faces +Z) flat, its normal → +Y. */
+export const HORIZONTAL_GRID_QUATERNION = new Quaternion().setFromUnitVectors(
+  new Vector3(0, 0, 1),
+  UP,
+)
+
+/**
+ * Lay the horizontal grid plane on the lattice the active tools snap on: a
+ * building's own frame (`pose`, its yaw and offset — the lattice
+ * `snapWorldXZForActiveBuilding` snaps to), or with `pose` null the world XZ
+ * grid anchored at (0, 0). The lattice lines run at multiples of the cell size
+ * from the plane's origin, so a turned house's walls sit square on them. `y`
+ * is the plane's height in the grid parent's frame.
+ */
+export function layHorizontalGrid(
+  pose: BuildingPose | null,
+  y: number,
+  position: Vector3,
+  quaternion: Quaternion,
+) {
+  position.set(pose?.position[0] ?? 0, y, pose?.position[2] ?? 0)
+  quaternion.setFromAxisAngle(UP, pose?.rotationY ?? 0).multiply(HORIZONTAL_GRID_QUATERNION)
+}

package/src/lib/history.test.ts

@@ -488,7 +488,8 @@ describe('standalone history source invalidation', () => {
       const effects = []
       mockShared('react', () => ({ ...react, useEffect: effect => effects.push(effect), useRef: current => ({ current }) }))
       const segment = core.StairSegmentNode.parse({ id: 'sseg_history', parentId: 'stair_history', height: 2.5 })
-      const stair = core.StairNode.parse({ id: 'stair_history', parentId: level.id, children: [segment.id] })
+      // Off the slab: the flight rises from the level base, whatever elects the stair's support.
+      const stair = core.StairNode.parse({ id: 'stair_history', parentId: level.id, position: [10, 0, 10], children: [segment.id] })
       scene.setState({ nodes: { ...baseline, [level.id]: { ...level, height: 2.5, children: [stair.id] }, [stair.id]: stair, [segment.id]: segment } })
       const { StairOpeningSystem } = await import(${JSON.stringify(resolve(import.meta.dir, '../../../core/src/systems/stair/stair-opening-system.tsx'))})
       StairOpeningSystem()