# Material manager shell The manager shell composes the existing VirtualBox models and actions into the geometry defined by the checked-in Material Design 3 prototype. It does not replace `UITools`, `UIToolPane`, `UIChooser`, or `UIActionPoolManager`; those remain the source of selection state, restrictions, data, and commands. ## Layout and behavior - The frameless manager window has a reachable 640 by 360 logical-pixel minimum. Restored geometry is clamped to the active screen's available geometry before it is shown. - A 48-pixel title bar contains the application mark and display name, manager subtitle, command-palette action, notification status, and compact native window actions. The legacy `QMenuBar` remains the action model but is hidden; its real menus open from the title-bar menu action instead of occupying a second permanent row. - A 48-pixel workspace strip renders 120-to-210-pixel tab bodies and keeps 48-pixel New tab, Tab manager, overflow, and inline close targets. Selecting an overflow result moves the transient viewport so the active tab becomes visible, and closing the active tab resolves one enabled visible fallback before one persisted model update and one final selection notification. The exact historical order of the seven-tab layout generated by earlier Material builds is migrated once to a single pinned initial destination. User-created order, pinning, grouping, and a valid restored destination are preserved. - A 92-pixel rail launches Home, Machines, Extensions, Media, Network, Cloud, and Resources in the prototype order. Visiting a destination opens or raises its workspace tab on demand, so the rail and strip no longer repeat the same seven entries at startup. - Below 1000 logical pixels of content width, the desktop rail yields to a 48-pixel navigation action. Its anchored, locally searchable menu exposes the same destination model and Preferences action without creating a second navigation authority. - The active destination has an eyebrow, title, and contextual action row. Existing `QAction` objects remain authoritative; their toolbar presentation uses compact icon-and-label pills instead of a detached icon-over-text slab. - The Machines destination uses 20-pixel outer padding, a 12-pixel splitter gutter, a chooser width bounded between 240 and 360 pixels with a 274-pixel default, and rounded chooser/workspace surface cards. Language and theme changes update the header, destination heading, rail, tabs, action row, and cards without changing technical identifiers, COM objects, or the persisted tool model. The destination heading names the selected machine or global tool instead of showing a placeholder. The header switches its command-palette action to an icon presentation at constrained widths and elides the display name while retaining the full accessible name and tooltip. Rail icons are recolored from their bundled alpha masks with the current Material role at the active device-pixel ratio. Theme, screen, and display-scale changes rebuild normal, selected, and unavailable icon states. Arrow-key focus traversal follows the visible rail order, includes Preferences, and skips hidden or unavailable destinations without activating them. Every unavailable destination retains a localized reason in its tooltip, status text, and accessible description. Application, toolbar, navigation, tab, group, and appearance menus use their own `UIMd3SearchField`, so plain-text filtering and the current anchored regular-expression panel stay local to the menu being searched. The effective pattern and supported flags remain visible in the originating field, and unknown or duplicate flags are rejected. Menu-hosted panels expand inside a scroll-bounded widget action rather than escaping the popup lifetime, and a menu filter restores the exact pre-existing visibility of every reused action when the popup closes. Preparing a menu is idempotent — a menu already carrying a search field is left alone rather than given a second field and a second layer of proxies — and every proxy holds its original action through a `QPointer`, so an original destroyed while the menu lives retires its proxy instead of leaving a row that triggers nothing. The filter runs once at preparation time so separator visibility is correct before the first keystroke. The custom Material buttons expose an accessible Button role and press action; a dedicated tab-list child owns only `PageTab` controls, while New tab, Tab manager, overflow, and independent close buttons remain accessible sibling actions. The strip retains its custom Material painting without mixing those button roles into the tab-list tree. ## Failure modes and security The shell contains no machine-management implementation. Disabled destinations continue to use the existing expert-mode and empty-chooser checks, and every action delegates to the existing action pool. The seven-tab migration is deliberately narrow and versioned: it runs only for the exact historical generated order with unpinned, ungrouped destinations. Any reordered or customized tab layout is left untouched, and transient enabled states are never written into durable tab state. If the local VirtualBox COM/SDS registration is unavailable, the native manager cannot reach this shell. A design prototype or static HTML page is not runtime evidence for that failure path. ## Verification and remaining work The current compile evidence was built from exact source commit [`74004bd7025fd9c81284d540625fc583737dc8c0`](https://github.com/Ding-Ding-Projects/material-virtualbox/commit/74004bd7025fd9c81284d540625fc583737dc8c0) on a Windows x64 development host. It used MSVC 14.44, Windows SDK 10.0.26100.0, Qt 6.8.3 with the official `qtscxml` add-on, and the bundled kBuild executable. | Target | Result | Completed (UTC-04:00) | Installed artifact SHA-256 | | --- | --- | --- | --- | | `UICommon` | Exit 0, compiled and linked | 2026-08-09 13:17:03 | `3443A91C69E08E21B7130E3A667D9CEA8F2584FDBD6FDE686B2804AACD6E876C` | | `VirtualBox` | Exit 0, compiled and linked | 2026-08-09 13:12:21 | `6A5E7F04EA44454F929A0E798ED425B6F878C953C1FAAA47C70A719877AD04B4` | | `VirtualBoxVM` | Exit 0, target up to date against rebuilt `UICommon` | 2026-08-09 13:13:07 | `2A4E0398C304289090CD49DE0695E17915B8795BDB66168275B89C3E0DD47DD0` | The serial targets rebuilt and installed the changed shared library and manager executable, then confirmed the runtime target was dependency-current. This is local build evidence, not a result attributed to a repository commit and not runtime or release proof. The repository validation workflow checks the 48/48/92 desktop geometry, 640-by-360 responsive floor, hidden legacy menu row, compact navigation action, on-demand tab integration, accessible button/tab roles, destination heading, compact contextual toolbar, searchable menus, and bounded machine layout. Real native capture remains open until a supported COM/SDS-capable test runtime is available. Native Snap Layout, drag/restore, 100/125/150/200-percent scale, bilingual overflow, and accessibility-tree behavior still require runtime evidence. Vertical tab docking, drag reordering, the four cross-surface tab searches, the full guided regex construction/capture/copy surface, and replacement of remaining legacy machine-tool painting are active design-coverage items. The current regex panel validates a raw pattern, `i`, `m`, `s`, and `x` flags, and a bounded sample; it is not yet the complete guided builder described by the design handoff. Suggested articles: [Title bar](TitleBar.md), [Navigation rail](NavigationRail.md), [Tab navigation](TabNavigation.md), and [Runtime capture](RuntimeCapture.md).