docs(viewer): document npm registry bootstrap (#521)

README.md

@@ -10,19 +10,38 @@ A 3D building editor built with React Three Fiber and WebGPU.
 
 https://github.com/user-attachments/assets/8b50e7cf-cebe-4579-9cf3-8786b35f7b6b
 
+## Using Published Packages
+
+The viewer runtime and built-in node definitions are separate packages. Install the full built-in
+viewer set, then load the built-in plugin once before mounting `<Viewer>`:
+
+```bash
+npm install @pascal-app/core @pascal-app/viewer @pascal-app/editor @pascal-app/nodes
+```
+
+```typescript
+import { loadPlugin } from '@pascal-app/core'
+import { builtinPlugin } from '@pascal-app/nodes'
+
+await loadPlugin(builtinPlugin)
+```
+
+See the [`@pascal-app/viewer` quick start](packages/viewer/README.md#usage) for a React example.
 
 
 ## Repository Architecture
 
-This is a Turborepo monorepo with three main packages:
+This is a Turborepo monorepo with four main runtime packages:
 
 ```
 editor/
 ├── apps/
 │   └── editor/          # Next.js application
 ├── packages/
-│   ├── core/            # Schema definitions, state management, systems
+│   ├── core/            # Schemas, scene state, and registry contracts
-│   ├── viewer/          # 3D rendering components
+│   ├── viewer/          # 3D rendering runtime and shared systems
+│   ├── editor/          # Editing tools and UI components
+│   ├── nodes/           # Built-in node definitions, renderers, and systems
 │   └── ui/              # Shared UI components
 ```
 
@@ -30,9 +49,11 @@ editor/
 
 | Package | Responsibility |
 |---------|---------------|
-| **@pascal-app/core** | Node schemas, scene state (Zustand), systems (geometry generation), spatial queries, event bus |
+| **@pascal-app/core** | Node schemas, scene state (Zustand), registry contracts, spatial queries, and event bus |
-| **@pascal-app/viewer** | 3D rendering via React Three Fiber, default camera/controls, post-processing |
+| **@pascal-app/viewer** | 3D rendering via React Three Fiber, shared render systems, default camera/controls, and post-processing |
-| **apps/editor** | UI components, tools, custom behaviors, editor-specific systems |
+| **@pascal-app/editor** | Editing tools, panels, selection, and direct-manipulation UI |
+| **@pascal-app/nodes** | Built-in registry plugin with node definitions, renderers, geometry, and systems |
+| **apps/editor** | Standalone Next.js host for the editor packages |
 
 The **viewer** renders the scene with sensible defaults. The **editor** extends it with interactive tools, selection management, and editing capabilities.
 

packages/core/README.md

@@ -18,7 +18,7 @@ npm install react three @react-three/fiber @react-three/drei
 
 - **Node Schemas** - Zod schemas for all building primitives (walls, slabs, items, etc.)
 - **Scene State** - Zustand store with IndexedDB persistence and undo/redo
-- **Systems** - Geometry generation for walls, floors, ceilings, roofs
+- **Registry Contracts** - Plugin and node-definition APIs shared by renderers and editor tools
 - **Scene Registry** - Fast lookup from node IDs to Three.js objects
 - **Spatial Grid** - Collision detection and placement validation
 - **Event Bus** - Typed event emitter for inter-component communication
@@ -27,11 +27,12 @@ npm install react three @react-three/fiber @react-three/drei
 ## Usage
 
 ```typescript
-import { useScene, WallNode, ItemNode } from '@pascal-app/core'
+import { useScene, WallNode } from '@pascal-app/core'
 
 // Create a wall
 const wall = WallNode.parse({
-  points: [[0, 0], [5, 0]],
+  start: [0, 0],
+  end: [5, 0],
   height: 3,
   thickness: 0.2,
 })
@@ -61,15 +62,21 @@ function MyComponent() {
 - `ScanNode` - 3D scan reference
 - `GuideNode` - 2D guide image reference
 
-## Systems
+## Built-in Node Definitions
 
-Systems process dirty nodes each frame to update geometry:
+Core contains the schemas, scene state, and registry contracts. The built-in node definitions,
+renderers, geometry builders, tools, and systems ship in `@pascal-app/nodes`:
 
-- `WallSystem` - Wall geometry with mitering and CSG cutouts
+```typescript
-- `SlabSystem` - Floor polygon generation
+import { loadPlugin } from '@pascal-app/core'
-- `CeilingSystem` - Ceiling geometry
+import { builtinPlugin } from '@pascal-app/nodes'
-- `RoofSystem` - Roof generation
+
-- `ItemSystem` - Item positioning on walls/ceilings/floors
+await loadPlugin(builtinPlugin)
+```
+
+Load the plugin before mounting `@pascal-app/viewer`. See the
+[`@pascal-app/viewer` quick start](https://github.com/pascalorg/editor/tree/main/packages/viewer#usage)
+for a React example.
 
 ## License
 

packages/nodes/README.md

@@ -0,0 +1,34 @@
+# @pascal-app/nodes
+
+Built-in node definitions for the Pascal viewer and editor.
+
+## Installation
+
+```bash
+npm install @pascal-app/core @pascal-app/viewer @pascal-app/editor @pascal-app/nodes
+```
+
+The package declares the remaining React, Next.js, Three.js, and UI libraries it needs as peer
+dependencies. Install any peers reported by your package manager.
+
+## Usage
+
+Load `builtinPlugin` once before mounting a Pascal viewer or editor:
+
+```typescript
+import { loadPlugin } from '@pascal-app/core'
+import { builtinPlugin } from '@pascal-app/nodes'
+
+await loadPlugin(builtinPlugin)
+```
+
+The plugin registers the built-in schemas, renderers, geometry builders, tools, and systems. Hosts
+can load additional plugins through the same `loadPlugin` API.
+
+See the
+[`@pascal-app/viewer` quick start](https://github.com/pascalorg/editor/tree/main/packages/viewer#usage)
+for bootstrap ordering in a React application.
+
+## License
+
+MIT

packages/viewer/README.md

@@ -5,19 +5,19 @@
 ## Installation
 
 ```bash
-npm install @pascal-app/viewer @pascal-app/core
+npm install @pascal-app/core @pascal-app/viewer @pascal-app/editor @pascal-app/nodes
 ```
 
 ## Peer Dependencies
 
 ```bash
-npm install react three @react-three/fiber @react-three/drei
+npm install next react react-dom three @react-three/fiber @react-three/drei lucide-react zustand
 ```
 
 ## What's Included
 
 - **Viewer Component** - WebGPU-powered 3D viewer with camera controls
-- **Node Renderers** - React Three Fiber components for all node types
+- **Node Rendering Runtime** - Registry-driven dispatch for node renderers supplied by `@pascal-app/nodes`
 - **Post-Processing** - SSGI (ambient occlusion + global illumination), TRAA (anti-aliasing), outline effects
 - **Level System** - Level visibility and positioning (stacked/exploded/solo modes)
 - **Wall Cutout System** - Dynamic wall hiding based on camera position
@@ -26,10 +26,22 @@ npm install react three @react-three/fiber @react-three/drei
 ## Usage
 
 ```typescript
-import { Viewer, useViewer } from '@pascal-app/viewer'
+import { loadPlugin } from '@pascal-app/core'
-import { useScene } from '@pascal-app/core'
+import { builtinPlugin } from '@pascal-app/nodes'
+import { Viewer } from '@pascal-app/viewer'
+import { useEffect, useState } from 'react'
+
+const registryReady = loadPlugin(builtinPlugin)
 
 function App() {
+  const [ready, setReady] = useState(false)
+
+  useEffect(() => {
+    void registryReady.then(() => setReady(true))
+  }, [])
+
+  if (!ready) return null
+
   return (
     <div style={{ width: '100vw', height: '100vh' }}>
       <Viewer />
@@ -38,6 +50,9 @@ function App() {
 }
 ```
 
+Load the built-in plugin once, before mounting any viewer. Without it, the registry has no node
+definitions and scene nodes cannot render. Host-provided plugins use the same `loadPlugin` API.
+
 ## Custom Camera Controls
 
 ```typescript

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

@@ -418,6 +418,14 @@ const Viewer = forwardRef<ViewerHandle, ViewerProps>(function Viewer(
   },
   ref,
 ) {
+  useEffect(() => {
+    if (nodeRegistry.size === 0) {
+      console.warn(
+        '[viewer] Node registry is empty. Install @pascal-app/nodes and call await loadPlugin(builtinPlugin) before mounting <Viewer>.',
+      )
+    }
+  }, [])
+
   useImperativeHandle(
     ref,
     () => ({