@happyvertical/smrt-svelte 0.55.6 → 0.55.8

package/agents/overview-surfaces.md

@@ -0,0 +1,255 @@
+# smrt-svelte/overview
+
+Module semantics for `src/components/overview/` (`./overview` and
+`./overview/server`, #3727). Package orientation and cross-module invariants are
+in [../AGENTS.md](../AGENTS.md); the shell edit mode it joins is in
+[workspace.md](workspace.md#editing-the-layout-in-place).
+
+An overview is a **customizable surface**: a flow grid of registered widgets,
+each with an options object. A page declares which widget types it allows and
+its default arrangement; admins (or users, per role) add, reorder, resize,
+configure and remove widgets inside that confined set, and reset returns to the
+default. Phase 1 (this module) is the surface, the registry, the data model, the
+server load contract and five core widgets; phase 2 adds package widgets from
+recipes ("Recipe widgets"). Persistence and assistant operations are later
+phases (see "Extension points").
+
+## Two entries
+
+| Entry | Contents |
+|---|---|
+| `./overview/server` (`server.ts`) | Svelte-free: types, `validateWidgetOptions`, the model (`resolveOverview`, `checkOverviewOverride`, `applyOverviewOverride`, `diffOverview`, `sanitizeOverview`, ...), `WidgetRegistry` / `registerWidget`, `loadOverview`. Safe in a `+page.server.ts` or a save endpoint. |
+| `./overview` (`index.ts`) | Everything above plus `OverviewGrid`, `createOverview` (controller), `WidgetOptionsForm`, the core widgets and `registerCoreWidgets`, `shortcutsFromNav`, `formatWidgetValue`, `parseMarkdown` / `safeHref`. |
+
+## Data model (`types.ts`, `model.ts`)
+
+A saved overview is data, never code:
+`{ widgets: [{ id, type, span, options, version? }] }`. `span` is 1 to 4 (a widget
+type may narrow its own range); `options` is a flat object of JSON primitives;
+`version` is the widget's option-schema version the options were written
+against (absent means 1).
+
+- **`OverviewDefinition`** (what a page declares): `id` (dotted ids allowed,
+  `events.home`), `defaults`, `allowed` (widget types; omit for every registered
+  type), `models` (confines `model` options, including a substituted default: a
+  default outside the list fails validation, so its loader never runs),
+  `maxWidgets` (default 24).
+  `defineOverview` validates ids.
+- **`OverviewOverride`** is the sparse, versioned (`version: 1`) delta a host
+  stores: `order`, `removed`, `added`, `changed[id] = { span?, options?, version? }`.
+  `applyOverviewOverride(base, override)` is total: ids the base no longer has
+  are ignored, an added widget colliding with a base id is skipped, and widgets
+  the order does not list keep their slots (a default shipped later still
+  appears). `diffOverview(base, next)` is its inverse (round-trip tested), so
+  every client edit is "mutate the document, store the diff"; an edit that
+  returns to the defaults stores `null`.
+- **Ids are stable.** `nextWidgetId` yields `w<n>` and reserves the ids of
+  removed defaults, so a new widget never takes a removed default's id (the
+  override would delete it). It is total for any stored ids: numeric suffixes
+  beyond `Number.MAX_SAFE_INTEGER` are ignored when picking the next number
+  (they would stop incrementing), and an exhausted high end restarts at `w1`.
+- **Tiers.** `resolveOverview` merges one override. A host with tenant defaults
+  and user overrides merges the tenant tier into the definition's `defaults`
+  first (phase 3); the user override then applies to that.
+- **Reset** is `controller.reset()` (store `null`) or `resetWidget(id)`.
+
+## Validation: what keeps a stored overview from running anything
+
+Options are validated against the widget's versioned schema on **save**
+(`checkOverviewOverride`, strict: any issue rejects, and the returned override is
+re-derived from the sanitized result, so persist that) and on **load**
+(`sanitizeOverview`, lenient: the bad widget is dropped and reported as an
+`OverviewIssue`, the rest render). Nothing here calls a widget's `load` for a
+widget that failed validation.
+
+- `schema.ts` field types: `text`, `markdown`, `identifier`, `model`, `integer`,
+  `number`, `boolean`, `enum`. There is **no free-form query, filter expression,
+  URL or SQL field**. "Which data" is a `model` (a bare `Class`, `pkg:Class` or
+  `@scope/pkg:Class`, optionally confined to the page's `models`), an
+  `identifier` (a field or named-filter id, `[A-Za-z_][A-Za-z0-9_.-]{0,63}`) or a
+  closed `enum`. The loader maps those to queries it owns and authorizes.
+- Strict: unknown keys, wrong types, out-of-range numbers, values outside a closed
+  set and missing required fields fail the whole options object. Missing optional
+  fields take their default; `null` counts as missing.
+- `sanitizeOverview` also drops: unknown types, types outside the page's
+  `allowed` set or a widget's `allowedIn`, duplicate ids, widgets over the cap,
+  newer-than-known versions, and older versions without a working `migrate`.
+  Spans are clamped to the widget's range. It is idempotent.
+- `migrate(options, fromVersion)` upgrades stored options to the current version
+  (return `null` to drop). It runs on untrusted input inside a try/catch, and its
+  result is validated like any other options.
+- A widget id removed by the user and a type removed by a release both degrade to
+  "dropped and reported", never an error page.
+
+## Registry (`registry.ts`)
+
+`registerWidget({ type, title, options, component | loadComponent, load, allowedIn,
+version, migrate, defaultSpan, minSpan, maxSpan })` on the shared
+`defaultWidgetRegistry`, or `createWidgetRegistry()` for an isolated one (tests,
+several surfaces). Registration is code, at module scope; registering a type
+twice throws unless `{ replace: true }`. `title`, `description` and option
+`label` / `help` / `choices[].label` are text **or i18n keys** (the UI runs them
+through `t`, which returns an unregistered string unchanged); the core widgets
+use `ui.overview.*` keys from `i18n/strings.overview.ts` (registered in
+`i18n/server.ts`).
+
+`component` renders synchronously. `loadComponent` is the lazy form (dynamic import
+by export ref): resolve it **before** render with `resolveWidgetComponents(types)`
+in a universal load and pass the map to `OverviewGrid components`, so server and
+client render the same tree. A type that cannot resolve renders as unavailable.
+
+## Server load contract (`load.ts`)
+
+```ts
+// +page.server.ts
+const resolved = resolveOverview(definition, await storedOverride(event), registry);
+const overview = await loadOverview(resolved.document, definition, registry, {
+  locale, tenantId, db /* the request's permission-checked capabilities */,
+});
+return { overview };   // LoadedOverview: JSON, serializable
+```
+
+- A widget's `load(options, ctx)` receives **validated options only** and a
+  `WidgetLoadContext` the host built from the request principal: `overviewId`, an
+  abort `signal`, `locale`, and any host capabilities (index keys). It must
+  authorize through `ctx` (the user's permissions and tenant filters), never
+  through option values. Reports-backed chart loaders call the runtime-report
+  compiler with this context; this package does not depend on it.
+- Loads run in parallel with a per-widget timeout (default 8 s; the signal
+  aborts). A thrown error, a timeout or non-serializable / oversized data
+  (default 256 KB of JSON) becomes a per-widget error tile
+  (`error.code`: `load_failed | timeout | invalid_data`); the real error goes only
+  to `onError` for server logs, never to the client. One bad widget never fails
+  the page.
+- `LoadedOverview` is what the page returns and `createOverview({ loaded })` seeds
+  the controller from, so the grid renders every widget at first paint with no
+  client-only fetching and **no hydration mismatch** (the grid has no
+  effect-dependent content; the only `$effect` requests data for widgets the
+  seeded entries do not cover, which never happens on first render).
+  `scripts/overview-ssr.test.mjs` renders the grid through Vite SSR.
+- Formatting is deterministic per locale (`Intl` with the i18n store's locale), and
+  no widget formats dates or reads the clock; loaders send preformatted meta.
+
+## Controller (`controller.svelte.ts`)
+
+`createOverview({ definition, registry?, override?, onchange?, canCustomize?,
+loaded?, loadWidget? })`, the `ShellLayout` pattern: **persistence is host-owned**.
+With an `override` getter the host is the source of truth and feeds each edit back
+(`onchange(override | null)`); without it the value is kept in memory. Reactive
+reads: `document`, `base`, `override`, `issues`, `customized`, `canCustomize`,
+`addable`, `full`, `entry(widget)`. Operations, each returning
+`{ ok: true, id } | { ok: false, reason, issues? }` and refused with
+`not_allowed` when `canCustomize()` is false (the role gate; the server must check
+the same on save): `add(type, options?)`, `remove`, `move(id, toIndex)` (index
+after removal), `resize(id, span)`, `setOptions`, `resetWidget`, `reset`,
+`restore(override)` (the Undo hook), `reload(id)`.
+
+`loadWidget(widget, signal)` is how a client edit gets data for an added or
+reconfigured widget: the host runs the widget's `load` where its data lives (a
+remote function in production, the in-browser source in smrt-planner). The
+controller drops results for stale option keys and aborts superseded loads.
+Call `destroy()` when the owner unmounts.
+
+## Grid and edit mode (`OverviewGrid.svelte`)
+
+Props in `grid-types.ts`. `editing` defaults to the shell's layout editor
+(`tryUseShellLayout()?.editing`), so the same pencil edits the grid under an
+`AppShell` with `layoutEditing`; pass `editing` to drive it without a shell. It is
+off whenever `controller.canCustomize` is false.
+
+- **Flow grid.** CSS grid of 4 columns, 2 below 40rem and 1 below 22rem of the
+  grid's own width (container queries); `data-span` / `--span` carry the span. Gaps
+  are tile padding, not grid gap, so a drag never crosses a dead zone.
+- **Reorder** uses the headless `createSortable` engine in its `flow` mode (a
+  single wrapping list): the handle is the existing grip (Space picks up, any
+  arrow steps along reading order, mirrored in RTL, Enter drops, Escape cancels;
+  pointer and native drag use the horizontal midpoint for tiles sharing a row).
+- **Resize** is an end-edge `role="slider"` (arrows, Home, End; pointer drag snaps
+  to a column boundary via the pure `spanFromPointer`, committed on release).
+- **Chrome** is icon-only `ShellIconButton`s (configure, remove) plus the toolbar
+  (add, reset). Widgets render as on the site inside an `inert` wrapper. Add and
+  configure open `Modal`s; `WidgetOptionsForm` is generated from the option field
+  descriptors with smrt-ui `Form` / `FormGroup` / `Input` / `Select` / `Textarea` /
+  `Checkbox` (the descriptors mirror the generated screens' field shape) and shows
+  each schema issue beside its field. A widget with a required option and no
+  default opens the form before it is added.
+- A polite live region announces moves, resizes, adds, removals and resets.
+  `OverviewGrid.test.ts` runs axe in view and edit mode.
+
+## Core widgets (`widgets/`)
+
+`registerCoreWidgets(registry, loaders)` registers `note` always and each
+data-backed widget only when its loader is given (structural injection: this
+package depends on no data package). Widgets render only when the grid has
+`ready` data (it draws loading and error tiles) and treat `data` as untrusted
+shape. Data shapes are in `widgets/data.ts`.
+
+| Type | Options | Data |
+|---|---|---|
+| `metric` | `title`, `model`*, `measure`, `field`, `filter` | `{ value, format?, currency?, label?, change?, href? }` (money = integer minor units) |
+| `chart` | `title`, `model`*, `groupBy`, `measure`, `field`, `period`, `style` (bar/line), `filter` | `{ points: [{ label, value }], format?, currency?, href? }`, one measure of a runtime report |
+| `records` | `title`, `model`*, `sort`, `direction`, `limit`, `filter` | `{ rows: [{ id, title, subtitle?, meta?, href? }], total?, href? }`; the loader chooses the title field and the visible records |
+| `shortcuts` | `title`, `section` | `{ items: [{ id, label, href, icon?, description? }] }`; `shortcutsFromNav(sections, sectionId)` maps `resolveShellNavModel` / `useShellLayout().sections` (visible entries, user renames) |
+| `note` | `title`, `body` (Markdown) | none |
+
+`note` renders `parseMarkdown` output as elements (headings, paragraphs, lists,
+quotes, fenced code, bold/italic/code/links). There is no `{@html}`; raw HTML is
+literal text and `safeHref` limits links to http(s), mailto, same-site paths and
+fragments. Record and shortcut hrefs pass `safeHref` too. Charts carry their
+numbers as text (inline for bars, a visually hidden table for the line).
+
+## Recipe widgets (`recipe-widgets.ts`)
+
+A package contributes a widget with a `widget` surface on a recipe
+([core recipes.md](../../core/agents/recipes.md#widget-surfaces-3727) has the
+declaration and its scan-time rules). `registerRecipeWidgets(registry, recipes,
+resolveExport, { replace?, enabled? })` (async, Svelte-free, on both entries)
+turns the manifest's widget surfaces into `registry.register(...)` calls:
+
+| Surface field | Registration |
+|---|---|
+| `type`, `label`, `description`, `icon`, `version` | `type`, `title`, `description`, `icon`, `version` |
+| `options` | `options` (plain JSON; `registry.register` re-validates the schema) |
+| `export` | `loadComponent` (lazy; the export may be a component or a `{ default }` module) |
+| `data.load` | `load` (resolved on first use; a missing or non-function loader is that widget's error tile) |
+| `migrate` | `migrate`, **resolved eagerly** because the registry's `migrate` is synchronous |
+| `allowedIn`, `defaultSpan`, `minSpan`, `maxSpan` | same names |
+| `data.models` | not registered: documentation of what the loader reads; confine with the page's `models` |
+
+- **The module resolver is injected.** `resolveExport(specifier, exportName)` is
+  the host's: a static map of dynamic imports in a bundled app, a stub in tests.
+  Nothing is imported when the manifest is read, and the registration itself
+  imports nothing except `migrate` exports. Relative or absolute specifiers
+  are refused.
+- **Never throws for a bad surface.** The result is `{ registered, skipped,
+  dispose }`; a skip carries `reason` `duplicate_type` (a core widget or another
+  recipe owns the type; `replace` overrides), `invalid` (the registry refused the
+  definition) or `unresolved` (a `migrate` export is missing). One broken package
+  cannot take down the overview.
+- **`enabled(recipeId)`** keeps widgets of recipes that are off out of the add
+  list. Call the helper again (after `dispose()`) when the set changes.
+- Widget types share one registry namespace with the core widgets
+  (`metric`, `chart`, `records`, `shortcuts`, `note`). Pages still confine what
+  can appear with `defineOverview({ allowed })`, and a widget with `allowedIn`
+  only validates inside those overview ids.
+- `src/components/overview/__tests__/recipe-widgets.test.ts` covers lazy
+  resolution, the loader and migrate paths, allowed placements and the skip
+  reasons. The scanner's copy of the option vocabulary and patterns is checked
+  against `types.ts` / `schema.ts` by `packages/scanner/src/__tests__/recipe-widgets.test.ts`,
+  and a type-level assertion here keeps `RecipeWidgetOptionType` equal to
+  `WidgetOptionType`.
+
+## Extension points left for later phases
+
+- **Phase 2, package widgets (#3727, done).** See "Recipe widgets" below.
+- **Phase 3, production persistence.** Implement the `override` getter /
+  `onchange` pair against the `_smrt_` table (tenant tier merged into
+  `definition.defaults`, user tier as the override), validate saves with
+  `checkOverviewOverride` and persist its canonical `override`, run
+  `loadOverview` in the page load, and supply `loadWidget` as a remote function
+  that calls the same `load`. Role gating = `canCustomize` plus the same check in
+  the save endpoint. No migration or table lives in this package.
+- **Phase 4, assistant.** The controller methods are the structured operations;
+  `restore(override)` plus the `override` getter give Undo (snapshot before,
+  restore after). `OverviewOpResult.issues` is the validation feedback to return.
+- **Not built:** the activity widget (Track B, #3710) and agenda.

package/agents/screens.md

@@ -0,0 +1,57 @@
+# smrt-svelte/screens
+
+Module semantics for `src/components/screens/` (`./screens`). Package orientation, the cross-module
+invariants, and the traps that apply before editing anything live in
+[../AGENTS.md](../AGENTS.md) — read that first.
+
+## Manifest-derived record screens (`./screens`, #3718)
+
+`RecipeScreens` is the default screen set for a package that ships models but no
+consumer UI (tags, facts, secrets, profiles, reports, prompts). It composes
+`ListScreen`, `DetailScreen` and `EditForm`, each of which can also be used on
+its own. Every screen takes a generated web `definition`
+(`ScreenCollectionDefinition`, structurally a `SmrtWebCollectionDefinition`) and
+an optional resolved `policy` (`ScreenPolicy`, structurally smrt-fields'
+`ResolvedObjectFieldPolicy`). The module imports neither package: smrt-svelte
+stays below the domain layer, and the app passes both in as props.
+
+- **Field selection is `fields.ts`, pure and node-testable.** `deriveScreenFields`
+  is the single rule for list / view / edit. A field renders only when it is in
+  BOTH the definition and the policy, so sensitive, transient and
+  read-permission-gated fields (which the policy resolver omits) can never appear
+  on a generated screen. Hidden fields are dropped; system fields (`id`,
+  `tenantId`, `createdBy`, `updatedBy`, `createdAt`, `updatedAt`) are never
+  editable, and the two timestamps appear on a view as read-only advanced meta.
+  Do not add a second selection rule in a component.
+- **Without a policy the code seed applies**: `ui.basic` / `ui.group` / `ui.order`
+  hints and the cold-start rule (no `basic` markers => everything basic; any
+  marker => unmarked fields advanced). Order is `order`, then declaration order.
+- **Tiers**: list shows basic scalar columns only (no long text, JSON or raw
+  reference columns; capped at `DEFAULT_MAX_LIST_COLUMNS`, an explicit `columns`
+  list is never capped); view and edit show advanced fields behind a disclosure
+  (the edit one opens itself when an advanced field has a problem). Policy
+  `label`, `help` and `required` win over the manifest; on create, a resolved
+  policy default (an explicit `null` included) beats the manifest default.
+  `locked` governs who may change the POLICY, never the record value, so it is
+  not applied here.
+- **Values are `values.ts`**: money (`ui.widget: 'currency'` on an INTEGER field
+  only) is integer minor units end to end. Editing shows major units but converts
+  with exact string math (`majorStringToMinorUnits`), never `* 100`; integers are
+  rejected unless JavaScript-safe; datetimes go out as ISO strings (an unchanged datetime keeps the
+  loaded record's full precision via `parseDraft`'s `record` context; the control
+  only shows minutes); JSON as parsed values. Empty optional text becomes `null` when the field is nullable and `''`
+  otherwise (unset text persists as `''`); every other empty optional field is
+  `null`. Errors are codes, mapped to messages by the component via `useI18n`.
+- **Transport-neutral.** `RecipeScreens` drives a `RecipeScreensSource`
+  (`list` / `get` / `create` / `update` / `delete`); an operation the source lacks
+  (or `can` turns off) is simply not offered, so a read-only source is a
+  read-only screen set. `view` and `recordId` are bindable and `onnavigate`
+  fires on every user navigation, so an app can mirror them into its router.
+  `EditForm.onsubmit` throws to report a failed save or returns `{ fieldErrors }`.
+  Remount `EditForm` with `{#key}` when switching records (`RecipeScreens` does).
+- **Not the policy-editing surface.** The policy gear, field-usage telemetry and
+  the per-field renderer registry live in `ObjectForm`
+  (`@happyvertical/smrt-fields/svelte`); `EditForm` is the dependency-light
+  default and does not replace it. Not wired into recipe surfaces yet (#3708).
+- Component props live in `types.ts`, not in the `.svelte` files, so the barrel
+  never re-exports types from a component.

package/agents/workspace.md

@@ -83,6 +83,140 @@ and touch input across mobile widths and desktop panel-state combinations.
 
 See `src/components/workspace/MIGRATION.md` for the old-to-new concept map.
 
+### Regions and slots
+
+Four regions map to the existing edges (ids and `ShellLayout.panels` keys are
+unchanged): Header (`top`), Left sidebar (`left`), Right sidebar (`right`),
+Footer (`bottom`). Default labels are those names; override via `config`.
+`AdminShell`/`AppShell` take `slots?: Partial<Record<ShellSlot, Snippet>>`
+(`ShellSlot` from `./workspace`): `header.start|center|end`,
+`footer.start|center|end`, `leftSidebar.header|footer`,
+`rightSidebar.header|footer`. Header/footer slots sit in the bar (start after
+the brand/menu opener, end after the account), sidebar header sits above and
+footer below the sidebar's main area. Defaults: brand/title/menu opener/account
+stay where they were (`header.start`/`header.end` areas), `tenantFooter` stays
+the left sidebar footer, `dockToggles` default to `header.end`. There is no
+separate header row.
+
+Fallback when a slot's region is hidden (or a sidebar is collapsed), first
+visible wins (`slotFallbackChain`): header.X -> leftSidebar.header ->
+rightSidebar.header -> footer.X; footer.X -> leftSidebar.footer ->
+rightSidebar.footer -> header.X; leftSidebar.header -> header.start ->
+rightSidebar.header -> footer.start; leftSidebar.footer -> footer.start ->
+header.start -> rightSidebar.footer; rightSidebar.header -> header.end ->
+leftSidebar.header -> footer.end; rightSidebar.footer -> footer.end ->
+header.end -> leftSidebar.footer. The legacy `tenantFooter` prop keeps its own
+`footerInHeader` fallback.
+
+### Edge toggles and hotkeys are opt-in (#3661)
+
+`AdminShell`/`AppShell` `edgeToggles?: boolean | Partial<Record<PanelEdge,
+boolean>>` defaults to `false`: no edge toggle buttons, no hotkey hints, and
+WASD/`?` are inert. Regions are laid out inline: the left sidebar is docked
+open off phones (`ShellState.setInlineEdges`/`isInline`; viewport defaults and
+`overlayMedia` do not apply), and the header/footer are plain bands without a
+drop-down drawer (so `appPanel`/`systemPanel` are not reachable). Visibility
+comes from `ShellLayout.panels.visible` and edit mode. The right edge is the
+dock: dock toggles and focus tools still open it, it just loses its button.
+`hotkeys` (default: follows the toggles) forces shortcuts on (`true`, panels
+behave as drop-downs without buttons) or off. Phones keep the Menu opener and
+the left drawer's close toggle. `showTenantToggle` is a deprecated alias for
+`edgeToggles.left`. Migration: pass `edgeToggles` (true) to keep the previous
+behaviour.
+
+### Moving items between slots
+
+Movable items have stable ids: dock toggles `dock:<tool>`, each host `slots`
+snippet `slot:<slot>`, and host `slotItems` (`AppShell`, `{ id, label, slot,
+render }[]`, exported type `ShellSlotItem`; keep ids stable, they are stored in
+layouts). `AppShell` also supplies the built-in item `item:brand` (the shell
+`logoSrc`/`logoAlt`, title and subtitle, linked to `homeHref` when set, default slot `header.start`, movable, same fallback chain
+when the header is hidden); it sets `AdminShell` `brandInSlot` so the top band
+draws no brand of its own (standalone `AdminShell` still does). The menu
+opener and account content are not items yet (#3656 step 3).
+
+`ShellLayout.placements?: Record<itemId, ShellSlot>` (additive, still version
+1) overrides default slots. Pure helpers in `layout.ts` (also `./workspace/layout`):
+`placeShellItem(layout, id, slot, defaultSlot?)` (passing the default drops a
+no-op override; re-placing puts the item last), `resetShellItemPlacement`,
+`resolveShellPlacements(items, layout)` (default order first, then placement
+order; unknown ids and slots ignored) and `resolveShellVisiblePlacements(items,
+layout, visible)` (placement first, then the hidden-region fallback above).
+`useShellLayout()` adds `placeItem(id, slot)`, `resetItem(id)`, and readers
+`placementItems`, `placements` (per slot) and `isRegionVisible(region)`.
+
+### Editing the layout in place
+
+`AppShell` `layoutEditing?: boolean | { slot?; floating? }` opts in (off: no toggle,
+`setEditing(true)` refused, existing apps unchanged). It adds the built-in item
+`item:layout-edit` (default slot `header.end`, normal hidden-region fallback):
+a pencil `ShellIconButton` named "Edit layout" with `aria-pressed`; the same
+button turns edit mode off (it stays a pencil, highlighted while on). Escape
+also exits when no section toolbar is open (an open toolbar, or a keyboard move,
+consumes Escape first).
+`{ floating: true }` instead renders the same button fixed in the top-right
+corner (round, elevated, safe-area aware, z-index 45): not a slot item, not
+movable, never displaced by hidden regions. The header reserves end padding for
+it, or, when the header is hidden, the right sidebar reserves top padding, or main
+does when no right sidebar is shown
+(`--smrt-shell-floating-reserve-inline|block|main`, set by `AppShell`).
+A polite live region announces the mode. `useShellLayout()` has
+`editable`, `editing` and `setEditing(boolean)` for hosts and assistants.
+
+While `editing`:
+
+- `AdminShell` `layoutEdit` (`ShellLayoutEditSurface`, set by `AppShell`) renders
+  every slot of a visible region as a dashed drop zone (entering edit mode
+  expands a collapsed left/right sidebar so its header/footer zones exist, and
+  leaving restores it; a railless `rail: false` edge is never revealed: it
+  stays as the user left it, and while editing a closed railless right edge
+  with focus/dock tools shows a slim "Open <tool>" indicator tab
+  (`data-edit-indicator`, z 21, no layout shift) that opens it and closes it
+  again on exit) (`data-smrt-edit-zone`)
+  labelled "Header · Left", empty ones included, highlighted
+  (`data-drop-target`) while a drag targets it. Movable items render exactly as
+  on the site (inside an `inert` wrapper) with a grip; the toggle itself is
+  fixed. One headless `createSortable` engine (confined to the shell root,
+  `allowSameContainerReorder: false`) drives pointer, native-drag and keyboard
+  moves (Space, Up/Down across zones in visual order, Enter drops, Escape
+  cancels) with the same announcements as `Sortable`
+  (`sortable/announce.ts`), committing `placeItem(id, slot)`. Items whose region
+  is hidden show in the zone they fall back to.
+- Nothing in the header band renders outside the drop zones except each
+  region's edit control: the brand is an item in `header.start`, and the Menu
+  opener is hidden off phones. Every region, a collapsed sidebar rail included, gets an icon-only eye-off
+  "Hide <region>" button (`ShellLayoutEditSurface.regionControl`, end of the
+  header/footer band, top of a sidebar) that writes
+  `setPanel(edge, { visible: false })`; the strip's "Show" restores it. The
+  last visible region's button is disabled with an explanatory tooltip. Items
+  of a hidden region (the edit toggle included) follow the fallback chain.
+  Hiding the right sidebar (the dock) makes `useShellDock().available` false:
+  dock toggles render unregistered and `open` is refused until it is shown.
+- Hidden, available regions render as thin dashed strips ("Right sidebar ·
+  hidden") with an eye "Show <region>" button (`setPanel(edge, { visible })`).
+- `ShellNavEditor` replaces `TenantNav`: the real rows plus grips on every
+  heading and item (existing reorder/move-across-sections), icon-only
+  `ShellIconButton`s (eye `aria-pressed` = shown in navigation, heading
+  `aria-pressed` = title shown, host actions) on each section and an eye per
+  item, and a "New section" button at the end.
+- Clicking a section heading opens its floating toolbar (rename input focused,
+  title, hide, delete for custom sections with a confirm when non-empty, host
+  actions). With `(hover: hover) and (pointer: fine)` hovering also opens it
+  (closes on leave unless a click pinned it); touch or no hover is click/tap
+  only. One toolbar at a time; Escape closes and returns focus to the heading;
+  a pinned toolbar closes on outside pointer or focus leaving.
+
+Host extension point: `AppShell` `sectionActions?: Snippet<[ShellSectionActionsContext]>`
+(`{ sectionId, label, custom, editing }`) renders icon buttons in both the
+section overlay and its toolbar (e.g. the planner's Options gear and Help);
+use `ShellIconButton` (from `./workspace`) for matching looks. It renders only
+while editing.
+
+`ShellLayoutEditor` no longer has a Placement section (superseded by dragging in
+place); it keeps panels, the navigation sort (icon toggles `aria-pressed` for
+"Show <name> in navigation" / "Show title of <name>"), the preview and Reset.
+The layout helpers and `placeItem`/`resetItem` stay.
+
 ### Activity ticker
 
 `ActivityTicker` accepts app-owned `activities: ReadonlyArray<ShellActivity>` plus
@@ -219,11 +353,75 @@ control panel), wired by `app/AppShell.svelte`.
   `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
+  `isHidden`; item placement is in "Moving items between slots", edit mode in
+  "Editing the layout in place"). An assistant calls the same methods the editor does. The
   context is separate from `useAdminShell()` because `AppShell`, not
   `AdminShell`, owns the navigation.
+- **Sections belong to the app.** Hosts (and recipes, via the host) suggest
+  sections as `ShellNavGroup`s; the user overrides them in the same additive
+  version-1 layout: `sections[id] = { label?, showTitle? }` (rename; hide the
+  title) and `customSections: { id: 'custom:...', label }[]` (user-created).
+  Custom sections join `sectionOrder`, receive items through `moved`, show in
+  the editor when empty but not in the nav, and get a unique `custom:` id.
+  `showTitle: false` (also settable by a host on `ShellNavGroup.showTitle`)
+  renders the items flat in a `role="group"` named by the heading, no
+  `<details>`/`<summary>`. `applyShellLayout` keeps the section's original id
+  on renamed output groups. Helpers: `renameShellSection`,
+  `setShellSectionTitleVisible`, `createShellSection`, `deleteShellSection`
+  (custom only; items return to their default sections). Old stored layouts
+  need no migration; new host sections and items land in their suggested slot.
+  Controller: `renameSection`, `setSectionTitleVisible`, `createSection(label)`
+  (returns the id), `deleteSection`.
+- **Item labels.** The same layout renames single navigation entries:
+  `items[itemId] = { label? }` (additive; trimmed, blank removed; ids as above,
+  top-level items of `nav` and groups). `resolveShellNavModel` items carry
+  `label` / `defaultLabel`; `applyShellLayout` emits the renamed item with
+  `label` = the user's and `defaultLabel` = the host's (so nav, breadcrumbs and
+  titles that read `nav` follow the rename). Helper `renameShellItem(nav, groups,
+  layout, itemId, label | null)`; controller `renameItem(itemId, label | null)`
+  (null or blank resets). Edit mode: each `ShellNavEditor` row has an icon-only
+  "Rename <label>" button opening an inline field (Enter saves, Escape cancels,
+  blur saves) and, once renamed, "Reset <label> to <original>"; the original shows
+  as the row tooltip. Presets ("cookbooks") ship it in the stored layout.
+- **Sections-only navigation (`navMode: 'sections'`).** `AppShell` (and
+  `TenantNav` / `ShellNavEditor` directly) take `navMode?: 'items' | 'sections'`
+  (default `'items'`, unchanged). In `'sections'` the left sidebar shows one
+  link per section (icon + label), no entries; a collapsed rail (`tenantRail`)
+  shows the icons with tooltips. The link goes to `ShellNavGroup.href`, else
+  `AppShell` `sectionHref(sectionId)` (user-created sections), else the first
+  entry; it is `aria-current="page"` on that page and `"true"` on any of the
+  section's entry pages. `AppShell` also takes `iconComponent` for host icon
+  names. `ShellNavGroup.icon` / `.href` are additive; the user override is
+  `sections[id].icon` (trimmed; blank or the host's icon removes it), helper
+  `setShellSectionIcon(nav, groups, layout, id, icon | null)`, controller
+  `setSectionIcon(id, icon | null)`; `resolveShellNavModel` sections carry
+  `icon` / `defaultIcon` and `applyShellLayout` emits the effective `icon`.
+  Icons are shell icon names (`SHELL_SECTION_ICONS` is the picker set, drawn
+  from Material icons like the rest of `SHELL_ICON_PATHS`; `SHELL_DEFAULT_SECTION_ICON`
+  is `folder`) or host names rendered by `iconComponent` (`ShellSectionIcon`
+  tries the built-in set first). Edit mode in this mode: sections keep grip,
+  rename, hide, delete; the title toggle is replaced by an "Icon of <label>"
+  popover grid ("Use <icon> icon", `aria-pressed` on the current one; Escape
+  closes the grid before the toolbar). Entries are not in the sidebar.
+- **`ShellSectionMenu`** (`sectionId`, `controller?`, `meta(entry)`,
+  `actions(entry)`, `iconComponent`, `aria-label`, `layout`): the section's page body.
+  `layout="cards"` renders an auto-fill grid (min 16rem) of cards: 32px icon in a
+  tinted circle, title, `ShellNavItem.description` (2 lines), then `meta` and
+  `actions` at the bottom; one stretched link, actions stay separate controls;
+  edit mode keeps grip/rename/hide in the grid. Unknown icon names draw the
+  default glyph (dev warning), never the name. `layout.items[id].description` (host/preset-set, not editable in the UI)
+  overrides an item's `description`. Default `list`: A
+  `<ul>` of rows (icon, label link, host `meta`, host `actions`, chevron; the
+  row is one stretched link, actions sit above it) in applied order with
+  renames; hidden entries are omitted. While editing, the same rows become the
+  nav editor's chrome (single-container `Sortable` grip with keyboard moves,
+  inline rename/reset, show/hide toggle) driving `moveItem`/`renameItem`/
+  `hide`/`show`; rows are not links then. `ShellSectionMenuEntry` is the snippet
+  argument (`id, href, label, defaultLabel, icon, hidden, item`).
 - **`ShellLayoutEditor`**: `controller` (default: context), `preview` (default
-  true), `iconComponent`. Mount it on a settings page or in a dock tool.
+  true), `iconComponent`. Each section has an inline name input, icon toggles
+  for visibility and title, and (custom only) a trash button, which confirms
+  when non-empty; a New section button creates one. Mount it on a settings page or in a dock tool.
 
 ### Sortable and the Board engine
 
@@ -255,9 +453,8 @@ lives beside, not inside, `./workspace` so the AdminShell barrel stays free of
   (`{#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. `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
+  (`{ tool, label, icon?, slot? }[]`) renders icon buttons in the shell slot
+  named by `slot` (default `header.end`; see "Regions and slots"), 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

package/dist/browser-ai/adapters/stt/dictation-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dictation-source.d.ts","sourceRoot":"","sources":["../../../../src/browser-ai/adapters/stt/dictation-source.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE5D,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,aAA0C,GAClD,MAAM,OAAO,CAAC,UAAU,CAAC,CAc3B"}
+{"version":3,"file":"dictation-source.d.ts","sourceRoot":"","sources":["../../../../src/browser-ai/adapters/stt/dictation-source.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE5D,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,aAA0C,GAClD,MAAM,OAAO,CAAC,UAAU,CAAC,CAmB3B"}

package/dist/browser-ai/adapters/stt/dictation-source.js

@@ -7,7 +7,8 @@
  * adapter lazily, once, the first time someone starts dictating: nothing
  * loads and no microphone prompt appears until then. Defaults to the
  * browser's own speech recognition (`browser-speech`), which needs no
- * download; an unsupported browser rejects with
+ * download; an on-device model is never downloaded by dictation (see
+ * `LocalSpeechSTTAdapter.prepare`). An unsupported browser rejects with
  * `CapabilityNotAvailableError`, which `Dictation` reports in plain words.
  *
  * @example
@@ -26,7 +27,12 @@ export function createSttDictationSource(options = { type: 'browser-speech' }) {
     return () => {
         adapter ??= (async () => {
             const created = await getSTT(options);
-            await created.ensureInitialized();
+            // An adapter that needs a download is never loaded here: dictation must
+            // not start one. It checks its own model when started, and the host
+            // loads it explicitly (after asking).
+            if (!created.getCapabilities().requiresDownload) {
+                await created.ensureInitialized();
+            }
             return created;
         })().catch((error) => {
             // Let a later tap try again (for example after a permission change).

package/dist/browser-ai/adapters/stt/factory.d.ts

@@ -20,8 +20,11 @@ import type { GetSTTOptions, STTAdapter } from './types.js';
  * // Whisper.cpp (recommended for accuracy)
  * const stt = await getSTT({ type: 'whisper-cpp', model: 'tiny.en' });
  *
- * // Whisper WASM (transformers.js - has known issues)
- * const stt = await getSTT({ type: 'whisper-wasm', modelSize: 'tiny' });
+ * // Local Whisper (transformers.js; WebGPU or WASM, one-time ~45 MB download)
+ * const stt = await getSTT({ type: 'whisper-local' });
+ *
+ * // Moonshine (fastest for live dictation, one-time ~32 MB download)
+ * const stt = await getSTT({ type: 'moonshine' });
  * ```
  */
 export declare function getSTT(options?: GetSTTOptions): Promise<STTAdapter>;
@@ -45,5 +48,5 @@ export declare function getSTTAuto(options?: Partial<Omit<GetSTTOptions, 'type'>
 /**
  * Check if a specific STT backend is available
  */
-export declare function isSTTAvailable(type: 'browser-speech' | 'whisper-wasm'): boolean;
+export declare function isSTTAvailable(type: 'browser-speech' | 'whisper-wasm' | 'whisper-local' | 'moonshine'): boolean;
 //# sourceMappingURL=factory.d.ts.map

package/dist/browser-ai/adapters/stt/factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../../src/browser-ai/adapters/stt/factory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,KAAK,EAEV,aAAa,EACb,UAAU,EAGX,MAAM,YAAY,CAAC;AA6BpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,UAAU,CAAC,CAqB7E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,UAAU,CAC9B,OAAO,GAAE,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,CAAM,GACjD,OAAO,CAAC,UAAU,CAAC,CAmBrB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,gBAAgB,GAAG,cAAc,GACtC,OAAO,CAYT"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../../src/browser-ai/adapters/stt/factory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,KAAK,EAEV,aAAa,EAEb,UAAU,EAEX,MAAM,YAAY,CAAC;AAkCpB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,UAAU,CAAC,CAuB7E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,UAAU,CAC9B,OAAO,GAAE,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,CAAM,GACjD,OAAO,CAAC,UAAU,CAAC,CAmBrB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,gBAAgB,GAAG,cAAc,GAAG,eAAe,GAAG,WAAW,GACtE,OAAO,CAgBT"}