Falling-Metal-Interactive/Blacksite
2
0
Fork 0
Code Issues 15 Pull Requests Actions Packages Projects Releases Wiki Activity
634ec16c5e
Blacksite/docs/adr/0048-modular-editor-composition-and-debt-ratchet.md

2.7 KiB
Raw Blame History

ADR 0048: Modular Editor Composition and Architecture-Debt Ratchet

Status

Accepted

Context

The Content Browser and Inspector accumulated unrelated navigation, rendering, import, material, transaction, and component-card behavior in files thousands of lines long. That made small changes high-risk, encouraged duplicate UI, and obscured ownership. ADR 0012 states a zero-debt intent but did not provide an enforceable point-of-change budget.

Decision

Editor panels are composed from thin shells, domain modules, and UI-independent services. The Inspector delegates every visible built-in component through EditorComponentRegistry; a hard-coded type dispatcher is not a second authority. Material slot presentation uses a shared view-model/action contract, and Content Browser and Material Library cards use one bounded asset card/status model.

The machine-readable policy is .codex/architecture.toml. Its audit enforces 500 nonblank lines for UI shells, 800 for other UI modules, and 1,200 for other production Rust modules. Existing over-limit modules have frozen ceilings. A temporary exception requires a tracker issue, rationale, hard maximum, extraction target, and expiry milestone. Selective verification and candidate CI run the audit.

The M2 extraction is tracked by Gitea #68. The Content Browser and Inspector shells are now below the 500-line budget, their domain behavior lives in bounded submodules, and no temporary #68 exception is active. Closing the issue still requires the selective and native acceptance evidence defined by the milestone.

The Penpot-led material-inspector refinement remains inside #68's shared-UI scope. The reusable visual primitives live in ui/design_system, while ui/materials owns the action-returning domain panel. This keeps authored visual policy separate from Inspector world access and prevents the first design-system migration from rebuilding a panel monolith. ADR 0049 owns the visual contract.

Consequences

  • New behavior is added through a sustainable extension seam instead of enlarging a monolith.
  • Shrinking an over-limit module is always accepted; regrowth above its frozen baseline fails.
  • Passing the audit is a no-regression statement; issue closure additionally requires functional and native evidence for the extracted seams.
  • Architecture work remains visible in the same tracker and milestone as the feature that exposes it.
  • ADR 0034 owns registry-driven component semantics; this ADR owns editor composition and the mechanical debt guard.

Related decisions: ADR 0012, ADR 0034, and ADR 0047, and ADR 0049.