feat: stair system, scene graph utilities, read-only mode, viewer state improvements (#210)

Stair system (full stack):
- New StairNode + StairSegmentNode schemas with flights, landings, L/U-shapes
- StairSystem: geometry generation with throttled per-frame updates
- Stair tool, edit system, panels, tree node, and renderers
- Event bus types, scene registry, and command palette entries

Scene graph utilities:
- cloneLevelSubtree: deep-clone a level with remapped IDs
- forkSceneGraph: clone + strip scan/guide nodes for project forking

Core improvements:
- Read-only mode on scene store (blocks create/update/delete when locked)
- readOnly guards on node-actions and collection actions
- Upload store for scan/guide file upload handling

Viewer state:
- previewSelectedIds for box-select live preview
- hoverHighlightMode (default/delete) for delete-mode hover outline

packages/viewer/src/components/renderers/node-renderer.tsx

@@ -12,6 +12,8 @@ import { RoofSegmentRenderer } from './roof-segment/roof-segment-renderer'
 import { ScanRenderer } from './scan/scan-renderer'
 import { SiteRenderer } from './site/site-renderer'
 import { SlabRenderer } from './slab/slab-renderer'
+import { StairRenderer } from './stair/stair-renderer'
+import { StairSegmentRenderer } from './stair-segment/stair-segment-renderer'
 import { WallRenderer } from './wall/wall-renderer'
 import { WindowRenderer } from './window/window-renderer'
 import { ZoneRenderer } from './zone/zone-renderer'
@@ -35,6 +37,8 @@ export const NodeRenderer = ({ nodeId }: { nodeId: AnyNode['id'] }) => {
       {node.type === 'zone' && <ZoneRenderer node={node} />}
       {node.type === 'roof' && <RoofRenderer node={node} />}
       {node.type === 'roof-segment' && <RoofSegmentRenderer node={node} />}
+      {node.type === 'stair' && <StairRenderer node={node} />}
+      {node.type === 'stair-segment' && <StairSegmentRenderer node={node} />}
       {node.type === 'scan' && <ScanRenderer node={node} />}
       {node.type === 'guide' && <GuideRenderer node={node} />}
     </>

packages/viewer/src/components/renderers/stair-segment/stair-segment-renderer.tsx

@@ -0,0 +1,37 @@
+import { type StairSegmentNode, useRegistry, useScene } from '@pascal-app/core'
+import { useLayoutEffect, useMemo, useRef } from 'react'
+import type * as THREE from 'three'
+import { useNodeEvents } from '../../../hooks/use-node-events'
+import { createMaterial, DEFAULT_STAIR_MATERIAL } from '../../../lib/materials'
+
+export const StairSegmentRenderer = ({ node }: { node: StairSegmentNode }) => {
+  const ref = useRef<THREE.Mesh>(null!)
+
+  useRegistry(node.id, 'stair-segment', ref)
+
+  useLayoutEffect(() => {
+    useScene.getState().markDirty(node.id)
+  }, [node.id])
+
+  const handlers = useNodeEvents(node, 'stair-segment')
+
+  const material = useMemo(() => {
+    const mat = node.material
+    if (!mat) return DEFAULT_STAIR_MATERIAL
+    return createMaterial(mat)
+  }, [node.material, node.material?.preset, node.material?.properties, node.material?.texture])
+
+  return (
+    <mesh
+      material={material}
+      position={node.position}
+      ref={ref}
+      rotation-y={node.rotation}
+      visible={node.visible}
+      {...handlers}
+    >
+      {/* StairSystem will replace this geometry in the next frame */}
+      <boxGeometry args={[0, 0, 0]} />
+    </mesh>
+  )
+}

packages/viewer/src/components/renderers/stair/stair-renderer.tsx

@@ -0,0 +1,43 @@
+import { type StairNode, useRegistry, useScene } from '@pascal-app/core'
+import { useLayoutEffect, useMemo, useRef } from 'react'
+import type * as THREE from 'three'
+import { useNodeEvents } from '../../../hooks/use-node-events'
+import { createMaterial, DEFAULT_STAIR_MATERIAL } from '../../../lib/materials'
+import { NodeRenderer } from '../node-renderer'
+
+export const StairRenderer = ({ node }: { node: StairNode }) => {
+  const ref = useRef<THREE.Group>(null!)
+
+  useRegistry(node.id, 'stair', ref)
+
+  useLayoutEffect(() => {
+    useScene.getState().markDirty(node.id)
+  }, [node.id])
+
+  const handlers = useNodeEvents(node, 'stair')
+
+  const material = useMemo(() => {
+    const mat = node.material
+    if (!mat) return DEFAULT_STAIR_MATERIAL
+    return createMaterial(mat)
+  }, [node.material, node.material?.preset, node.material?.properties, node.material?.texture])
+
+  return (
+    <group
+      position={node.position}
+      ref={ref}
+      rotation-y={node.rotation}
+      visible={node.visible}
+      {...handlers}
+    >
+      <mesh castShadow material={material} name="merged-stair" receiveShadow>
+        <boxGeometry args={[0, 0, 0]} />
+      </mesh>
+      <group name="segments-wrapper" visible={false}>
+        {(node.children ?? []).map((childId) => (
+          <NodeRenderer key={childId} nodeId={childId} />
+        ))}
+      </group>
+    </group>
+  )
+}

packages/viewer/src/components/viewer/index.tsx

@@ -6,6 +6,7 @@ import {
   ItemSystem,
   RoofSystem,
   SlabSystem,
+  StairSystem,
   WallSystem,
   WindowSystem,
 } from '@pascal-app/core'
@@ -142,6 +143,7 @@ const Viewer: React.FC<ViewerProps> = ({
       <ItemSystem />
       <RoofSystem />
       <SlabSystem />
+      <StairSystem />
       <WallSystem />
       <WindowSystem />
       <ZoneSystem />

packages/viewer/src/hooks/use-node-events.ts

@@ -19,6 +19,10 @@ import {
   type SiteNode,
   type SlabEvent,
   type SlabNode,
+  type StairEvent,
+  type StairNode,
+  type StairSegmentEvent,
+  type StairSegmentNode,
   type WallEvent,
   type WallNode,
   type WindowEvent,
@@ -40,6 +44,8 @@ type NodeConfig = {
   ceiling: { node: CeilingNode; event: CeilingEvent }
   roof: { node: RoofNode; event: RoofEvent }
   'roof-segment': { node: RoofSegmentNode; event: RoofSegmentEvent }
+  stair: { node: StairNode; event: StairEvent }
+  'stair-segment': { node: StairSegmentNode; event: StairSegmentEvent }
   window: { node: WindowNode; event: WindowEvent }
   door: { node: DoorNode; event: DoorEvent }
 }

packages/viewer/src/lib/materials.ts

@@ -35,8 +35,8 @@ export function createMaterial(material?: MaterialSchema): THREE.MeshStandardMat
 }
 
 export function createDefaultMaterial(
-  color: string = '#ffffff',
-  roughness: number = 0.9,
+  color = '#ffffff',
+  roughness = 0.9,
 ): THREE.MeshStandardMaterial {
   return new THREE.MeshStandardMaterial({
     color,
@@ -59,6 +59,7 @@ export const DEFAULT_WINDOW_MATERIAL = new THREE.MeshStandardMaterial({
 })
 export const DEFAULT_CEILING_MATERIAL = createDefaultMaterial('#f5f5dc', 0.95)
 export const DEFAULT_ROOF_MATERIAL = createDefaultMaterial('#808080', 0.85)
+export const DEFAULT_STAIR_MATERIAL = createDefaultMaterial('#ffffff', 0.9)
 
 export function disposeMaterial(material: THREE.Material): void {
   material.dispose()

packages/viewer/src/store/use-viewer.d.ts

@@ -12,6 +12,10 @@ type Outliner = {
 }
 type ViewerState = {
   selection: SelectionPath
+  previewSelectedIds: BaseNode['id'][]
+  setPreviewSelectedIds: (ids: BaseNode['id'][]) => void
+  hoverHighlightMode: 'default' | 'delete'
+  setHoverHighlightMode: (mode: 'default' | 'delete') => void
   hoveredId: AnyNode['id'] | ZoneNode['id'] | null
   setHoveredId: (id: AnyNode['id'] | ZoneNode['id'] | null) => void
   cameraMode: 'perspective' | 'orthographic'

packages/viewer/src/store/use-viewer.ts

@@ -20,6 +20,10 @@ type Outliner = {
 
 type ViewerState = {
   selection: SelectionPath
+  previewSelectedIds: BaseNode['id'][]
+  setPreviewSelectedIds: (ids: BaseNode['id'][]) => void
+  hoverHighlightMode: 'default' | 'delete'
+  setHoverHighlightMode: (mode: 'default' | 'delete') => void
   hoveredId: AnyNode['id'] | ZoneNode['id'] | null
   setHoveredId: (id: AnyNode['id'] | ZoneNode['id'] | null) => void
 
@@ -75,6 +79,10 @@ const useViewer = create<ViewerState>()(
   persist(
     (set) => ({
       selection: { buildingId: null, levelId: null, zoneId: null, selectedIds: [] },
+      previewSelectedIds: [],
+      setPreviewSelectedIds: (ids) => set({ previewSelectedIds: ids }),
+      hoverHighlightMode: 'default',
+      setHoverHighlightMode: (mode) => set({ hoverHighlightMode: mode }),
       hoveredId: null,
       setHoveredId: (id) => set({ hoveredId: id }),
 
@@ -164,7 +172,7 @@ const useViewer = create<ViewerState>()(
             if (updates.selectedIds === undefined) newSelection.selectedIds = []
           }
 
-          return { selection: newSelection }
+          return { selection: newSelection, previewSelectedIds: [] }
         }),
 
       resetSelection: () =>
@@ -175,6 +183,7 @@ const useViewer = create<ViewerState>()(
             zoneId: null,
             selectedIds: [],
           },
+          previewSelectedIds: [],
         }),
 
       outliner: { selectedObjects: [], hoveredObjects: [] },