Blacksite/docs/adr/0034-registry-driven-authoring-components.md

ADR 0034: Registry-driven authoring components

Status

Accepted

Context

The Add Component palette was registry-backed, but presence checks, copy/paste, reset, removal, history, save filtering, validation, and most inspector dispatch were duplicated as Rust match statements. InspectorOrder also stored active state, causing hydration and game systems to depend on editor presentation metadata. ActorKind was used as validation authority, which prevented otherwise valid component composition such as a rendered mesh that also emits light.

Decision

• Every authoring component registration has an immutable editor/protocol ID separate from its reflected Rust type path. Startup validation rejects duplicate IDs/types, missing reflection adapters, and unknown recommendation/conflict references.
• Bevy reflection supplies generic presence, default insertion/reset, removal, copy/paste, and RON values for atomic ComponentTransaction history. A transaction includes the derived ActorKind hint so one undo restores the complete component edit.
• The registry builds the scene component allowlist. A statically linked extension uses register_authoring_component to register reflection metadata, lifecycle metadata, and an inspector callback together.
• Persisted AuthoringComponentStates owns component active state. InspectorOrder owns only card ordering. Schema-v3 state embedded in InspectorOrder is moved lazily and remains a read fallback during migration.
• ActorKind remains serialized for compatibility and presentation, but is derived from component composition on load and component transactions. Validation enforces component data and explicit geometry-source conflicts rather than comparing behavior with the stored hint. Compatible components, including mesh plus light, may coexist.

Consequences

• New statically linked authoring components participate in save filtering and generic component operations without adding editor-core history or persistence branches.
• Runtime systems read active state independently from inspector layout. Old scenes preserve their disabled components and upgrade in memory before their next save.
• Geometry source conflicts remain explicit, while presentation categories no longer prohibit unrelated behavior composition.
• Existing whole-entity spawn/duplicate snapshots still have typed fields. Moving those snapshots and every built-in inspector renderer to the reflected registry is follow-up work; the generic transaction path is the required path for new component operations.