@pascal-app/editor 1.0.0 → 1.0.3

package/src/lib/send-to-app.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, test } from 'bun:test'
+import { LocalAppError, probeLocalApp, sendGlbToLocalApp, waitForLocalImport } from './send-to-app'
+
+type Handler = (url: string, init?: RequestInit) => Response | Promise<Response>
+
+function fakeFetch(handler: Handler): typeof fetch {
+  return ((input: RequestInfo | URL, init?: RequestInit) =>
+    Promise.resolve(handler(String(input), init))) as typeof fetch
+}
+
+const json = (body: unknown, status = 200) =>
+  new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json' } })
+
+describe('probeLocalApp', () => {
+  test('reports unreachable when nothing answers on any port', async () => {
+    const tried: string[] = []
+    const probe = await probeLocalApp(
+      fakeFetch((url) => {
+        tried.push(url)
+        throw new TypeError('Failed to fetch')
+      }),
+      27412,
+      3,
+    )
+    expect(probe).toEqual({ status: 'unreachable' })
+    expect(tried).toEqual([
+      'http://127.0.0.1:27412/pascal/health',
+      'http://127.0.0.1:27413/pascal/health',
+      'http://127.0.0.1:27414/pascal/health',
+    ])
+  })
+
+  test('finds the app on a fallback port and tells whether it allows this origin', async () => {
+    const health = { app: 'blender', version: '5.2.1', addon: '0.1.0', port: 27413, allowed: false }
+    const probe = await probeLocalApp(
+      fakeFetch((url) => {
+        if (url.startsWith('http://127.0.0.1:27413/')) return json(health)
+        throw new TypeError('Failed to fetch')
+      }),
+    )
+    expect(probe).toEqual({ status: 'refused', base: 'http://127.0.0.1:27413', health })
+  })
+})
+
+describe('sendGlbToLocalApp', () => {
+  test('posts the GLB with percent-encoded project headers', async () => {
+    let seen: RequestInit | undefined
+    const status = await sendGlbToLocalApp(
+      'http://127.0.0.1:27412',
+      new Blob([new Uint8Array([1, 2, 3])]),
+      { name: 'Maison été', projectId: 'project_1' },
+      fakeFetch((_url, init) => {
+        seen = init
+        return json({ id: 'abc', state: 'queued' }, 202)
+      }),
+    )
+    expect(status).toEqual({ id: 'abc', state: 'queued' })
+    expect(seen?.method).toBe('POST')
+    expect(seen?.headers).toEqual({
+      'Content-Type': 'model/gltf-binary',
+      'X-Pascal-Project-Name': 'Maison%20%C3%A9t%C3%A9',
+      'X-Pascal-Project-Id': 'project_1',
+    })
+  })
+
+  test('maps a 403 to a refused error', async () => {
+    await expect(
+      sendGlbToLocalApp(
+        'http://127.0.0.1:27412',
+        new Blob([]),
+        {},
+        fakeFetch(() => json({ error: 'origin_not_allowed' }, 403)),
+      ),
+    ).rejects.toMatchObject({ name: 'LocalAppError', reason: 'refused' })
+  })
+})
+
+describe('waitForLocalImport', () => {
+  test('polls until the import is done', async () => {
+    let calls = 0
+    const status = await waitForLocalImport(
+      'http://127.0.0.1:27412',
+      'abc',
+      fakeFetch(() => {
+        calls += 1
+        return json(
+          calls < 3
+            ? { id: 'abc', state: 'queued' }
+            : { id: 'abc', state: 'done', summary: 'Imported' },
+        )
+      }),
+      { intervalMs: 1 },
+    )
+    expect(status.state).toBe('done')
+    expect(calls).toBe(3)
+  })
+
+  test('surfaces a failed import', async () => {
+    const error = await waitForLocalImport(
+      'http://127.0.0.1:27412',
+      'abc',
+      fakeFetch(() => json({ id: 'abc', state: 'failed', error: 'boom' })),
+      { intervalMs: 1 },
+    ).catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(LocalAppError)
+    expect((error as LocalAppError).reason).toBe('failed')
+  })
+})

package/src/lib/send-to-app.ts

@@ -0,0 +1,121 @@
+/**
+ * Hand a scene to a desktop app listening on loopback (the Pascal Blender add-on
+ * today). The app answers `GET /pascal/health`, accepts a GLB on
+ * `POST /pascal/import`, and reports the import on `GET /pascal/import/<id>`.
+ * Protocol reference: https://github.com/pascalorg/blender-addon#send-to-blender-from-the-editor
+ */
+
+export const LOCAL_APP_PORT = 27412
+export const LOCAL_APP_PORT_RANGE = 5
+const PROBE_TIMEOUT_MS = 1000
+
+export type LocalAppHealth = {
+  app: string
+  version: string
+  addon: string
+  port: number
+  allowed: boolean
+}
+
+export type LocalAppProbe =
+  | { status: 'listening'; base: string; health: LocalAppHealth }
+  | { status: 'refused'; base: string; health: LocalAppHealth }
+  | { status: 'unreachable' }
+
+export type LocalImportStatus = {
+  id: string
+  state: 'queued' | 'done' | 'failed'
+  summary?: string
+  error?: string
+}
+
+export class LocalAppError extends Error {
+  constructor(
+    readonly reason: 'refused' | 'rejected' | 'failed' | 'timeout',
+    message: string,
+  ) {
+    super(message)
+    this.name = 'LocalAppError'
+  }
+}
+
+type FetchLike = typeof fetch
+
+function isHealth(value: unknown): value is LocalAppHealth {
+  const health = value as Partial<LocalAppHealth> | null
+  return Boolean(health && typeof health.app === 'string' && typeof health.allowed === 'boolean')
+}
+
+/** Try the app's port and a few after it, one second each. */
+export async function probeLocalApp(
+  fetchImpl: FetchLike = fetch,
+  port = LOCAL_APP_PORT,
+  range = LOCAL_APP_PORT_RANGE,
+): Promise<LocalAppProbe> {
+  for (let candidate = port; candidate < port + range; candidate++) {
+    const base = `http://127.0.0.1:${candidate}`
+    try {
+      const response = await fetchImpl(`${base}/pascal/health`, {
+        cache: 'no-store',
+        signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+      })
+      if (!response.ok) continue
+      const health: unknown = await response.json()
+      if (!isHealth(health)) continue
+      return { status: health.allowed ? 'listening' : 'refused', base, health }
+    } catch {
+      // Nothing listening there; try the next port.
+    }
+  }
+  return { status: 'unreachable' }
+}
+
+export type SendSceneMeta = {
+  name?: string
+  projectId?: string
+  version?: string
+}
+
+/** POST the GLB; resolves with the queued import id. */
+export async function sendGlbToLocalApp(
+  base: string,
+  blob: Blob,
+  meta: SendSceneMeta = {},
+  fetchImpl: FetchLike = fetch,
+): Promise<LocalImportStatus> {
+  const headers: Record<string, string> = { 'Content-Type': 'model/gltf-binary' }
+  // Header values are Latin-1; the listener percent-decodes these.
+  if (meta.name) headers['X-Pascal-Project-Name'] = encodeURIComponent(meta.name)
+  if (meta.projectId) headers['X-Pascal-Project-Id'] = meta.projectId
+  if (meta.version) headers['X-Pascal-Version'] = meta.version
+  const response = await fetchImpl(`${base}/pascal/import`, { method: 'POST', headers, body: blob })
+  if (response.status === 403) {
+    throw new LocalAppError('refused', 'The app has not allowed this site to send scenes.')
+  }
+  if (!response.ok) {
+    throw new LocalAppError('rejected', `The app rejected the scene (HTTP ${response.status}).`)
+  }
+  return (await response.json()) as LocalImportStatus
+}
+
+/** Poll until the app has imported (or failed to import) the queued scene. */
+export async function waitForLocalImport(
+  base: string,
+  id: string,
+  fetchImpl: FetchLike = fetch,
+  { timeoutMs = 120_000, intervalMs = 500 } = {},
+): Promise<LocalImportStatus> {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    const response = await fetchImpl(`${base}/pascal/import/${id}`, { cache: 'no-store' })
+    if (response.ok) {
+      const status = (await response.json()) as LocalImportStatus
+      if (status.state === 'done') return status
+      if (status.state === 'failed') {
+        throw new LocalAppError('failed', status.error ?? 'The app could not import the scene.')
+      }
+    }
+    await new Promise((resolve) => setTimeout(resolve, intervalMs))
+  }
+  throw new LocalAppError('timeout', 'The app did not finish importing in time.')
+}

package/src/lib/sfx/movement-tick.ts

@@ -1,3 +1,5 @@
+import { sfxEmitter } from '../sfx-bus'
+
 const DEFAULT_FREE_MOVEMENT_SFX_STEP_M = 0.1
 
 type MovementSfxStepKeyArgs = {
@@ -16,3 +18,38 @@ export function movementSfxStepKey({
   const step = gridSnapActive && gridStep > 0 ? gridStep : freeStep
   return coords.map((coord) => Math.round(coord / step)).join(',')
 }
+
+export function createMovementSfxTick() {
+  let previousKey: string | null = null
+  let pending: (() => void) | null = null
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const tick = (args: MovementSfxStepKeyArgs, emitInitialStep = false) => {
+    const nextKey = movementSfxStepKey(args)
+    if (nextKey !== previousKey && (previousKey !== null || emitInitialStep)) {
+      sfxEmitter.emit('sfx:grid-snap')
+    }
+    previousKey = nextKey
+  }
+  const cancel = () => {
+    clearTimeout(timer)
+    timer = undefined
+    pending = null
+  }
+  const flush = () => {
+    const apply = pending
+    cancel()
+    apply?.()
+  }
+  return {
+    tick,
+    schedule(args: MovementSfxStepKeyArgs, shouldPlay: () => boolean, emitInitialStep = false) {
+      pending = () => {
+        if (shouldPlay()) tick(args, emitInitialStep)
+      }
+      // Wait for R3F host dispatch after the native grid listener, without delaying the move.
+      if (timer === undefined) timer = setTimeout(flush, 0)
+    },
+    flush,
+    cancel,
+  }
+}

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

@@ -1,5 +1,9 @@
 import { describe, expect, it } from 'bun:test'
-import { GROUP_MOVE_DRAG_LABEL, ROTATE_HANDLE_DRAG_LABEL } from './contextual-help'
+import {
+  GROUP_MOVE_DRAG_LABEL,
+  GROUP_ROTATE_DRAG_LABEL,
+  ROTATE_HANDLE_DRAG_LABEL,
+} from './contextual-help'
 import {
   cycleSnappingModeIn,
   DEFAULT_SNAPPING_MODE,
@@ -49,6 +53,12 @@ describe('resolveSnapFlags', () => {
 })
 
 describe('per-context snapping', () => {
+  it('rotation defaults to angles and cycles independently to free rotation', () => {
+    expect(defaultSnappingModeFor('rotation')).toBe('angles')
+    expect(snappingModesFor('rotation')).toEqual(['angles', 'off'])
+    expect(cycleSnappingModeIn('rotation', 'angles')).toBe('off')
+    expect(cycleSnappingModeIn('rotation', 'off')).toBe('angles')
+  })
   it('items default to magnetic alignment with no angle lock', () => {
     expect(defaultSnappingModeFor('item')).toBe('lines')
     expect(snappingModesFor('item')).toEqual(['lines', 'grid', 'off'])
@@ -132,7 +142,8 @@ describe('snapContextOf (profile-driven, node-declared)', () => {
     expect(ctx({ kind: 'handle-drag', nodeId: 'unknown_1' })).toBeNull()
     expect(
       ctx({ kind: 'handle-drag', nodeId: 'cabinet-module_1', handle: ROTATE_HANDLE_DRAG_LABEL }),
-    ).toBeNull()
+    ).toBe('rotation')
+    expect(ctx({ kind: 'handle-drag', handle: GROUP_ROTATE_DRAG_LABEL })).toBe('rotation')
   })
 
   it('gives mesh rotation the angle context and other edit operations polygon snapping', () => {

package/src/lib/snapping-mode.ts

@@ -1,5 +1,9 @@
 import type { SnapProfile } from '@pascal-app/core'
-import { GROUP_MOVE_DRAG_LABEL, ROTATE_HANDLE_DRAG_LABEL } from './contextual-help'
+import {
+  GROUP_MOVE_DRAG_LABEL,
+  GROUP_ROTATE_DRAG_LABEL,
+  ROTATE_HANDLE_DRAG_LABEL,
+} from './contextual-help'
 
 /**
  * Snapping mode is a single global, user-cyclable control that maps onto the
@@ -68,14 +72,13 @@ export function nextSnappingMode(mode: SnappingMode): SnappingMode {
 // alignment lines). The mode is remembered per context and shown live, so it's
 // never a silent surprise — it just matches what you're doing.
 
-export type SnapContext = 'wall' | 'item' | 'polygon'
+export type SnapContext = 'wall' | 'item' | 'polygon' | 'rotation'
 
 // The cyclable mode-set for a context (distinct from the node's `SnapProfile`).
 type SnapModeSet = { modes: SnappingMode[]; default: SnappingMode }
 
 // `modes[0]` is the cycle's first entry; `default` is what a context starts at.
-// The 'wall' set is the ONLY one with an angle lock — it applies solely when
-// you're setting a segment's DIRECTION (wall/fence drafting + endpoint drag).
+// The 'wall' set includes angle lock when setting a segment's direction.
 // Translating a whole wall, curving it, or drawing/moving a slab can't change an
 // angle, so those use the no-angle 'polygon' set.
 const SNAP_PROFILES: Record<SnapContext, SnapModeSet> = {
@@ -88,9 +91,10 @@ const SNAP_PROFILES: Record<SnapContext, SnapModeSet> = {
   // whole wall/fence translate, curve reshape, polygon boundary edit. Grid by
   // default, NO angle lock.
   polygon: { modes: ['grid', 'lines', 'off'], default: 'grid' },
+  rotation: { modes: ['angles', 'off'], default: 'angles' },
 }
 
-export const SNAP_CONTEXTS: SnapContext[] = ['wall', 'item', 'polygon']
+export const SNAP_CONTEXTS: SnapContext[] = ['wall', 'item', 'polygon', 'rotation']
 
 export function snappingModesFor(context: SnapContext): SnappingMode[] {
   return SNAP_PROFILES[context].modes
@@ -171,7 +175,8 @@ export function snapContextOf(args: {
         ? contextForProfile(profileOfNode?.(scope.nodeId), scope.operator === 'rotate')
         : null
     case 'handle-drag':
-      if (scope.handle === ROTATE_HANDLE_DRAG_LABEL) return null
+      if (scope.handle === ROTATE_HANDLE_DRAG_LABEL || scope.handle === GROUP_ROTATE_DRAG_LABEL)
+        return 'rotation'
       return scope.nodeId ? contextForProfile(profileOfNode?.(scope.nodeId), false) : null
     case 'placing':
     case 'moving':

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

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

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

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

package/src/lib/spatial-pointer-input.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from 'bun:test'
+import { Ray, Vector3 } from 'three'
+import { getSpatialPointerId, SpatialPointerInput } from './spatial-pointer-input'
+
+describe('SpatialPointerInput', () => {
+  test('recognizes current and legacy XR native event shapes', () => {
+    const source = {}
+    expect(getSpatialPointerId({ inputSource: source })).toBe(source)
+    expect(getSpatialPointerId({ pointerState: { inputSource: source } })).toBe(source)
+    expect(getSpatialPointerId({ pointerType: 'mouse' })).toBeNull()
+  })
+
+  test('keeps move and release bound to the pointer that captured a handle', () => {
+    const input = new SpatialPointerInput()
+    const moves: Ray[] = []
+    let releases = 0
+    input.capture(42, {
+      onMove: (ray) => moves.push(ray.clone()),
+      onRelease: () => releases++,
+      onCancel: () => undefined,
+    })
+    const ray = new Ray(new Vector3(1, 2, 3), new Vector3(0, 1, 0))
+    expect(input.move(7, ray)).toBe(false)
+    expect(input.move(42, ray)).toBe(true)
+    expect(input.release(7)).toBe(false)
+    expect(input.release(42)).toBe(true)
+    expect(moves).toHaveLength(1)
+    expect(moves[0]?.origin.toArray()).toEqual([1, 2, 3])
+    expect(releases).toBe(1)
+    expect(input.move(42, ray)).toBe(false)
+  })
+
+  test('cancels a captured handle without releasing it', () => {
+    const input = new SpatialPointerInput()
+    let cancels = 0
+    let releases = 0
+
+    input.capture(9, {
+      onMove: () => undefined,
+      onRelease: () => releases++,
+      onCancel: () => cancels++,
+    })
+
+    expect(input.cancel(9)).toBe(true)
+    expect(cancels).toBe(1)
+    expect(releases).toBe(0)
+  })
+
+  test('cleans up a replaced capture without letting its stale disposer clear the replacement', () => {
+    const input = new SpatialPointerInput()
+    const ray = new Ray(new Vector3(), new Vector3(0, 0, -1))
+    let replacements = 0
+    let replacementMoves = 0
+
+    const disposeOriginal = input.capture(12, {
+      onMove: () => undefined,
+      onRelease: () => undefined,
+      onCancel: () => undefined,
+      onReplace: () => replacements++,
+    })
+    input.capture(12, {
+      onMove: () => replacementMoves++,
+      onRelease: () => undefined,
+      onCancel: () => undefined,
+    })
+
+    expect(replacements).toBe(1)
+    disposeOriginal()
+    expect(input.move(12, ray)).toBe(true)
+    expect(replacementMoves).toBe(1)
+  })
+})

package/src/lib/spatial-pointer-input.ts

@@ -0,0 +1,62 @@
+import type { Ray } from 'three'
+
+type SpatialPointerCapture = {
+  onMove: (ray: Ray) => void
+  onRelease: () => void
+  onCancel: () => void
+  onReplace?: () => void
+}
+
+export type SpatialPointerId = object | number | string
+
+export function getSpatialPointerId(nativeEvent: unknown): SpatialPointerId | null {
+  if (!nativeEvent || typeof nativeEvent !== 'object') return null
+  const event = nativeEvent as {
+    inputSource?: object
+    pointerState?: { inputSource?: object }
+  }
+  return event.inputSource ?? event.pointerState?.inputSource ?? null
+}
+
+export class SpatialPointerInput {
+  private readonly captures = new Map<SpatialPointerId, SpatialPointerCapture>()
+
+  capture(pointerId: SpatialPointerId, capture: SpatialPointerCapture): () => void {
+    const previous = this.captures.get(pointerId)
+    if (previous && previous !== capture) {
+      this.captures.delete(pointerId)
+      ;(previous.onReplace ?? previous.onCancel)()
+    }
+    this.captures.set(pointerId, capture)
+    return () => {
+      if (this.captures.get(pointerId) === capture) {
+        this.captures.delete(pointerId)
+      }
+    }
+  }
+
+  move(pointerId: SpatialPointerId, ray: Ray): boolean {
+    const capture = this.captures.get(pointerId)
+    if (!capture) return false
+    capture.onMove(ray)
+    return true
+  }
+
+  release(pointerId: SpatialPointerId): boolean {
+    const capture = this.captures.get(pointerId)
+    if (!capture) return false
+    this.captures.delete(pointerId)
+    capture.onRelease()
+    return true
+  }
+
+  cancel(pointerId: SpatialPointerId): boolean {
+    const capture = this.captures.get(pointerId)
+    if (!capture) return false
+    this.captures.delete(pointerId)
+    capture.onCancel()
+    return true
+  }
+}
+
+export const spatialPointerInput = new SpatialPointerInput()

package/src/lib/spatial-snap.test.ts

@@ -0,0 +1,47 @@
+import { test } from 'bun:test'
+import assert from 'node:assert/strict'
+import { snapLocalXZInWorld } from '@pascal-app/core'
+import { Group, Vector3 } from 'three'
+
+const close = (a: number, b: number) => assert.ok(Math.abs(a - b) < 1e-8)
+
+test('free placement stays under the same hit through God-mode zoom and rotation', () => {
+  const pose = { position: [5, 0, -3] as [number, number, number], rotationY: 0.7 }
+  const world = new Group()
+  const building = new Group()
+  building.position.fromArray(pose.position)
+  building.rotation.y = pose.rotationY
+  world.add(building)
+  for (const scale of [0.01, 0.1, 1, 4]) {
+    world.scale.setScalar(scale)
+    world.position.set(8, 1, -4)
+    world.rotation.y = 1.2
+    world.updateWorldMatrix(true, true)
+    const hit = building.localToWorld(new Vector3(2, 0, -6))
+    const local = building.worldToLocal(hit.clone())
+    const snapped = snapLocalXZInWorld([local.x, local.z], pose, (value) => value)
+    const placed = building.localToWorld(new Vector3(snapped[0], 0, snapped[1]))
+    close(placed.distanceTo(hit), 0)
+  }
+})
+
+test('grid snapping still uses model units and the item footprint', () => {
+  const dimensions: number[] = []
+  const result = snapLocalXZInWorld([1.23, -2.16], null, (value, axis) => {
+    dimensions.push([1.8, 0.6][axis]!)
+    return Math.round(value / 0.1) * 0.1
+  })
+  close(result[0], 1.2)
+  close(result[1], -2.2)
+  assert.deepEqual(dimensions, [1.8, 0.6])
+})
+
+test('rotated buildings snap in model-world axes then return building-local coordinates', () => {
+  const result = snapLocalXZInWorld(
+    [1.2, 2.3],
+    { position: [10, 0, 20], rotationY: Math.PI / 2 },
+    Math.round,
+  )
+  close(result[0], 1)
+  close(result[1], 2)
+})