Wassim SAMADandClaude Opus 4.7
11015ea1ed
Captures the gotchas surfaced while building the shelf so the next
contributor adding a registry-driven kind doesn't rediscover them.
`node-definitions.md` — new Pitfalls section + a rule that builders
must emit local-space children. Covers:
- `<GeometrySystem>` must NOT mutate `group.position` / `group.rotation`
after rebuild (the renderer binds them via JSX prop).
- Tag geometry-built children with `userData.__fromGeometry` so
rebuilds don't dispose React-mounted hosted children (the
item-disappears-on-shelf bug).
- Previews must clone materials before mutating them when the kind's
builder caches at module scope.
- Host kinds need a `children: z.array(...).default([])` field on their
schema (and a migration patch for older scenes).
`tools.md` — three new move/placement pitfalls:
- Disable raycast on the moved mesh during drag, otherwise it captures
the ray and starves `grid:move` → commits land at the stale start.
- Commit handlers listen to `grid:click` AND every `${kind}:click` to
catch clicks that land on neighbouring 3D geometry first.
- Move tools must preserve the node's actual `rotation[1]` in
`useLiveTransforms` — hardcoding 0 makes the node un-rotate mid-drag.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Architecture
Canonical rules for code that touches packages/core, packages/viewer, packages/editor, packages/mcp, or apps/editor. Read on demand from AGENTS.md and from .agents/skills/review-architecture/SKILL.md.
Pages
| Page | Covers |
|---|---|
| layers | Three.js layer constants, ownership, and rendering separation |
| systems | Core and viewer systems architecture |
| renderers | Node renderer pattern in packages/viewer |
| node-definitions | Three-checkbox composition model for registry-driven kinds (geometry / renderer / system) |
| tools | Editor tools structure in apps/editor |
| viewer-isolation | Keeping @pascal-app/viewer editor-agnostic |
| selection-managers | Two-layer selection (viewer + editor), events, outliner |
| scene-registry | Global node ID → Object3D map and useRegistry |
| spatial-queries | Placement validation (canPlaceOnFloor/Wall/Ceiling) for tools |
| node-schemas | Zod schema pattern for node types, createNode, updateNode |
| events | Typed event bus — emitting and listening to node and grid events |
| creating-rules | How to add or update a page in this folder |
Reading order for an architecture review
- layers, systems, renderers, tools, viewer-isolation — required every review.
- The remaining pages on demand, based on what the diff touches.