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>
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>
