wiki: add node-definitions doc for three-checkbox composition model

New page covering the geometry/renderer/system trio that registry-driven
kinds opt into. Documents:

- The three optional fields on NodeDefinition and when each applies
- Generic <GeometrySystem> + <ParametricNodeRenderer> runtime
- GeometryContext shape (resolve / children / siblings / parent)
- Combination matrix for shelf / spawn / zone / door / window / GLB items
- Migration recipe from custom renderer+system files to def.geometry
- Rules around purity, dispose-on-rebuild, register-once

renderers.md and systems.md gain "prefer registry-driven" banners and
link out to the new page. Architecture README adds the page to the
index so review-architecture skill picks it up.

The pattern was validated by the shelf spike: inline-JSX geometry was
visibly laggy on parametric edits; moving to a per-kind system reading
dirtyNodes (mirroring door/wall/item) restored smoothness. The three-
checkbox model generalises that win so most future kinds need only a
pure geometry function.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Wassim SAMAD
2026-05-15 08:29:54 -04:00
co-authored by Claude Opus 4.7
parent 7f24593041
commit 7b946ce8b7
4 changed files with 193 additions and 0 deletions
+2
View File
@@ -6,6 +6,8 @@ Applies to: `packages/core/src/systems/**`, `packages/viewer/src/systems/**`.
Systems own business logic, geometry generation, and constraints. They run in the Three.js frame loop and are never rendered directly.
> **For registry-driven kinds, prefer no per-kind system.** If your kind's only job is "rebuild geometry on dirty", set `def.geometry` and let the framework's `<GeometrySystem>` handle the rebuild loop. Per-kind systems remain for *extra* responsibilities — animations, cross-kind dirty cascades, named-mesh material poking. See [node-definitions.md](node-definitions.md).
## Two Kinds of Systems
### Core Systems — `packages/core/src/systems/`