solvecraft/docs/ui-container-audit.md

# Layout-aware container audit

Shared container foundation (#4411) and compact composition (#2029), on top of
History #3953 and Assistant #3985. Interface preferences save Floating or Compact;
`view.layout` changes the same preference without changing the design.

## Ownership

`ui_kit::Container` is the only production constructor for outer egui hosts in the
UI crate and the desktop/web apps. `Surface` declares purpose, not a second layout
setting. The shell publishes `LayoutMode` before drawing any page. Adaptive panels
and shell layout use `Container::floating()`; frames use the same policy. There is
one definition of floating/compact chrome and workspace gaps in `ui_kit/container.rs`.
Compact joins the workspace and ribbon, puts Browser flush beneath it with a square
join and content-hugging height, and opens feature/palette sheets at their edge without
card gaps or shadows. Tool sheets remain draggable in either layout; compact sheets
round all four corners when detached and square only the right corners at their right dock. Contacts declare which edges meet; the container rounds only
exposed convex corners and collapses adjoining outlines into one stroke. Stacked
headers cover the viewport without reserving a blank column beneath them.
Floating keeps its card chrome; both layouts retain tool drag offsets.
Menus, system windows, notifications and canvas content retain their existing roles.

The shell still owns ordering, viewport reservations and shared-column geometry.
A container does not infer geometry from a title or panel ID. Browser and History
share a column width; Assistant remains outermost on either side. Tool sheets may overlap Browser and History,
but cannot enter Assistant’s reserved rail or cover the ribbon/workspace selector. Those relationships
must survive the compact composition. Existing `Panel`, `Window`, `Confirm` and
`Menu` are content compositions over the universal container, not alternative hosts.
The low-level window builder is visible only inside the UI kit: feature and platform
windows use the shared composition, including its header and fixed outer frame.

## Inventory and migration

| Surfaces | Owners / composition | Container policy |
| --- | --- | --- |
| Browser, vertical History and Browser/History shared column | `browser`, `timeline_left`, `lib` | Adaptive panel; shared shell placement, resizing and fold state remain with owners |
| Horizontal History | `timeline` | Adaptive panel surface; floating strip or bottom dock |
| Assistant sheet and folded strip | `agent_chat/panel` → `Panel` | Adaptive feature surface; left/right position, resize, drag targets and native pop-out retained |
| Feature forms, Parameters, material review, Redefine Sketch Plane | `dialogs`, `params_dialog`, `material_card_review`, `sketch_attachment_ui` → `Panel` | Adaptive feature surface; bounded anchors and pinned actions retained |
| Sketch options | `sketch_palette` → `Panel` | Adaptive palette surface, preserving transparency |
| Application bar, workspace and ribbon | `toolbar`, `shell` | Chrome hosts; adaptive card geometry comes from the shared policy |
| Status bar | `status_bar` | Application-bar surface along the window's bottom edge; flat and full width in both layouts, allocated before History and the viewport and counted as covered by the shell |
| Render settings | `render_workspace` | Panel host; existing right dock retained |
| Preferences, managers, About, update/install/recovery/crash/issue prompts | `Window`, `Confirm` | System windows and modal sheets retain modality; these are not workspace sidebars |
| BOM, Messages, mouse gestures, 3D mouse calibration | respective modules → `Window::show_body` | Shared header, tokenised frame and bounded body; native egui title bars/resize highlights and legacy report/width helpers removed |
| Web stored-files and web recovery windows | `apps/solidcraft-web` → `Window::show_body` | Same shared composition; recovery requires an explicit choice and cannot be dismissed through the header |
| File/workspace/document/Help/context/overflow menus, radial menu, Select Other and inline rename | respective owners → `Menu` / container popup | Anchored transient hosts; never consume workspace dock space |
| Search, completions, colour and library popovers | `shortcut_box`, kit fields/choice/colour/table | Anchored popup containers; editor focus and completion semantics retained |
| Dimension values, canvas placement values, canvas feedback and History resize seam | `dim_view`, `sketch_dims`, `canvas`, `timeline_left` | Model/control-anchored overlays; retain their coordinates rather than becoming docks |
| Status and loading/progress messages | `viewport`, `open_meshing` | Notification surfaces independent of layout |
| Navigation bar | `navigation_bar_view` | Measured single-row Navigation surface; upward Popup menus use kit list rows; shell supplies the free canvas bounds |
| Persistent viewport status items | `ui_kit::viewport_status` | Content-hugging ViewportStatus pill surface; anchored row and Popup key cards, independent of workspace docking |
| OK and Cancel in the view's corner | `view_confirm` | Navigation surface in its own area; the viewport layout reserves its corner and the shell counts it as covered |
| Home, model viewport, Render canvas and native Assistant window content | `home`, `lib`, `agent_chat/panel` | Central content hosts, not floating workspace panels |
| Loading input shield | `file_load` | Explicit input shield; must remain interactive while CAD input is blocked |

The compass, geometry previews, drag handles, selection outlines, dimension lines,
charts and thumbnails are drawn content, not independent card hosts. Giving them
workspace docks would be incorrect. egui-managed tooltips and widget internals
remain with their owning shared widget. OS file/program/colour pickers and native
viewport creation remain host services, not in-app panels.

## Enforcement for additions

`cargo xtask ui-containers` is the mandatory repository gate, implemented once in
`xtask/src/ui_containers.rs`. The fast CI job runs it and its regression tests before
approval for heavy UI tests; `cargo xtask ci` runs it too. Draft PRs retain the repository’s
normal CI policy. It recursively parses Rust source and examples under every crate and
app, so new packages and nested modules are included automatically. The sole constructor
implementation exception is the exact `ui_kit/container.rs` path.

The gate rejects raw Area, Panel, Window, Modal, CentralPanel, Popup and SubMenu
constructors, imported/module/type aliases and re-exports, constructor function references,
qualified default constructors, struct literals, macro-hidden hosts and popup shortcuts.
Host APIs are default-denied except for explicit popup-state operations, so new egui
constructors are rejected automatically. Private raw host/module imports are rejected too,
preventing aliases from escaping into another source file.
It also rejects raw outer popup/window frames and custom outer shadows. Invalid Rust
fails closed. Read-only state queries, content-only frames, and test-only fixtures remain
valid; there are no per-feature allowances. This enforces the construction boundary;
surface purpose and hand-painted content still need ordinary review.

New workspace panels must declare an adaptive `Surface` and use this policy for
host choice and outer chrome. Do not introduce another layout bool, raw host,
shadow or mode-specific frame in the feature module. Body groups, message bubbles,
field backgrounds and image frames are content; they may use local zero-shadow
frames or existing kit controls. Add new surface policies in the universal module
and test both modes and themes. Never add a per-file allowance to bypass the guard.

## Retired implementation cleanup

The old report-window builder, window-width enum, heading-band colours and
caller-coloured icon API have been removed. Theme palettes and built-in theme
files no longer carry procedural command-icon colours; SVG artwork has one
palette authority. Only marker/pointer colours remain in the native glyph palette.
Older theme exports discard retired colour names at import so active overrides
still work; these names do not create renderer tokens or appear in new exports.
Unused History height state and superseded click/preview/modifier helpers are
also removed. The remaining `frame` helpers implement dragging and bounded
anchors used by current `Panel` compositions, rather than a second host or style.
Buttons and editors use shared kit controls too, including Assistant code-block
actions. The control guard scans all UI feature modules, even without a kit import,
so adding a new module cannot silently bypass the shared controls.