@jskit-ai/agent-docs 0.1.279 → 0.1.281

package/guide/agent/app-setup/upgrading-jskit.md

@@ -164,12 +164,108 @@ The check fails when:
 - a JSKIT override tries to force a private graph;
 - a root/workspace declaration has no lockfile installation, or the lockfile is missing;
 - installed package versions or root/workspace declarations disagree with the lockfile.
+- a package script runs tests outside the machine's test budget (`test/*`, see
+  [Test files run in parallel](/guide/framework/typed-features#test-files-run-in-parallel)).
 
 Shared client owners such as the kernel, HTTP runtime, shell, auth web runtime,
 realtime runtime, and assistant runtime use exact peer dependencies where they
 must share application state. A partial upgrade can therefore fail during npm
 installation instead of silently nesting a second client stack.
 
+## Run tests within the test budget
+
+Plain `jskit check` fails a test run that ignores the machine's test budget
+([Test files run in parallel](/guide/framework/typed-features#test-files-run-in-parallel)).
+An application adopts it once, at the upgrade that brings `jskit test`:
+
+1. Its test scripts run `jskit test` with their own files or globs, for
+   example `"test": "jskit test"`, never `node --test` or
+   `--test-concurrency`.
+2. `playwright.config.*` sets `workers: testConcurrency()` and the Vitest
+   config sets `maxWorkers: testConcurrency()`, with
+   `import { testConcurrency } from "@jskit-ai/jskit-catalog/test-budget";`,
+   and no script passes `--workers`, `-j` or `--maxWorkers`.
+3. Files that collide when run together get their own port, temporary
+   directory, database or schema, and Vite `cacheDir`; a file that truly
+   must run alone says why on its first line, `// jskit-test: alone - <reason>`.
+4. The whole suite passes with the budget, and its time before and after is
+   recorded.
+
+## Move browser and database tests onto the JSKIT harness
+
+The release that brings `browserTestConfig()` and `jskit test --databases`
+makes JSKIT own the fast test harness. Plain `jskit check` fails a Playwright
+webServer on the development server (`test/playwright-dev-server`), one
+webServer every worker shares (`test/playwright-isolation`), and a config
+without a `globalTimeout` (`test/playwright-global-timeout`). At that repin, an
+application:
+
+1. Deletes its own copies of the harness: a local test-budget helper
+   (`testConcurrency()` in its own scripts), a launcher that starts a server
+   per worker, a cached production-build step, worker port and database-name
+   helpers, a Node test runner wrapper that hands each file a database, and
+   its schema-snapshot code. It imports `testConcurrency()` from
+   `@jskit-ai/jskit-catalog/test-budget` wherever it still needs the number.
+2. Replaces `playwright.config.*` with
+   `defineConfig(browserTestConfig({ testDir: "./tests/e2e", prepare: "tests/e2e/databases.js" }))`
+   from `@jskit-ai/jskit-catalog/browser-tests`, with `server`, `build`, `env`
+   or `port` only where its own differ from `node ./bin/server.js`,
+   `npm run build` and 4173, and `globalTimeout` only for a suite measured to
+   need more than 20 minutes. Settings a config adds (projects, a globalSetup
+   that proves the server's identity, `timezoneId`) spread over the result:
+   `defineConfig({ ...base, projects, use: { ...base.use, timezoneId } })`. A
+   second local Playwright config and any `npm run develop` or `vite`
+   webServer go.
+3. Copies its database pattern's `example/tests/e2e/databases.js` and moves
+   its browser fixture seed into its `seed`; each worker's server then gets a
+   seeded copy of `BROWSER_TEST_DB_NAME`. Server settings for tests only (a
+   simulated email or payment driver) go in `browserTestConfig({ env })`.
+4. Runs Node tests with `"test": "jskit test --databases"`, with
+   `TEST_DB_NAME` distinct from `DB_NAME`, `BROWSER_TEST_DB_NAME` and
+   `PROD_DB_NAME`, and a database user that may create its numbered copies
+   (`CREATEDB` on PostgreSQL). Test files read `DB_NAME`/`TEST_DB_NAME` as
+   given rather than naming the test database themselves, and no longer
+   create, migrate or drop it: the run hands each file a restored copy.
+5. Proves it with a timed full run: `npm test` and `npx playwright test`, every
+   test passing, the time of each before and after recorded, and the slowest
+   tests the run lists read.
+
+## Cache built assets for good
+
+The foundations' `server.js` serves each content-hashed file under
+`dist/assets/` with `Cache-Control: public, max-age=31536000, immutable`, so a
+page load no longer revalidates every script and stylesheet the build made;
+`index.html` and unhashed files are still revalidated on every load. An
+application copies `HASHED_ASSET`, `HASHED_ASSET_CACHE` and the
+`reply.sendFile()` choice from its foundation's `example/server.js` into its
+own `server.js`, with the browser test "built assets are kept for good and the
+page itself is revalidated" from `example/tests/e2e/startup.spec.ts`. A spec
+that mocks requests with `page.route()` turns Playwright's HTTP cache off, so
+it still fetches every asset on each navigation.
+
+## Sign each browser worker in once
+
+A suite whose tests sign in one by one, such as a helper that calls
+`loginAsExistingUser()` at the start of each test, signs each worker's server
+in once instead, with `browserTestConfig({ signIn: "tests/e2e/sign-in.js" })`:
+
+```js
+// tests/e2e/sign-in.js: `env` is the worker server's environment.
+import { loginRequestAsExistingUser } from "@jskit-ai/auth-web/test/playwright";
+
+export default ({ request, env }) =>
+  loginRequestAsExistingUser(request, { email: "owner@example.com", secret: env.AUTH_DEV_BYPASS_SECRET });
+```
+
+The servers' launcher runs it once per server, after the servers start. Each
+test of that worker then starts from the signed-in storage state, which the
+worker's process also finds in `PLAYWRIGHT_STORAGE_STATE`, as on a managed
+target, so a helper that skips signing in under `PLAYWRIGHT_STORAGE_STATE`
+skips it locally too. A test that must start signed out uses
+`test.use({ storageState: { cookies: [], origins: [] } })`; a test that signs
+out or ends other sessions signs in on its own first, so the worker's shared
+session lives on. A login state the host supplies is used as it is.
+
 ## Application migration
 
 The updater changes package manifests and the lockfile only. It does not
@@ -189,6 +285,15 @@ app source: the theme, icons, type classes, page titles and parents, and page
 actions. [Move an app to the Material 3 defaults](./material-3-migration.md)
 lists each change, most of which delete app CSS and overrides.
 
+A release can add message keys (each package's changelog names its new ones,
+such as `jskit.auth.local.register.closed`). JSKIT keeps no separate list: in
+an app with other locales, run `npx jskit i18n export <locale>` for each one
+after updating, which adds every new key in English beside the existing
+translations, translate them, and let `npx jskit i18n check <locale>` confirm
+none is missing (see [Translation](../framework/translation.md#add-a-language)).
+Missing keys fall back to English, so nothing breaks before then, but an app
+whose CI runs the check fails until they are added.
+
 Commit `package.json`, every changed workspace manifest, and
 `package-lock.json` together. Do not hand-edit one JSKIT version after the
 updater succeeds; select a different published cohort only through a catalog

package/guide/agent/app-setup/users.md

@@ -25,6 +25,13 @@ Use the `users/account-settings` pattern for profile, preference, and
 notification sections. Decide which fields are editable and which operations
 require reauthentication.
 
+The sections are pages in Material 3's list-detail layout: `/account` lists
+them (`src/pages/account/index.vue`) and `/account/<section>` opens one
+(`src/pages/account/[section].vue`, whose parent is the list, `"/"`). A phone
+shows the list or one section, with Up from the section back to the list; a wide
+window shows the list beside the open section. Link to a section by its path,
+such as `/account/preferences`.
+
 Use the framework account settings elements and command composables rather than
 new page-local request clients. Cached query data must hydrate editable fields
 immediately; clearing a value must send the clear operation rather than omit the
@@ -47,7 +54,8 @@ record existence is not leaked.
 ## Verification
 
 Test profile creation from an authenticated identity, read/update/clear flows,
-warm-cache navigation, uploads when enabled, forbidden administration, missing
+warm-cache navigation, the section list and a section one at a time at 390 px
+(Up returns to the list) and side by side at 1280 px, uploads when enabled, forbidden administration, missing
 records, pagination, and workspace isolation where relevant.
 
 Do not copy users-core tables or services into the application. Do not add

package/guide/agent/framework/client-features.md

@@ -237,7 +237,7 @@ const ConversationClientProvider = defineProvider({
   },
   /** @param {{ components: import("@jskit-ai/kernel/client/types").ClientComponents }} capabilities */
   setup({ components }) {
-    components.register("conversation.web.settings.element", ConversationSettingsElement);
+    components.register("conversation.web.status.widget", ConversationStatusWidget);
   }
 });
 
@@ -246,6 +246,40 @@ const components = new Map();
 export function registerComponent(id, component) { components.set(id, component); }
 ```
 
+### Provider subpaths
+
+**Export each client provider by a subpath of its own. The provider's file
+imports only what every page needs, such as a widget the shell always shows; a
+screen that only some routes show is imported by those routes.**
+
+Why: every page of every app loads the client providers, and what they import,
+before it shows anything. The client bootstrap imports a provider through the
+subpath export that names its file, so the screens `./client` re-exports, and
+their libraries, load only with the routes that show them. A provider without a
+subpath, or a `./client` that declares `routeComponents` or `clientRoutes` or
+uses `export *`, brings all of `./client` to every page.
+
+```json
+// good: package.json
+"exports": {
+  "./client": "./src/client/index.js",
+  "./client/providers/ConversationClientProvider": "./src/client/providers/ConversationClientProvider.js"
+}
+
+// bad: package.json, no subpath for the provider, so every page loads all of ./client
+"exports": {
+  "./client": "./src/client/index.js"
+}
+```
+
+```js
+// good: the provider's file imports the widget every page shows
+import ConversationStatusWidget from "../components/ConversationStatusWidget.vue";
+
+// bad: the provider's file imports a screen that only its route shows
+import ConversationSettingsScreen from "../components/ConversationSettingsScreen.vue";
+```
+
 ### Injected values
 
 **`inject()` takes the owner's exported key, never a literal. A required value

package/guide/agent/framework/material-3.md

@@ -47,7 +47,8 @@ app and never leaves it.
 - **What the person sees:** one Up arrow on every inner page, also when opened
   directly: icon only (`$arrowBack`), accessible name "Back" (localized), a
   tooltip on pointer devices. None on top-level destinations, and no other
-  back control anywhere; the bar title says where the person is. A list-detail
+  back control anywhere; the bar title says where the person is. A new or edit
+  form shows a close (X) in the arrow's place, which cancels. A list-detail
   layout showing the parent beside the page needs no arrow for that step;
   collapsed to one pane, the record pane gets it back.
 - **Where Up goes:** to the previous trail entry while it is valid, so inside
@@ -79,11 +80,17 @@ Exactly this, and nothing more:
    </script>
    ```
 
-   The same key works in a `<route lang="json">` block. A record names its
-   list, an edit page its record, a sub-page its page. Tabs under a layout
+   The same key works in a `<route lang="json">` block. Tabs under a layout
    (`settings.vue` rendering `<RouterView>` for `settings/`) declare nothing:
    they inherit the nearest layout's declaration, and moving between them keeps
-   the trail.
+   the trail and the scroll. A folder without a layout (`bookings/` with no
+   `bookings.vue`) only groups routes: its pages are different pages, each
+   opening at the top. The parent is read from the page up to its surface root, the
+   record that declares `jskit.surface`, and stops there. So the surface goes
+   only on the surface's layout page (`account.vue`: `ShellLayout` around
+   `<RouterView />`) and the parent on the page it renders
+   (`account/index.vue`). A package route declares its parent in its
+   `package.json` `meta`; under no layout, its component draws `ShellLayout`.
 2. **Each top-level destination is a main-navigation item** (a `kind: "link"`
    placement with `target: "shell.primary-nav"` or `"shell.secondary-nav"`) and
    declares no parent; nor do its tabs. A shell page with no parent is
@@ -95,14 +102,20 @@ Exactly this, and nothing more:
    `:to="paths.page('/suppliers')"` and `router.push(paths.page(...))` with
    `usePaths()`, the CRUD runtime's `resolveViewUrl()`, `resolveEditUrl()` and
    `resolveParams()`, and link placements (`surface` with `scopedSuffix` and
-   `unscopedSuffix`; `to` only for a global route such as `/auth/login`). The
-   trail follows the router, so there is no special link component.
+   `unscopedSuffix`; `to` only for a global route). A global route
+   (`scope: "global"`, on no surface) is
+   `paths.page("/auth/login", { scope: "global" })`; `explicitTo` only passes
+   through a finished target that arrives as data, never a hand-written path.
+   The trail follows the router, so there is no special link component.
 4. **A custom new or edit page finishes through the shell:**
    `useShellNavigation()` (`@jskit-ai/shell-web/client/navigation/useShellNavigation`)
    gives `finish(target)` for Save (the target replaces the form in the trail)
    and `finish()` for Cancel (back to where the form was opened, else its
-   parent). A page whose record turns out deleted or forbidden calls
-   `pageUnavailable()`. JSKIT's CRUD screens already do both.
+   parent); `useShellPageClose({ label, close })`
+   (`@jskit-ai/shell-web/client/composables/useShellPageClose`) makes the
+   arrow its Cancel, never an X beside it. A page whose
+   record turns out deleted or forbidden calls `pageUnavailable()`. JSKIT's
+   CRUD screens already do all three.
 5. **A full page load goes through the shell too:** `reloadAppPage(path)`
    (after sign-in or a user switch, to rebuild client state) and
    `leaveApp(url)` (an external site in the same tab, such as a payment page),
@@ -118,11 +131,12 @@ Exactly this, and nothing more:
 | `nav/history` | `history.back()`, `history.go()`, `history.pushState()`/`replaceState()`, `router.back()`, `router.go()` |
 | `nav/window-location` | `window.location` assignments, `.href =`, `location.assign()`, `location.replace()` |
 | `nav/raw-link` | a hand-built in-app path in `to`, `href`, `router.push()`, `router.replace()` or a `to:`/`href:` object key outside a placement |
-| `nav/back-control` | any back control but the shell's Up that navigates the app: "Back to X", "← Suppliers", back arrows and navigating chevrons, breadcrumbs, a custom app-bar back button, a back component, a `goBack()`-style handler |
-| `nav/missing-parent` | an inner page of a shell surface without a declared parent |
+| `nav/back-control` | any back control but the shell's Up that navigates the app: "Back to X", "← Suppliers", back arrows and navigating chevrons, breadcrumbs, a custom app-bar back button, a back component (`<ContextBackButton />` or `<page-back-link>`, and its import), a `goBack()`-style handler |
+| `nav/missing-parent` | an inner page of a shell surface without a declared parent, when it always renders under the shell's top app bar (a layout that also renders its pages without `ShellLayout`, such as a shop device's sign-in in a `v-if`, leaves its pages unjudged) |
 | `nav/top-level-parent` | a main-navigation destination that declares a parent |
 | `nav/placement-data` | a main-navigation placement that isn't literal data (no page is judged for a missing parent until it is) |
 | `nav/missing-shell-layout` | a page that declares a parent with no shell layout rendering it, so its title, Up and actions never show |
+| `nav/surface-parent` | a parent declared beside `jskit.surface`, which the shell never reads |
 | `nav/allow` | any `m3-check: allow nav/...` comment: nothing excuses a navigation rule |
 
 ### Each rule, right and wrong
@@ -180,35 +194,43 @@ Exactly this, and nothing more:
 - **Type:** Vuetify 4 Material 3 roles (`text-headline-small`,
   `text-title-large`, `text-body-medium`, `text-label-large`). Never the
   Material 2 scale (`text-h5`, `text-body-2`) or a page-local type system.
-  Roboto Flex is the font.
+  Material 3 has two typefaces, both Roboto Flex unless the app names its own
+  in `src/theme/index.js`:
+  `typography: { brand: '"Fraunces", serif', plain: '"Inter", sans-serif' }`.
+  `brand` sets display, headline and title-large, `plain` the rest (title-medium
+  and -small, body, label); each is a CSS font-family value, and the app loads
+  the font. Never set `font-family` or `--v-font-body` in app CSS.
 - **Icons:** Material Symbols Rounded through Vuetify `$` aliases: Vuetify's
   standard ones (`$close`, `$menu`, `$delete`, `$prev`, `$next`) and JSKIT's
   camelCase names (`$add`, `$edit`, `$search`, `$moreVert`, `$filterList`,
   `$arrowBack`); `$homeFilled`-style `Filled` variants mark active navigation.
   An app adds an icon under `theme.icons` in `src/theme/index.js` as
   `{ name: "<24x24 path data>" }` from Material Symbols Rounded, then uses
-  `$name`. No `mdi-*` strings and no `@mdi/js` imports in app code.
+  `$name`. No `mdi-*` strings and no `@mdi/js` imports in app code. Material
+  Symbols has no brand marks (Google, GitHub, a payment network): a brand's
+  logo is the brand's own artwork, a content image or SVG used as its owner
+  publishes it, not an icon alias.
 
 ## Exact sizes
 
-JSKIT ships these exact sizes; an app never re-implements or overrides them,
-and needs no Sass and no `!important` (Vuetify 4 keeps its CSS in cascade
-layers):
+JSKIT ships these exact sizes; an app never re-implements or overrides them:
 
 - 40dp buttons with a 48dp touch target, icon buttons included; a smaller
   button is `size="small"` or `size="x-small"`, which keeps its smaller look
-  and the 48dp target;
-- one-line button labels: a label longer than its button ends in an ellipsis.
-  Keep labels short, and give a button whose label can run long, such as a
-  name, the full label as its `title`;
-- 12dp cards: elevated (the default) at level 1, flat and tonal at level 0;
+  and the 48dp target. No icon button is under 32dp, and a target stops at
+  the edge of a button beside it, so each of a row's touching icon buttons
+  answers its own press;
+- one-line button labels, ending in an ellipsis: keep labels short, and give
+  one that can run long, such as a name, its full label as `title`;
+- 12dp cards: flat (the default) and tonal at level 0, `variant="elevated"`
+  at level 1; flat expansion panels;
 - 28dp dialogs and bottom-sheet top corners, square full-screen dialogs;
 - 8dp chips, and FABs of 56dp (small 40dp, large 96dp; extended 56dp tall)
   with 16dp corners;
 - emphasized easing, with reduced motion honoured.
 
 So never set `height` or `min-height` on a button, or a radius on a card,
-dialog, chip or FAB. A missing size is a JSKIT defect.
+dialog, chip or FAB.
 
 ## The top app bar carries the page
 
@@ -216,35 +238,46 @@ dialog, chip or FAB. A missing size is a JSKIT defect.
   `useShellPageTitle(title)` (`@jskit-ai/shell-web/client/composables/useShellPageTitle`)
   for a runtime title such as the record's name. The shell renders it as the
   app bar's only `h1`; pages add no `h1`, page header, title block or
-  standalone heading. A section inside a page uses a title role. A page with
-  no top app bar (a hero front page, an intro, an invite or hand-off page)
-  has its own one `h1`.
-- **Up** sits in the bar on every inner page (see Navigation and Up). On phones
-  it replaces the menu icon.
+  standalone heading. Route pages own the title: a section or a nested
+  component uses a title role (a component's claim gives the title back when
+  it goes). A page with no top app bar (a hero front page, an intro, an invite
+  or hand-off page) has its own one `h1`.
+- **Up** leads the bar on every inner page; on phones it replaces the menu
+  icon.
 - **A layout that draws its own top app bar** (a workspace bar with the
   app's own controls, instead of `ShellLayout`) builds it from `ShellLayout`'s
   own pieces, from `@jskit-ai/shell-web/client`. It calls `useShellAppBar()`
   once, so its pages enter the trail and their `ShellPageActions` show in its
   bar, and renders `ShellUpButton` first, then `ShellPageTitle` (the page's one
-  `h1`: `useShellPageTitle()`, else the route's `jskit.title`, else its `title`
-  prop) and `ShellPageActionsTarget`. A title that is also a switcher, such as a
+  `h1`) and `ShellPageActionsTarget`. A title that is also a switcher, such as a
   project menu, goes in `ShellPageTitle`'s default slot (given `{ title }`) as
-  the menu's activator, so it stays the one `h1`. `jskit check` counts it as a shell
-  layout, so its inner pages need parents; an Up the app draws itself is a
-  `nav/back-control` finding.
+  the menu's activator, so it stays the one `h1`. `jskit check` counts it as a
+  shell layout, so its inner pages need parents.
 - **Actions:** a screen's actions go in the bar inside `ShellPageActions`
   (`@jskit-ai/shell-web/client/components/ShellPageActions`), each a
   `ShellPageAction` with `icon`, `label` (also its accessible name and compact
-  tooltip), and `primary`, `to`, `replace`, `disabled`, `loading` or `color`.
-  On compact widths every action shows only its icon except the single
-  `primary` one.
+  tooltip), and `primary`, `to`, `replace`, `href` (with `download` for a
+  file, such as a CSV export), `disabled`, `loading` or `color` (`error` for a
+  destructive one); attributes such as `target` reach its button. On compact
+  widths the bar keeps one trailing item after the title: the single
+  `primary` action when the page has one (a form's Save), otherwise its own
+  item nearest the corner (a top-right placement such as the account avatar).
+  Every other action and the bar's other items (a notification bell, tools)
+  go to its "More actions" menu, where `overflow` actions always are. Medium
+  and wider bars show them all.
 - **Window size classes:** compact under 600 (navigation bar), medium 600–839
-  (navigation rail), expanded 840–1199 and large from 1200 (drawer). A surface
-  with no navigation destinations, such as an account surface, draws no
-  navigation bar, rail or drawer; its pages keep the app bar. Read them
-  from `useShellWindowSizeClass()`
+  (navigation rail), expanded 840–1199 and large from 1200 (drawer), read from
+  `useShellWindowSizeClass()`
   (`@jskit-ai/shell-web/client/composables/useShellWindowSizeClass`), never from
-  copied breakpoint numbers.
+  copied breakpoint numbers. A surface with fewer than two navigation
+  destinations (none, as on an account surface, or Home alone) draws no
+  navigation bar, rail or drawer; its pages keep the app bar.
+- **Section tabs:** a page's own sections (`page.section-nav`) are Material 3
+  primary tabs: the topology names `ShellSectionTabLinkItem`'s token (the
+  starter registers it as `local.main.ui.section-tab-link-item`), and the page
+  draws one tab row, `display: flex; overflow-x: auto` over a 1dp
+  `outline-variant` bottom border. `ShellTabLinkItem` is the navigation bar's
+  destination; placed in a page it draws a section tab.
 
 ## Colour
 
@@ -267,35 +300,41 @@ dialog, chip or FAB. A missing size is a JSKIT defect.
   control; never a permanent panel of outlined fields. A card opens its record
   when tapped (a stretched title link); a table row opens on click. Row actions
   are trailing icon buttons (edit, a `$moreVert` overflow menu, a chevron to
-  open), never "View" or "Edit" text buttons on every row. "New" is an extended
-  FAB on compact and medium widths and a filled bar button on expanded. Empty
-  and error states carry an icon.
+  open), never "View" or "Edit" text buttons on every row. "New" is
+  `ShellPrimaryAction` (`label`, and `to` or a click handler): an extended FAB
+  on compact and medium widths, a filled bar button on expanded. On/off filters
+  are `aria-pressed` chips, or chips in a `v-chip-group`; JSKIT draws them as
+  filter chips. Empty and error states carry an icon.
 - **A list never scrolls sideways, at any width.** The list's own width (a
   container query, not the window) chooses cards or table. Cards flow into a
   grid; tables use a fixed layout with an ellipsis on long values, and fold
   low-priority columns into a stronger column's second line. Lists show figures
   ("120 kg", tabular and right-aligned) and names, never ids.
 - **Record:** a header (avatar, title, status chips) and value-first detail
-  lists, never a grid of label/value text. Edit sits in the bar; the record's
+  lists, never a grid of label/value text. Edit sits in the bar, its secondary
+  actions in the bar's overflow menu, never in the content; the record's
   next workflow step is the one filled button, shown in context rather than a
   row of mostly disabled actions.
-- **Form:** Cancel and Save sit in the bar. Fields use `hideDetails: "auto"`.
-  Nothing moves under a finger: a multi-select chip field keeps its input width
-  when it loses focus. A pick-one-of-N choice is a segmented button with
-  `role="radiogroup"` and `role="radio"`/`aria-checked` buttons.
+- **Form:** the bar's close (X) cancels and Save is its filled action. Fields
+  use `hideDetails: "auto"`. Nothing moves under a finger: a multi-select chip
+  field keeps its input width when it loses focus. A pick-one-of-N choice is a
+  segmented button (`v-btn-toggle`, drawn by JSKIT, with 12dp segment sides as
+  in any `v-btn-group`) with `role="radiogroup"` and
+  `role="radio"`/`aria-checked` buttons.
 - **Dialogs:** plain `v-dialog` and `v-bottom-sheet`; JSKIT gives them their
   Material 3 shapes. A full-screen dialog (compact and medium) puts close, title
   and its confirm action in a top bar, never at the bottom where a snackbar
   covers them.
 - **Menus and badges:** a menu's list has `role="menu"` and its items
   `role="menuitem"`, with `aria-disabled` on unavailable ones; a badge has a
-  `label` such as "3 batches".
+  `label` such as "3 batches". JSKIT draws a menu's list and a dialog's card;
+  an app sets no `VMenu` or `VDialog` defaults, under which
+  Vuetify 4.2.1 to 4.3.2 loses a `v-select`'s typeahead match, or a dialog's
+  virtual list, when an ancestor re-renders.
 
 ## Components, state, and feedback
 
-- Choose components by purpose. Prefer standard buttons, fields, lists,
-  tables, sheets, dialogs, menus, navigation, progress, alerts, snackbars, and
-  tooltips over custom imitations.
+- Choose standard components by purpose over custom imitations.
 - Give one primary action emphasis. Distinguish destructive, secondary, and
   icon-only actions without relying on color; give icon controls accessible
   names and fields meaningful labels, errors, and autocomplete behavior.
@@ -312,6 +351,11 @@ dialog, chip or FAB. A missing size is a JSKIT defect.
   field. A user-triggered command uses JSKIT's shared action
   feedback/snackbar path. Never insert a transient command-error alert above
   page content where it shifts the working layout.
+- A snackbar never covers the FAB or the actions it reports on. `ShellErrorHost`
+  centres it above the navigation bar on compact windows and starts it at the
+  content's start edge, at most half its width, on wider ones. A FAB takes
+  layout room (`<v-fab app layout>`, as `ShellPrimaryAction`'s does), so the
+  snackbar shows above it.
 
 ## Adaptive layout
 
@@ -333,16 +377,15 @@ npx jskit check m3 src/pages/home/books  # a section
 npx jskit check m3 $(git diff --name-only --diff-filter=d main)  # changed files
 ```
 
-Plain `jskit check` fails on the [navigation rules](#forbidden-in-app-code);
-fix every one, because nothing excuses them. `jskit check m3` lists those and
-the visual rules below. The visual rules are a report until every JSKIT app has
-been converted to them; the JSKIT release after that makes plain `jskit check`,
-and so every app's verify, fail on them too:
+Plain `jskit check` fails on the [navigation rules](#forbidden-in-app-code).
+`jskit check m3` lists those and the visual rules below. The visual rules are a
+report until every JSKIT app has been converted to them; the JSKIT release after
+that makes plain `jskit check`, and so every app's verify, fail on them too:
 
 | Rule | Finds |
 |---|---|
-| `m3/duplicate-h1` | a second `h1`, or an in-page `h1` under the shell's page title |
-| `m3/raw-hex` | a hex colour outside `src/theme/` (`palettes.js` holds content colours) |
+| `m3/duplicate-h1` | a second `h1` that can show beside the first (one per `v-if` branch is one), or an in-page `h1` under a layout that always shows the shell's page title |
+| `m3/raw-hex` | a hex colour, or one written as channels (`rgba(0, 0, 0, 0.15)`, as in a hand-made shadow), outside `src/theme/` (`palettes.js` holds content colours); `rgba(var(--v-theme-shadow), 0.2)` reads a role and passes |
 | `m3/dark-scheme` | no dark scheme, or the theme pinned to light |
 | `m3/outlined-card` | `variant="outlined"` or `border` on a card or sheet |
 | `m3/mdi-icon` | `mdi-*` icon strings and `@mdi/js` imports |
@@ -395,9 +438,9 @@ What is left, such as a colour inside static SVG markup that can't import,
 may be excused one line at a time, on its line or the line before: `<!-- m3-check: allow m3/raw-hex - the partner's contractual logo colour -->`
 (`// m3-check: ...` in scripts, `/* ... */` in CSS). **Never add one on your
 own:** ask the person first, naming the rule and the reason. A comment with no
-reason (`m3/allow-reason`) or an unknown rule (`m3/allow-rule`), and any
-`m3-check: allow nav/...` (`nav/allow`), is itself a finding; nothing turns the
-check off for a file, a folder or the app. `jskit check m3` lists every
+reason (`m3/allow-reason`) or an unknown rule (`m3/allow-rule`) is itself a
+finding, as any `nav/allow` is; nothing turns the check off for a file, a
+folder or the app. `jskit check m3` lists every
 exception with its file, line and reason, and their total.
 
 ## Material 3 audit
@@ -406,19 +449,16 @@ Run this behavior-preserving audit over every affected screen:
 
 1. Identify the owning JSKIT surface, shared screen, shell, placement, theme,
    and Vuetify components before judging local markup.
-2. Check navigation and Up first, as must-fix: plain `jskit check` passes;
-   every inner page has a parent and one Up arrow in the bar; main-menu
-   destinations have none; no inner link is hand-built; nothing writes back
-   logic.
+2. Check navigation and Up first, as must-fix: plain `jskit check` passes and
+   every rule in Navigation and Up holds.
 3. Find parallel components, duplicated state chrome, page-local themes, raw
    visual constants, CSS against Vuetify internals, nested generic cards,
-   borders instead of tones, Material 2 typography, and desktop-only layout.
-4. Check hierarchy, token use, component purpose, responsive presentation,
-   interaction states, keyboard/focus behavior, labels, targets, contrast, and
-   reduced motion against the rules above.
-5. Correct issues at the narrowest established owner. Consolidate only truly
+   borders instead of tones, Material 2 typography, and desktop-only layout;
+   check states, focus, labels, targets, contrast and reduced motion against
+   the rules above.
+4. Correct issues at the narrowest established owner. Consolidate only truly
    repeated policy; avoid pass-through wrappers and speculative abstractions.
-6. Run `jskit check` and `jskit check m3` on the affected files, then focused
+5. Run `jskit check` and `jskit check m3` on the affected files, then focused
    tests and Playwright at compact, medium, and expanded widths in light and
    dark (`shellBackButton(page)` and `pressShellBack(page)` from
    `@jskit-ai/shell-web/test/shellNavigation` drive Up).