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

package/src/components/walkthrough-hud.tsx

@@ -0,0 +1,111 @@
+'use client'
+
+import type { ReactNode } from 'react'
+import { cn } from '../lib/utils'
+import type { WalkthroughInteract } from '../store/use-first-person-hud'
+
+export type { WalkthroughInteract } from '../store/use-first-person-hud'
+
+export type WalkthroughHudProps = {
+  floorLabel?: string | null
+  zoneLabel?: string | null
+  interact?: WalkthroughInteract
+  /** Pointer lock temporarily released (OS screenshot) — the pill flips to
+   *  "Click to resume" and lets clicks fall through to the canvas. */
+  suspended?: boolean
+  onExit?: () => void
+  children?: ReactNode
+}
+
+export function WalkthroughHud({
+  floorLabel,
+  zoneLabel,
+  interact = null,
+  suspended = false,
+  onExit,
+  children,
+}: WalkthroughHudProps) {
+  const kbdClass = 'rounded border border-border/60 bg-white/10 px-1.5 py-0.5 font-mono text-[10px]'
+  const pillClass =
+    'flex items-center gap-1.5 rounded-full border border-border/40 bg-background/70 px-3 py-1 text-muted-foreground text-xs backdrop-blur-xl'
+  const exitContent = (
+    <>
+      <kbd className={kbdClass}>Esc</kbd>
+      to exit
+    </>
+  )
+
+  return (
+    <div className="dark pointer-events-none absolute inset-0 z-30 text-foreground">
+      <div className="absolute top-6 left-1/2 flex -translate-x-1/2 flex-col items-center gap-1.5">
+        {floorLabel && (
+          <div className="font-medium text-[10px] text-muted-foreground uppercase tracking-wider">
+            {floorLabel}
+          </div>
+        )}
+        {zoneLabel && (
+          <div className="corner-smooth rounded-full border border-border/40 bg-background/80 px-3 py-1 font-medium text-sm shadow-elevation-3 backdrop-blur-xl">
+            {zoneLabel}
+          </div>
+        )}
+        {children}
+      </div>
+
+      <div className="absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2">
+        <div
+          className={cn(
+            'rounded-full transition-all duration-150',
+            interact
+              ? 'h-4 w-4 border-2 border-emerald-400 bg-emerald-400/10'
+              : 'h-1.5 w-1.5 bg-white/80 shadow-[0_0_2px_rgba(0,0,0,0.6)]',
+          )}
+        />
+      </div>
+
+      <div className="absolute bottom-6 left-1/2 flex -translate-x-1/2 items-center gap-2">
+        {suspended ? (
+          <div className={pillClass}>
+            <span className="font-medium text-foreground">Click</span>
+            <span>or</span>
+            <kbd className={kbdClass}>P</kbd>
+            <span>to resume</span>
+            <span className="text-muted-foreground/60">·</span>
+            {exitContent}
+          </div>
+        ) : (
+          <>
+            <div className={pillClass}>
+              <kbd className={kbdClass}>P</kbd>
+              free cursor
+            </div>
+            {onExit ? (
+              <button
+                className={cn(pillClass, 'pointer-events-auto')}
+                onClick={onExit}
+                type="button"
+              >
+                {exitContent}
+              </button>
+            ) : (
+              <div className={pillClass}>{exitContent}</div>
+            )}
+          </>
+        )}
+      </div>
+
+      {interact && (
+        <div className="absolute top-1/2 left-1/2 mt-7 -translate-x-1/2 whitespace-nowrap">
+          <div className="corner-smooth flex items-center gap-1.5 rounded-full border border-border/40 bg-background/80 px-3 py-1 text-xs shadow-elevation-3 backdrop-blur-xl">
+            <kbd className="rounded border border-border/60 bg-white/10 px-1.5 py-0.5 font-mono text-[10px]">
+              E
+            </kbd>
+            <span className="text-muted-foreground">or click to</span>
+            <span className="font-medium">
+              {interact.verb} {interact.label}
+            </span>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/hooks/use-auto-save.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, test } from 'bun:test'
+import { isSuspiciousNodeDrop } from './use-auto-save'
+
+describe('isSuspiciousNodeDrop', () => {
+  test('blocks populated scenes from being flushed as empty skeletons', () => {
+    expect(isSuspiciousNodeDrop(12, 0)).toBe(true)
+    expect(isSuspiciousNodeDrop(12, 4)).toBe(true)
+  })
+
+  test('allows ordinary edits and intentionally empty starting scenes', () => {
+    expect(isSuspiciousNodeDrop(12, 11)).toBe(false)
+    expect(isSuspiciousNodeDrop(4, 0)).toBe(false)
+  })
+})

package/src/hooks/use-auto-save.ts

@@ -5,6 +5,11 @@ import { type MutableRefObject, useCallback, useEffect, useRef } from 'react'
 import { type SceneGraph, saveSceneToLocalStorage } from '../lib/scene'
 
 const AUTOSAVE_DEBOUNCE_MS = 1000
+const STRUCTURAL_NODE_COUNT = 4
+
+export function isSuspiciousNodeDrop(previousNodeCount: number, currentNodeCount: number) {
+  return previousNodeCount > STRUCTURAL_NODE_COUNT && currentNodeCount <= STRUCTURAL_NODE_COUNT
+}
 
 export type SaveStatus = 'idle' | 'pending' | 'saving' | 'saved' | 'paused' | 'error'
 
@@ -61,6 +66,13 @@ export function useAutoSave({
   useEffect(() => {
     let lastNodesSnapshot = JSON.stringify(useScene.getState().nodes)
     let lastNodeCount = Object.keys(useScene.getState().nodes).length
+    // Collections + scene materials are document-level state that persists with
+    // the graph but lives outside `nodes`. Track them by reference (zustand
+    // hands out a new object on every mutation) so a material edit or a
+    // collection change still triggers a save.
+    let lastCollectionsRef = useScene.getState().collections
+    let lastMaterialsRef = useScene.getState().materials
+    let lastInstalledPluginsRef = useScene.getState().installedPlugins
 
     async function executeSave() {
       if (isLoadingSceneRef.current || isVersionPreviewModeRef.current) {
@@ -69,14 +81,19 @@ export function useAutoSave({
         return
       }
 
-      const { nodes, rootNodeIds } = useScene.getState()
-      const sceneGraph = { nodes, rootNodeIds } as SceneGraph
+      const { nodes, rootNodeIds, collections, materials, installedPlugins } = useScene.getState()
+      const sceneGraph = {
+        nodes,
+        rootNodeIds,
+        collections,
+        materials,
+        installedPlugins,
+      } as SceneGraph
 
       // Guard: refuse to autosave if the scene went from populated to nearly empty.
       // This catches accidental full deletions before they're persisted.
       const currentNodeCount = Object.keys(nodes).length
-      const STRUCTURAL_NODE_COUNT = 4 // site + building + levels (empty scene skeleton)
-      if (lastNodeCount > STRUCTURAL_NODE_COUNT && currentNodeCount <= STRUCTURAL_NODE_COUNT) {
+      if (isSuspiciousNodeDrop(lastNodeCount, currentNodeCount)) {
         console.warn(
           `[autosave] Blocked: scene dropped from ${lastNodeCount} to ${currentNodeCount} nodes. Likely accidental deletion.`,
         )
@@ -118,19 +135,33 @@ export function useAutoSave({
     const unsubscribe = useScene.subscribe((state) => {
       if (isLoadingSceneRef.current) {
         lastNodesSnapshot = JSON.stringify(state.nodes)
+        lastCollectionsRef = state.collections
+        lastMaterialsRef = state.materials
+        lastInstalledPluginsRef = state.installedPlugins
         return
       }
 
       if (isVersionPreviewModeRef.current) {
         setSaveStatus('paused')
         lastNodesSnapshot = JSON.stringify(state.nodes)
+        lastCollectionsRef = state.collections
+        lastMaterialsRef = state.materials
+        lastInstalledPluginsRef = state.installedPlugins
         return
       }
 
       const currentNodesSnapshot = JSON.stringify(state.nodes)
-      if (currentNodesSnapshot === lastNodesSnapshot) return
+      const changed =
+        currentNodesSnapshot !== lastNodesSnapshot ||
+        state.collections !== lastCollectionsRef ||
+        state.materials !== lastMaterialsRef ||
+        state.installedPlugins !== lastInstalledPluginsRef
+      if (!changed) return
 
       lastNodesSnapshot = currentNodesSnapshot
+      lastCollectionsRef = state.collections
+      lastMaterialsRef = state.materials
+      lastInstalledPluginsRef = state.installedPlugins
       hasDirtyChangesRef.current = true
       onDirtyRef.current?.()
       setSaveStatus('pending')
@@ -155,9 +186,25 @@ export function useAutoSave({
     // (mobile Safari, bfcache) where `beforeunload` does not.
     function flushOnExit() {
       if (!hasDirtyChangesRef.current) return
+      const { nodes, rootNodeIds, collections, materials, installedPlugins } = useScene.getState()
+      const currentNodeCount = Object.keys(nodes).length
+      if (isSuspiciousNodeDrop(lastNodeCount, currentNodeCount)) {
+        console.warn(
+          `[autosave] Blocked unload flush: scene dropped from ${lastNodeCount} to ${currentNodeCount} nodes. Likely accidental deletion.`,
+        )
+        setSaveStatus('error')
+        return
+      }
+
       hasDirtyChangesRef.current = false
-      const { nodes, rootNodeIds } = useScene.getState()
-      const sceneGraph = { nodes, rootNodeIds } as SceneGraph
+      lastNodeCount = currentNodeCount
+      const sceneGraph = {
+        nodes,
+        rootNodeIds,
+        collections,
+        materials,
+        installedPlugins,
+      } as SceneGraph
       if (onSaveRef.current) {
         onSaveRef.current(sceneGraph, { keepalive: true }).catch(() => {})
       } else {

package/src/hooks/use-ceiling-events.ts

@@ -12,6 +12,7 @@ import { useThree } from '@react-three/fiber'
 import { useEffect, useRef } from 'react'
 import { type Object3D, Plane, Raycaster, Vector2, Vector3 } from 'three'
 import useEditor from '../store/use-editor'
+import { getMovingNode } from '../store/use-interaction-scope'
 
 const UP = new Vector3(0, 1, 0)
 
@@ -59,7 +60,7 @@ export function useCeilingEvents() {
     const isActive = (): boolean => {
       const ed = useEditor.getState()
       if (ed.selectedItem?.attachTo === 'ceiling') return true
-      const moving = ed.movingNode
+      const moving = getMovingNode()
       return moving?.type === 'item' && moving.asset?.attachTo === 'ceiling'
     }
 
@@ -85,7 +86,7 @@ export function useCeilingEvents() {
 
       for (const id of ceilingIds) {
         const node = nodes[id as AnyNodeId] as CeilingNode | undefined
-        if (!node || node.type !== 'ceiling' || node.polygon.length < 3) continue
+        if (node?.type !== 'ceiling' || node.polygon.length < 3) continue
         if (resolveLevelId(node, nodes) !== activeLevelId) continue
         const mesh = sceneRegistry.nodes.get(id)
         if (!mesh) continue

package/src/hooks/use-drag-action.ts

@@ -19,7 +19,10 @@ import { useEffect, useRef } from 'react'
 const sceneApi = createSceneApi(useScene)
 
 function modifiersFromGridEvent(event: GridEvent): Modifiers {
-  const ne = event.nativeEvent?.nativeEvent as Partial<KeyboardEvent> | undefined
+  // Both grid-event emit paths (use-grid-events.ts and the floorplan panel)
+  // store the raw DOM event directly at `.nativeEvent` — there is no second
+  // `.nativeEvent` hop.
+  const ne = event.nativeEvent as Partial<MouseEvent> | undefined
   return {
     shift: ne?.shiftKey ?? false,
     alt: ne?.altKey ?? false,

package/src/hooks/use-grid-events.ts

@@ -9,6 +9,8 @@ import { useViewer } from '@pascal-app/viewer'
 import { useThree } from '@react-three/fiber'
 import { useEffect, useRef } from 'react'
 import { Plane, Raycaster, Vector2, Vector3 } from 'three'
+import { getPlacementSurface } from '../lib/active-placement-surface'
+import { resolveTerrainGroundHit } from '../lib/ground-surface'
 
 /**
  * Custom grid events hook that uses manual raycasting instead of mesh events.
@@ -38,6 +40,28 @@ export function useGridEvents(gridY: number) {
       // Update raycaster
       raycaster.current.setFromCamera(pointer.current, camera)
 
+      // Sculpted ground wins over the plane, but only while the plane IS the
+      // ground (see `isSiteGroundPlane`): a plane riding a storey base or a slab
+      // top is a real flat surface and must stay planar. The march is what removes
+      // the perspective skew — a ray intersected at the datum instead of at the
+      // hillside reports an XZ that slides along the ray, so every tool consuming
+      // `position`/`localPosition` was placing short of the cursor on a slope.
+      //
+      // The plane's own height is the query height, not the `gridY` argument: this
+      // effect is keyed on `[camera, gl]` (re-attaching listeners mid-drag would
+      // drop the gesture), so the argument in this closure is the value from mount.
+      // `constant = -gridY` by construction in the effect above.
+      const { origin, direction } = raycaster.current.ray
+      const fixedConstructionPlane = getPlacementSurface()?.projection === 'fixed-plane'
+      const hit = fixedConstructionPlane
+        ? null
+        : resolveTerrainGroundHit(
+            [origin.x, origin.y, origin.z],
+            [direction.x, direction.y, direction.z],
+            -groundPlane.current.constant,
+          )
+      if (hit) return intersectionPoint.current.set(hit.x, hit.y, hit.z).clone()
+
       // Intersect with ground plane
       if (raycaster.current.ray.intersectPlane(groundPlane.current, intersectionPoint.current)) {
         return intersectionPoint.current.clone()