@malva-ui/core 0.1.13 → 0.1.14

package/docs/ai/layout.md

@@ -56,6 +56,12 @@ host: {
 }
 ```
 
+The host binding scopes the theme to this subtree. Publishing the theme on the
+**document element** is `MlvThemeService`'s job, not the layout's — see below.
+`mlv-layout` used to own that write, which meant an application (or a single
+route) that renders no layout got a theme switcher that flipped a signal nobody
+read.
+
 #### Content Children
 
 | Name      | Directive       | Description                        |
@@ -118,6 +124,23 @@ Marks template for sidebar. Provides `templateRef: TemplateRef`.
 - `setTheme(mode: MlvThemeMode): void` — set a selected mode, persist it, and
   synchronize the resolved theme
 
+#### Root Theme Attribute
+
+The service writes the resolved theme to `document.documentElement` as
+`mlvTheme="light|dark"` from a constructor `effect`, browser-only. `theme.scss`
+keys its dark token map off a plain `[mlvTheme='dark']` attribute selector, so
+nothing changes colour until that attribute exists above the content.
+
+- It lives here, not on `mlv-layout`, so the theme applies regardless of which
+  components are on screen. Any route that renders no layout still themes.
+- The service is `providedIn: 'root'`, so the write happens as soon as anything
+  injects it — which any theme control already does.
+- A scoped `mlvTheme` attribute further down the tree still wins locally: it is
+  a plain attribute selector and custom properties inherit, so the nearest
+  matching ancestor decides. That is how a permanently-dark rail inside an
+  otherwise light page works.
+- Server rendering never touches `documentElement`.
+
 #### Storage Behavior
 
 1. Attempts `localStorage` first

package/docs/ai/list.md

@@ -18,6 +18,7 @@ Exported from `@malva-ui/core/list`:
 |--------|------|-------------|
 | `MlvList` | Component | List container — `mlv-list` |
 | `MlvListVariant` | Type alias | `'plain' \| 'inset'` |
+| `MlvListAppearance` | Type alias | `'default' \| 'menu'` — context-specific row styling (standalone vs. overlay panel) |
 | `MlvListItem` | Component | List row — `mlv-list-item` |
 | `MlvListItemAccent` | Type alias | Semantic accent key or raw CSS color for the leading bar |
 | `MlvListItemMedia` | Directive | Leading rich-media slot — `[mlvListItemMedia]` |
@@ -48,10 +49,11 @@ Template: `<ng-content />`
 
 #### Inputs
 
-| Name       | Type             | Default   | Description                                                                                                                                                                                                                                                                         |
-| ---------- | ---------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `listRole` | `string`         | `'list'`  | WAI-ARIA role for the host element. Override to `'menu'` when used as a menu container.                                                                                                                                                                                             |
-| `variant`  | `MlvListVariant` | `'plain'` | Visual variant. `'plain'` — spaced rows with no container styling. `'inset'` — iOS Settings-style grouped look: rows sit on a raised surface inside a sunken, rounded card; consecutive rows are joined by inset dividers and group headers become sticky uppercase section labels. |
+| Name         | Type                | Default     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ------------ | ------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `listRole`   | `string`            | `'list'`    | WAI-ARIA role for the host element. Override to `'menu'` when used as a menu container.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `variant`    | `MlvListVariant`    | `'plain'`   | Visual variant. `'plain'` — hairline-separated rows, no per-row card: the container has zero gap and paints a single `border-top` (`--mlv-border-subtle`) between consecutive `mlv-list-item` rows (never on the row itself), each row's own `--mlv-list-item-radius` is `0`, and `--mlv-list-item-bg` is `transparent` at rest — a row gets a fill only on hover, selection, or focus (SL-R5). `'inset'` — iOS Settings-style grouped look: rows sit on a raised surface inside a sunken, rounded card; consecutive rows are joined by inset dividers (not the plain variant's container hairline — `:not(.mlv-list--inset)` scopes it out) and group headers become sticky uppercase section labels.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `appearance` | `MlvListAppearance` | `'default'` | Context-specific row styling, orthogonal to `variant`. `mlv-list` is a shared primitive used both as a standalone content list and as the panel container inside overlays (select/combobox/autocomplete dropdown, `mlv-menu`, popover menus like the tabs overflow / breadcrumb overflow / drawer-sections menu). `'default'` emits no modifier class — the airy SL-R5 standalone look above. `'menu'` adds `.mlv-list--appearance-menu`, which (a) suppresses the `'plain'`-variant hairline separator (`list.css` — `:not(.mlv-list--appearance-menu)` scopes it out) and (b) restores the pre-harmonization compact overlay rhythm on every descendant `mlv-list-item` via an ancestor-selector override in `list-item.scss`: `--mlv-list-item-padding-block: var(--mlv-spacing-2)` (was `--mlv-spacing-3`) and `--mlv-list-item-radius: var(--mlv-radius-m)` (was `0`), so the row has rounded corners for the hover/selection pill instead of being clipped by the container. Every internal overlay consumer (`mlv-dropdown-panel`, `mlv-menu`, tabs overflow popup, breadcrumb overflow popup, `mlv-drawer-sections`) sets this; standalone/docs list examples stay on the `'default'` appearance. |
 
 ---
 
@@ -89,14 +91,16 @@ The component automatically switches to the rich layout when any of the rich slo
 The row exposes a consistent state hierarchy styled via component-scoped CSS variables:
 
 - `:hover` — subtle tinted background
-- `:focus-visible` — accent focus ring via `--mlv-border-focus`
+- `:focus-visible` — Form A focus ring, `var(--mlv-stroke-width-medium)` `var(--mlv-border-focus)` at `var(--mlv-focus-ring-offset)` (SF-R3)
 - `:active` — pressed scale (0.985)
-- `--active` / `[aria-selected='true']` — tinted accent background and revealed leading accent bar
+- `--active` / `[aria-selected='true']` / `[aria-current]:not([aria-current='false'])` — `--mlv-background-selected` / `-hover` fill, `--mlv-text-on-selected` label, and revealed leading accent bar. Selection is its own token (SF-R1) — it never resolves the pressed `-active` fill. `aria-current` covers rows that name the state their context is already in (active heading level / list type / alignment in an editor menu, current saved view); presence minus the one negative value, so navigational `page`/`step` rows match too.
 - `--unread` — semibold title + leading unread dot
 - `--has-accent` — explicit accent bar always rendered
 
 Rendered row content is wrapped in `.mlv-list-item__surface`; the host owns focus/selection state, while pressed `:active` scaling is applied only to that inner surface.
 
+**Content projection (template invariant):** `list-item.html` follows the conditional-projection pattern — every `ng-content` slot (each selector and the wildcard default) appears exactly **once**, wrapped in an `ng-template`, and the rich/legacy layout branches stamp those templates through `ngTemplateOutlet`. Never duplicate a selector (or the bare `<ng-content />`) across the `@if` branches: slot assignment is static, so projected nodes bind to the first matching slot even when that branch never renders, and the content silently vanishes (this is exactly how legacy `[mlvListItemPrefix]` rows inside menus used to lose their icons). ng-content `select` attribute names are camelCase, matching the authored directive attributes.
+
 #### Density
 
 `list-item.scss` carries a density ladder driven by the shared cascade mixins (`@malva-ui/styles` `density.scss`): an ancestor `mlv--{density}` class (from `mlvDensityRoot`, or the class `mlv-popup` stamps on its detached overlay panel) scales the `--mlv-list-item-padding-block` / `--mlv-list-item-padding-inline` vars — tight `--mlv-spacing-1`, compact `--mlv-spacing-1-5`, comfortable `--mlv-spacing-2` (baseline default), spacious `--mlv-spacing-2-5`, airy `--mlv-spacing-3`. Consumers that override row padding must route it through those vars (not a direct `padding:`), or the ladder cannot apply — see the menu-panel row rule in `menu.scss` for the pattern.

package/docs/ai/menu.md

@@ -18,6 +18,13 @@ Exported from `@malva-ui/core/menu`:
 | `MlvMenuGroup` | Component | Group container — `mlv-menu-group` |
 | `MlvMenuGroupLabel` | Directive | Group label slot — `[mlvMenuGroupLabel]` |
 | `MlvMenuTrigger` | Directive | Opens a menu on click/hover — `[mlvMenuTrigger]` |
+| `MlvMenuItemData` | Interface | Typed reactive menu item data with optional lazy `children` |
+| `MlvMenuDataSource` | Type | Array or `MlvDataSource` accepted by reactive menus |
+| `MlvMenuItemDef` | Directive | Typed projected row template — `[mlvMenuItemDef]` |
+| `MlvMenuItemDefContext` | Interface | `$implicit`, `index`, `hasChildren`, and `loading` template context |
+| `MlvMenubarDividerData` | Interface | Root-level data divider discriminator and stable id |
+| `MlvMenubarEntry` | Type | Menubar item-or-divider entry type |
+| `MlvMenubarDataSource` | Type | Array or `MlvDataSource` accepted by reactive menubars |
 | `MlvMenubar` | Component | Horizontal application menu bar — `mlv-menubar` |
 | `MlvMenuAccessor` | Interface | Parent menu accessor interface (via `MENU_TOKEN`) |
 | `MENU_TOKEN` | Token | `InjectionToken<MlvMenuAccessor>` |
@@ -42,6 +49,7 @@ Exported from `@malva-ui/core/menu`:
 | ------------ | ------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `label`      | `string`                  | `''`        | `aria-label` for the menu panel                                                                                                                                                                                                                                                                                                                                                                                     |
 | `mlvDensity` | `MlvDensity \| undefined` | `undefined` | Density for the panel's item rows. The panel is portaled to the CDK overlay container, outside the trigger's density cascade — forwarded to the inner `mlv-popup`, which stamps `mlv--{density}` on the detached panel; row padding responds via the `mlv-list-item` density ladder. Omitted → global `MlvDensityService`. Submenus are separate `mlv-menu` instances — set per menu when overriding a nested tree. |
+| `dataSource`  | `MlvMenuDataSource<TItem> \| undefined` | `undefined` | Reactive item collection. Accepts an array or `MlvDataSource<TItem>`; when set, the menu renders the projected `[mlvMenuItemDef]` row template instead of projected menu rows. |
 
 #### Outputs
 
@@ -65,13 +73,51 @@ Exported from `@malva-ui/core/menu`:
 - `_isOpen: WritableSignal<boolean>` — managed by `MlvMenuTrigger`
 - `_popup: Signal<MlvPopup>` — accessed by `MlvMenuTrigger` for overlay management
 
+#### Reactive data mode
+
+`dataSource` accepts either `MlvMenuItemData<T>[]` or an `MlvDataSource`
+instance. Project one typed row definition with `[mlvMenuItemDef]`; the
+template receives the item as `$implicit` plus `index`, `hasChildren`, and
+`loading`:
+
+```html
+<mlv-menu [dataSource]="items">
+  <mlv-list-item
+    mlvMenuItem
+    *mlvMenuItemDef="let item; let hasChildren = hasChildren"
+  >
+    {{ item.label }}
+    @if (hasChildren) {
+      <mlv-spacer />
+      <svg mlvListItemSuffix lucideChevronRight [size]="16" />
+    }
+  </mlv-list-item>
+</mlv-menu>
+```
+
+An item with `children: Observable<MlvMenuItemData<T>[]>` becomes a submenu
+trigger automatically. The child stream is subscribed to on first open and
+the submenu displays the localized loader while it is pending. A generated
+submenu arrow is supplied by menu styling; an explicit suffix in a custom row
+template takes precedence.
+
+#### Key-manager lifecycle (roving tabindex)
+
+The `FocusKeyManager` is reconciled from a constructor `effect()` reading `_items()`, and the reconciliation is deliberately **`untracked`**:
+
+- `_syncTabIndices()` reads `FocusKeyManager.activeItem`, which CDK backs with a **signal** (`ListKeyManager._activeItem`). Reading it inside the effect's reactive context made the effect depend on the active item, so **every** arrow key re-ran the effect → new manager → `activeItemIndex` reset to `-1`. Symptoms: ArrowDown always returned to the first item, ArrowUp to the last, and no `role="menuitem"` ever held `tabindex="0"`. Home/End/type-ahead hid the bug because they are absolute moves. **`_items()` must stay the effect's only dependency.**
+- `_syncKeyManager(items)` bails when the item set is member-identical to `_managedItems` (a snapshot), so a change-detection pass that re-runs the content query never rebuilds the manager.
+- A real item change rebuilds and carries the active item over with `updateActiveItem()` (no focus steal). If the active item was removed/disabled, `mlvNearestEnabledItem()` picks the closest enabled item to its old index — the tab stop never falls back to "nothing".
+- `_teardownKeyManager()` unsubscribes the `change` stream and calls `FocusKeyManager.destroy()`; also wired to `DestroyRef.onDestroy`.
+- `_syncTabIndices()` invariant: **exactly one enabled item carries `tabindex="0"` while the panel is open.** That is the active item once navigation started; before then (pointer-opened panel, focus on the `role="menu"` list) the first enabled item is the tab stop. The key manager's index stays `-1` in that state, so the first ArrowDown still lands on the **first** item.
+
 ---
 
 ### `MlvMenuItem`
 
 **Selector:** `mlv-list-item[mlvMenuItem]`
 
-Applied to `mlv-list-item` to give it menu-item semantics. Overrides `role="listitem"` → `role="menuitem"`, wires into the parent `FocusKeyManager`, and closes the parent menu stack on activation.
+Applied to `mlv-list-item` to give it menu-item semantics. Overrides `role="listitem"` → `role="menuitem"`, wires into the parent `FocusKeyManager`, and closes the parent menu stack on leaf activation. When the same row is an enabled `[mlvMenuTrigger]` with `[isSubmenuTrigger]="true"`, the trigger owns click/Enter/Space activation so opening the child menu does not select the row or dismiss its ancestor. A disabled submenu trigger falls back to the item's leaf `itemClick` and close-all behavior.
 
 Users must import both `MlvListItem` (from `@malva-ui/core/list`) and `MlvMenuItem` (from `@malva-ui/core/menu`).
 
@@ -127,6 +173,7 @@ A horizontal File / Edit / View style application menu bar implementing the [WAI
 | Name    | Type     | Default | Description                                |
 | ------- | -------- | ------- | ------------------------------------------ |
 | `label` | `string` | `''`    | `aria-label` for the `role="menubar"` host |
+| `dataSource` | `MlvMenubarEntry<TItem>[] \| MlvDataSource<MlvMenubarEntry<TItem>> \| undefined` | `undefined` | Reactive top-level items. Entries may be item data or `MlvMenubarDividerData`; dividers are visual root separators and are excluded from keyboard navigation. |
 
 #### Host bindings
 
@@ -141,6 +188,15 @@ A horizontal File / Edit / View style application menu bar implementing the [WAI
 - **In-menu crossing** — `ArrowRight` / `ArrowLeft` at the top level of an open dropdown crosses to the adjacent menubar menu (focusing its first item); a focused submenu-trigger item's own `ArrowRight` opens the submenu instead — **submenu wins** (it stops propagation before the panel's handler runs).
 - **Escape** — closes the menu and restores focus to its top-level item (via `MlvMenuTrigger`'s focus-restore).
 
+#### Reactive data mode
+
+Menubars accept the same typed item definition as menus. Set `dataSource` to an
+array or `MlvDataSource` and use `MlvMenubarDividerData` entries for root-level
+vertical separators. Dividers render with `role="separator"` and
+`aria-orientation="vertical"`; they never receive a tabindex or participate in
+roving navigation. Lazy `children` streams create generated dropdown menus and
+use the localized pending loader.
+
 #### `MlvMenubarAccessor` methods (used by child triggers via `MENUBAR_TOKEN`)
 
 | Method                            | Description                                                                      |
@@ -201,6 +257,23 @@ When a `[mlvMenuTrigger]` is a **direct child of a `mlv-menubar`** it can inject
 
 ---
 
+## Generated submenu overlay origin
+
+`MlvMenuDataItem` anchors a generated submenu to the row that `ngTemplateOutlet`
+stamps, which does not exist yet when the overlay controller is constructed. The
+origin is therefore a real `ElementRef` instance whose `nativeElement` is
+redefined as a lazy getter, **not** a plain object with the same shape.
+
+The instance matters: CDK's `FlexibleConnectedPositionStrategy._getOriginRect()`
+only calls `getBoundingClientRect()` when the origin passes
+`instanceof ElementRef` (or `instanceof Element`). Anything else is read as an
+`{x, y}` point — `undefined` coordinates propagate to `NaN`, the pane's `top`
+and `left` are dropped as invalid, and every generated submenu renders at the
+viewport's top-left corner instead of beside its row. Covered by
+"anchors a generated submenu to the rendered row through a real ElementRef
+
+---
+
 ## Submenu Hover Intent
 
 When `isSubmenuTrigger="true"`, the directive installs a document-level `mousemove`
@@ -313,6 +386,7 @@ import { MlvListItem } from '@malva-ui/core/list'; // always needed for mlv-list
 - Submenu keyboard: `ArrowRight` on a submenu trigger opens the submenu and focuses its first item; `ArrowLeft` inside a submenu closes it and returns focus to the parent item.
 - `MlvMenuGroup` names its `role="group"` via `aria-labelledby` pointing at the generated id of the projected `[mlvMenuGroupLabel]` (that id is now `mlvNextId('mlv-menu-group-label')` from `@malva-ui/cdk/utils`, replacing a hand-rolled counter).
 - **Type-ahead** (added with `@angular/aria` migration Task 2.6): typing a printable letter while the menu is open moves focus to the first item whose visible text starts with the typed string (200 ms debounce, wraps). Implemented via CDK `FocusKeyManager.withTypeAhead()`; `MlvMenuItem.getLabel()` returns the item's trimmed `textContent`. Disabled items are skipped. The key manager's `change` stream keeps the roving tabindex in sync when type-ahead moves the active item asynchronously.
+- **Roving tabindex** — exactly one enabled `role="menuitem"` holds `tabindex="0"` while the panel is open, and it follows ArrowUp/ArrowDown/Home/End/type-ahead. See "Key-manager lifecycle" under `MlvMenu` for the rebuild rules that keep this true (a rebuilt `FocusKeyManager` would otherwise reset the active index to `-1`).
 
 ## `@angular/aria` migration status (Task 2.6) — deviation
 

package/docs/ai/page.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-`@malva-ui/core/page` provides composable application-page primitives. `mlv-page-shell` owns the reusable geometry that joins existing action bars, one or two sidebars, and the rounded Page canvas; the projected navigation components retain their own behavior. The remaining primitives own page scrolling, structured headers, a collapsible key-facts summary strip, responsive main/aside content, and a bottom workflow action dock.
+`@malva-ui/core/page` provides composable application-page primitives. `mlv-page-shell` owns the reusable geometry that joins an existing action bar, zero to two start sidebars, one optional static or responsive end pane, and the rounded Page canvas; the projected navigation components retain their own behavior. The remaining primitives own page scrolling, structured headers, a collapsible key-facts summary strip, responsive main/aside content, and a bottom workflow action dock.
 
 Record-editor experiences (draft/live switches, version history, diff views, suggestions, delayed publish) are built by **composition**: this library ships the structure, slots, and scroll-linked behaviour; the host owns the domain state. See docs page example 3 for the full pattern.
 
@@ -10,54 +10,76 @@ Record-editor experiences (draft/live switches, version history, diff views, sug
 
 Exported from `@malva-ui/core/page`:
 
-| Export                     | Kind          | Selector / values             |
-| -------------------------- | ------------- | ----------------------------- |
-| `MlvPageShell`             | Component     | `mlv-page-shell`              |
-| `MlvPageTopbar`            | Shell slot    | `[mlvPageTopbar]`             |
-| `MlvPageSidebar`           | Shell slot    | `[mlvPageSidebar]`            |
-| `MlvPageEndSidebar`        | Shell slot    | `[mlvPageEndSidebar]`         |
-| `MlvPage`                  | Component     | `main[mlvPage]`               |
-| `MlvPageHeader`            | Component     | `mlv-page-header`             |
-| `MlvPageContent`           | Component     | `mlv-page-content`            |
-| `MlvPageBreadcrumb`        | Template slot | `[mlvPageBreadcrumb]`         |
-| `MlvPageHeaderIcon`        | Template slot | `[mlvPageHeaderIcon]`         |
-| `MlvPageTitle`             | Template slot | `[mlvPageTitle]`              |
-| `MlvPageHeaderStatus`      | Template slot | `[mlvPageHeaderStatus]`       |
-| `MlvPageHeaderActions`     | Template slot | `[mlvPageHeaderActions]`      |
-| `MlvPageHeaderDescription` | Template slot | `[mlvPageHeaderDescription]`  |
-| `MlvPageHeaderMeta`        | Template slot | `[mlvPageHeaderMeta]`         |
-| `MlvPageHeaderTabs`        | Template slot | `[mlvPageHeaderTabs]`         |
-| `MlvPageHeaderTabsActions` | Template slot | `[mlvPageHeaderTabsActions]`  |
-| `MlvPageAside`             | Template slot | `[mlvPageAside]`              |
-| `MlvPageSummary`           | Component     | `mlv-page-summary`            |
-| `MlvPageSummaryItem`       | Component     | `mlv-page-summary-item`       |
-| `MlvPageDock`              | Component     | `mlv-page-dock`               |
-| `MlvPageDockStart`         | Dock slot     | `[mlvPageDockStart]`          |
-| `MlvPageDockCenter`        | Dock slot     | `[mlvPageDockCenter]`         |
-| `MlvPageDockEnd`           | Dock slot     | `[mlvPageDockEnd]`            |
-| `MLV_PAGE_SCROLL`          | Token         | `MlvPageScrollState`          |
-| `MlvPageScrollState`       | Interface     | `{ scrollTop; scrolled }`     |
-| `MlvPageSnapController`    | Service       | provided by `MlvPage`         |
-| `MlvPageSnap`              | Directive     | `[mlvPageSnap]`               |
-| `MlvPageSnapMode`          | Type          | `'hide' \| 'fade' \| 'keep'`  |
-| `MlvPageDockAppearance`    | Type          | `'bar' \| 'floating'`         |
-| `MlvPageScroll`            | Type          | `'auto' \| 'none'`            |
-| `MlvPagePadding`           | Type          | `'none' \| 's' \| 'm' \| 'l'` |
-| `MlvPageSurface`           | Type          | `'anchored' \| 'flat'`        |
-| `MlvPageHeaderSize`        | Type          | `'m' \| 's'`                  |
-| `MlvPageHeaderTabsAlign`   | Type          | `'start' \| 'center'`         |
-| `MlvPageAsidePlacement`    | Type          | `'start' \| 'end'`            |
-| `MlvPageContentGap`        | Type          | `'s' \| 'm' \| 'l'`           |
+| Export                     | Kind             | Selector / values                    |
+| -------------------------- | ---------------- | ------------------------------------ |
+| `MlvPageShell`             | Component        | `mlv-page-shell`                     |
+| `MlvPageTopbar`            | Shell slot       | `[mlvPageTopbar]`                    |
+| `MlvPageSidebar`           | Shell slot       | `[mlvPageSidebar]`                   |
+| `MlvPageEndSidebar`        | Shell slot       | `[mlvPageEndSidebar]`                |
+| `MlvPageEndPane`           | Component        | `mlv-page-end-pane`                  |
+| `MlvPageEndPaneContent`    | Template slot    | `ng-template[mlvPageEndPaneContent]` |
+| `MlvPageEndPaneTrigger`    | Button directive | `button[mlvPageEndPaneTrigger]`      |
+| `MlvPage`                  | Component        | `main[mlvPage]`                      |
+| `MlvPageHeader`            | Component        | `mlv-page-header`                    |
+| `MlvPageContent`           | Component        | `mlv-page-content`                   |
+| `MlvPageBreadcrumb`        | Template slot    | `[mlvPageBreadcrumb]`                |
+| `MlvPageHeaderIcon`        | Template slot    | `[mlvPageHeaderIcon]`                |
+| `MlvPageTitle`             | Template slot    | `[mlvPageTitle]`                     |
+| `MlvPageHeaderStatus`      | Template slot    | `[mlvPageHeaderStatus]`              |
+| `MlvPageHeaderActions`     | Template slot    | `[mlvPageHeaderActions]`             |
+| `MlvPageHeaderDescription` | Template slot    | `[mlvPageHeaderDescription]`         |
+| `MlvPageHeaderMeta`        | Template slot    | `[mlvPageHeaderMeta]`                |
+| `MlvPageHeaderTabs`        | Template slot    | `[mlvPageHeaderTabs]`                |
+| `MlvPageHeaderTabsActions` | Template slot    | `[mlvPageHeaderTabsActions]`         |
+| `MlvPageAside`             | Template slot    | `[mlvPageAside]`                     |
+| `MlvPageSummary`           | Component        | `mlv-page-summary`                   |
+| `MlvPageSummaryItem`       | Component        | `mlv-page-summary-item`              |
+| `MlvPageDock`              | Component        | `mlv-page-dock`                      |
+| `MlvPageDockStart`         | Dock slot        | `[mlvPageDockStart]`                 |
+| `MlvPageDockCenter`        | Dock slot        | `[mlvPageDockCenter]`                |
+| `MlvPageDockEnd`           | Dock slot        | `[mlvPageDockEnd]`                   |
+| `MLV_PAGE_SCROLL`          | Token            | `MlvPageScrollState`                 |
+| `MlvPageScrollState`       | Interface        | `{ scrollTop; scrolled }`            |
+| `MlvPageSnapController`    | Service          | provided by `MlvPage`                |
+| `MlvPageSnap`              | Directive        | `[mlvPageSnap]`                      |
+| `MlvPageSnapRegionBase`    | Abstract base    | focus contract for snap regions      |
+| `MlvPageSnapRegion`        | Interface        | `{ reveal; syncHiddenState }`        |
+| `MlvPageSnapMode`          | Type             | `'hide' \| 'fade' \| 'keep'`         |
+| `MlvPageDockAppearance`    | Type             | `'bar' \| 'floating'`                |
+| `MlvPageScroll`            | Type             | `'auto' \| 'none'`                   |
+| `MlvPagePadding`           | Type             | `'none' \| 's' \| 'm' \| 'l'`        |
+| `MlvPageSurface`           | Type             | `'anchored' \| 'flat'`               |
+| `MlvPageHeaderSize`        | Type             | `'m' \| 's'`                         |
+| `MlvPageHeaderTabsAlign`   | Type             | `'start' \| 'center'`                |
+| `MlvPageAsidePlacement`    | Type             | `'start' \| 'end'`                   |
+| `MlvPageContentGap`        | Type             | `'s' \| 'm' \| 'l'`                  |
 
 ## `MlvPageShell`
 
 `MlvPageShell` is the application-page composition boundary. It supplies stable topbar/body/content tracks, continuous dark chrome, and the integration styling that turns a collapsed `mlv-sidebar` into a rail beside an attached Page canvas. Consumers project existing navigation components through marker directives; Page does not duplicate their interaction logic.
 
 - `[mlvPageTopbar]` spans the shell above every column.
-- `[mlvPageSidebar]` marks the primary start sidebar.
-- `[mlvPageEndSidebar]` optionally adds a second shell-level sidebar after the canvas.
+- `[mlvPageSidebar]` marks zero to two start sidebars. Repeated hosts project in their author DOM order.
+- `[mlvPageEndSidebar]` optionally adds one static shell-level end sidebar after the canvas.
+- `mlv-page-end-pane` adds a responsive trailing pane that becomes a modal Drawer below its configured breakpoint.
 - Unmarked content occupies the central canvas track and should normally be one `main[mlvPage]`.
 
+### Multi-sidebar projection contract
+
+`mlv-page-shell` accepts zero, one, or two repeated `[mlvPageSidebar]` hosts.
+Their DOM order is their visual and reading order, so an icon rail followed by an
+expanded navigation panel stays a rail followed by navigation for every user.
+The shell accepts at most one `[mlvPageEndSidebar]`, projected after the central
+content track for a labelled inspector or complementary navigation region.
+The same end projection also accepts one `mlv-page-end-pane`; existing static
+end-sidebar markup remains compatible and unchanged.
+
+The shell deliberately has no numbered sidebar selectors and no column-count
+input. Each projected host owns its own `width`, collapsed state, and
+`offcanvas` mode. The shell only preserves the tracks around it: the central
+content track remains `flex: 1 1 auto` with `min-width: 0`, allowing it to
+shrink instead of overflowing when sidebars are present.
+
 A projected sidebar in `mode="offcanvas"` renders as an overlay drawer while its
 host element stays in the shell's body row. `mlv-sidebar--offcanvas` is
 `width: 100%` so a standalone sidebar can fill its container, which inside the
@@ -97,10 +119,12 @@ Everything projected into `[mlvPageTopbar]` / `[mlvPageSidebar]` /
 `[mlvPageEndSidebar]` sits on the chrome background, not on a page surface, so
 the theme tokens those components resolve read wrong against it. The shell
 remaps them scoped to the chrome slots only — a control inside `main[mlvPage]`
-keeps the normal tokens. All values derive from
-`--mlv-page-shell-effective-foreground`, the same contrast-derived value the
-topbar already uses, so one set of rules covers a light brand colour, a dark
-brand colour, and the default `neutral-900` chrome in both themes.
+keeps the normal tokens. Every remap mixes
+`--mlv-page-shell-effective-foreground` **against
+`--mlv-page-shell-effective-background`** — never against `transparent` — so
+one formula is correct on a light chrome, a dark chrome, and a brand chrome,
+and the result is opaque (a portalled flyout no longer picks up whatever is
+behind it) (SF-R2).
 
 On `&__sidebar.mlv-sidebar`:
 
@@ -109,22 +133,82 @@ On `&__sidebar.mlv-sidebar`:
 | `--mlv-sidebar-border-width`        | `0rem`               | The rail has no wall of its own inside the shell.                                     |
 | `--mlv-text-primary`                | effective foreground | Row labels.                                                                           |
 | `--mlv-text-secondary`              | foreground 78 %      | Idle row labels.                                                                      |
-| `--mlv-text-action`                 | effective foreground | Active row text (the pill, not colour, carries the active state — see below).         |
-| `--mlv-background-neutral-1`        | foreground 15 %      | Neutral interactive fill.                                                             |
-| `--mlv-background-neutral-1-hover`  | foreground 15 %      | Transparent-variant `mlvButton`s and other projected chrome resolve this pair direct. |
-| `--mlv-background-neutral-1-active` | foreground 24 %      | Same — e.g. the workspace switcher's open state.                                      |
-| `--mlv-sidebar-hover-bg`            | foreground 15 %      | Row hover / focus-visible fill (see `libs-sidebar.md` → **State surfaces**).          |
-| `--mlv-sidebar-active-bg`           | foreground 24 %      | Active row pill.                                                                      |
-| `--mlv-sidebar-rail-color`          | foreground 30 %      | Expanded group tree line.                                                             |
+| `--mlv-text-action`                 | effective foreground | Link/action foreground inside the rail.                                               |
+| `--mlv-background-neutral-1`        | foreground 8 %       | Neutral interactive fill.                                                             |
+| `--mlv-background-neutral-1-hover`  | foreground 8 %       | Transparent-variant `mlvButton`s and other projected chrome resolve this pair direct. |
+| `--mlv-background-neutral-1-active` | foreground 12 %      | Same — e.g. the workspace switcher's open state.                                      |
+| `--mlv-sidebar-hover-bg`            | foreground 8 %       | Row hover / focus-visible fill (see `libs-sidebar.md` → **State surfaces**).          |
+| `--mlv-sidebar-active-bg`           | foreground 12 %      | Active row pill.                                                                      |
+| `--mlv-sidebar-rail-color`          | foreground 24 %      | Expanded group tree line.                                                             |
+| `--mlv-text-on-selected`            | effective foreground | Active row label — see below.                                                         |
+| `--mlv-background-selected`         | foreground 12 %      | Selected fill for anything resolving it directly (workspace switcher row).            |
+| `--mlv-background-selected-hover`   | foreground 8 %       | Same, hovered.                                                                        |
 | `--mlv-border-focus`                | effective foreground | Focus ring.                                                                           |
 
-Measured on a `rgb(65, 99, 169)` brand colour (white foreground): active pill =
-white 24 % → white icon at 3.53:1; hover = white 15 % → 4.26:1. Both clear the
-WCAG AA 3:1 minimum for UI components.
+The six row-state fills above (`--mlv-background-neutral-1*`,
+`--mlv-sidebar-hover-bg/-active-bg/-rail-color`) sit lower than the
+field-fill/border/foreground mixes elsewhere in this remap — SF-R2/SL-R5's "no
+state fill darker than the darkest resting surface." Resolved on three
+chromes: light (`#ffffff` bg, near-black fg) hover `rgb(236,236,236)` / active
+`rgb(227,227,227)`; dark default (`#171717` bg, `#fafafa` fg) hover
+`rgb(41,41,41)` / active `rgb(50,50,50)`; brand blue `rgb(65,99,169)` with
+white foreground — hover `rgb(80,111,176)` / active `rgb(88,118,179)`. One
+formula, three correct answers.
+
+`--mlv-text-on-selected` has to be remapped **in its own right**, not through
+`--mlv-text-action`. It is declared once per theme block as
+`var(--mlv-text-action)`, so it resolves in the scope it is declared in — the
+document root — and remapping `--mlv-text-action` on the sidebar never reaches
+it. Without the direct remap an active row keeps the theme accent: a lavender
+label on the chrome-derived 12 % pill, unreadable on a coloured chrome and deaf
+to a `color`/`foreground` override.
+
+The seam between two adjacent start sidebars
+(`.mlv-page-shell__body > [mlvPageSidebar] + [mlvPageSidebar]`) is derived the
+same way — `border-inline-start: var(--mlv-stroke-width) solid` foreground
+**16 %**, between the 8/12 % row-state fills and the 24 % rail line.
+`--mlv-border-subtle` resolves against the page surface and painted a near-white
+hairline across a dark or brand chrome.
 
 `&__topbar .mlv-form-control-wrapper` / `&__sidebar .mlv-form-control-wrapper`
 carry the matching remap for projected form controls (container background,
-border ramp, text and focus tokens).
+border ramp, text and focus tokens) — same chrome-background mix, unchanged
+percentages (10 / 30 / 40 / 50 for the field fill/border ramp; 78 / 78 / 60 for
+the action/text-secondary/text-tertiary foregrounds).
+
+## `MlvPageEndPane`
+
+`MlvPageEndPane` owns one trailing region across two renderers. It projects the
+single required `ng-template[mlvPageEndPaneContent]` into a labelled inline
+`aside` above `collapseBelow` and into a right-side modal `MlvDrawer` below it.
+Only one branch exists at a time, so consumers never create duplicate forms,
+subscriptions, ids, or tab stops while the viewport crosses the breakpoint.
+
+| Input / model          | Type                     | Default   | Description                                                     |
+| ---------------------- | ------------------------ | --------- | --------------------------------------------------------------- |
+| `opened`               | `boolean` model          | `false`   | One logical open state shared by inline and Drawer renderers.   |
+| `width`                | `string`                 | `'20rem'` | Inline track width and compact Drawer size.                     |
+| `collapseBelow`        | `MlvBreakpoint \| null`  | `null`    | Breakpoint below which the pane uses the modal Drawer renderer. |
+| `ariaLabel`            | `string`                 | required  | Accessible name of the active aside or dialog.                  |
+| `closeOnBackdropClick` | `boolean`                | `true`    | Allows backdrop dismissal in compact mode.                      |
+| `closeOnEscape`        | `boolean`                | `true`    | Allows Escape dismissal in compact mode.                        |
+| `initialFocus`         | `MlvOverlayInitialFocus` | `'auto'`  | Compact Drawer initial-focus strategy.                          |
+
+| Output         | Description                                                                                              |
+| -------------- | -------------------------------------------------------------------------------------------------------- |
+| `openedChange` | Model output emitted when the logical `opened` state changes.                                            |
+| `afterOpened`  | Emits once for each logical false-to-true transition. Breakpoint migration does not emit.                |
+| `afterClosed`  | Emits once after a real close and after the active renderer is gone. Breakpoint migration does not emit. |
+
+Public methods `open()`, `close()`, and `toggle()` update the same logical
+model. `button[mlvPageEndPaneTrigger]` requires a pane instance, toggles it,
+and mirrors `aria-expanded` plus `aria-controls`. The pane host owns a stable
+`panelId`, so that relationship resolves while open, closed, inline, or modal.
+
+The pane captures the pre-open active element only on a logical false-to-true
+transition. Its internal Drawer disables its own focus restoration; the pane
+restores focus once after a real close. Moving an already-open pane across the
+breakpoint neither restores focus nor emits a false close event.
 
 ## `MlvPage`
 
@@ -140,8 +224,29 @@ border ramp, text and focus tokens).
 | `stickyHeader` | `boolean`        | `true`       | Makes a projected `mlv-page-header` sticky within the page scroll area. |
 | `snapRange`    | `number`         | `96`         | Scroll distance in px mapped onto the full 0..1 snap timeline.          |
 
+`MlvPage` also exposes its snap controller as a `snap` getter, so a component
+that only _hosts_ the page (and therefore cannot inject the controller) can
+reach it with `viewChild(MlvPage).snap` — see `expand()` below.
+
 The anchored surface rounds only the top corners. This makes the page read as one continuous canvas rather than a detached card floating inside the application shell.
 
+The host rounds its border box and publishes the matching _padding_-box curve as
+`--mlv-page-surface-radius` (`calc(var(--mlv-radius-xl) - 0.0625rem)` when
+anchored, `0rem` when flat). A **first-child** `mlv-page-header` /
+`mlv-page-summary` consumes it for its own top corners; full-bleed chrome
+further down the page stays square.
+
+That radius cannot be left to the host's `overflow: clip`. The header and the
+summary strip paint a glass surface with `backdrop-filter`, and a filtered
+backdrop is composited into a backdrop root that an ancestor's _rounded_
+overflow clip never reaches — verified in Chromium: forcing
+`backdrop-filter: none` on the header rounds the corners, restoring the blur
+squares them off again. Clipping on `.mlv-page__inner` is **not** the
+alternative: `overflow` there makes `__inner` the nearest scroll container for
+the sticky header, and `__inner` scrolls with the content, so the header would
+stop sticking — and every inline-rendered overlay would be cut off at the canvas
+edge.
+
 ### Chrome surface (glass)
 
 Header, summary strip, and dock share the `mlv-action-bar` glass recipe:
@@ -199,11 +304,32 @@ manually (skipped under `prefers-reduced-motion`).
 Controller API: `progress`/`pinned`/`snapped`/`spacerScale` signals,
 `toggle()` (snap fully open/closed — a manual pin, otherwise the next scroll
 event would undo it; collapsing also tweens `spacerScale` to 0 so the
-compensation spacer is reclaimed), `setPinned(boolean)` (freeze at the
+compensation spacer is reclaimed), `expand()` / `collapse()` (the same manual
+pin, driven imperatively), `setPinned(boolean)` (freeze at the
 current progress / release back to scroll-following). Pin origin matters: a
 manual (chevron) pin survives everywhere with the spacer reclaimed; a
 scroll-origin (pin button) pin auto-releases at the top of the page.
 
+**`expand()` also reveals collapsed chrome for a programmatic focus.** A
+collapsed snap region is `visibility: hidden`, so a consumer's `focus()` on a
+control inside it is silently refused. `expand()` therefore reveals every
+registered region **synchronously**, before its own tween runs, so the naive
+sequence works:
+
+```ts
+// A component that hosts the page reaches the controller through the page.
+private readonly page = viewChild.required(MlvPage);
+
+onEscapeToTop(): void {
+  this.page().snap.expand();
+  this.activeHeaderTab()?.focus();
+}
+```
+
+A component _inside_ `main[mlvPage]` injects `MlvPageSnapController` directly
+instead. `revealing` (`@internal`) is the bridge flag the regions read between
+the call and the tween leaving their window.
+
 ### `MlvPageSnap` (`[mlvPageSnap]`)
 
 Every element can define its own state on the snap timeline: the directive
@@ -217,9 +343,30 @@ behaviour — `hide` (height + opacity collapse, default), `fade`, or `keep`.
 | `snapSize`            | `'3rem'`  | Nominal expanded size for the `hide` height scrub.     |
 
 Fully elapsed `hide`/`fade` elements get `visibility: hidden` so they leave
-the accessibility tree and tab order. The behaviour CSS lives in `page.scss`
+the accessibility tree and tab order — a control nobody can see must not be an
+invisible tab stop. The behaviour CSS lives in `page.scss`
 (`.mlv-page-snap--hide/--fade`), so it is only active inside a page.
 
+**Focus contract (`MlvPageSnapRegionBase`).** The collapse is driven by
+_scrolling_, not by a user action, so hiding it unconditionally would let a
+scroll blur whatever the user had focused — the browser drops that focus to
+`<body>` and the next Tab restarts at the top of the page. A region therefore
+**never hides while it holds focus**: `focusin`/`focusout` (with a
+`relatedTarget` containment test, so moving between two controls inside the
+region does not count as leaving) drive a `mlv-page-snap--revealed` /
+`mlv-page-summary--revealed` class that zeroes the region's local
+`--mlv-snap-progress`, taking it off the timeline until focus leaves. Nothing
+relocates focus, and the mouse-only scrub — nothing focused — is unchanged.
+`MlvPageSnap` and `MlvPageSummary` share the contract through
+`MlvPageSnapRegionBase`; a subclass supplies its own end-of-window test and
+binds `_hidden()` / `_revealed()` plus the two focus listeners in its `host`.
+
+The base also implements the `MlvPageSnapRegion` methods the controller calls —
+`reveal()` lifts the hide immediately (ahead of change detection, so a
+same-task `focus()` lands) and `syncHiddenState()` re-applies it when the
+reveal window closes without a render in between. Both are controller
+plumbing; consumers call `expand()`, never these.
+
 ## `MlvPageHeader`
 
 The header renders a predictable hierarchy for breadcrumb/back navigation, one semantic page title, inline status, actions, supporting description, metadata, and a tabs row. All content areas are optional structural template slots.
@@ -275,8 +422,12 @@ collapse/expand and pinning are driven by the header's snap controls through
 `MlvPageSnapController` — the strip itself just scrubs its height (against a
 `ResizeObserver`-measured natural row height) and opacity from
 `--mlv-page-snap` over its stagger window, and turns `visibility: hidden`
-once fully collapsed. Breaking change: the former `collapsed`/`pinned`
-models, `collapseOnScroll`, and the strip-owned controls were removed.
+once fully collapsed — unless it holds focus, in which case it reveals itself
+(`mlv-page-summary--revealed`) rather than let a scroll blur a projected
+interactive fact into `<body>`; see the snap focus contract above. Breaking
+change: the former `collapsed`/`pinned` models, `collapseOnScroll`, and the
+strip-owned controls were removed. As a `MlvPageSnapRegionBase` subclass it
+also carries the controller-facing `reveal()` / `syncHiddenState()` pair.
 
 | Input          | Type     | Default          | Description                              |
 | -------------- | -------- | ---------------- | ---------------------------------------- |
@@ -348,6 +499,12 @@ sticky dock is destroyed or `sticky` goes false.
 | `stackBelow`     | `number`                | `1024`              | Container width in CSS pixels below which the columns stack. |
 | `asideLabel`     | `string`                | `'Related content'` | Accessible name for the aside landmark.                      |
 
+### Aside track reservation
+
+- The complementary grid track exists **only while an `[mlvPageAside]` template is actually projected**. The component sets `mlv-page-content--has-aside` on the host from the same `contentChild(MlvPageAside)` query that renders the `<aside>`, and the SCSS keys the two-track definition (and the stacked two-row definition) on that class.
+- Without an aside the host is a single `minmax(0, 1fr)` track / `'main'` area, so a consumer that projects no aside keeps the full inline size instead of losing `asideWidth` to an empty track. No opt-in input; no `:has()`; consumer-side overrides that collapsed the track are no longer needed.
+- Inline geometry is scoped `--has-aside:not(--stacked)` so the compound `--has-aside.--aside-start` selector cannot out-specify the stacked single-column rules.
+
 ## Usage
 
 ```html
@@ -406,11 +563,14 @@ Record-editor composition (compact header, summary strip, dock):
 - `@angular/cdk/coercion`
 - `@lucide/angular`
 - `@malva-ui/cdk` (`MlvStructural`, `MlvResizeObserverService`)
+- `@malva-ui/cdk/overlay` (`MlvOverlayInitialFocus`)
+- `@malva-ui/cdk/utils` (`MlvBreakpointService`, `MlvBreakpoint`, `mlvNextId`)
 - `@malva-ui/cdk/floating-container` — **SCSS only**: `page-dock.scss` `@use`s
   `floating-container.mixins.scss` for the floating appearance. The mixins are
   inlined at compile time, so this is not a runtime or package dependency (and
   the Nx graph does not model it — see the same arrangement with *(internal)*).
 - `@malva-ui/core/button` (summary chevron/pin controls)
+- `@malva-ui/core/drawer` (compact end-pane renderer)
 - `@malva-ui/core/expand` (summary collapse animation)
 - `@malva-ui/core/link`
 - `@malva-ui/core/scrollbar` (page scroll owner; `viewportElement` feeds the scroll context)