feat: complete M2 content workspace and inspector

This commit is contained in:
Rbanh committed 2026-07-17 23:40:49 -04:00
1 parent 931f561e7f
commit cf6eaba534
438 files changed
+59749 -19043

No files matched your search

+10
View File
@@ -23,6 +23,12 @@ The editor has one primary **Viewport** tab backed by one HDR `ViewportRenderTar
transform gizmos, visualizers, and selectable proxies without changing camera ownership.
- `Ctrl+G` toggles the grid.
- Saved dock layouts containing the old Game View tab are migrated to one Viewport tab.
- Ordinary dock and Inspector resizing mutates the existing HDR Image asset's extent while keeping
its stable asset ID. Egui owns exactly one strong registration for that ID; an exceptional target
replacement or absent/collapsed target explicitly unregisters the previous image.
- The editor host window prefers a non-FIFO presentation path (`AutoNoVsync`) so interactive
NVIDIA/Wayland window resizing cannot wedge the UI behind repeated one-second swapchain-acquire
timeouts. Packaged game windows retain `AutoVsync`.
- Multi-viewport support is represented as future-facing state/API shape only; secondary visible
viewports remain future work.
@@ -32,6 +38,10 @@ The editor has one primary **Viewport** tab backed by one HDR `ViewportRenderTar
- Camera ownership is explicit: F8 possession selects player camera vs editor camera; G only hides
editor overlays.
- The HDR/swapchain invariant remains centralized around one offscreen viewport target.
- Repeated splitter movement has bounded render-target ownership instead of retaining one
full-resolution HDR image per intermediate panel width.
- Repeated native-window resizing remains interactive even when the compositor cannot immediately
supply a FIFO swapchain image; this editor-specific latency choice does not change game VSync.
- Future secondary viewports should add viewport-id keyed rects, targets, cameras, and overlay state
rather than reintroducing a Scene View/Game View split.
- Post-FX and GI on the active viewport camera are owned by `game_hot::rendering::viewport_camera`
@@ -12,51 +12,81 @@ copies per actor, and left rigged geometry without the same assignment model as
Matching imported materials by a display name was also unsafe: names are neither unique nor stable
when a model is reimported.
Static and skinned renderers need the same Unity-like authoring contract without sharing their mesh
or hydration components. A project material must be reusable, an instance must express explicit
overrides over one base material, and each renderer must expose stable material slots independently
from its draw or skeleton representation.
Primitives, static renderers, and skinned renderers need the same Unity-like authoring contract
without sharing their geometry or hydration components. A project material must be reusable, an
instance must express explicit overrides over one base material, and every renderable surface must
expose stable material slots independently from its draw or skeleton representation.
## Decision
- Project materials use versioned `MaterialAsset` documents. A `MaterialInstanceAsset` references
one direct base `MaterialAsset` and stores parameter and texture overrides. Nested material
instances are invalid.
instances are invalid. Schema-driven input storage and processed Texture bindings are defined by
[ADR 0046](0046-schema-driven-material-inputs-and-processed-textures.md).
- `MaterialRef` is the assignment type. Its registry UUID and subasset ID are authoritative;
`source_path` is a cached loading hint that validation or migration may repair after a move.
- `StaticMeshRenderer` and `SkinnedMeshRenderer` each own a `RendererMaterialSet`. They do not share
a mesh component or hydration path. Each `RendererMaterialSlot` has a stable ID, a presentation
name, a read-only imported `source_material`, and an optional explicit `material` assignment.
Explicit assignment wins; clearing it returns to the imported source material.
- `Primitive`, `StaticMeshRenderer`, and `SkinnedMeshRenderer` own `MaterialSlot` values. Mesh
renderers use a `MaterialSlotSet`; a primitive owns one stable `surface` slot with ID
`slot:primitive:surface`. They do not share a geometry component or hydration path. Each saved
slot has a stable ID, a presentation name, and only an optional actor/prefab `material`
assignment. Model defaults and imported source materials remain asset-owned in model import
metadata and runtime manifests. Clearing an actor assignment returns resolution to those weaker
model-owned layers.
- Static draw parts and imported skinned-hierarchy draws bind to material slots by stable IDs.
Reimport reconciles by ID only. An explicit assignment whose source slot disappears is retained as
an `OrphanedMaterialAssignment`; the editor never silently reconnects it by display name.
- Asset Browser **Apply Material** assigns a shared material or material instance to every material
slot on each selected static or skinned renderer. Renderer inspectors provide per-slot
Browse/Select/Locate/Clear controls and expose orphan warnings.
- `HydratedRendererMaterialBinding` identifies each runtime draw's owner, slot, and effective
material. A skinned renderer material-only edit patches the instantiated hierarchy without
reloading its source hierarchy or joints.
- Asset Browser **Apply Material** assigns a shared material or material instance to a selected
primitive surface or every material slot on each selected static/skinned renderer. One inspector
widget provides drag/drop, Browse/Locate/Clear, inherited status, expandable shared parameters,
exact-slot extraction, and orphan diagnostics.
- `HydratedMaterialSlotBinding` identifies each runtime draw's owner and exact slot.
`HydratedMaterialSelection` carries Project Actor, Project Model, Imported Source, or Inherit
ownership without copying model defaults into the scene. A skinned renderer material-only edit
patches the instantiated hierarchy without reloading its source hierarchy or joints.
- `MaterialPropertyBlocks` are runtime-only, per-slot overrides. They do not mutate a shared asset
and are excluded from scene and prefab persistence. Persisting a reusable variation requires an
explicit material instance.
- Scene schema v4 migrates legacy renderer assignments into `RendererMaterialSet`. Project material,
material-instance, shader-schema, and scene rewrites are performed by the explicit transactional
`cargo upgrade-project` command; ordinary loading remains read-only.
- Model assets may provide a project Material/Instance default between their imported source and a
scene/prefab assignment. The terminal fallback chain and immutable DefaultGrid contract are owned
by [ADR 0045](0045-content-workspace-and-material-fallback-contract.md).
- Effective precedence is runtime MaterialPropertyBlock, scene/prefab assignment, model-asset
default, imported source, project default, then built-in DefaultGrid. A configured but broken
authored reference uses the fallback with diagnostics instead of silently exposing another
authored layer.
- Repository scenes use schema v6, where renderable slots persist actor/prefab assignments only.
This pre-production project updates its fixtures directly. The explicit project upgrader remains
available for legacy primitive `MaterialDesc`, mesh-wide descriptors, and per-slot
`MaterialOverride` values: it deduplicates canonical descriptors as deterministic project
Materials under `assets/materials/migrated/` and rewrites project references transactionally.
Ordinary loading remains non-writing.
## Consequences
- Static and skinned renderers have a consistent material-slot workflow while retaining distinct
geometry ownership and hydration behavior.
- Primitives, static renderers, and skinned renderers have one material-slot workflow while
retaining distinct geometry ownership and hydration behavior.
- An assignment remains a reference rather than a copied material value, so editing or replacing a
shared asset does not create actor-local material copies. Material/base/schema/evaluator
dependency revisions update the shared runtime handle in place across all assigned slots.
- Source reimport cannot silently move an override to the wrong draw. Orphans require an explicit
user decision to reassign or discard.
- Legacy primitive/actor `MaterialDesc` paths remain compatibility paths until their consumers move
to renderer slots; new mesh-renderer work uses shared references.
- `MaterialPropertyBlocks` currently define the runtime-only schema and persistence exclusion, but
renderer application and the editor promote-to-instance transaction are not implemented. Gitea
#53 owns that complete workflow; callers must not treat the component as visibly applied yet.
- Material graph authoring, nested instances, blended/transmissive materials, and a generalized
per-renderer property-block inspector are outside this decision.
- Component-form `MaterialDesc` is restricted to the brush fallback compatibility path. It is not
addable to primitives or mesh renderers, does not override their slots, and never causes a
primitive-local runtime material allocation. Unmigrated actor material components produce an
upgrade diagnostic and visible fallback.
- `MaterialPropertyBlocks` define the runtime-only schema and persistence exclusion. Runtime
application clones and caches the resolved Standard or Surface material per owner/slot, above
direct-base Material Instance values. An invalid block leaves the resolved base visible and emits
a deduplicated diagnostic instead of applying a partial override. Promotion to a reusable
instance uses an explicit target-path review and source/target fingerprint guards, assigns one
exact slot through history, and clears the block only after the file, registry, and scene
transaction succeeds. It may never use DefaultGrid as its base. The editor registers the
component with reflection for trusted local BRP runtime injection and native promotion testing;
that registration does not add it to authoring persistence or the Inspector component registry.
- Material graph authoring, nested instances, and blended/transmissive materials are outside this
decision.
Scene schema v6 stores only the actor/prefab assignment in a renderable slot. Model defaults and
imported source selections remain model-owned, and hydration carries their origin through
`HydratedMaterialSelection`. Live project resolution is owned solely by the overlay/cache boundary
in [ADR 0047](0047-editor-authored-asset-documents.md); shared slot presentation follows
[ADR 0048](0048-modular-editor-composition-and-debt-ratchet.md).
@@ -31,6 +31,8 @@ lighting, fog, shadows, and render-pipeline bindings under engine ownership.
`SurfaceInput` provides UV0, world position, and world normal. `Surface` returns base color,
tangent-space normal, emissive, metallic, perceptual roughness, reflectance, occlusion, alpha,
and lit/unlit model selection.
- The schema-driven authoring inputs and canonical processed Texture/ARM artifacts feeding this ABI
are defined by [ADR 0046](0046-schema-driven-material-inputs-and-processed-textures.md).
- The ABI has 16 `vec4` parameter lanes, eight sampled 2D texture slots with UV transforms, and a
400-byte `SurfaceUniform`. Shader schemas map typed Bool/Float/Vec2/Vec3/Color/Enum properties and
texture properties into that fixed layout. Exceeding either limit is a validation error.
@@ -51,3 +51,5 @@ provider.
- Native filesystem replacement cannot coordinate with unrelated writers that ignore advisory
conventions after Blacksite's final revision check; the narrow check-to-rename interval is the
platform boundary, and deterministic race hooks cover the editor-controlled interval.
- [ADR 0047](0047-editor-authored-asset-documents.md) applies these guards at explicit asset Save
boundaries; interactive parameter edits never enter the authored-file publication path.
@@ -55,3 +55,5 @@ tabs switch, while saves may establish a clean point in the middle of a timeline
direct non-history repairs, entity respawns, and tab switches.
- Operating-system process kill and power loss cannot be confirmed; recovery and abnormal-session
handling remain the safety boundary for those cases.
- [ADR 0047](0047-editor-authored-asset-documents.md) extends the guarded decision to dirty asset
documents and project settings while derived processing remains resumable after source save.
@@ -16,8 +16,8 @@ paths more than once.
Import, manifest generation, project validation, editor previews, and the runtime loader must agree
on one dependency graph. That graph also crosses a security boundary: an imported source must not
read or copy a parent-traversing path or an arbitrary absolute path outside its bundle. A missing
source texture is required when Source Materials is active, but it can be an intentional authoring
condition when an asset explicitly uses Authoring Override.
source texture is required when any stable model slot selects Source, but it can be an intentional
authoring condition when every slot selects a project Material/Instance or Default.
## Decision
@@ -36,8 +36,10 @@ loader warning instead of deferred asset-server requests.
Static-mesh manifests are the authoritative model import dependency graph. Their existing
`source.dependencies` list records every parsed FBX external texture, including unavailable files.
Project validation checks that list without loading native assets. Missing FBX textures are a
blocking consolidated finding under Source Materials and an informational consolidated finding
under Authoring Override. Unsafe paths remain blocking under either policy. Model registry records
blocking consolidated finding while any slot selects Source and an informational consolidated
finding when every slot selects Project/Default. The former whole-model Authoring Override value is
accepted only as registry-v1 migration input and expands to explicit Default selections. Unsafe
paths remain blocking under either selection state. Model registry records
mirror the list for editor details, but validation does not duplicate it when a generated static
manifest exists.
@@ -50,16 +52,17 @@ Unreferenced `.fbm` contents are not copied.
The Asset Browser renders FBX model and mesh thumbnails through the neutral direct mesh path.
Source-material thumbnails preflight the authoritative dependency resolver first and cache one
non-retryable actionable failure when required textures are unavailable. Dependency rows expose
present/missing state. The committed painted-chair fixture uses Authoring Override deliberately and
remains untextured; its three source paths stay visible in manifests, validation, and asset details.
present/missing state. The committed painted-chair fixture's legacy Authoring Override migrates to
per-slot Default selections and remains untextured; its three source paths stay visible in
manifests, validation, and asset details.
## Consequences
- FBX sibling `textures/` and `.fbm/` bundles import and validate with identical normalized paths.
- Missing texture files are visible before native loading and cannot create repeated Bevy
asset-server errors.
- Source Materials fails release validation when its FBX textures are absent. Authoring Override
remains release-valid but retains an informational dependency finding.
- Any Source slot fails release validation when its FBX textures are absent. An all-Project/Default
model remains release-valid but retains an informational dependency finding.
- Absolute exporter paths, traversal attempts, and destination symlink redirects cannot read or
copy arbitrary host files.
- FBX files with external textures are parsed twice during loading so no non-`Send` ufbx scene
@@ -0,0 +1,90 @@
# ADR 0045: Content Workspace and Material Fallback Contract
## Status
Accepted
## Context
Blacksite's Content Browser scans the project `assets/` tree, but authored RON type detection and
import destinations still depend on conventional folders. The asset registry is editor-owned and
serialized as an unversioned record list, so validation, packaging, runtime hydration, and future
headless processing duplicate parts of its contract. Imported model materials are either read-only
source defaults or scene-level assignments; a model asset cannot own editable project defaults.
Missing renderer materials currently create separate magenta `StandardMaterial` values, while
skinned, primitive, brush, terrain, thumbnail, raster, and Solari paths use different fallback
rules. A missing or broken material therefore does not have one predictable, production-safe
result.
## Decision
- User-authored content may live in any normal nested folder beneath the project `assets/` root.
Folder names are organizational only. External absolute linked assets are not supported.
- `AssetId` is authoritative identity. Project-relative paths and labels are repairable cached
metadata. Moves and reimports reconcile by stable IDs and never by display name.
- Registry contracts move to `shared::content`: typed asset kinds, versioned registry documents,
project content defaults, import settings, model material policies, and runtime catalog records.
UI-independent filesystem scanning, classification, transaction planning, import/reimport, and
processing live in a `content_pipeline` crate used by the editor, validator, watcher, and xtask.
- Registry schema v3 is `AssetRegistryDocument { schema_version, defaults, records }` with typed
Model/Texture import settings as extended by [ADR 0046](0046-schema-driven-material-inputs-and-processed-textures.md). The source
registry remains editor-managed under `assets/.index/`; packages receive a stripped runtime
catalog without editor import provenance or source-only dependencies.
- Project content roots normalize to `assets/`. `.index`, `.trash`, thumbnails, recovery data, and
implementation-owned derived artifacts are hidden and protected from normal file operations.
- Fixed-folder consumers are retired or explicitly constrained as follows:
| Consumer | Current contract / migration |
|----------|------------------------------|
| Project settings and templates | `asset_roots` upgrades to exactly `["assets"]`; the explicit project upgrader performs the write. |
| Content Browser and registry scanner | Walk all user-managed descendants and classify by extension plus document schema, never by parent folder. |
| Material, shader, model, audio, level, and prefab lookup | Resolve the registry's stable ID to its current path; a cached path is a repair hint only. |
| Scene/prefab validation and hydration | Consume registry/runtime-catalog resolution rather than conventional authoring directories. |
| Packaging and headless processing | Scan the same content root and publish the same stripped catalog and normalized model manifests. |
| Material creation UX | The current browser folder is authoritative; `assets/materials/` remains only a Material Library convenience default. |
| Generated mesh, animation, navigation, thumbnail, trash, and index data | Their fixed implementation-owned locations remain hidden managed storage, excluded from user classification and ordinary file operations. |
- Model material selections are per stable slot: Source, Project Material/Instance, or Default.
Extracting a source material creates an ordinary project Material and then stores a Project
selection. Re-extraction may replace a provenance-matched Material only after an explicit diff
and fingerprint-guarded Apply decision; Create New remains available and unrelated provenance is
never overwritten. Reimport retains removed project assignments as explicit orphans.
- Effective material precedence, strongest first, is: runtime MaterialPropertyBlock, scene/prefab
assignment, model-asset default, imported source, project default, built-in DefaultGrid. Missing
layers inherit downward. A configured but broken authored reference renders the fallback and
reports the broken layer rather than silently revealing a different authored layer.
- Primitive surfaces participate in that same chain through their saved
`slot:primitive:surface`; they no longer hydrate from a separate actor-local descriptor. Static
and skinned draws bind their exact saved slot IDs through the same runtime binding contract.
- DefaultGrid is immutable engine content compiled into the renderer. It is a shared,
UV-independent world-space checker with raster/Solari parity and a neutral StandardMaterial
emergency path. A project may choose a Material/Instance fallback; clearing or breaking it
returns to DefaultGrid. Terrain retains its specialized layer fallback.
- Built-in DefaultGrid is not editable, instanceable, or a valid MaterialPropertyBlock promotion
base. Promotion requires a resolved project or imported Material base.
- Ordinary editor/runtime loading is read-only. Registry, project-settings, and scene migrations
run only through the explicit transactional project upgrader.
## Consequences
- Editor, runtime, validation, packaging, watcher, and headless processing share one content model
and one stable-ID resolver.
- Arbitrary organization no longer changes asset type, runtime behavior, or package inclusion.
- The content pipeline becomes a reusable crate boundary instead of an editor implementation
detail; this adds one workspace crate and moves registry types out of `editor`.
- Older registries, conventional asset roots, global model material policy, and legacy mesh material
overrides require the explicit transactional upgrader; normal loading accepts current schemas.
- Broken assignments stay visible and diagnosable, but may look different from their previous
imported source because failure uses the project/engine fallback deliberately.
- One cached DefaultGrid/emergency handle covers repeated primitive and mesh hydration, so missing
assignments do not grow the material asset stores.
- Thumbnail cache ownership includes the backing Egui image registration. Replacement, retry, and
catalog invalidation explicitly release the last registration before a new studio render owns
the key, preventing refresh-driven GPU resource growth.
- File operations and imports must be staged transactions that update authored references,
registry state, derived manifests, and runtime catalogs together.
- Ordinary asset-property edits use the explicit dirty-document and two-phase publication boundary
defined by [ADR 0047](0047-editor-authored-asset-documents.md); topology transactions remain immediate.
- Scene schema v6 carries actor/model/imported/inherit origin explicitly at hydration time, so a
broken authored layer uses DefaultGrid instead of accidentally revealing a weaker layer.
@@ -0,0 +1,55 @@
# ADR 0046: Schema-driven material inputs and processed textures
## Status
Accepted
## Context
The first Material asset format stored a resolved `MaterialDesc` plus a second generic parameter
list. The editor consequently rendered Standard Lit twice, could not pair a scalar or color with its
texture, and had no stable place to describe future shader-graph inputs. Texture files also carried
no import intent, so color maps, normals, and packed mask data could be sampled interchangeably.
## Decision
Material, direct-base Material Instance, and Shader Schema documents use schema v2.
`MaterialInputSchema` is the presentation and validation contract for built-in Standard Lit,
custom Surface evaluators, and future generated shaders. `MaterialInputSet` is the only authored
value/texture store; instance sets remain sparse. Scalar texture bindings select R, G, B, or A,
and scalar values multiply the sampled value. Standard Lit pairs Base Color with albedo, Metallic
and Roughness with scalar maps, Occlusion with a scalar map, and Emissive Color/Intensity with an
emissive map.
The registry uses v3 `AssetImportSettings`, with typed Model and Texture settings. Texture settings
own semantic, color space, mip policy, compression, size limit, filtering, wrapping, anisotropy,
and normal convention. One GPU-free processor is called by editor publication, imports, the
watcher refresh path, and `cargo process-assets`. It writes content-addressed UASTC Basis or
uncompressed KTX2 artifacts below `assets/.import-cache/runtime/`, records sampler/color-space data
in runtime catalog v2, and canonicalizes authored AO/Roughness/Metallic selections to R/G/B ARM.
Source images remain editable and unchanged. Processing computes the normalized content key before
image decode or compression. An existing artifact at that key is reused directly, so validation and
catalog repair do not recompress unchanged Texture or packed-Material inputs.
The actor inspector and asset editors consume the same schema-driven controls. A renderable owns
one compact material-slot header; expanding it edits the resolved shared Material or Instance.
Slot provenance and diagnostics live outside parameter rows. Valid authoring changes refresh the
shared runtime handle immediately but only mark the asset document dirty. Explicit save uses the
two-phase source/derived boundary from [ADR 0047](0047-editor-authored-asset-documents.md), without
recompiling an unchanged Surface evaluator or scheduling a project-wide watcher pass.
This is an intentional foundation break. Normal loading accepts current documents only; explicit
`cargo upgrade-project --project <root> --apply` converts the repository's v1/v2 documents and
backs up every replaced file transactionally.
## Consequences
- Shader additions no longer require bespoke inspector layout code when their schema can describe
the input.
- Color-space and packed-channel choices are deterministic in editor, CI, and packages.
- Cached content-addressed artifacts keep `process-assets --check` and unchanged dependency refreshes
on the source-hash/catalog path instead of the image-compression path.
- Runtime and Solari receive the same canonical input mapping.
- Changing a Texture setting can invalidate dependent packed Material artifacts.
- The future node-graph compiler must emit this schema and Surface WGSL; graph authoring itself is
outside this decision.
@@ -0,0 +1,71 @@
# ADR 0047: Editor Authored-Asset Documents and Two-Phase Publication
## Status
Accepted
## Context
Material controls previously updated the viewport immediately but also wrote source when a pointer
interaction ended. That publication could trigger file guards, Git refresh, watcher work,
thumbnail invalidation, and whole-project processing on the editor frame thread. A slider release
therefore behaved like an implicit save and could freeze the editor.
Project RON files and registry metadata are already suitable authoritative source documents. The
editor needs a fast, durable edit boundary without adding an opaque asset database or conflating
editor-dirty documents with source-control status.
## Decision
The editor owns an `AuthoredAssetDocumentStore` keyed by stable asset ID and document kind. It
holds clean and current values, source path, loaded file revision, editor revision, publication
error, recovery state, and derived-processing state for Materials, Material Instances, model import
settings, Texture import settings, and project content defaults.
Interactive controls mutate the current document and `blacksite_surface`'s stable-ID-keyed
`LiveMaterialDocumentOverlay` in the same tick. `SurfaceMaterialCache` is the sole owner of project
Material and Material Instance handles; resolution is overlay-first and disk-second. Controls
perform no source write, watcher refresh, Git query, thumbnail invalidation, or derived processing,
including when the pointer is released. Dirtiness is derived from `current != clean` and remains
distinct from Git `MODIFIED`, `UNTRACKED`, and `CONFLICT` state.
The cache never polls file metadata or reparses a project Material for every bound entity. Explicit
Save and accepted watcher events invalidate the disk generation once; interactive overlay
revisions mutate the existing cached handle in place. Imported glTF/FBX source materials stay on
their AssetServer-owned path and do not enter the project-material resolver.
`Ctrl+S` saves the last edited context. `Ctrl+Shift+S` and **File > Save All** save every dirty
scene, authored asset document, and project setting. Source publication remains guarded and atomic.
Registry-backed documents use a clean registry baseline plus per-document overlays so saving one
setting cannot publish another unsaved setting.
Successful source publication advances the clean value, then classifies its
`DerivedProcessingImpact`. Scalar, color, emissive, shader-value, label, and render-state Material
changes queue no derived work. ARM/ORM texture or channel changes queue material packing; Texture
settings, model settings, and project defaults queue only their exact dependency closure. Packing
signatures exclude scalar multipliers and are checked before image decoding so an existing
content-addressed artifact can be reused. The previous valid runtime artifact remains authoritative until replacement
publication succeeds; a processing failure is reported separately and does not make saved source
dirty again. Stale job completions are ignored.
Dirty asset documents receive editor-local recovery snapshots after two seconds of inactivity,
with five generations retained outside `assets/`. Startup restoration never overwrites source: a
changed source fingerprint restores the document as an external conflict. Guarded shutdown and
project switching count scenes, assets, and project settings in the same Save All / Discard /
Cancel decision. Returning a document exactly to its clean value retires any older recovery
generation on the next editor tick. Startup also discards a recovery envelope whose value already
matches authoritative source, covering a crash between the clean edit and that cleanup tick.
## Consequences
- Parameter editing and pointer release stay frame-local and responsive.
- Material and direct-base Instance users share one stable live handle authority instead of
competing editor and renderer caches.
- Saving source and generating derived artifacts are observable, independent phases.
- The project remains plain, reviewable RON plus source assets; no asset binary database is added.
- Unsaved editor state survives selection changes and can be recovered after a crash without
affecting Git until the user saves.
- Packaging and read-only processing validation must reject required pending or failed derived
work rather than silently packaging stale content.
- Import, extract, create, rename, move, and delete remain explicit immediate transactions because
they create or remove project identity.
@@ -0,0 +1,52 @@
# 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](0012-zero-tech-debt-editor.md),
[ADR 0034](0034-registry-driven-authoring-components.md), and
[ADR 0047](0047-editor-authored-asset-documents.md), and
[ADR 0049](0049-penpot-led-editor-visual-system.md).
@@ -0,0 +1,119 @@
# ADR 0049: Penpot-Led Editor Visual System
## Status
Accepted
## Context
Blacksite's editor controls evolved inside individual panels. Even after the material data and
Inspector composition became shared, local egui styling still produced inconsistent spacing,
typography, interaction states, and narrow-panel behavior. The Penpot **Inspector Material Slot**
provides an authored reference for the visual language rather than another implementation-specific
mock-up.
## Decision
The Penpot **Inspector Material Slot** is the source of truth for geometry, type roles, control
heights, radii, spacing, property-column geometry, and interaction states. Color is semantic rather
than panel-owned: Penpot's Assets / Colors library and `editor::ui::theme::EditorVisualPalette`
name the same roles, with Blacksite's existing palette as the default. A later Editor Settings slice
may select or override that palette without changing widgets or material behavior. At the 620 px
reference width, implementations match the documented geometry. Below that width, controls deliberately
reflow instead of shrinking, clipping, scrolling horizontally, or hiding required state.
Fixed Penpot sections use deterministic geometry models rather than nested egui flow layouts.
Surface, parameter rows, texture fields, UV groups, and Advanced each receive an owning rectangle;
every child rectangle is derived from it and clipped to it. The 569 px and 369 px section widths
encode the exported wide and compact references. A bounded transient mode below 372 px keeps all
rectangles finite, stacks the row, and collapses low-frequency texture actions into overflow while
the Inspector restores its 420 px minimum.
The reusable implementation lives under `editor::ui::design_system`. It consumes the editor-owned
semantic palette and owns spacing tokens, Source Sans Pro Regular/Bold typography roles, section chrome, property grids,
asset and texture fields, segmented controls, switches, status presentation, and the Blacksite
color picker. Domain widgets consume these primitives instead of copying raw colors or absolute
Penpot coordinates.
Material authoring is the first migrated domain. One action-returning `MaterialsSection` is used by
primitive, static-mesh, and skinned-mesh inspectors. It owns an ordered list of collapsible
`MaterialSlotPanel` models, and every returned action carries its stable slot ID. The widgets do not
query or mutate arbitrary world state.
Supported material behavior only is shown. Asset identity, health, inheritance, dirty state, and
read-only state share one geometry, while stable IDs and fingerprints remain in secondary
diagnostics.
The final Penpot component supersedes the earlier v2.2/v2.3 geometry. A 32 px **Materials** heading
precedes repeated slots. Expanded slot headers are 82 px with a 64 px preview; collapsed headers
are 52 px with a 32 px preview. A cyan disclosure spine and **PARAMETERS** ownership label inset the
Surface, Inputs, UV, and Advanced body. The asset identity block owns the single Shader selector. Penpot's former duplicate Surface
"Shading Model" selector was removed from the component and every state reference in handoff
v2.3.1. Surface contains blend mode, Separate/ORM selection, and Double Sided. UV
precedes Advanced with
an explicit 8 px section gap. Advanced render controls
that do not yet have renderer contracts are shown only as a clearly disabled preview: they emit no
actions and create no authored or runtime state.
The Material slot header is one assignment interaction, not an identity block beside a second drop
box. Its whole 596 x 82 px wide reference area accepts valid Material/Instance drops. Preview and
identity clicks plus the first-class Browse action open the compact current/recent Penpot menu;
Shader, Locate, Clear,
and overflow actions are isolated and cannot accidentally open it. The picker returns a stable
asset reference to the owning Inspector instead of mutating scene or world state.
The custom 420 x 350 color popup is a fixed modal centered over its owning Inspector clip, with an
Inspector-local dim layer rather than application- or viewport-relative placement. Its header,
mode tabs, wheel and values regions, RGBA byte fields, HSV degree/percentage fields, HEX copy,
checkerboard alpha control, recents, and footer use the exported Penpot coordinates. The exported
eyedropper lane remains a tooltip-labelled disabled preview until screen sampling has an owned
runtime contract. Apply keeps the in-memory dirty value and closes; Cancel, Escape, Close, or
outside dismissal restores the exact pre-open value. Neither path saves source or schedules derived
processing.
Standard Lit declares seven independently stored inputs but six primary presentation rows.
`emissive_intensity` is a schema companion of `emissive_color`; the Emissive popup previews and
restores both values as one interaction without merging their authored/runtime identities. Custom
shader binding counts likewise count primary rows while rendering companions through their owner.
Bounded scalar material inputs use one 132 px control composed from a 78 px track, 6 px gap, and
48 x 22 numeric field. Expanding the 178 px Advanced preview requests a bounded
Inspector scroll reveal so its note and lower boundary are visible. The same no-implicit-persistence
rule applies to sliders, texture assignments, and shader controls.
Inspector overflow is part of the shared visual contract. A floating scrollbar keeps component
width stable as content crosses the vertical overflow threshold, and every nested component clip is
an intersection with the owning Inspector body. Ready texture fields use the typed thumbnail as
their sole leading identity; generic image glyphs are reserved for empty states.
Standard Lit exposes one shared UV Offset/Tiling transform through the same schema-driven input
document. The renderer maps it to Bevy StandardMaterial UV transforms and to every Surface ABI
texture lane. Material Instances may override it sparsely; resetting an instance restores its base.
Penpot's `CODEGEN MAP` and handoff annotations are design documentation. Runtime egui layout remains
responsive and semantic; generated SVG or code is not copied into production. Reviewed numeric
geometry is represented by small testable layout models instead of ad hoc child flow or generated
widget trees.
The same release slice applies the active Inspector Header, Array Header, renderer-panel, asset
field, vector, selection, and overlay components across the Inspector. Built-in component cards
dispatch through the registry and share one clipped actor-body scroll owner; domain behavior stays
outside the visual primitives.
## Consequences
- New editor UI has one reviewed visual vocabulary rather than panel-local approximations.
- Theme colors have one runtime owner and one design-side asset vocabulary; the material panel does
not carry a private blue/teal palette.
- The 620 px and 420 px geometries are deterministic and unit-testable. The Inspector has a 420 px
floor and one actor-body scroll region; material slots never introduce nested scrolling.
- Unsupported prototype controls are omitted until their runtime contracts exist.
- The explicitly approved Advanced preview is the sole exception: it is disabled, muted, and
labelled as planned work rather than functioning authoring state.
- Native acceptance compares rendered geometry, typography, states, and interaction behavior with
the Penpot reference; compile-only evidence is insufficient.
- Source Sans Pro and its SIL Open Font License are bundled with the editor.
- ADR 0048 continues to own composition and module-size policy. This ADR owns visual tokens,
responsive component geometry, and interaction presentation.
Related decisions: [ADR 0035](0035-shared-material-assets-and-renderer-slots.md),
[ADR 0047](0047-editor-authored-asset-documents.md), and
[ADR 0048](0048-modular-editor-composition-and-debt-ratchet.md).