Use and adapt editor

Use the documented interfaces and source layout for editor. The sections below retain the README’s examples and configuration details.

Repository Architecture

This is a Turborepo monorepo with three main packages:

1editor-v2/
2├── apps/
3│   └── editor/          # Next.js application
4├── packages/
5│   ├── core/            # Schema definitions, state management, systems
6│   └── viewer/          # 3D rendering components

Separation of Concerns

The viewer renders the scene with sensible defaults. The editor extends it with interactive tools, selection management, and editing capabilities.

Stores

Each package has its own Zustand store for managing state:

Access patterns:

1// Subscribe to state changes (React component)
2const nodes = useScene((state) => state.nodes)
3const levelId = useViewer((state) => state.selection.levelId)
4const activeTool = useEditor((state) => state.tool)
5 
6// Access state outside React (callbacks, systems)
7const node = useScene.getState().nodes[id]
8useViewer.getState().setSelection({ levelId: 'level_123' })

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:

1. Renderer creates a placeholder mesh/group
2. Registers it with useRegistry
3. 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):

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

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.

Editor Architecture

The editor extends the viewer with:

Tools

Tools are activated via the toolbar and handle user input for specific operations:

• SelectTool - Selection and manipulation
• WallTool - Draw walls
• ZoneTool - Create zones
• ItemTool - Place furniture/fixtures
• SlabTool - Create floor slabs

Selection Manager

The editor uses a custom selection manager with hierarchical navigation:

1Site → Building → Level → Zone → Items

Each depth level has its own selection strategy for hover/click behavior.

Editor-Specific Systems

• ZoneSystem - Controls zone visibility based on level mode
• Custom camera controls with node focusing

Commands in the root manifest

The captured package.json declares the following scripts. Run them from the directory containing that manifest.

Troubleshoot a local change

1. Reproduce the smallest example from the quick-start guide.
2. Compare required configuration and dependency versions with the README.
3. Check the linked issue tracker for the same error. Include the command, runtime version, and relevant error when reporting a problem; omit credentials.

Source and help

• GitHub repository
• Original README
• Issues and existing reports
• Open the project website

The catalog identifies the license as MIT. Read the repository license before redistributing source or assets.

This catalog entry is a fork. The README may describe upstream packages, domains, or release procedures; those destinations do not establish a separate release of this fork.