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

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

@@ -8,10 +8,17 @@ import {
   findLevelAncestorId,
   nodeRegistry,
   registerNode,
+  type SceneCommit,
+  subscribeSceneCommits,
   useScene,
 } from '@pascal-app/core'
 import { z } from 'zod'
-import { commitFreshPlacementSubtree, createFreshPlacementSubtree } from './fresh-planar-placement'
+import {
+  commitFreshPlacementSubtree,
+  createFreshPlacementSubtree,
+  duplicatesAsFreshSubtree,
+  prepareFreshPlacementRootDuplicate,
+} from './fresh-planar-placement'
 
 type RafFn = (cb: (time: number) => void) => number
 ;(globalThis as { requestAnimationFrame?: RafFn }).requestAnimationFrame ??= ((
@@ -170,12 +177,15 @@ describe('commitFreshPlacementSubtree', () => {
   })
 
   test('commits a fresh draft as one undoable clean subtree', () => {
+    const commits: SceneCommit[] = []
+    const unsubscribe = subscribeSceneCommits((commit) => commits.push(commit))
     useScene.temporal.getState().pause()
 
     const committedId = commitFreshPlacementSubtree(SHELF_ID, {
       position: [2, 0, 3],
       visible: true,
     } as Partial<AnyNode>)
+    unsubscribe()
 
     expect(committedId).toBeTruthy()
     expect(committedId).not.toBe(SHELF_ID)
@@ -192,6 +202,12 @@ describe('commitFreshPlacementSubtree', () => {
     expect((useScene.getState().nodes[LEVEL_ID] as { children: AnyNodeId[] }).children).toEqual([
       finalId,
     ])
+    expect(commits).toHaveLength(1)
+    expect(commits[0]?.origin).toBe('local')
+    expect(commits[0]?.before.nodes[SHELF_ID]).toBeUndefined()
+    expect(commits[0]?.before.nodes[finalId]).toBeUndefined()
+    expect(commits[0]?.current.nodes[SHELF_ID]).toBeUndefined()
+    expect(commits[0]?.current.nodes[finalId]).toEqual(committed)
 
     useScene.temporal.getState().resume()
     useScene.temporal.getState().undo()
@@ -201,6 +217,33 @@ describe('commitFreshPlacementSubtree', () => {
     expect((useScene.getState().nodes[LEVEL_ID] as { children: AnyNodeId[] }).children).toEqual([])
   })
 
+  test('uses the subtree contract for childless variants and never aliases root-only children', () => {
+    registerCabinetClonePrepTestKind()
+    const childlessCabinet = {
+      ...shelf(),
+      type: 'cabinet',
+      children: [],
+      metadata: { isTransient: true, label: 'source' },
+    } as AnyNode
+    expect(duplicatesAsFreshSubtree(childlessCabinet)).toBe(true)
+
+    const source = {
+      ...shelf(),
+      children: ['item_original' as AnyNodeId],
+      metadata: { isTransient: true, label: 'source' },
+    } as AnyNode
+    const duplicate = prepareFreshPlacementRootDuplicate(source) as AnyNode & {
+      children: AnyNodeId[]
+      id?: AnyNodeId
+      metadata?: Record<string, unknown>
+    }
+
+    expect(duplicate.id).toBeUndefined()
+    expect(duplicate.children).toEqual([])
+    expect(duplicate.metadata).toEqual({ isNew: true, label: 'source' })
+    expect((source as AnyNode & { children: AnyNodeId[] }).children).toEqual(['item_original'])
+  })
+
   test('commits a duplicated cabinet draft without deleting the original modules', () => {
     seedCabinetRun()
     useScene.temporal.getState().clear()

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

@@ -27,10 +27,27 @@ function duplicableConfigFor(node: AnyNode): DuplicableConfig | null {
 }
 
 export function duplicatesAsFreshSubtree(node: AnyNode): boolean {
-  const children = (node as { children?: unknown }).children
-  return (
-    duplicableConfigFor(node)?.subtree === true && Array.isArray(children) && children.length > 0
-  )
+  return duplicableConfigFor(node)?.subtree === true
+}
+
+/**
+ * Prepares a non-subtree duplicate without retaining ownership of the
+ * original node's children. Subtree-capable kinds take the path above and
+ * receive fresh descendant IDs; every other kind duplicates only its root.
+ */
+export function prepareFreshPlacementRootDuplicate(node: AnyNode): AnyNode {
+  const duplicate = structuredClone(node) as unknown as Record<string, unknown> & {
+    id?: AnyNodeId
+    children?: unknown
+    metadata?: unknown
+  }
+  delete duplicate.id
+  if (Array.isArray(duplicate.children)) duplicate.children = []
+  duplicate.metadata = {
+    ...getPlacementMetadataRecord(stripPlacementMetadataFlags(duplicate.metadata)),
+    isNew: true,
+  }
+  return duplicate as unknown as AnyNode
 }
 
 /**

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

@@ -2,7 +2,13 @@ import { afterEach, describe, expect, test } from 'bun:test'
 import { type AnyNode, DoorNode, registerNode, sceneRegistry } from '@pascal-app/core'
 import { buildDoorPreviewMesh } from '@pascal-app/viewer'
 import * as THREE from 'three'
-import { prepareSceneForExport } from './glb-export'
+import type { GLTFWriter } from 'three/examples/jsm/exporters/GLTFExporter.js'
+import { prepareSceneForExport, writeTextureReferenceExtras } from './glb-export'
+
+// The reference module reads the storage origin lazily on first use, so
+// setting the env here (before any validation call) pins it for the file.
+process.env.NEXT_PUBLIC_SUPABASE_URL ??= 'https://test-storage.supabase.co'
+const STORAGE_ORIGIN = new URL(process.env.NEXT_PUBLIC_SUPABASE_URL).origin
 
 afterEach(() => {
   sceneRegistry.clear()
@@ -62,6 +68,79 @@ describe('prepareSceneForExport', () => {
     expect(meshes[0]!.material).toBe(meshes[1]!.material)
   })
 
+  test('reference mode swaps stamped compressed textures and leaves unstamped textures embedded', () => {
+    const root = new THREE.Group()
+    const stamped = new THREE.CompressedTexture([], 4, 4)
+    stamped.wrapS = THREE.MirroredRepeatWrapping
+    stamped.wrapT = THREE.ClampToEdgeWrapping
+    stamped.repeat.set(2, 3)
+    stamped.offset.set(0.25, 0.5)
+    stamped.center.set(0.5, 0.5)
+    stamped.rotation = 0.75
+    stamped.flipY = false
+    stamped.colorSpace = THREE.SRGBColorSpace
+    stamped.updateMatrix()
+    stamped.userData.pascalTextureRef = {
+      v: 1,
+      kind: 'library-material',
+      src: `${STORAGE_ORIGIN}/storage/v1/object/public/materials/user/material/oak_basecolor_512.ktx2`,
+      map: 'basecolor',
+      colorSpace: 'srgb',
+    }
+    const unstamped = new THREE.DataTexture(new Uint8Array([128, 128, 255, 255]), 1, 1)
+    root.add(
+      meshWithNodeMaterial(nodeMaterial({ map: stamped, normalMap: unstamped })),
+      meshWithNodeMaterial(nodeMaterial({ map: stamped })),
+    )
+
+    const { scene } = prepareSceneForExport(root, {}, { textures: 'reference' })
+
+    const material = (scene.children[0] as THREE.Mesh).material as THREE.MeshStandardMaterial
+    const placeholder = material.map as THREE.DataTexture
+    expect(placeholder).not.toBe(stamped)
+    expect(placeholder.isDataTexture).toBe(true)
+    expect(
+      (placeholder as THREE.DataTexture & { isCompressedTexture?: boolean }).isCompressedTexture,
+    ).toBeUndefined()
+    expect(placeholder.image.width).toBe(1)
+    expect(placeholder.image.height).toBe(1)
+    expect(Array.from(placeholder.image.data!)).toEqual([255, 255, 255, 255])
+    expect(placeholder.wrapS).toBe(stamped.wrapS)
+    expect(placeholder.wrapT).toBe(stamped.wrapT)
+    expect(placeholder.repeat.toArray()).toEqual(stamped.repeat.toArray())
+    expect(placeholder.offset.toArray()).toEqual(stamped.offset.toArray())
+    expect(placeholder.center.toArray()).toEqual(stamped.center.toArray())
+    expect(placeholder.rotation).toBe(stamped.rotation)
+    expect(placeholder.flipY).toBe(stamped.flipY)
+    expect(placeholder.colorSpace).toBe(stamped.colorSpace)
+    expect(placeholder.userData.pascalTextureRef).toEqual(stamped.userData.pascalTextureRef)
+    expect(material.normalMap).toBe(unstamped)
+    const sharedMaterial = (scene.children[1] as THREE.Mesh).material as THREE.MeshStandardMaterial
+    expect(sharedMaterial.map).toBe(placeholder)
+  })
+
+  test('writes identical texture-reference extras to the texture and image definitions', () => {
+    const texture = new THREE.DataTexture(new Uint8Array([255, 255, 255, 255]), 1, 1)
+    const ref = {
+      v: 1,
+      kind: 'item-glb',
+      src: `${STORAGE_ORIGIN}/storage/v1/object/public/items/system/chair/models/chair.glb`,
+      imageIndex: 3,
+      map: 'normal',
+      colorSpace: 'linear',
+    }
+    texture.userData.pascalTextureRef = ref
+    const imageDef: { extras?: Record<string, unknown> } = {}
+    const textureDef: { source: number; extras?: Record<string, unknown> } = { source: 0 }
+    const writer = { json: { images: [imageDef] } } as unknown as GLTFWriter
+
+    writeTextureReferenceExtras(writer, texture, textureDef)
+
+    expect(textureDef.extras?.pascalTextureRef).toEqual(ref)
+    expect(imageDef.extras?.pascalTextureRef).toEqual(ref)
+    expect(textureDef.extras?.pascalTextureRef).toEqual(imageDef.extras?.pascalTextureRef)
+  })
+
   test('strips editor overlays that live off the scene layer', () => {
     const root = new THREE.Group()
     const realMesh = meshWithNodeMaterial(nodeMaterial())
@@ -78,6 +157,22 @@ describe('prepareSceneForExport', () => {
     expect(meshes).toHaveLength(1)
   })
 
+  test('strips presentation-only geometry marked by its renderer', () => {
+    const root = new THREE.Group()
+    const siteGround = meshWithNodeMaterial(nodeMaterial())
+    const horizonDisc = meshWithNodeMaterial(nodeMaterial())
+    horizonDisc.userData.pascalExport = 'strip'
+    root.add(siteGround, horizonDisc)
+
+    const { scene } = prepareSceneForExport(root, {})
+
+    const meshes: THREE.Mesh[] = []
+    scene.traverse((object) => {
+      if ((object as THREE.Mesh).isMesh) meshes.push(object as THREE.Mesh)
+    })
+    expect(meshes).toHaveLength(1)
+  })
+
   test('neutralises an invisible hitbox root but keeps its visible children', () => {
     // Door/window roots are selection hitboxes: a box geometry with an invisible
     // material (object stays visible). Left intact it would plug the wall opening.
@@ -107,6 +202,26 @@ describe('prepareSceneForExport', () => {
     expect(visibleChildren).toHaveLength(1)
   })
 
+  test('fills undefined slots in an array material so no undefined survives the prune', () => {
+    // Multi-material / group geometry where one slot was never assigned:
+    // `mesh.material = [validMat, undefined]`. The scalar-null guard doesn't
+    // catch this (an array is never `== null`), so the undefined slot used to
+    // reach GLTFExporter and crash on `material.isShaderMaterial`.
+    const root = new THREE.Group()
+    const mesh = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1))
+    mesh.material = [nodeMaterial(), undefined as unknown as THREE.Material]
+    root.add(mesh)
+
+    const { scene } = prepareSceneForExport(root, {})
+
+    const exported = scene.children[0] as THREE.Mesh
+    const materials = exported.material as THREE.Material[]
+    expect(Array.isArray(materials)).toBe(true)
+    expect(materials).toHaveLength(2)
+    // No undefined/null slot survives; every slot is a real material.
+    expect(materials.every((m) => m != null)).toBe(true)
+  })
+
   test('stamps identity from the scene registry and strips other userData', () => {
     const root = new THREE.Group()
     const doorGroup = new THREE.Group()

package/src/lib/glb-export.ts

@@ -13,6 +13,7 @@ import {
   type ZoneNode,
 } from '@pascal-app/core'
 import {
+  getPascalTextureRef,
   poseDoorMovingParts,
   poseWindowMovingParts,
   SCENE_LAYER,
@@ -20,7 +21,11 @@ import {
 } from '@pascal-app/viewer'
 import type { Object3D } from 'three'
 import * as THREE from 'three'
-import { GLTFExporter } from 'three/examples/jsm/exporters/GLTFExporter.js'
+import {
+  GLTFExporter,
+  type GLTFExporterPlugin,
+  type GLTFWriter,
+} from 'three/examples/jsm/exporters/GLTFExporter.js'
 import * as WebGPUTextureUtils from 'three/examples/jsm/utils/WebGPUTextureUtils.js'
 
 /**
@@ -41,6 +46,10 @@ export type GlbExport = {
   animations: THREE.AnimationClip[]
 }
 
+export type GlbExportOptions = {
+  textures?: 'embed' | 'reference'
+}
+
 /** Resolve after the next couple of animation frames, giving React/R3F time to
  * commit and mount export-only geometry (e.g. instanced kinds' real meshes)
  * before the exporter clones the scene graph. Callers must set
@@ -51,10 +60,63 @@ export function nextFrames(): Promise<void> {
   })
 }
 
+type GltfExtrasDef = {
+  extras?: Record<string, unknown>
+}
+
+type TextureReferenceWriter = GLTFWriter & {
+  json: {
+    images?: GltfExtrasDef[]
+  }
+}
+
+function getExportedImageIndex(textureDef: Record<string, unknown>): number | null {
+  if (Number.isInteger(textureDef.source)) return textureDef.source as number
+  const extensions = textureDef.extensions as Record<string, { source?: unknown }> | undefined
+  const source = extensions?.EXT_texture_webp?.source ?? extensions?.EXT_texture_avif?.source
+  return Number.isInteger(source) ? (source as number) : null
+}
+
+export function writeTextureReferenceExtras(
+  writer: GLTFWriter,
+  texture: THREE.Texture,
+  textureDef: Record<string, unknown>,
+) {
+  const ref = getPascalTextureRef(texture)
+  if (!ref) return
+
+  const imageIndex = getExportedImageIndex(textureDef)
+  const imageDef =
+    imageIndex === null ? undefined : (writer as TextureReferenceWriter).json.images?.[imageIndex]
+  if (!imageDef) {
+    throw new Error('GLTFExporter did not expose an image for a referenced Pascal texture')
+  }
+
+  const textureWithExtras = textureDef as GltfExtrasDef
+  textureWithExtras.extras = {
+    ...textureWithExtras.extras,
+    pascalTextureRef: ref,
+  }
+  imageDef.extras = {
+    ...imageDef.extras,
+    pascalTextureRef: ref,
+  }
+}
+
+function textureReferencePlugin(writer: GLTFWriter): GLTFExporterPlugin {
+  return {
+    writeTexture: (texture, textureDef) => {
+      writeTextureReferenceExtras(writer, texture, textureDef)
+    },
+  }
+}
+
 export async function exportSceneToGlb(
   sceneGroup: Object3D,
   nodes: Record<string, AnyNode>,
+  options: GlbExportOptions = {},
 ): Promise<ArrayBuffer> {
+  const textureMode = options.textures ?? 'embed'
   emitter.emit('thumbnail:before-capture', undefined)
   // Snap levels to their true stacked positions (like thumbnail capture) so the
   // export always reflects the clean stacked building, regardless of the live
@@ -63,7 +125,10 @@ export async function exportSceneToGlb(
   const restoreLevels = snapLevelsToTruePositions()
   let prepared: ReturnType<typeof prepareSceneForExport>
   try {
-    prepared = prepareSceneForExport(sceneGroup, nodes)
+    prepared =
+      textureMode === 'reference'
+        ? prepareSceneForExport(sceneGroup, nodes, { textures: 'reference' })
+        : prepareSceneForExport(sceneGroup, nodes)
   } finally {
     restoreLevels()
     emitter.emit('thumbnail:after-capture', undefined)
@@ -71,6 +136,7 @@ export async function exportSceneToGlb(
   const { scene: exportScene, animations } = prepared
 
   const exporter = new GLTFExporter()
+  if (textureMode === 'reference') exporter.register(textureReferencePlugin)
   // Painted finishes use KTX2 (GPU-compressed) maps; GLTFExporter can't read
   // those directly. WebGPUTextureUtils blits each one to RGBA on its own
   // offscreen renderer (passing the live renderer would resize/draw over the
@@ -112,6 +178,7 @@ export async function exportSceneToGlb(
 export function prepareSceneForExport(
   source: THREE.Object3D,
   nodes: Record<string, AnyNode>,
+  options: GlbExportOptions = {},
 ): GlbExport {
   const scene = source.clone(true)
   const cloneByOriginal = pairClones(source, scene)
@@ -142,7 +209,7 @@ export function prepareSceneForExport(
 
   pruneNonRenderableMeshes(scene, identityNodes)
   sanitizeMaterialGroups(scene, identityNodes)
-  convertMaterials(scene)
+  convertMaterials(scene, options.textures ?? 'embed')
 
   const { clips, clipNamesByNode } = bakeAnimationClips(cloneByOriginal, nodes)
 
@@ -185,6 +252,10 @@ const PLACEHOLDER_MATERIAL = new THREE.MeshBasicMaterial({ visible: false })
 
 /**
  * Strip everything that must not bake into the model:
+ *  - Renderer-owned presentation geometry explicitly marked
+ *    `userData.pascalExport = 'strip'` (for example the site's 800 m horizon
+ *    disc). These meshes make the authoring viewport look grounded but aren't
+ *    part of the portable scene artifact.
  *  - Editor overlays on non-scene layers (gizmos, selection handles, ground
  *    grid, zone fills). The editor camera shows them via extra layers; a
  *    thumbnail/bake is layer 0 only. Scene-layer affordances that can't be
@@ -199,6 +270,10 @@ const PLACEHOLDER_MATERIAL = new THREE.MeshBasicMaterial({ visible: false })
 function pruneNonRenderableMeshes(root: THREE.Object3D, identityNodes: Set<THREE.Object3D>) {
   const toRemove: THREE.Object3D[] = []
   root.traverse((object) => {
+    if (object.userData.pascalExport === 'strip') {
+      toRemove.push(object)
+      return
+    }
     // Editor-only overlays (gizmos, selection handles, ground grid, zone fills)
     // live off the scene layer; the editor camera shows them via extra layers
     // but a thumbnail/bake only wants layer 0. Drop the whole overlay subtree —
@@ -228,6 +303,20 @@ function pruneNonRenderableMeshes(root: THREE.Object3D, identityNodes: Set<THREE
       }
       return
     }
+    // The scalar branch above only catches `material == null`; an ARRAY material
+    // (multi-material / group geometry) is never `== null`, so a slot that was
+    // never assigned — e.g. `[validMat, undefined]` — slips through and reaches
+    // GLTFExporter, which reads `material.isShaderMaterial` on every group's
+    // material and crashes on the undefined slot. Don't drop the mesh (the other
+    // slots may be real geometry): fill any null/undefined holes with the hidden
+    // placeholder so the exporter never sees an undefined material.
+    if (
+      (renderable.isMesh === true || renderable.isLine === true || renderable.isPoints === true) &&
+      Array.isArray(renderable.material) &&
+      renderable.material.some((m) => m == null)
+    ) {
+      renderable.material = renderable.material.map((m) => m ?? PLACEHOLDER_MATERIAL)
+    }
     const mesh = object as THREE.Mesh
     if (!mesh.isMesh || isRenderableMesh(mesh)) return
     if (mesh.children.length > 0) {
@@ -330,14 +419,31 @@ const STANDARD_MAP_SLOTS = [
   'bumpMap',
 ] as const
 
-function convertMaterials(root: THREE.Object3D) {
+const REFERENCE_MAP_SLOTS = [
+  ...STANDARD_MAP_SLOTS,
+  'clearcoatMap',
+  'clearcoatNormalMap',
+  'clearcoatRoughnessMap',
+  'iridescenceMap',
+  'iridescenceThicknessMap',
+  'transmissionMap',
+  'thicknessMap',
+  'specularIntensityMap',
+  'specularColorMap',
+  'sheenRoughnessMap',
+  'sheenColorMap',
+  'anisotropyMap',
+] as const
+
+function convertMaterials(root: THREE.Object3D, textureMode: 'embed' | 'reference') {
   const cache = new Map<THREE.Material, THREE.Material>()
+  const placeholderCache = new Map<THREE.Texture, THREE.Texture>()
   root.traverse((object) => {
     const mesh = object as THREE.Mesh
     if (!mesh.isMesh) return
     const material = mesh.material
     if (Array.isArray(material)) {
-      mesh.material = material.map((m) => convertMaterial(m, cache))
+      mesh.material = material.map((m) => convertMaterial(m, cache, textureMode, placeholderCache))
       return
     }
     // glTF has no BackSide — GLTFExporter renders the *front* face for any
@@ -351,7 +457,7 @@ function convertMaterials(root: THREE.Object3D) {
     ) {
       mesh.geometry = flipGeometryWinding(mesh.geometry)
     }
-    mesh.material = convertMaterial(material, cache)
+    mesh.material = convertMaterial(material, cache, textureMode, placeholderCache)
   })
 }
 
@@ -401,8 +507,19 @@ function flipGeometryWinding(geometry: THREE.BufferGeometry): THREE.BufferGeomet
 function convertMaterial(
   material: THREE.Material,
   cache: Map<THREE.Material, THREE.Material>,
+  textureMode: 'embed' | 'reference',
+  placeholderCache: Map<THREE.Texture, THREE.Texture>,
 ): THREE.Material {
-  if ((material as { isNodeMaterial?: boolean }).isNodeMaterial !== true) return material
+  const isNodeMaterial = (material as { isNodeMaterial?: boolean }).isNodeMaterial === true
+  if (!isNodeMaterial) {
+    if (textureMode === 'embed') return material
+    const cached = cache.get(material)
+    if (cached) return cached
+    const target = material.clone()
+    replaceReferencedTextures(target, placeholderCache)
+    cache.set(material, target)
+    return target
+  }
 
   const cached = cache.get(material)
   if (cached) return cached
@@ -443,10 +560,90 @@ function convertMaterial(
     }
   }
 
+  if (textureMode === 'reference') replaceReferencedTextures(target, placeholderCache)
+
   cache.set(material, target)
   return target
 }
 
+function replaceReferencedTextures(
+  material: THREE.Material,
+  placeholderCache: Map<THREE.Texture, THREE.Texture>,
+) {
+  const textureMaterial = material as THREE.Material & Record<string, unknown>
+  for (const slot of REFERENCE_MAP_SLOTS) {
+    const texture = textureMaterial[slot]
+    if (!(texture instanceof THREE.Texture) || !getPascalTextureRef(texture)) continue
+
+    let placeholder = placeholderCache.get(texture)
+    if (!placeholder) {
+      placeholder = createReferencePlaceholder(texture)
+      placeholderCache.set(texture, placeholder)
+    }
+    textureMaterial[slot] = placeholder
+  }
+}
+
+/** GLTFExporter serializes images via canvas drawImage/createImageBitmap,
+ *  which reject a DataTexture's raw `{data,width,height}` image — so in DOM
+ *  environments the placeholder must be canvas-backed. The DataTexture branch
+ *  covers non-DOM runs (bun tests), where the exporter itself never runs. */
+function createPlaceholderCanvas(): OffscreenCanvas | HTMLCanvasElement | null {
+  const canvas =
+    typeof OffscreenCanvas !== 'undefined'
+      ? new OffscreenCanvas(1, 1)
+      : typeof document !== 'undefined'
+        ? Object.assign(document.createElement('canvas'), { width: 1, height: 1 })
+        : null
+  if (!canvas) return null
+  const ctx = canvas.getContext('2d') as
+    | OffscreenCanvasRenderingContext2D
+    | CanvasRenderingContext2D
+    | null
+  if (!ctx) return null
+  ctx.fillStyle = '#ffffff'
+  ctx.fillRect(0, 0, 1, 1)
+  return canvas
+}
+
+function createReferencePlaceholder(texture: THREE.Texture): THREE.Texture {
+  const ref = getPascalTextureRef(texture)
+  if (!ref) throw new Error('Cannot create a placeholder for an invalid Pascal texture reference')
+
+  const canvas = createPlaceholderCanvas()
+  const placeholder = canvas
+    ? new THREE.Texture(canvas)
+    : new THREE.DataTexture(
+        new Uint8Array([255, 255, 255, 255]),
+        1,
+        1,
+        THREE.RGBAFormat,
+        THREE.UnsignedByteType,
+      )
+  placeholder.name = texture.name
+  placeholder.mapping = texture.mapping
+  placeholder.channel = texture.channel
+  placeholder.wrapS = texture.wrapS
+  placeholder.wrapT = texture.wrapT
+  placeholder.magFilter = texture.magFilter
+  placeholder.minFilter = texture.minFilter
+  placeholder.anisotropy = texture.anisotropy
+  placeholder.offset.copy(texture.offset)
+  placeholder.repeat.copy(texture.repeat)
+  placeholder.center.copy(texture.center)
+  placeholder.rotation = texture.rotation
+  placeholder.matrixAutoUpdate = texture.matrixAutoUpdate
+  placeholder.matrix.copy(texture.matrix)
+  placeholder.generateMipmaps = texture.generateMipmaps
+  placeholder.premultiplyAlpha = texture.premultiplyAlpha
+  placeholder.flipY = texture.flipY
+  placeholder.unpackAlignment = texture.unpackAlignment
+  placeholder.colorSpace = texture.colorSpace
+  placeholder.userData = { pascalTextureRef: ref }
+  placeholder.needsUpdate = true
+  return placeholder
+}
+
 // --- Animation clip baking ----------------------------------------------
 
 function bakeAnimationClips(

package/src/lib/ground-surface.ts

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