Falling-Metal-Interactive/Blacksite
2
0
Fork 0
Code Issues 15 Pull Requests Actions Packages Projects Releases Wiki Activity

BS-JD-220 - Modular Editor UI Architecture and Debt Ratchet #68

New Issue
Closed
opened 2026-07-15 01:06:00 -04:00 by Rbanh · 5 comments
Rbanh commented 2026-07-15 01:06:00 -04:00
Owner
Copy Link

Goal

Finish M2 with a scalable editor UI architecture and an automated debt ratchet while preserving the live-material correctness owned by #67.

Scope

  • Decompose the Content Browser and Inspector into bounded domain modules with shells no larger than 500 nonblank lines.
  • Make EditorComponentRegistry the sole built-in Inspector card dispatcher; remove hard-coded component-type dispatch.
  • Move shared material authoring into a reusable view-model/action-based UI module used by Inspector, Content Browser, and Material Library.
  • Add a reusable clipped Asset Card with bounded labels and non-overlapping dirty/processing/error status.
  • Split authored-document and touched surface-runtime responsibilities into focused modules.
  • Add .codex architecture policy and scripts/codex/architecture_audit.py with deterministic ratchet and exception self-tests.
  • Record the architecture in ADR 0048 and add sustainable extension seams / debt-at-the-point-of-change to editor workflow guidance.

Architecture budgets

  • UI shell: at most 500 nonblank lines.
  • Other new UI module: at most 800 nonblank lines.
  • Other new production Rust module: at most 1,200 nonblank lines.
  • Existing over-limit modules receive a frozen baseline and may not grow.
  • Exceptions require a tracker issue, rationale, maximum size, extraction target, and expiry milestone.

Acceptance criteria

  • Content Browser and Inspector shells satisfy the 500-line budget.
  • Every visible built-in component registers an Inspector callback; the old hard-coded dispatcher is absent.
  • Primitive, static-mesh, and skinned-mesh material slots use the same reusable UI contract.
  • Narrow and wide material cards retain every action without clipping or overlap.
  • Long and Unicode asset names remain clipped inside reusable cards; status indicators never overlap labels.
  • Architecture audit catches new oversize modules, legacy growth, invalid exceptions, and accepts shrinking baselines and valid exceptions.
  • Selective verification and candidate CI run the architecture audit.
  • ADR 0048, editor architecture/debt documentation, mission, README, and agent workflow guidance are coherent.

Ownership boundary

#67 remains the authority for live material state, explicit source saving, conditional derived processing, conflicts, recovery, and responsiveness. This issue owns the modular editor architecture and permanent debt ratchet needed for M2 signoff.

Child of #59 and required by #65 before M2 closure. Visual QA remains user-owned. No issue closure or milestone closure occurs before acceptance and explicit publication approval.

## Goal Finish M2 with a scalable editor UI architecture and an automated debt ratchet while preserving the live-material correctness owned by #67. ## Scope - Decompose the Content Browser and Inspector into bounded domain modules with shells no larger than 500 nonblank lines. - Make `EditorComponentRegistry` the sole built-in Inspector card dispatcher; remove hard-coded component-type dispatch. - Move shared material authoring into a reusable view-model/action-based UI module used by Inspector, Content Browser, and Material Library. - Add a reusable clipped Asset Card with bounded labels and non-overlapping dirty/processing/error status. - Split authored-document and touched surface-runtime responsibilities into focused modules. - Add `.codex` architecture policy and `scripts/codex/architecture_audit.py` with deterministic ratchet and exception self-tests. - Record the architecture in ADR 0048 and add sustainable extension seams / debt-at-the-point-of-change to editor workflow guidance. ## Architecture budgets - UI shell: at most 500 nonblank lines. - Other new UI module: at most 800 nonblank lines. - Other new production Rust module: at most 1,200 nonblank lines. - Existing over-limit modules receive a frozen baseline and may not grow. - Exceptions require a tracker issue, rationale, maximum size, extraction target, and expiry milestone. ## Acceptance criteria - [x] Content Browser and Inspector shells satisfy the 500-line budget. - [x] Every visible built-in component registers an Inspector callback; the old hard-coded dispatcher is absent. - [x] Primitive, static-mesh, and skinned-mesh material slots use the same reusable UI contract. - [x] Narrow and wide material cards retain every action without clipping or overlap. - [x] Long and Unicode asset names remain clipped inside reusable cards; status indicators never overlap labels. - [x] Architecture audit catches new oversize modules, legacy growth, invalid exceptions, and accepts shrinking baselines and valid exceptions. - [x] Selective verification and candidate CI run the architecture audit. - [x] ADR 0048, editor architecture/debt documentation, mission, README, and agent workflow guidance are coherent. ## Ownership boundary #67 remains the authority for live material state, explicit source saving, conditional derived processing, conflicts, recovery, and responsiveness. This issue owns the modular editor architecture and permanent debt ratchet needed for M2 signoff. Child of #59 and required by #65 before M2 closure. Visual QA remains user-owned. No issue closure or milestone closure occurs before acceptance and explicit publication approval.
Rbanh added this to the M2 - Content workspace and asset pipeline milestone 2026-07-15 01:06:00 -04:00
Rbanh commented 2026-07-17 23:45:38 -04:00
Author
Owner
Copy Link

Candidate-ready — commit cf6eaba

The current Penpot boards are now exported with the candidate and are the pinned visual acceptance source for this issue: design export index.

Required Inspector matches

The Inspector and Content Browser shells meet the architecture ratchet; built-in cards dispatch through the component registry; primitive/static/skinned Material slots share the same action-returning UI. Focused geometry/containment/resize tests, strict candidate lint, architecture audit, and native wide/narrow interaction acceptance pass. The Penpot CODEGEN MAP remains documentation-only and is not rendered.

## Candidate-ready — commit `cf6eaba` The current Penpot boards are now exported with the candidate and are the pinned visual acceptance source for this issue: [design export index](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/src/commit/cf6eaba53473d2825d0109f5a18f44794af5bd48/docs/editor/evaluations/content-workspace-m2/penpot/README.md). ### Required Inspector matches - [Foundation components catalog](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/src/commit/cf6eaba53473d2825d0109f5a18f44794af5bd48/docs/editor/evaluations/content-workspace-m2/penpot/foundation-components-catalog.svg): shared controls, selection, fields, asset/drop states, vector layouts, buttons, and disclosure rules. - [Materials 620 px](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/src/commit/cf6eaba53473d2825d0109f5a18f44794af5bd48/docs/editor/evaluations/content-workspace-m2/penpot/materials-wide-620.svg) / [Materials 420 px](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/src/commit/cf6eaba53473d2825d0109f5a18f44794af5bd48/docs/editor/evaluations/content-workspace-m2/penpot/materials-narrow-420.svg): 596/396 px slots, 569/369 px parameter bodies, deterministic wide/narrow rows, no clipping or horizontal scroll. - [50 px component header](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/src/commit/cf6eaba53473d2825d0109f5a18f44794af5bd48/docs/editor/evaluations/content-workspace-m2/penpot/component-header-50.svg) and [40 px array header](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/src/commit/cf6eaba53473d2825d0109f5a18f44794af5bd48/docs/editor/evaluations/content-workspace-m2/penpot/array-header-40.svg): the reusable Inspector chrome and collection contracts. - [Static Mesh Renderer 760 px](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/src/commit/cf6eaba53473d2825d0109f5a18f44794af5bd48/docs/editor/evaluations/content-workspace-m2/penpot/static-mesh-renderer-wide-760.svg) / [480 px](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/src/commit/cf6eaba53473d2825d0109f5a18f44794af5bd48/docs/editor/evaluations/content-workspace-m2/penpot/static-mesh-renderer-narrow-480.svg): full renderer hierarchy, stable slot order, and repeated shared Material slots. - [Material state catalog](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/src/commit/cf6eaba53473d2825d0109f5a18f44794af5bd48/docs/editor/evaluations/content-workspace-m2/penpot/material-components-states.svg): direct, inherited, imported, built-in, dirty, processing, failed, and read-only states. - Color overlay: [Wheel](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/src/commit/cf6eaba53473d2825d0109f5a18f44794af5bd48/docs/editor/evaluations/content-workspace-m2/penpot/color-picker-wheel.svg), [Adjusted](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/src/commit/cf6eaba53473d2825d0109f5a18f44794af5bd48/docs/editor/evaluations/content-workspace-m2/penpot/color-picker-adjusted.svg), [Sliders](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/src/commit/cf6eaba53473d2825d0109f5a18f44794af5bd48/docs/editor/evaluations/content-workspace-m2/penpot/color-picker-sliders.svg), and [Presets](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/src/commit/cf6eaba53473d2825d0109f5a18f44794af5bd48/docs/editor/evaluations/content-workspace-m2/penpot/color-picker-presets.svg). The Inspector and Content Browser shells meet the architecture ratchet; built-in cards dispatch through the component registry; primitive/static/skinned Material slots share the same action-returning UI. Focused geometry/containment/resize tests, strict candidate lint, architecture audit, and native wide/narrow interaction acceptance pass. The Penpot CODEGEN MAP remains documentation-only and is not rendered.
Rbanh closed this issue 2026-07-17 23:48:03 -04:00
Rbanh reopened this issue 2026-07-17 23:53:19 -04:00
Rbanh commented 2026-07-17 23:53:19 -04:00
Author
Owner
Copy Link

Acceptance reopened — visual proof incomplete

The prior closure was premature. Exported Penpot targets and automated geometry tests do not by themselves prove current native 1:1 conformance. Fresh implemented-UI captures were not attached beside each authoritative design target, and the latest user review identifies remaining visible Inspector work.

This item is reopened. Acceptance now requires current side-by-side design/implementation evidence for the applicable 620 px and 420 px Material layouts, shared component headers, Static Mesh Renderer compositions, material states, and color overlays. Each observed delta must be recorded and resolved before this item can return to Candidate-ready or Closed.

## Acceptance reopened — visual proof incomplete The prior closure was premature. Exported Penpot targets and automated geometry tests do not by themselves prove current native 1:1 conformance. Fresh implemented-UI captures were not attached beside each authoritative design target, and the latest user review identifies remaining visible Inspector work. This item is reopened. Acceptance now requires current side-by-side design/implementation evidence for the applicable 620 px and 420 px Material layouts, shared component headers, Static Mesh Renderer compositions, material states, and color overlays. Each observed delta must be recorded and resolved before this item can return to Candidate-ready or Closed.
Rbanh commented 2026-07-18 12:09:15 -04:00
Author
Owner
Copy Link

Mainline publication checkpoint — commit 53dc1e4

The current implementation and exported design evidence are now published on main at 53dc1e44d861c9ff85c6d63b328d95bd5042eea4.

The exact published tree passes the architecture audit, formatting, full workspace/all-feature tests, strict all-target/all-feature Clippy, process-assets --check, level/sample validation, QA packaging, and documentation audit. The generated runtime catalog was refreshed before the final candidate run, and publication readback confirms origin/main resolves the exact commit.

This is a mainline evidence checkpoint only. The reopened visual-acceptance requirement remains in force: #68, #65, #59, and M2 stay open until the required current side-by-side Penpot/native evidence is reviewed and accepted.

## Mainline publication checkpoint — commit `53dc1e4` The current implementation and exported design evidence are now published on `main` at [`53dc1e44d861c9ff85c6d63b328d95bd5042eea4`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/commit/53dc1e44d861c9ff85c6d63b328d95bd5042eea4). The exact published tree passes the architecture audit, formatting, full workspace/all-feature tests, strict all-target/all-feature Clippy, `process-assets --check`, level/sample validation, QA packaging, and documentation audit. The generated runtime catalog was refreshed before the final candidate run, and publication readback confirms `origin/main` resolves the exact commit. This is a mainline evidence checkpoint only. The reopened visual-acceptance requirement remains in force: #68, #65, #59, and M2 stay open until the required current side-by-side Penpot/native evidence is reviewed and accepted.
Rbanh commented 2026-07-18 15:33:42 -04:00
Author
Owner
Copy Link

Acceptance-in-progress — Penpot Page 03 Content Browser refinement

The current Penpot 03 — Content Browser · Workspace boards are now the visual source of truth for this issue in addition to the Inspector/Foundation exports already pinned above.

Required Content Browser matches

  • Wide — Blacksite Editor / Content Browser / Wide (e755994a-6c1d-80bd-8008-58e2e8668f78): 1240×650 standalone reference; 36 px title row mapped to the production dock tab, 88 px toolbar, 216 px Sources, flexible asset grid, 290 px Details, and 32 px status footer.
  • Compact — Blacksite Editor / Content Browser / Compact (e755994a-6c1d-80bd-8008-58e2e8dbf894): 620×650 reference; grid-only default, explicit mutually-exclusive Sources/Details access, preserved navigation/search/grid-list controls, Import/New on the breadcrumb row, and no clipped actions.
  • Shared controls continue to follow the pinned Foundation components catalog rather than introducing Content Browser-only chrome.

Fresh PNG exports are now present in the local candidate worktree as:

  • docs/editor/evaluations/content-workspace-m2/penpot/content-browser-wide-1240.png
  • docs/editor/evaluations/content-workspace-m2/penpot/content-browser-compact-620.png

The production slice maps the same shared chrome into the docked editor, renames the tab to Content Browser, implements wide Sources/grid/Details and compact grid/Sources/Details states, and adds catalog/processing/selection status. Managed architecture/format/check/strict-lint gates pass. Direct native QA passed wide, compact, Sources/Details toggle isolation, and a repeated 1200×760 ↔ 1800×1100 resize sweep without the prior crash/freeze.

This remains Acceptance-in-progress on a dirty worktree. The export links will be made immutable only when the exact candidate is published; this comment does not nominate, close, or publish the issue.

## Acceptance-in-progress — Penpot Page 03 Content Browser refinement The current Penpot **03 — Content Browser · Workspace** boards are now the visual source of truth for this issue in addition to the Inspector/Foundation exports already pinned above. ### Required Content Browser matches - **Wide** — `Blacksite Editor / Content Browser / Wide` (`e755994a-6c1d-80bd-8008-58e2e8668f78`): 1240×650 standalone reference; 36 px title row mapped to the production dock tab, 88 px toolbar, 216 px Sources, flexible asset grid, 290 px Details, and 32 px status footer. - **Compact** — `Blacksite Editor / Content Browser / Compact` (`e755994a-6c1d-80bd-8008-58e2e8dbf894`): 620×650 reference; grid-only default, explicit mutually-exclusive Sources/Details access, preserved navigation/search/grid-list controls, Import/New on the breadcrumb row, and no clipped actions. - Shared controls continue to follow the pinned **Foundation components catalog** rather than introducing Content Browser-only chrome. Fresh PNG exports are now present in the local candidate worktree as: - `docs/editor/evaluations/content-workspace-m2/penpot/content-browser-wide-1240.png` - `docs/editor/evaluations/content-workspace-m2/penpot/content-browser-compact-620.png` The production slice maps the same shared chrome into the docked editor, renames the tab to **Content Browser**, implements wide Sources/grid/Details and compact grid/Sources/Details states, and adds catalog/processing/selection status. Managed architecture/format/check/strict-lint gates pass. Direct native QA passed wide, compact, Sources/Details toggle isolation, and a repeated 1200×760 ↔ 1800×1100 resize sweep without the prior crash/freeze. This remains **Acceptance-in-progress** on a dirty worktree. The export links will be made immutable only when the exact candidate is published; this comment does not nominate, close, or publish the issue.
Rbanh commented 2026-07-22 18:11:43 -04:00
Author
Owner
Copy Link

Closed — verified main candidate 634ec16

Accepted against 634ec16c5e627d598aaccf130974224ba76b0e13, now published on both main and codex/m2-content-workspace.

Closure evidence:

  • Inspector and Content Browser composition satisfy the architecture ratchet; shared Material-slot, asset-card, thumbnail-cache, toolbar, responsive, and valid/invalid drop-state paths are in the published tree.
  • The committed Penpot export index and M2 evaluation remain the immutable design/evidence record.
  • Architecture audit, full workspace/all-feature tests, strict all-target/all-feature Clippy, deterministic asset processing, level/sample validation, QA packaging, and documentation authority all pass on the exact candidate.
  • The final responsive and interaction corrections were reviewed through the iterative native UI workflow, then explicitly authorized for publication and closure.

This closes #68 only; consolidated milestone signoff proceeds through #65 next.

## Closed — verified main candidate `634ec16` Accepted against [`634ec16c5e627d598aaccf130974224ba76b0e13`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/commit/634ec16c5e627d598aaccf130974224ba76b0e13), now published on both `main` and `codex/m2-content-workspace`. Closure evidence: - Inspector and Content Browser composition satisfy the architecture ratchet; shared Material-slot, asset-card, thumbnail-cache, toolbar, responsive, and valid/invalid drop-state paths are in the published tree. - The committed [Penpot export index](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/src/commit/634ec16c5e627d598aaccf130974224ba76b0e13/docs/editor/evaluations/content-workspace-m2/penpot/README.md) and [M2 evaluation](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/src/commit/634ec16c5e627d598aaccf130974224ba76b0e13/docs/editor/evaluations/content-workspace-m2/README.md) remain the immutable design/evidence record. - Architecture audit, full workspace/all-feature tests, strict all-target/all-feature Clippy, deterministic asset processing, level/sample validation, QA packaging, and documentation authority all pass on the exact candidate. - The final responsive and interaction corrections were reviewed through the iterative native UI workflow, then explicitly authorized for publication and closure. This closes #68 only; consolidated milestone signoff proceeds through #65 next.
Rbanh closed this issue 2026-07-22 18:11:51 -04:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels   
area:animation

Skeletal animation import, preview, graph/state authoring, and runtime integration.

  
area:assets

Asset browser, material browser, thumbnails, import, processing, and asset watcher.

  
area:audio

Audio source/listener authoring, buses, spatial preview, and runtime integration.

  
area:brushes

Brush geometry, CSG, face editing, UVs, and brush diagnostics.

  
area:build-release

Build profiles, packaging, content validation, release gates, and distribution diagnostics.

  
area:extensions

Static extension API, extension scaffolds, dylib exploration.

  
area:governance

Policy, attribution, planning, and production process.

  
area:hierarchy

Outliner hierarchy, parenting, grouping, prefab structure, ordering, and selection workflows.

  
area:inspector

Inspector, component metadata, component editing UX.

  
area:navigation

Navigation mesh authoring, baking, diagnostics, and AI path preview.

  
area:operators

Editor operator/action framework, undo, commit/cancel semantics.

  
area:physics

Physics placement, colliders, rigid bodies, diagnostics, and overlays.

  
area:project-ux

Project launcher, profiles, templates, or first-run project workflow.

  
area:quality

Regression packs, tests, performance budgets, profiler, first-hour UX.

  
area:rendering

Static and skinned renderers, material slots, shaders, ray tracing, and render-path integration.

  
area:runtime

BRP, remote inspector, PIE, game preview, runtime integration.

  
area:scene-io

Scene document, save/load, schema, migration, or reference repair.

  
area:terrain

Terrain authoring, terrain sculpting, heightmaps, and terrain materials.

  
area:viewport

Viewport interaction, selection, shortcuts, camera, overlays, and controls.

  
priority:P0

Must-have prerequisite or milestone-critical item.

  
priority:P1

Important production feature after P0 work is stable.

  
priority:P2

Useful follow-up or polish item.

  
priority:P3

Exploratory or later spike.

  
roadmap:jackdaw

Jackdaw-inspired Blacksite editor roadmap item.

  
roadmap:production

Blacksite production-readiness roadmap item beyond the Jackdaw-inspired foundation.

  
type:architecture

Architecture, internal framework, or hard-to-reverse technical decision.

  
type:docs

Documentation, policy, samples, or issue-board structure.

  
type:epic

Tracking epic that groups related milestone work.

  
type:feature

User-visible feature or capability.

No Label
area:animation
area:assets
area:audio
area:brushes
area:build-release
area:extensions
area:governance
area:hierarchy
area:inspector
area:navigation
area:operators
area:physics
area:project-ux
area:quality
area:rendering
area:runtime
area:scene-io
area:terrain
area:viewport
priority:P0
priority:P1
priority:P2
priority:P3
roadmap:jackdaw
roadmap:production
type:architecture
type:docs
type:epic
type:feature
Milestone
Clear milestone
No items
No Milestone
M2 - Content workspace and asset pipeline
Projects
Clear projects
No project
Assignees
Clear assignees
No Assignees
1 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: Falling-Metal-Interactive/Blacksite#68
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?