feat(editor): finalize M2 content workspace UX

This commit is contained in:
Rbanh committed 2026-07-22 17:14:07 -04:00
1 parent 93e23ba194
commit 106d947c98
69 files changed
+5893 -4343

No files matched your search

+2 -2
View File
@@ -84,7 +84,7 @@ records below are dated evidence, not product specifications.
| `ui/mod.rs` | Dock layout, unified viewport, menus | README controls |
| `ui/scene_tabs.rs` | Main-toolbar scene tabs and composition controls | multi-scene-composition.md, ADR 0026 |
| `ui/component_registry.rs` | Stable authoring component identities, lifecycle metadata, save policy, and inspector callbacks | extensibility.md, ADR 0034 |
| `ui/asset_browser/` | Asset Browser tree, grid/list, details | roadmap Phase 4b |
| `editor_ui::content_browser` / `ui/asset_browser/` | Shared responsive Content Browser chrome/body presentation plus production project state, list behavior, and content transactions | content-workspace.md, ADR 0045, ADR 0049 |
| `history/` | Undo/redo command stack | README controls |
| `crates/scene` | Schema stamp/migrate/validate (shared) | ADR 0006, ADR 0008 |
| `ext/extensibility.rs` | Command registry, `ActorInspectorSection`, palette | Phase 6 |
@@ -98,7 +98,7 @@ records below are dated evidence, not product specifications.
- **Dedicated egui `Camera2d`** at full window — never attach `PrimaryEguiContext` to a viewport-cropped 3D camera (NaN layout panic).
- **Unified viewport** uses one render-to-texture target for both the editor fly camera and the possessed player camera so HDR/atmosphere is not broken by sub-viewport cropping.
- **PIE:** F8 possess/eject while sim runs; **F6** pauses/resumes simulation in Play; project settings drive shared rendering for the active viewport camera.
- **Asset browser** mirrors the on-disk `assets/` directory with project tree, breadcrumb, search/filter/sort, grid/list views, texture/model/material thumbnails, a details pane, and context-aware row/menu actions. It uses file-manager selection semantics across files and folders (click, Ctrl/Cmd toggle, Shift range, Ctrl/Cmd+A), batch clipboard/duplicate/trash/drag operations, keyboard shortcuts, and empty-space workspace menus. The details divider is draggable so asset and import settings can use more horizontal space, and double-clicking it restores the default width. Narrow docks prioritize content, keep the root panel fixed, switch list view to a compact single-column layout, and hide tree/details panes when they would crowd the content area. The footer stays pinned while only the project tree, asset content, and details panels scroll. **Built-ins** holds spawnable primitives and lights. Materials and shaders are classified by document schema anywhere under `assets/`; the browser renders material thumbnails on a sphere and exposes shader-schema-driven parameters/textures in Details. **Audio** accepts Bevy-supported Ogg/Vorbis and Speex (`.ogg`, `.oga`, `.spx`), WAV, MP3, and FLAC clips, with a dedicated filter, waveform icon, format/file details, and stable registry-backed references. glTF/GLB/FBX rows expand into normalized embedded mesh, material, and texture subassets. Model and Texture Details edit asset-keyed **UNSAVED** documents; `Ctrl+S` saves the active context and `Ctrl+Shift+S` saves all before affected-only background processing. FBX previews use the same sandboxed dependency resolver as import and validation; missing textures are required when any slot uses Source and informational when every slot uses Project/Default. Bundle import preserves referenced sibling or `.fbm/` layout transactionally. See [content-workspace.md](content-workspace.md) and [ADR 0044](../adr/0044-sandboxed-fbx-external-texture-dependencies.md).
- **Asset browser** mirrors the on-disk `assets/` directory with project tree, breadcrumb, search/filter/sort, grid/list views, texture/model/material thumbnails, a details pane, and context-aware row/menu actions. It uses file-manager selection semantics across files and folders (click, Ctrl/Cmd toggle, Shift range, Ctrl/Cmd+A), batch clipboard/duplicate/trash/drag operations, keyboard shortcuts, and empty-space workspace menus. The details divider is draggable so asset and import settings can use more horizontal space, and double-clicking it restores the default width. Narrow docks prioritize content, keep the root panel fixed, switch list view to a compact single-column layout, and hide tree/details panes when they would crowd the content area. The footer stays pinned while only the project tree, asset content, and details panels scroll. **Built-ins** holds spawnable primitives and lights. Materials and shaders are classified by document schema anywhere under `assets/`; the browser renders material thumbnails on a sphere and exposes shader-schema-driven parameters/textures in Details. Typed 256 px previews persist in the managed `.thumbnails` cache, revalidate against visual dependency hashes, retain the last-good image during regeneration, and self-heal corrupt artifacts across restarts. **Audio** accepts Bevy-supported Ogg/Vorbis and Speex (`.ogg`, `.oga`, `.spx`), WAV, MP3, and FLAC clips, with a dedicated filter, waveform icon, format/file details, and stable registry-backed references. glTF/GLB/FBX rows expand into normalized embedded mesh, material, and texture subassets. Model and Texture Details edit asset-keyed **UNSAVED** documents; `Ctrl+S` saves the active context and `Ctrl+Shift+S` saves all before affected-only background processing. FBX previews use the same sandboxed dependency resolver as import and validation; missing textures are required when any slot uses Source and informational when every slot uses Project/Default. Bundle import preserves referenced sibling or `.fbm/` layout transactionally. See [content-workspace.md](content-workspace.md) and [ADR 0044](../adr/0044-sandboxed-fbx-external-texture-dependencies.md).
- **Imported-source fingerprints** use exact byte length plus lowercase BLAKE3 for model, texture, and audio registry records and for generated static-mesh/animation manifests. Filesystem timestamps are scan hints only; equivalent refresh preserves the exact committed RON bytes and registry publication order is normalized by project path. See [ADR 0043](../adr/0043-content-addressed-import-fingerprints.md) and the [acceptance record](evaluations/deterministic-asset-fingerprints/).
- **Material Library** is a dockable bottom-panel catalog for cross-folder Material and direct-base Material Instance authoring. It provides search, type and scene-usage filters, grid/list thumbnails, dependency health, usage counts, creation, guarded details editing, and first-class drag sources. Viewport drops resolve an exact renderer slot, primitive, or brush face under the pointer, preview transiently, reject incompatible/read-only targets explicitly, restore on target change/cancel, and commit one typed undo step on release.
- **Static/skinned renderer split** — model drag/drop uses normalized artifacts under `assets/meshes/generated/`. Unrigged, non-animated sources create `ActorKind::StaticMesh + StaticMeshRenderer`; skin-bound or animated sources create `ActorKind::SkinnedMesh + SkinnedMeshRenderer` and preserve the imported hierarchy. Static slots never contain marked skinned primitives or geometry from animated sources. `SceneInstance` placement keeps `ImportedModel + ModelRef` for generic full-source scenes. See [ADR 0033](../adr/0033-dedicated-skinned-mesh-renderer.md).
+8 -3
View File
@@ -254,9 +254,14 @@ the Edit-to-Play boundary restore the complete runtime snapshot. See
poses. Material subassets expose source defaults, and texture dependencies can be applied to
selected actors. The thumbnail studio renders each generated model/subasset/material preview into
its own render target before registering it in the cache so later thumbnails cannot overwrite
earlier cache entries. FBX model and mesh previews use neutral direct geometry; source-material
previews preflight external textures and retain one stable hover-visible failure reason instead
of enqueueing a known-missing path.
earlier cache entries. Completed renders are asynchronously read back into typed,
content-addressed 256 px PNG artifacts under `assets/.thumbnails/v3/`. Visual signatures include
source/dependency bytes, resolved Material inputs, textures, shader files, and the studio version.
Catalog refresh increments a validation epoch without discarding the last-good GPU registration;
only a changed signature schedules replacement. Corrupt artifacts regenerate, publication is
atomic, and retryable studio failures receive one bounded retry. FBX model and mesh previews use
neutral direct geometry; source-material previews preflight external textures and retain one
stable hover-visible failure reason instead of enqueueing a known-missing path.
- **Default placement:** **Renderable Asset (Auto)** creates
`ActorKind::StaticMesh + StaticMeshRenderer` for unrigged, non-animated models and
`ActorKind::SkinnedMesh + SkinnedMeshRenderer` when any part is skin-bound or the source contains
+54 -8
View File
@@ -14,8 +14,32 @@ is mutable metadata that moves, validation, and packaging repair through the sha
## Content Browser workflow
The Content Browser toolbar provides **New Folder**, **Rename**, **Duplicate**, **Cut**, **Copy**,
and **Paste**. The selected folder is the destination for paste and **File > Import Assets**. These
The docked Content Browser maps the standalone Penpot title row to the editor dock tab instead of
rendering a second title inside the panel. At wide widths it uses the Penpot 55 px single-row
content toolbar: navigation, import, folder creation, breadcrumbs, search, type filtering, and view
controls share one dense row. At 1400 px and wider, sort order and the grid thumbnail-size slider
also become first-class controls in that row; narrower wide and compact layouts keep those
lower-frequency controls in overflow. Sorting preserves selection, while thumbnail scaling is a
presentation-only change and is disabled in list view. Below the 1000 px responsive breakpoint,
the compact 88 px two-row
toolbar keeps search in the flexible center lane, Sources and Details become
explicit mutually exclusive drawers, Import/New remain on the breadcrumb row, and infrequent
operations move to overflow. The default compact view is the content grid; no hidden pane silently
consumes its width. Wide mode uses a 216 px Sources pane and a 290 px default Details pane; the
Details divider remains resizable and double-click restores 290 px.
Grid mode uses one continuous row-major stream for folders and assets. Folders retain navigation
and drop-target behavior but use the same bounded card contract as files; they never force
the first asset onto a new row. The 56 px content heading owns the folder name, sort summary, and
selection chip before that single card stream begins. Each card clips a single bounded name and a
separate asset-kind line; long or Unicode names expose their full value by tooltip instead of
wrapping across card bounds. Sources, that shared card presentation, and bounded Details rows live
in `editor_ui::content_browser`; production supplies real project state and handles the actions,
while the UI Gallery supplies fixtures to the same functions. Details paths and dependency
identities receive the exported 32 px two-line treatment; other scalar values stay one line.
The Content Browser provides **New Folder**, **Rename**, **Duplicate**, **Cut**, **Copy**, and
**Paste**. The selected folder is the destination for paste and **File > Import Assets**. These
operations use the shared content transaction engine: it previews collisions, rejects managed or
symlink paths, stages filesystem and cached-reference changes together, preserves IDs on moves,
assigns new IDs to copies, and rolls back on failure. Successful move, rename, create-folder, copy,
@@ -80,7 +104,9 @@ unused content space clears any old selection and opens workspace actions for **
current folder; the Material Library's create button retains `assets/materials/` as its convenient
default.
Double-clicking a scene opens it, a model toggles its embedded contents, and other asset types reveal
their editable Details. The footer and Details pane summarize multi-selections; single-selection
their editable Details. The fixed footer reports catalog health, thumbnail/derived processing, and
the current selection without moving card labels. The content header reports folder/item count,
active sort, and a bounded selection chip. The footer and Details pane summarize multi-selections; single-selection
Details remains the authoritative editor for import and material settings. Drag the Details divider
to resize it for long slot/shader forms; double-click the divider to restore its default width.
Texture Details uses the same pane for semantic/color-space intent, mip generation, UASTC or
@@ -92,9 +118,23 @@ Thumbnail cache keys are typed by asset category. Texture cards may use direct i
model cards always queue the offscreen geometry studio—even when a glTF has a base-color texture.
Expanded mesh rows request their exact mesh-subasset render, and source materials use a separate
material-sphere key. Missing dependencies produce an explicit failed thumbnail; a model or mesh
card never substitutes an albedo texture. Replacing, retrying, or invalidating a thumbnail also
unregisters its last Egui image handle, so repeated catalog refreshes release the prior GPU image
instead of accumulating hidden render targets.
card never substitutes an albedo texture.
Successful 256 px previews are persisted beneath the managed, untracked
`assets/.thumbnails/v3/` cache. The artifact key hashes the typed thumbnail identity, renderer
version, source bytes, model bundle dependencies, resolved Material values, referenced textures,
and custom shader files. A restart decodes that small validated PNG instead of reloading a 4K
texture or re-rendering geometry. Catalog refreshes revalidate signatures, and retained prior
generations restore the last-good image even after a restart while a changed preview is rebuilt or
its broken source is diagnosed; corrupt/missing artifacts self-heal, retryable studio
failures receive one bounded automatic retry, and **Regenerate Thumbnail** explicitly evicts the
selected key. Publication is atomic, retains one prior generation until the replacement is valid,
and trims only old derived entries after the cache exceeds its 512 MiB soft limit.
The grid slider scales cards from 68×88 through the 116×136 default to 132×152. Only the preview
region scales: every size reserves the same 40 px identity footer, keeps the name and kind bounded,
and paints the category keyline inside the card bottom. Canonical 256 px thumbnail artifacts are
aspect-fitted as squares rather than stretched to the card's changing preview rectangle.
**Import Here** pins the current/selected folder before the native picker opens. **Import To...**
first opens a project-folder chooser without navigating away from the current browser location.
@@ -173,8 +213,14 @@ shown separately from Git state. `Ctrl+S` saves the last edited context; `Ctrl+S
never discard a dirty asset. Source publication is guarded and atomic, then affected-only derived
processing runs in the background while the previous valid artifact remains active.
Material scalar/color/render-state saves do not show `PROCESSING`; only packed-map binding changes
do. Content Browser and Material Library cards share clipped two-line labels, a top-right grid-card
status rail, and fixed-width list markers, so state never paints over or shifts an asset name.
do. Content Browser cards use a clipped one-line identity plus a separate kind line, a top-right
grid-card status rail, and fixed-width list markers, so state never paints over or shifts an asset
name. Every registered asset category retains its theme-owned classification color as a narrow
keyline along the bottom of the complete card, including when a rendered thumbnail is ready. The
keyline never tints or otherwise alters preview content; folders remain neutral, while loading,
failure, dirty, and selection indicators remain independent states. The canonical category palette
is documented in the [editor design system](design-system.md#asset-category-colors). Material
Library cards consume the same authored-document status model.
## Headless processing
+45 -2
View File
@@ -47,6 +47,48 @@ The material implementation is split as follows:
- `ui/materials/inputs.rs` renders schema-declared material controls.
- Inspector and asset editors provide state and apply returned actions through authored documents.
The Content Browser follows the same boundary. `editor_ui::content_browser` owns the standalone or
docked chrome mode plus the shared Sources rows, content heading, bounded folder/asset cards,
Details identity/rows, status presentation, and returned actions. The production
`ui/asset_browser` modules supply project state and own navigation history, selection, transactions,
thumbnail requests, and action handling; they do not carry a second body renderer. The UI Gallery
uses the same presentation functions with fixture view models, so a Gallery correction reaches the
production panel. The dock tab supplies the 36 px title row represented in the standalone Penpot
board. Production therefore renders the remaining 55 px single-row toolbar at wide widths or the
88 px two-row compact toolbar below 1000 px. An expanded composition at 1400 px and wider adds
foundation Combo Box and Slider instances for sort and thumbnail scale without changing the
standard-wide anchors; those controls return the same actions as their overflow counterparts.
### Asset category colors
Asset classification is a theme role, independent from thumbnail health, Git state, processing,
selection, or hover. Every `EditorAssetKind` maps exhaustively to the shared `AssetTypePalette` and
renders a 3 px keyline inside the bottom edge of its grid card. Primitive, Light, Model, Texture,
Material, Audio, Level, Prefab, Post Process, Rendering Profile, and Shader each have a distinct
default color; folders have no category keyline. The keyline remains stable for placeholder,
pending, ready, and failed thumbnails, so a rendered image never hides the asset type and a failure
never replaces it. The UI Gallery `theme.json` exposes the same roles for live iteration.
At the 1240 px Penpot reference, Sources is 216 px, Details is 290 px, and the grid owns the flexible
middle lane. At the 620 px reference, Sources and Details are absent by default and are opened from
dedicated toolbar actions. The compact toolbar preserves Back/Forward/Up, a 292 px reference search
field, Grid/List, Sources, Details, Import, New, and overflow. Status geometry is invariant: catalog
health is left, active processing is shown when space permits, and selection is right-aligned.
The content heading is 56 px, and grid cards form one continuous row-major stream across folder and
asset kinds rather than separate folder and file rows. Each body lane uses the semantic panel fill,
5 px radius, and strong inside border from the Penpot board. The grid's recessed surface begins 16
px inside that lane and cards begin another 6 px inside the surface; the resulting 22 px card
origin is shared by production and Gallery. The Details heading stays outside its scrolling content
body, and its identity stack owns the same fixed vertical geometry in both consumers. Ordinary
Details values use one clipped line; project-relative paths and dependency identities use the
Penpot 32 px two-line value region with ellipsis and a full-value tooltip, so a resized Details pane
never paints text across its boundary.
At the 1600 px expanded reference, only the flexible toolbar gap and grid lane grow. Sort and
thumbnail scale appear between the type filter and view controls. Grid cards scale from 68×88 to
132×152 around a fixed 40 px identity footer, and ready 256 px thumbnails remain square and
aspect-fitted at every size.
## Reference layout
At the current 620 px wide reference, 12 px outer padding produces a 596 px slot and a 569 px parameter
@@ -154,8 +196,9 @@ python scripts/editor/ui_gallery.py watch
```
The gallery links `editor_ui` and `material_schema` directly and does not open a project, scene,
renderer, or gameplay runtime. F1–F4 select Materials 620, Materials 420, Renderer 760, and Renderer
480; Shift+F1–F4 select Live, Side by side, Overlay, and Difference; Page Up/Page Down cycle the
renderer, or gameplay runtime. F1–F7 select Content Browser 1240/620, Materials 620/420,
Renderer 760/480, and Content Browser 1600 expanded; Shift+F1–F4 select Live, Side by side,
Overlay, and Difference; Page Up/Page Down cycle the
ownership and health fixtures. `crates/ui_gallery/fixtures/theme.json` and `material.json` reload in
the running process. Rust changes rebuild only the focused dependency closure, report a bounded
`resolved/rebuilt` counter, launch the replacement, and then stop the last-good gallery; a failed
@@ -17,6 +17,14 @@ runtime invariant or substitutes for the paired full-editor acceptance capture.
| [Static Mesh Renderer — wide](static-mesh-renderer-wide-760.svg) | Page 02, `6cb78075-fbd0-8045-8008-57f5315abf0a` | Full 760 px renderer composition, stable slot ordering, shared component chrome, and repeated material slots. |
| [Static Mesh Renderer — narrow](static-mesh-renderer-narrow-480.svg) | Page 02, `6cb78075-fbd0-8045-8008-57f5419afad2` | Full 480 px renderer composition and bounded narrow reflow. |
## Content Browser targets
| Export | Penpot page and shape | Required match |
|---|---|---|
| [Content Browser — wide](content-browser-wide-1240.png) | Page 03, `e755994a-6c1d-80bd-8008-58e2e8668f78` | 1240×650 standalone reference; 36 px dock/title row, 55 px single-row content toolbar, 216 px Sources, 56 px content heading, one mixed folder/asset card stream, flexible grid, 290 px Details, and 32 px status bar. Production maps the title row to its dock tab. |
| [Content Browser — expanded](content-browser-expanded-1600.png) | Page 18, `e4366b2b-77bd-8058-8008-5a57e6c9a02f` | 1600×650 expanded reference; the standard toolbar gains first-class Name sort and thumbnail-scale controls composed from the foundation Combo Box and Slider. Cards retain their identity footer while previews scale. |
| [Content Browser — compact](content-browser-compact-620.png) | Page 03, `e755994a-6c1d-80bd-8008-58e2e8dbf894` | 620×650 compact reference; 88 px two-row content toolbar, grid-only default body, explicit Sources/Details access, preserved search/navigation/grid-list controls, Import/New on the breadcrumb row, the same mixed card stream, and no clipped actions. |
## Shared component targets
| Export | Penpot page and shape | Required match |
@@ -39,6 +47,7 @@ runtime invariant or substitutes for the paired full-editor acceptance capture.
## Issue ownership
- **#68** owns exact Inspector/component/material/color-picker geometry and responsive behavior against these exports.
- **#68** also owns Content Browser visual-system conformance against the current Page 03 wide and compact boards.
- **#67** owns the live authored-document and save-state behavior represented by the material-state and adjusted-color exports: interaction remains memory-only until explicit save, with distinct unsaved, processing, failed, and conflict state.
- **#65** owns consolidated native comparison evidence across wide, narrow, short-height, multi-slot, overlay, save, restart, and failure scenarios.
- **#59** indexes the design authority and requires the relevant child acceptance targets to be satisfied before epic closure.
+9 -3
View File
@@ -53,9 +53,15 @@ This keeps renderer, asset server, import registry, and project settings rooted
On the supported Linux workstation, the **Blacksite Editor** desktop entry provides an **Open
Project Browser** action. Its wrapper launches the current managed development binary directly,
shows the normal startup splash, avoids duplicate processes, and preserves the Wayland, session-bus,
graphics, and XDG environment required by the detached process. A desktop click never invokes Cargo.
An explicit `~/.local/bin/blacksite-editor --build-only` rebuild uses the repository's managed Cargo
lane; a missing binary produces an actionable splash error instead of starting an implicit build.
graphics, and XDG environment required by the detached process. Before launch, the wrapper runs an
incremental build of both editor binaries through the persistent managed Cargo lane and its storage
pre/postflight. The splash reports exact resolved-crate progress, and any build or storage-preflight
failure remains visible with an actionable log instead of launching a stale executable. An explicit
`~/.local/bin/blacksite-editor --build-only` performs the same managed update without opening a GUI.
If an editor is already running, the wrapper still performs that update check before focusing it.
When Cargo replaced the executable, the running process is deliberately left untouched to protect
unsaved authored documents; the splash and desktop notification explicitly ask for a normal
close-and-reopen instead of implying that the old process already contains the rebuilt UI.
The browser's **New Sandbox** workflow requires a missing or empty folder and a non-empty name.
Creation failures remain in the browser as status text; a successful scaffold is validated and