Node registry & plugin-ready architecture (Phase 0-5)

apps/editor/components/scene-loader.tsx

@@ -1,5 +1,6 @@
 'use client'
 
+import '../lib/bootstrap'
 import {
   applySceneGraphToEditor,
   Editor,

apps/editor/lib/bootstrap.ts

@@ -0,0 +1,50 @@
+import { discoverPlugins, loadPlugin, nodeRegistry } from '@pascal-app/core'
+import { builtinPlugin } from '@pascal-app/nodes'
+
+// Idempotency guard: HMR can reload this module, but `registerNode` throws on
+// duplicate kinds. The flag lives in the module closure so it's reset on a
+// hard reload but survives within a session.
+let loaded = false
+
+function isDev(): boolean {
+  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process
+    ?.env
+  return env?.NODE_ENV !== 'production'
+}
+
+export async function loadBuiltinNodes(): Promise<void> {
+  if (loaded) return
+  loaded = true
+  await loadPlugin(builtinPlugin)
+
+  // Phase 6 plugin discovery hook. Always called; default impl returns
+  // `[]`. Apps that ship external node packs override the discovery via
+  // `setPluginDiscovery(...)` before this module loads. See
+  // `wiki/editor-plugin-authoring.md` for the contract.
+  const externals = await discoverPlugins()
+  for (const plugin of externals) {
+    await loadPlugin(plugin)
+  }
+
+  if (isDev()) {
+    const kinds = Array.from(nodeRegistry.entries(), ([k]) => k)
+    if (typeof console !== 'undefined') {
+      // Visible in the browser dev console — the verification anchor for
+      // "which path is running this kind?" Empty array = every kind is on
+      // the legacy path. Kind in the array = registry path is live for it.
+      console.info(
+        `[pascal:registry] loaded ${builtinPlugin.id} v${builtinPlugin.apiVersion} (${kinds.length} kinds: ${kinds.join(', ') || '∅'})${externals.length > 0 ? ` + ${externals.length} discovered plugin(s)` : ''}`,
+      )
+    }
+    // Expose the registry on window for ad-hoc dev inspection. In prod the
+    // registry is reachable through @pascal-app/core's exports only.
+    if (typeof globalThis !== 'undefined') {
+      ;(globalThis as { __pascalNodeRegistry?: typeof nodeRegistry }).__pascalNodeRegistry =
+        nodeRegistry
+    }
+  }
+}
+
+// Run as a side effect on first import so any consumer of this module gets a
+// populated registry without remembering to call the function explicitly.
+void loadBuiltinNodes()

apps/editor/package.json

@@ -16,6 +16,7 @@
     "@pascal-app/core": "*",
     "@pascal-app/editor": "*",
     "@pascal-app/mcp": "*",
+    "@pascal-app/nodes": "*",
     "@pascal-app/viewer": "*",
     "@radix-ui/react-tooltip": "^1.2.8",
     "@react-three/drei": "^10.7.7",

biome.jsonc

@@ -122,6 +122,30 @@
           }
         }
       }
+    },
+    {
+      "includes": [
+        "packages/core/**/*.ts",
+        "packages/core/**/*.tsx",
+        "packages/viewer/**/*.ts",
+        "packages/viewer/**/*.tsx",
+        "packages/editor/**/*.ts",
+        "packages/editor/**/*.tsx"
+      ],
+      "linter": {
+        "rules": {
+          "style": {
+            "noRestrictedImports": {
+              "level": "error",
+              "options": {
+                "paths": {
+                  "@pascal-app/nodes": "Framework packages must not import from @pascal-app/nodes — consult nodeRegistry.get(kind) instead. See plans/editor-node-registry.md."
+                }
+              }
+            }
+          }
+        }
+      }
     }
   ]
 }

packages/core/package.json

@@ -16,6 +16,11 @@
       "import": "./dist/utils/clone-scene-graph.js",
       "default": "./dist/utils/clone-scene-graph.js"
     },
+    "./registry": {
+      "types": "./dist/registry/index.d.ts",
+      "import": "./dist/registry/index.js",
+      "default": "./dist/registry/index.js"
+    },
     "./schema": {
       "types": "./dist/schema/index.d.ts",
       "import": "./dist/schema/index.js",
@@ -54,6 +59,8 @@
   "scripts": {
     "build": "tsc --build",
     "dev": "tsc --build --watch",
+    "test": "bun test",
+    "bench:registry": "bun run src/registry/__bench__/relations-resolver.bench.ts",
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {

packages/core/src/events/bus.ts

@@ -13,6 +13,8 @@ import type {
   LevelNode,
   RoofNode,
   RoofSegmentNode,
+  ScanNode,
+  ShelfNode,
   SiteNode,
   SlabNode,
   SpawnNode,
@@ -35,7 +37,14 @@ export interface GridEvent {
    */
   localPosition: [number, number, number]
   faceIndex?: number
-  object: Object3D
+  /**
+   * Optional: the hit Three.js object. Present when the grid event was
+   * synthesized from a R3F mesh hit (the legacy grid-plane mesh path);
+   * absent when emitted by the canvas-level raycaster in
+   * `use-grid-events.ts`, where there is no specific mesh to attribute
+   * the intersection to.
+   */
+  object?: Object3D
   nativeEvent: ThreeEvent<PointerEvent>
 }
 
@@ -57,6 +66,7 @@ export type SiteEvent = NodeEvent<SiteNode>
 export type BuildingEvent = NodeEvent<BuildingNode>
 export type LevelEvent = NodeEvent<LevelNode>
 export type ZoneEvent = NodeEvent<ZoneNode>
+export type ShelfEvent = NodeEvent<ShelfNode>
 export type SlabEvent = NodeEvent<SlabNode>
 export type SpawnEvent = NodeEvent<SpawnNode>
 export type CeilingEvent = NodeEvent<CeilingNode>
@@ -68,6 +78,8 @@ export type StairSegmentEvent = NodeEvent<StairSegmentNode>
 export type WindowEvent = NodeEvent<WindowNode>
 export type DoorEvent = NodeEvent<DoorNode>
 export type ElevatorEvent = NodeEvent<ElevatorNode>
+export type ScanEvent = NodeEvent<ScanNode>
+export type GuideEvent = NodeEvent<GuideNode>
 
 // Event suffixes - exported for use in hooks
 export const eventSuffixes = [
@@ -189,6 +201,7 @@ type EditorEvents = GridEvents &
   NodeEvents<'level', LevelEvent> &
   NodeEvents<'zone', ZoneEvent> &
   NodeEvents<'slab', SlabEvent> &
+  NodeEvents<'shelf', ShelfEvent> &
   NodeEvents<'spawn', SpawnEvent> &
   NodeEvents<'ceiling', CeilingEvent> &
   NodeEvents<'column', ColumnEvent> &
@@ -198,6 +211,8 @@ type EditorEvents = GridEvents &
   NodeEvents<'stair-segment', StairSegmentEvent> &
   NodeEvents<'window', WindowEvent> &
   NodeEvents<'door', DoorEvent> &
+  NodeEvents<'scan', ScanEvent> &
+  NodeEvents<'guide', GuideEvent> &
   CameraControlEvents &
   ToolEvents &
   GuideEvents &

packages/core/src/hooks/scene-registry/scene-registry.ts

@@ -3,63 +3,75 @@
 import { useLayoutEffect } from 'react'
 import type * as THREE from 'three'
 
+// `byType` is a Proxy-backed Map keyed by kind. Sets are created lazily on
+// first access, so any kind (built-in or plugin-contributed) participates
+// without needing a hardcoded seed list. The previous `KNOWN_NODE_KINDS`
+// array was a pre-seed for autocomplete; with every kind now flowing
+// through `nodeRegistry`, the seed is redundant.
+//
+// The type expresses that *any* string key returns a `Set<string>` — the
+// Proxy auto-creates on first access so there's no `undefined` branch at
+// runtime. Without this shape, `noUncheckedIndexedAccess` would force
+// every caller to defend against an impossible undefined.
+type ByTypeMap = { [kind: string]: Set<string> }
+const byTypeStore = new Map<string, Set<string>>()
+
+const byTypeProxy = new Proxy({} as ByTypeMap, {
+  get(_target, key) {
+    if (typeof key !== 'string') return undefined
+    let set = byTypeStore.get(key)
+    if (!set) {
+      set = new Set<string>()
+      byTypeStore.set(key, set)
+    }
+    return set
+  },
+  ownKeys() {
+    return Array.from(byTypeStore.keys())
+  },
+  has(_target, key) {
+    return typeof key === 'string' && byTypeStore.has(key)
+  },
+  getOwnPropertyDescriptor(_target, key) {
+    if (typeof key !== 'string') return undefined
+    const set = byTypeStore.get(key)
+    if (!set) return undefined
+    return { configurable: true, enumerable: true, value: set, writable: false }
+  },
+})
+
 export const sceneRegistry = {
   // Master lookup: ID -> Object3D
   nodes: new Map<string, THREE.Object3D>(),
 
-  // Categorized lookups: Type -> Set of IDs
-  // Using a Set is faster for adding/deleting than an Array
-  byType: {
-    site: new Set<string>(),
-    building: new Set<string>(),
-    ceiling: new Set<string>(),
-    column: new Set<string>(),
-    elevator: new Set<string>(),
-    level: new Set<string>(),
-    wall: new Set<string>(),
-    fence: new Set<string>(),
-    item: new Set<string>(),
-    slab: new Set<string>(),
-    spawn: new Set<string>(),
-    zone: new Set<string>(),
-    roof: new Set<string>(),
-    'roof-segment': new Set<string>(),
-    stair: new Set<string>(),
-    'stair-segment': new Set<string>(),
-    scan: new Set<string>(),
-    guide: new Set<string>(),
-    window: new Set<string>(),
-    door: new Set<string>(),
-  },
+  // Categorized lookups: Kind -> Set of IDs. Backed by a Proxy so any kind
+  // gets a Set on first touch — no hardcoded list.
+  byType: byTypeProxy,
 
   /** Remove all entries. Call when unloading a scene to prevent stale 3D refs. */
   clear() {
     this.nodes.clear()
-    for (const set of Object.values(this.byType)) {
+    for (const set of byTypeStore.values()) {
       set.clear()
     }
   },
 }
 
-export function useRegistry(
-  id: string,
-  type: keyof typeof sceneRegistry.byType,
-  ref: React.RefObject<THREE.Object3D>,
-) {
+export function useRegistry(id: string, type: string, ref: React.RefObject<THREE.Object3D>) {
   useLayoutEffect(() => {
     const obj = ref.current
     if (!obj) return
 
     // 1. Add to master map
     sceneRegistry.nodes.set(id, obj)
 
-    // 2. Add to type-specific set
-    sceneRegistry.byType[type].add(id)
+    // 2. Add to type-specific set — Proxy auto-creates on first access.
+    sceneRegistry.byType[type]!.add(id)
 
-    // 4. Cleanup when component unmounts
+    // 3. Cleanup when component unmounts
     return () => {
       sceneRegistry.nodes.delete(id)
-      sceneRegistry.byType[type].delete(id)
+      sceneRegistry.byType[type]!.delete(id)
     }
   }, [id, type, ref])
 }