Core Concepts

Nodes

Nodes are the data primitives that describe the 3D scene. All nodes extend BaseNode:

1BaseNode {
2  id: string              // Auto-generated with type prefix (e.g., "wall_abc123")
3  type: string            // Discriminator for type-safe handling
4  parentId: string | null // Parent node reference
5  visible: boolean
6  camera?: Camera         // Optional saved camera position
7  metadata?: JSON         // Arbitrary metadata (e.g., { isTransient: true })
8}

Node Hierarchy:

1Site
2└── Building
3    └── Level
4        ├── Wall → Item (doors, windows)
5        ├── Slab
6        ├── Ceiling → Item (lights)
7        ├── Roof
8        ├── Zone
9        ├── Scan (3D reference)
10        └── Guide (2D reference)

Nodes are stored in a flat dictionary (Record<id, Node>), not a nested tree. Parent-child relationships are defined via parentId and children arrays.

Scene State (Zustand Store)

The scene is managed by a Zustand store in @pascal-app/core:

1useScene.getState() = {
2  nodes: Record<id, AnyNode>,  // All nodes
3  rootNodeIds: string[],       // Top-level nodes (sites)
4  dirtyNodes: Set<string>,     // Nodes pending system updates
5 
6  createNode(node, parentId),
7  updateNode(id, updates),
8  deleteNode(id),
9}

Middleware:

Persist - Saves to IndexedDB (excludes transient nodes)
Temporal (Zundo) - Undo/redo with 50-step history

Scene Registry

The registry maps node IDs to their Three.js objects for fast lookup:

1sceneRegistry = {
2  nodes: Map<id, Object3D>,    // ID → 3D object
3  byType: {
4    wall: Set<id>,
5    item: Set<id>,
6    zone: Set<id>,
7    // ...
8  }
9}

Renderers register their refs using the useRegistry hook:

1const ref = useRef<Mesh>(null!)
2useRegistry(node.id, 'wall', ref)

This allows systems to access 3D objects directly without traversing the scene graph.

Node Renderers

Renderers are React components that create Three.js objects for each node type:

1SceneRenderer
2└── NodeRenderer (dispatches by type)
3    ├── BuildingRenderer
4    ├── LevelRenderer
5    ├── WallRenderer
6    ├── SlabRenderer
7    ├── ZoneRenderer
8    ├── ItemRenderer
9    └── ...

Pattern:

Renderer creates a placeholder mesh/group
Registers it with useRegistry
Systems update geometry based on node data

Example (simplified):

1const WallRenderer = ({ node }) => {
2  const ref = useRef<Mesh>(null!)
3  useRegistry(node.id, 'wall', ref)
4 
5  return (
6    <mesh ref={ref}>
7      <boxGeometry args={[0, 0, 0]} />  {/* Replaced by WallSystem */}
8      <meshStandardMaterial />
9      {node.children.map(id => <NodeRenderer key={id} nodeId={id} />)}
10    </mesh>
11  )
12}

Systems

Systems are React components that run in the render loop (useFrame) to update geometry and transforms. They process dirty nodes marked by the store.

Core Systems (in @pascal-app/core):

System	Responsibility
`WallSystem`	Generates wall geometry with mitering and CSG cutouts for doors/windows
`SlabSystem`	Generates floor geometry from polygons
`CeilingSystem`	Generates ceiling geometry
`RoofSystem`	Generates roof geometry
`ItemSystem`	Positions items on walls, ceilings, or floors (slab elevation)

Viewer Systems (in @pascal-app/viewer):

System	Responsibility
`LevelSystem`	Handles level visibility and vertical positioning (stacked/exploded/solo modes)
`ScanSystem`	Controls 3D scan visibility
`GuideSystem`	Controls guide image visibility

Processing Pattern:

1useFrame(() => {
2  for (const id of dirtyNodes) {
3    const obj = sceneRegistry.nodes.get(id)
4    const node = useScene.getState().nodes[id]
5 
6    // Update geometry, transforms, etc.
7    updateGeometry(obj, node)
8 
9    dirtyNodes.delete(id)
10  }
11})

Dirty Nodes

When a node changes, it's marked as dirty in useScene.getState().dirtyNodes. Systems check this set each frame and only recompute geometry for dirty nodes.

1// Automatic: createNode, updateNode, deleteNode mark nodes dirty
2useScene.getState().updateNode(wallId, { thickness: 0.2 })
3// → wallId added to dirtyNodes
4// → WallSystem regenerates geometry next frame
5// → wallId removed from dirtyNodes

Manual marking:

1useScene.getState().dirtyNodes.add(wallId)

Event Bus

Inter-component communication uses a typed event emitter (mitt):

1// Node events
2emitter.on('wall:click', (event) => { ... })
3emitter.on('item:enter', (event) => { ... })
4emitter.on('zone:context-menu', (event) => { ... })
5 
6// Grid events (background)
7emitter.on('grid:click', (event) => { ... })
8 
9// Event payload
10NodeEvent {
11  node: AnyNode
12  position: [x, y, z]
13  localPosition: [x, y, z]
14  normal?: [x, y, z]
15  stopPropagation: () => void
16}

Spatial Grid Manager

Handles collision detection and placement validation:

1spatialGridManager.canPlaceOnFloor(levelId, position, dimensions, rotation)
2spatialGridManager.canPlaceOnWall(wallId, t, height, dimensions)
3spatialGridManager.getSlabElevationAt(levelId, x, z)

Used by item placement tools to validate positions and calculate slab elevations.

Source captured: 2026-10-11