@happyvertical/smrt-svelte 0.55.0 → 0.55.2

package/README.md

@@ -32,6 +32,24 @@ pipeline (`opportunity.stage`) without importing `@happyvertical/smrt-projects`.
 
 Svelte 5 component library for the s-m-r-t framework. Provides UI components, browser AI integration (STT/TTS/LLM with warm cache), a theme system, permission-aware rendering, and module UI registry for agent admin panels.
 
+## Sortable and shell layout
+
+`@happyvertical/smrt-svelte/sortable` provides `Sortable`, an accessible
+(pointer, touch, keyboard, screen-reader announcements) list of containers and
+items that share Board's drag engine. `AppShell` lets users customize their
+shell: pass `layout` and `onlayoutchange` to own persistence (for example in an
+exported app blueprint), or neither to store it in the user's settings. Mount
+`ShellLayoutEditor` (from `/app` or `/workspace`) on a settings page, and call
+`useShellLayout()` to make the same changes from code or an assistant. See
+`agents/workspace.md`; the pure `ShellLayout` model is published without Svelte
+as `@happyvertical/smrt-svelte/workspace/layout`.
+
+```svelte
+<AppShell {nav} {navGroups} layout={stored} onlayoutchange={(next) => (stored = next)}>
+  <ShellLayoutEditor />
+</AppShell>
+```
+
 ## Installation
 
 ```bash
@@ -450,10 +468,15 @@ keys the shell renders exactly as before.
   sheet, `phone.swipeToClose` closes drawers by swiping. A `path` change on a
   phone closes open drawers. `overlays` is a layer above the edges (and above
   the bottom bar's row) for `PhoneSheet`s and status strips.
-- **Page contracts** on phones: `data-shell-breadcrumbs` is hidden,
-  `data-shell-page-title` is visually hidden while the phone top bar shows
-  (the bar carries the title), `data-shell-tabs` sticks under the top bar and
-  slides away with it. smrt-ui's `PageHeader` renders the first two.
+- **Page contracts** on phones: `data-shell-breadcrumbs` is hidden only when
+  the phone bar contains `data-shell-page-navigation-replacement` (the back
+  link in `PhoneTopBar` detail mode declares it). A title alone leaves
+  breadcrumb navigation available.
+  `data-shell-page-title` is visually hidden only when the phone top bar
+  contains `data-shell-page-title-replacement`. `PhoneTopBar` marks its detail
+  title automatically; a workspace-name or action-only bar leaves the page
+  heading visible. Custom bars should mark only an actual replacement title.
+  `data-shell-tabs` sticks under the top bar and slides away with it. smrt-ui's `PageHeader` renders the first two.
 - **Page trail**: `shellPageTrailFor({ path, homeHref, homeTitle, navItems,
   parents })` is the one source for a page's ancestors: section homes (home
   and top-level nav pages) have none; other pages get the home, the nav items
@@ -481,6 +504,15 @@ keys the shell renders exactly as before.
 - **Nav attention**: a `ShellNavItem` with `attention: true` (or a string
   label) shows a dot in `TenantNav`, over the icon when collapsed, and
   announces the label ("Needs attention" by default) inside the link.
+- **Nav action**: a `ShellNavItem` with `action: { href, label, icon?,
+  visibility? }` renders a separate icon-only link after the item's link
+  (`aria-label`/tooltip = `label`, default settings-gear icon,
+  `aria-current="page"` on its own page). `visibility: 'active'` omits the link
+  from the DOM unless the item's section is current: for a `ShellNavGroup`
+  item, any item of the group, their children, or any action href is current;
+  for a top-level item, the item, its children, or its action href. A collapsed
+  nav renders no actions (the action page stays reachable by its route).
+  `AppShell` passes `nav`/`navGroups` through unchanged.
 - **Public region ids** (`ADMIN_SHELL_REGION_IDS`): `smrt-admin-shell-header`,
   `smrt-admin-shell-{top,left,right,bottom}-panel`, and
   `smrt-admin-shell-main`, which is the page scroller.
@@ -505,7 +537,7 @@ importable, even if it appears in `dist/`.
 | `@happyvertical/smrt-svelte/forms` | Form inputs (TextInput, Select, MoneyInput, DateTimeInput, Toggle, etc.) |
 | `@happyvertical/smrt-svelte/settings` | Server-paged settings search, selection, and list/detail layout (`SettingsCatalog`, `paginateSettingsCatalog`) |
 | `@happyvertical/smrt-svelte/workspace` | AdminShell, ShellState, tenant nav, focus tools, settings, activities, and system/app panels |
-| `@happyvertical/smrt-svelte/app` | `AppShell` (Provider + themes + AdminShell + nav/dock slots), `OwnerSetupForm` (first-run owner setup), `ShellSettingsPage`, `RuntimeDiagnosticsWebMcp` |
+| `@happyvertical/smrt-svelte/app` | `AppShell` (Provider + themes + AdminShell + nav/dock slots, `dockToggles` header buttons), `OwnerSetupForm` (first-run owner setup), `ShellSettingsPage`, `RuntimeDiagnosticsWebMcp` |
 | `@happyvertical/smrt-svelte/app/runtime-diagnostics` | Svelte-free diagnostics WebMCP registration and its tool name/endpoint constants, importable from server routes |
 | `@happyvertical/smrt-svelte/workspace/legacy` | Opt-in ToolsDock compatibility surface for applications migrating to AdminShell |
 | `@happyvertical/smrt-svelte/workspace/server` | Server-side workspace helpers (Node only) |
@@ -555,7 +587,7 @@ clears it.
 
 ### Components by Category
 
-**Forms**: `AddressInput`, `CheckboxInput`, `DateRangeInput`, `DateTimeInput`, `FileUpload`, `Form`, `FormGroup`, `FormMicButton`, `Input`, `MeasurementInput`, `MoneyInput`, `NumberInput`, `PhoneInput`, `SearchInput`, `Select`, `SelectInput`, `Textarea`, `TextareaInput`, `TextInput`, `Toggle`
+**Forms**: `AddressInput`, `CheckboxInput`, `DateRangeInput`, `DateTimeInput`, `FileUpload`, `Form`, `FormGroup`, `FormMicButton`, `Input`, `MeasurementInput`, `MoneyInput`, `NumberInput`, `PhoneInput`, `RelationInput`, `SearchInput`, `Select`, `SelectInput`, `Textarea`, `TextareaInput`, `TextInput`, `Toggle`
 
 **Layout**: `Container`, `EmptyState`, `Footer`, `Grid`, `Header`, `Masthead`, `PageHeader`, `SummaryCard`
 

package/agents/components.md

@@ -15,10 +15,11 @@ the top-of-stack, domain-aware pieces:
 | Category | Components |
 |----------|------------|
 | AI | `Provider`, `AILoadingOverlay`, `CapabilityGate`, `DownloadProgress`, `STTTest`, `VoiceInput` |
-| Forms (`/forms`) | `TextInput`, `Select`, `MoneyInput`, `DateTimeInput`, `Toggle`, `FileUpload`, `AddressInput`, + more (AI-wired inputs use the hooks/browser-ai here) |
+| Forms (`/forms`) | `TextInput`, `Select`, `MoneyInput`, `DateTimeInput`, `Toggle`, `FileUpload`, `AddressInput`, `RelationInput`, + more (AI-wired inputs use the hooks/browser-ai here) |
 | Module | `ModulePanel` |
 | Settings (`/settings`) | `SettingsCatalog`, `paginateSettingsCatalog` |
 | Audit (root export) | `RecordHistory`, `AuditList` — authorized data props; [contract](../../../docs/content/audit-trail.md) |
+| Board (`/board`) / Sortable (`/sortable`) | `Board` (kanban) and `Sortable` (nested lists) share one headless drag engine, `SortableController` — [details](workspace.md#sortable-and-the-board-engine) |
 | Workspace (`/workspace`) | `AdminShell`, `ShellState`, `TenantNav`, focus tools, settings, activities, and system/app panels |
 | Legacy workspace (`/workspace/legacy`) | First-generation `ToolsDock` compatibility surface during AdminShell migration |
 
@@ -49,6 +50,48 @@ migrate domain re-rolls *onto* them rather than build new primitives:
   flow.
 - **`Card`** (`./ui`) — the standard surface/container; retire local card CSS.
 
+### `RelationInput` (`./forms`, #3600)
+
+Searchable single-select for relation (foreign-key) fields, a thin wrapper over
+the smrt-ui `Combobox`. It is presentation only: the caller supplies the data,
+so the same lookup an assistant uses to turn "Acme" into a record id backs the
+picker. Option shape is `RelationOption` — `{ id, label, detail? }`.
+
+- **Props.** `name`, `label`, `value` (bindable id, `''` = none), `required`,
+  `disabled`, `error`, `placeholder`, `description`, `search(query)`, optional
+  `resolve(id)` and `onCreate(query)`, plus `debounceMs` (250), `interaction`,
+  `onchange` and overridable text (`createLabel`, `clearLabel`, `loadingText`,
+  `emptyText`, `errorText`, `resultsText`).
+- **`search`** runs with `''` when the list opens and then debounced per
+  keystroke; a response for a superseded query is dropped. A rejected search
+  shows `errorText` and the next keystroke retries.
+- **`resolve`** supplies the label of a `value` that has not been searched yet
+  (initial value, parent rebind, form reset). Without it such a value shows an
+  empty field, never the raw id. A `null` result also leaves the field empty.
+- **`onCreate`** adds a "New ..." button; it receives the text most recently
+  searched for and may return the created `RelationOption`, which is selected.
+- **Form integration** is through `Combobox`'s control registration (rich `Form`
+  provides the registry), not a `FieldDefinition`: agents see a `combobox`
+  control whose value is the id. The form posts the id under `name`.
+- **Known limit.** An agent staging a value through the registered control can
+  only choose among the options last listed (the registry matches against
+  `options`; `allowCustom` is off), so it cannot write an id it has not
+  searched. It fails closed. Writing a resolved id needs an async hook on
+  `Combobox` and is tracked separately.
+- **Stale options.** Typing clears the listed options until the new search
+  answers, so Enter or a click can never pick a record for an older query.
+- **Clear button** shows only when not `required`, not `disabled`, and a value
+  is set; it returns focus to the field.
+- **Accessibility** is the combobox pattern (`role=combobox`, `aria-expanded`,
+  `aria-activedescendant`, listbox/option, Arrow/Enter/Escape) plus a polite
+  `role=status` live region announcing searching / "N results" / no matches,
+  `aria-busy` while fetching, and `aria-invalid` + `aria-describedby` for
+  `error` and `description`.
+- Options render `detail` under the label, so the option's accessible name
+  includes it. The `Combobox` additions that make this possible (`filter`,
+  `onquery`, `status`, `busy`, `invalid`, `describedby`, `optionContent`) are
+  generic and default to the previous behaviour.
+
 ### Import convention (S10 #1415)
 
 Domain packages **consume** these primitives; they do not re-roll them. The

package/agents/workspace.md

@@ -172,6 +172,64 @@ enforce permissions.
 
 `ActivityTicker` accepts optional `statuses` restricted to queued/running; running-only remains the default. Opting into queued work adds an explicit localized Queued label without progress. Terminal outcomes belong in expanded `ActivityList`, with retention controlled by the app-owned data source.
 
+## Shell layout customization
+
+Users can show/hide the edge panels and reorder, hide, and move navigation
+sections and items. Source: `workspace/admin-shell/layout.ts` (pure model),
+`layout-controller.svelte.ts` (the API), `ShellLayoutEditor.svelte` (the
+control panel), wired by `app/AppShell.svelte`.
+
+- **`ShellLayout`** is a versioned (`version: 1`), JSON-serializable sparse
+  delta: `sectionOrder`, `itemOrder` (per section), `hidden` (section and item
+  ids), `moved` (item id to section id), `panels` (per edge `visible` /
+  `initial`). It is what a host stores or exports (smrt-planner bundles it in
+  its app blueprint). `normalizeShellLayout(unknown)` reads untrusted JSON and
+  never throws (unknown version yields an empty layout).
+- **Ids.** Sections: `ShellNavGroup.id ?? heading`; items: `ShellNavItem.id ??
+  href`; one shared namespace (duplicates get `#2`, `#3`). Set explicit ids
+  when headings are translated or hrefs change. The flat `nav` items are the
+  implicit first section, `@root` (`SHELL_NAV_ROOT_SECTION_ID`): items can be
+  moved in and out, the section itself cannot move or hide.
+- **`applyShellLayout(nav, groups, panels, layout)`** is pure and total. Ids the
+  host no longer has are ignored; new host items and sections keep their
+  default slots (listed ids permute among the slots they occupy). A hidden
+  section hides its items; a section the layout empties is dropped from
+  `groups`; an empty layout returns the inputs unchanged. A layout can hide a
+  panel but cannot bring back one the host removed (`false` / `initial:
+  'hidden'`). Published from the browser-safe `./workspace/layout` subpath (no
+  Svelte) as well as `./workspace`.
+- **Persistence is host-owned.** `AppShell` takes `layout` and `onlayoutchange`:
+  with `layout` the host is the single source of truth (pass `null` for none);
+  with only `onlayoutchange` the shell keeps the value in memory and reports
+  edits; with neither, the layout lives in the settings-core user tier
+  (`ShellSettingsDelta.layout`, via `storageKey`). `AppShell` now creates the
+  `ShellState` itself and passes it to `AdminShell`, so panel overrides reach
+  it (`ShellState.setLayoutPanels`); a layout-hidden edge ignores toggles,
+  hotkeys, viewport defaults, and the restore opener.
+- **Layout API** (`useShellLayout()` / `tryUseShellLayout()` under an
+  `AppShell`, also `ShellLayoutController`): `moveSection(id, toIndex)`,
+  `moveItem(id, sectionId, toIndex?)`, `hide(id)`, `show(id)`, `setPanel(edge,
+  { visible?, initial? })`, `reset()`, each returning whether anything changed,
+  plus readers (`layout`, `sections`, `panels`, `applied`, `customized`,
+  `isHidden`). An assistant calls the same methods the editor does. The
+  context is separate from `useAdminShell()` because `AppShell`, not
+  `AdminShell`, owns the navigation.
+- **`ShellLayoutEditor`**: `controller` (default: context), `preview` (default
+  true), `iconComponent`. Mount it on a settings page or in a dock tool.
+
+### Sortable and the Board engine
+
+`components/sortable/controller.svelte.ts` is the headless engine extracted from
+`Board`: keyboard pick-up (Space/Enter, arrows, Escape), pointer and native-drag
+moves with a 6px threshold, one in-flight move at a time (a rejected `commit`
+restores and announces), focus return, and announcements as typed events the
+host localizes. `Board` (own markup and `ui.board.*` strings) and `Sortable`
+(`ui.sortable.*`) both use it. `Sortable` renders stacked containers of items
+with a move handle per item, optional `reorderContainers` (a second engine; `fixed`
+containers lead and stay put), a drop marker, and cancel-on-blur; it is
+controlled and never mutates `items`. Item moves report `target.index` after
+removing the item from `source`.
+
 ## App shell and owner setup (`./app`)
 
 `@happyvertical/smrt-svelte/app` (`src/components/app/`) is browser-only. It
@@ -182,13 +240,30 @@ lives beside, not inside, `./workspace` so the AdminShell barrel stays free of
   unchanged), `ThemeProvider`, the theme CSS (`themes/styles/{all,fonts}.css`
   are imported by the component — forgetting them leaves `--smrt-*` unresolved),
   `AdminShell`, `TenantNav` from the consumer's `nav`/`navGroups`/`currentHref`,
-  and an `AppScopePanel`. Panels start collapsed as in `AdminShell`; pass
+  and an `AppScopePanel`. `ShellNavItem.action` (trailing icon link, optional `visibility: 'active'` = only while the item's section is current; omitted when collapsed) is rendered by `TenantNav` and passed through `AppShell` unchanged. Panels start collapsed as in `AdminShell`; pass
   `config` to change that. `dock` is a snippet rendered inside the shell: a host
   places its assistant there in a `ShellDockTool`, so this package never
   imports `smrt-chat`. It receives the Provider's `DataSurfaceRegistry`
   (`{#snippet dock(registry)}`), the instance mounted routes register on
   when `webmcp` UI is on; pass it to `<AssistantDock {registry} />`. `runtimeDiagnostics` (default false) mounts the
-  read-only `smrt.runtime.diagnostics.read` WebMCP tool. Server code that
+  read-only `smrt.runtime.diagnostics.read` WebMCP tool. `dockToggles`
+  (`{ tool, label, icon? }[]`) renders icon buttons at the right of the shell
+  header (the AdminShell `header` row, shown only when the prop is non-empty),
+  each toggling the `ShellDockTool` with that id: `aria-pressed` and
+  `aria-expanded` follow the dock, `aria-controls` is
+  `smrt-admin-shell-right-panel`, the label is the tooltip, and `assistant`
+  defaults to a chat-bubble icon (`icon: 'chat'`; other text is a glyph). A
+  toggle whose tool is not registered yet, or whose dock is not `available`
+  (the right edge removed by the host or hidden by the user's layout), is
+  `aria-disabled` and `open`/`toggle` return false. Hosts, routes and
+  assistants drive the same dock with `useShellDock()` from `./workspace`
+  (`{ active, tools, available, has, isOpen, open, close, toggle }`, throws outside a
+  shell). Opening moves focus into the dock (first focusable, else the panel);
+  closing by Escape, toggle or code returns it to the opener when focus was left
+  in the dock. `open(tool, { focus: false })` skips the focus move. The
+  dock-control state lives on `ShellState` (`openDockTool`, `toggleDockTool`,
+  `closeFocusTool`, `openFocusToolId`). Playground:
+  `playground/src/routes/app-shell-dock-toggles`. Server code that
   lists that tool (the diagnostics route's `toolNames`) imports
   `RUNTIME_DIAGNOSTICS_WEBMCP_TOOL_NAME` from `./app/runtime-diagnostics`,
   which is plain TypeScript; the `./app` barrel loads Svelte components and

package/dist/components/app/AppShell.svelte

@@ -5,23 +5,37 @@ import {
   ThemeProvider,
 } from '@happyvertical/smrt-ui/themes';
 import '@happyvertical/smrt-ui/themes/styles/all.css';
+import '@happyvertical/smrt-ui/themes/styles/base.css';
 import '@happyvertical/smrt-ui/themes/styles/fonts.css';
 import type { DataSurfaceRegistry } from '@happyvertical/smrt-ui/data';
 import { useI18n } from '@happyvertical/smrt-ui/i18n';
-import type { Snippet } from 'svelte';
+import { type Snippet, untrack } from 'svelte';
 import { M } from '../../i18n/strings.workspace.js';
 import Provider from '../../Provider.svelte';
 import type { User } from '../../state/app-state.js';
 import type { WebMcpProviderConfig } from '../../web/webmcp-provider.js';
 import AdminShell from '../workspace/admin-shell/AdminShell.svelte';
 import AppScopePanel from '../workspace/admin-shell/AppScopePanel.svelte';
+import {
+  applyShellLayout,
+  normalizeShellLayout,
+  type ShellLayout,
+} from '../workspace/admin-shell/layout.js';
+import { setShellLayout } from '../workspace/admin-shell/layout-context.js';
+import { ShellLayoutController } from '../workspace/admin-shell/layout-controller.svelte.js';
+import { resolveShellConfig } from '../workspace/admin-shell/settings.js';
+import { createShellState } from '../workspace/admin-shell/state.svelte.js';
 import TenantNav from '../workspace/admin-shell/TenantNav.svelte';
-import type {
-  ShellNavGroup,
-  ShellNavItem,
-  ShellPanelDefaults,
+import {
+  PANEL_EDGES,
+  type PanelEdge,
+  type ShellNavGroup,
+  type ShellNavItem,
+  type ShellPanelDefaults,
 } from '../workspace/admin-shell/types.js';
 import DockSlot from './DockSlot.svelte';
+import DockToggles from './DockToggles.svelte';
+import type { DockToggle } from './dock-toggle.js';
 import RuntimeDiagnosticsWebMcp from './RuntimeDiagnosticsWebMcp.svelte';
 
 interface Props {
@@ -53,6 +67,17 @@ interface Props {
   runtimeDiagnostics?: boolean;
   /** Initial panel states and presentation; forwarded to AdminShell. */
   config?: ShellPanelDefaults;
+  /**
+   * The user's layout customization (panel visibility, navigation order and
+   * visibility), applied over `nav`, `navGroups` and `config`. Passing it
+   * makes the host the owner: the shell never stores it, and reports edits
+   * through `onlayoutchange` for the host to pass back. Pass `null` for "no
+   * customization yet". Omit both `layout` and `onlayoutchange` to let the
+   * shell keep the layout in the user's settings (`storageKey`).
+   */
+  layout?: ShellLayout | null;
+  /** Called with the next layout whenever the user (or an assistant) edits it. */
+  onlayoutchange?: (layout: ShellLayout) => void;
   /** Theme preset applied by the ThemeProvider. */
   preset?: ThemePreset;
   /** Light, dark or system color scheme; the user's persisted choice wins. */
@@ -68,6 +93,15 @@ interface Props {
    * register on it when the `webmcp` UI is enabled (`webmcp: true`).
    */
   dock?: Snippet<[DataSurfaceRegistry]>;
+  /**
+   * Icon buttons rendered at the right of the shell header, each toggling
+   * the `ShellDockTool` with the same id open and closed. `aria-pressed` and
+   * `aria-expanded` follow the dock, focus moves into the dock when it
+   * opens and back to the button when it closes (Escape included). The
+   * `assistant` tool defaults to a chat-bubble icon. Hosts and assistants can
+   * drive the same dock from code with `useShellDock()`.
+   */
+  dockToggles?: DockToggle[];
   children: Snippet;
 }
 
@@ -86,20 +120,99 @@ let {
   permissions = [],
   runtimeDiagnostics = false,
   config,
+  layout,
+  onlayoutchange,
   preset = 'smrt',
   colorScheme = 'system',
   appPanelDocs,
   dock,
+  dockToggles = [],
   children,
 }: Props = $props();
 const { t } = useI18n();
-const hasNav = $derived(nav.length > 0 || navGroups.length > 0);
+
+// The shell state lives here (not inside AdminShell) so the layout can reach
+// it: panel overrides apply to it, and the user's layout is stored in it when
+// the host does not own persistence.
+const shell = untrack(() =>
+  createShellState({
+    config,
+    storageKey,
+    layoutPanels: normalizeShellLayout(layout).panels,
+  }),
+);
+// Hosts that pass only `onlayoutchange` own persistence but not the value:
+// keep it in memory so edits show at once.
+let localLayout = $state<ShellLayout | undefined>();
+const controlled = $derived(layout !== undefined);
+const effectiveLayout = $derived(
+  normalizeShellLayout(
+    controlled ? layout : onlayoutchange ? localLayout : shell.settings.layout,
+  ),
+);
+const applied = $derived(
+  applyShellLayout(nav, navGroups, config, effectiveLayout),
+);
+const hasNav = $derived(applied.nav.length > 0 || applied.groups.length > 0);
+
+// Starting-state edits made through the layout API, applied once the layout
+// carrying them is in force (or dropped if the host answered differently).
+const pendingStart = new Map<PanelEdge, 'collapsed' | 'expanded'>();
+$effect(() => {
+  const panels = effectiveLayout.panels ?? {};
+  shell.setLayoutPanels(panels);
+  for (const [edge, state] of pendingStart) {
+    const initial =
+      panels[edge]?.initial ?? resolveShellConfig(config).panels[edge].initial;
+    if (initial === state) shell.setPanelStart(edge, state);
+  }
+  pendingStart.clear();
+});
+
+setShellLayout(
+  new ShellLayoutController({
+    nav: () => nav,
+    groups: () => navGroups,
+    panels: () => config,
+    layout: () => effectiveLayout,
+    commit(next) {
+      // A changed starting state is an explicit edit: show it now. It waits
+      // for the layout to actually change (the host may reject the edit) and
+      // is never done for a loaded layout (hydration, a late `layout` prop),
+      // so loading cannot erase the user's own open/closed toggle.
+      for (const edge of PANEL_EDGES) {
+        const before = effectiveLayout.panels?.[edge]?.initial;
+        const after = next.panels?.[edge]?.initial;
+        if (before === after) continue;
+        const state = after ?? resolveShellConfig(config).panels[edge].initial;
+        if (state === 'collapsed' || state === 'expanded') {
+          pendingStart.set(edge, state);
+        }
+      }
+      if (!controlled) {
+        if (onlayoutchange) localLayout = next;
+        else shell.setLayout(next);
+      }
+      onlayoutchange?.(next);
+    },
+  }),
+);
 </script>
 
+{#snippet dockHeader()}
+  <DockToggles toggles={dockToggles} />
+{/snippet}
+
 <Provider {webmcp} {user} {permissions}>
   <RuntimeDiagnosticsWebMcp enabled={runtimeDiagnostics} />
   <ThemeProvider {preset} {colorScheme} persist={true}>
-    <AdminShell {title} {subtitle} {storageKey} {config} path={currentHref}>
+    <AdminShell
+      {title}
+      {subtitle}
+      state={shell}
+      path={currentHref}
+      header={dockToggles.length > 0 ? dockHeader : undefined}
+    >
       {#snippet appPanel()}
         <AppScopePanel
           appName={title}
@@ -119,8 +232,8 @@ const hasNav = $derived(nav.length > 0 || navGroups.length > 0);
       {#snippet tenantPanel()}
         {#if hasNav}
           <TenantNav
-            items={nav}
-            groups={navGroups}
+            items={applied.nav}
+            groups={applied.groups}
             {currentHref}
             aria-label={t(M['ui.app_shell.navigation'])}
           />
@@ -136,21 +249,6 @@ const hasNav = $derived(nav.length > 0 || navGroups.length > 0);
 </Provider>
 
 <style>
-  :global(*),
-  :global(*::before),
-  :global(*::after) {
-    box-sizing: border-box;
-  }
-  :global(html),
-  :global(body) {
-    min-height: 100%;
-    margin: 0;
-  }
-  :global(body) {
-    background: var(--smrt-color-background);
-    color: var(--smrt-color-on-background);
-    font-family: var(--smrt-font-family, Inter, system-ui, sans-serif);
-  }
   a {
     color: var(--smrt-color-primary);
   }

package/dist/components/app/AppShell.svelte.d.ts

@@ -1,11 +1,14 @@
 import { type ColorScheme, type ThemePreset } from '@happyvertical/smrt-ui/themes';
 import '@happyvertical/smrt-ui/themes/styles/all.css';
+import '@happyvertical/smrt-ui/themes/styles/base.css';
 import '@happyvertical/smrt-ui/themes/styles/fonts.css';
 import type { DataSurfaceRegistry } from '@happyvertical/smrt-ui/data';
-import type { Snippet } from 'svelte';
+import { type Snippet } from 'svelte';
 import type { User } from '../../state/app-state.js';
 import type { WebMcpProviderConfig } from '../../web/webmcp-provider.js';
-import type { ShellNavGroup, ShellNavItem, ShellPanelDefaults } from '../workspace/admin-shell/types.js';
+import { type ShellLayout } from '../workspace/admin-shell/layout.js';
+import { type ShellNavGroup, type ShellNavItem, type ShellPanelDefaults } from '../workspace/admin-shell/types.js';
+import type { DockToggle } from './dock-toggle.js';
 interface Props {
     /** Application name shown in the shell brand and app panel. */
     title?: string;
@@ -35,6 +38,17 @@ interface Props {
     runtimeDiagnostics?: boolean;
     /** Initial panel states and presentation; forwarded to AdminShell. */
     config?: ShellPanelDefaults;
+    /**
+     * The user's layout customization (panel visibility, navigation order and
+     * visibility), applied over `nav`, `navGroups` and `config`. Passing it
+     * makes the host the owner: the shell never stores it, and reports edits
+     * through `onlayoutchange` for the host to pass back. Pass `null` for "no
+     * customization yet". Omit both `layout` and `onlayoutchange` to let the
+     * shell keep the layout in the user's settings (`storageKey`).
+     */
+    layout?: ShellLayout | null;
+    /** Called with the next layout whenever the user (or an assistant) edits it. */
+    onlayoutchange?: (layout: ShellLayout) => void;
     /** Theme preset applied by the ThemeProvider. */
     preset?: ThemePreset;
     /** Light, dark or system color scheme; the user's persisted choice wins. */
@@ -50,6 +64,15 @@ interface Props {
      * register on it when the `webmcp` UI is enabled (`webmcp: true`).
      */
     dock?: Snippet<[DataSurfaceRegistry]>;
+    /**
+     * Icon buttons rendered at the right of the shell header, each toggling
+     * the `ShellDockTool` with the same id open and closed. `aria-pressed` and
+     * `aria-expanded` follow the dock, focus moves into the dock when it
+     * opens and back to the button when it closes (Escape included). The
+     * `assistant` tool defaults to a chat-bubble icon. Hosts and assistants can
+     * drive the same dock from code with `useShellDock()`.
+     */
+    dockToggles?: DockToggle[];
     children: Snippet;
 }
 declare const AppShell: import("svelte").Component<Props, {}, "">;

package/dist/components/app/AppShell.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AppShell.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/app/AppShell.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,WAAW,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,8CAA8C,CAAC;AACtD,OAAO,gDAAgD,CAAC;AACxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAGtC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAIzE,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,kBAAkB,EACnB,MAAM,mCAAmC,CAAC;AAK3C,UAAU,KAAK;IACb,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,GAAG,CAAC,EAAE,YAAY,EAAE,CAAC;IACrB,uEAAuE;IACvE,SAAS,CAAC,EAAE,aAAa,EAAE,CAAC;IAC5B,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC;IACxC,yFAAyF;IACzF,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACnB,+FAA+F;IAC/F,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,sEAAsE;IACtE,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,iDAAiD;IACjD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,4DAA4D;IAC5D,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC;IACtC,QAAQ,EAAE,OAAO,CAAC;CACnB;AA8ED,QAAA,MAAM,QAAQ,2CAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"AppShell.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/app/AppShell.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,WAAW,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,8CAA8C,CAAC;AACtD,OAAO,+CAA+C,CAAC;AACvD,OAAO,gDAAgD,CAAC;AACxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,OAAO,EAAE,KAAK,OAAO,EAAW,MAAM,QAAQ,CAAC;AAG/C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAGzE,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,oCAAoC,CAAC;AAM5C,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACxB,MAAM,mCAAmC,CAAC;AAG3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInD,UAAU,KAAK;IACb,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,GAAG,CAAC,EAAE,YAAY,EAAE,CAAC;IACrB,uEAAuE;IACvE,SAAS,CAAC,EAAE,aAAa,EAAE,CAAC;IAC5B,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC;IACxC,yFAAyF;IACzF,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACnB,+FAA+F;IAC/F,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,sEAAsE;IACtE,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,gFAAgF;IAChF,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;IAC/C,iDAAiD;IACjD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,4DAA4D;IAC5D,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC;IACtC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,QAAQ,EAAE,OAAO,CAAC;CACnB;AA+JD,QAAA,MAAM,QAAQ,2CAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}

package/dist/components/app/DockToggles.svelte

@@ -0,0 +1,103 @@
+<script lang="ts">
+import { useShellDock } from '../workspace/admin-shell/dock.js';
+import type { DockToggle } from './dock-toggle.js';
+
+interface Props {
+  toggles: DockToggle[];
+}
+
+let { toggles }: Props = $props();
+const dock = useShellDock();
+
+function iconFor(toggle: DockToggle): string | undefined {
+  return toggle.icon ?? (toggle.tool === 'assistant' ? 'chat' : undefined);
+}
+
+function press(event: MouseEvent, toggle: DockToggle): void {
+  if (!dock.has(toggle.tool) || !dock.available) return;
+  dock.toggle(toggle.tool, {
+    returnFocus: event.currentTarget as HTMLElement,
+  });
+}
+</script>
+
+<div class="smrt-dock-toggles" data-testid="dock-toggles">
+  {#each toggles as toggle (toggle.tool)}
+    {@const registered = dock.has(toggle.tool) && dock.available}
+    {@const open = dock.isOpen(toggle.tool)}
+    {@const icon = iconFor(toggle)}
+    <!-- raw-primitive-allow: shell chrome toggle, not a content button -->
+    <button
+      type="button"
+      class="smrt-dock-toggles__button"
+      class:active={open}
+      data-dock-tool={toggle.tool}
+      aria-label={toggle.label}
+      title={toggle.label}
+      aria-pressed={open}
+      aria-expanded={open}
+      aria-controls="smrt-admin-shell-right-panel"
+      aria-disabled={registered ? undefined : true}
+      onclick={(event) => press(event, toggle)}
+    >
+      {#if icon === 'chat'}
+        <svg
+          viewBox="0 0 24 24"
+          width="20"
+          height="20"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          aria-hidden="true"
+        >
+          <path d="M21 11.5a8.5 8.5 0 0 1-12.4 7.5L3 20.5l1.6-5A8.5 8.5 0 1 1 21 11.5z" />
+        </svg>
+      {:else}
+        <span aria-hidden="true">{icon ?? toggle.label.charAt(0)}</span>
+      {/if}
+    </button>
+  {/each}
+</div>
+
+<style>
+  .smrt-dock-toggles {
+    display: flex;
+    align-items: center;
+    gap: var(--smrt-spacing-1);
+    margin-inline-start: auto;
+  }
+
+  .smrt-dock-toggles__button {
+    display: inline-grid;
+    place-items: center;
+    inline-size: 2.25rem;
+    block-size: 2.25rem;
+    padding: 0;
+    border: 1px solid transparent;
+    border-radius: var(--smrt-radius-md, 0.5rem);
+    background: transparent;
+    color: var(--smrt-color-on-surface);
+    cursor: pointer;
+  }
+
+  .smrt-dock-toggles__button:hover {
+    background: var(--smrt-color-surface-container-high);
+  }
+
+  .smrt-dock-toggles__button:focus-visible {
+    outline: 2px solid var(--smrt-color-primary);
+    outline-offset: 2px;
+  }
+
+  .smrt-dock-toggles__button.active {
+    background: var(--smrt-color-primary-container, var(--smrt-color-surface-container-high));
+    color: var(--smrt-color-on-primary-container, var(--smrt-color-primary));
+  }
+
+  .smrt-dock-toggles__button[aria-disabled='true'] {
+    opacity: 0.5;
+    cursor: default;
+  }
+</style>

package/dist/components/app/DockToggles.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { DockToggle } from './dock-toggle.js';
+interface Props {
+    toggles: DockToggle[];
+}
+declare const DockToggles: import("svelte").Component<Props, {}, "">;
+type DockToggles = ReturnType<typeof DockToggles>;
+export default DockToggles;
+//# sourceMappingURL=DockToggles.svelte.d.ts.map

package/dist/components/app/DockToggles.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DockToggles.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/app/DockToggles.svelte.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,UAAU,KAAK;IACb,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AA2CD,QAAA,MAAM,WAAW,2CAAwC,CAAC;AAC1D,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAClD,eAAe,WAAW,CAAC"}

package/dist/components/app/dock-toggle.d.ts

@@ -0,0 +1,14 @@
+/** A header button that toggles one dock tool. */
+export interface DockToggle {
+    /** Id of the `ShellDockTool` to toggle. */
+    tool: string;
+    /** Accessible name and tooltip. */
+    label: string;
+    /**
+     * Icon name. `chat` (the default for the `assistant` tool) draws a
+     * chat bubble; any other text is shown as a glyph. Without an icon the
+     * label's first letter stands in.
+     */
+    icon?: string;
+}
+//# sourceMappingURL=dock-toggle.d.ts.map

package/dist/components/app/dock-toggle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dock-toggle.d.ts","sourceRoot":"","sources":["../../../src/components/app/dock-toggle.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,MAAM,WAAW,UAAU;IACzB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}

package/dist/components/app/dock-toggle.js

@@ -0,0 +1 @@
+export {};