@jskit-ai/agent-docs 0.1.273 → 0.1.275

package/guide/agent/app-extras/assistant-conversation.md

@@ -1106,6 +1106,11 @@ The always-visible `avatar-control` slot receives `{ size, height }` beside
 Show/Hide. An application can use it for a collapsed active-mic
 indicator or control without placing voice state in the conversation element.
 The element supplies no audio session or control actions.
+The optional `avatar-thumbnail` slot receives the same scope and replaces the
+collapsed **Show avatar** button's anonymous icon with application artwork, such
+as a still miniature of the avatar about 28 pixels across. The button's round
+32-pixel disc clips it to a circle; its label, title and 44-pixel target stay
+the same. Without the slot the button shows the anonymous icon.
 
 The effective artwork height uses the conversation container's actual remaining
 space after its composer, feedback, support and other controls, leaving a target
@@ -1257,7 +1262,8 @@ surface failures in `error`; return `false` on unsuccessful creation. The shared
 `AssistantGoalControl` owns the form and presentation, not a scheduler or goal
 storage. Supported statuses are `active`, `paused`, `blocked`, `usageLimited`,
 `budgetLimited`, and `complete`. The UI offers creation only without an unfinished
-goal and offers Pause/Resume only for their applicable statuses. `pending`
+goal and offers Pause/Resume only for their applicable statuses. Its menu closes
+after a successful Start or Cancel and stays open after Pause and Resume. `pending`
 disables Set and Resume; `stopPending` disables Pause and Cancel, which the
 supplied binding never blocks on message sending or unknown delivery.
 

package/guide/agent/app-extras/assistant-voice.md

@@ -323,7 +323,11 @@ the `reopen` slot and use `controller.reveal()` from its own header indicator.
 
 The host's `avatar` slot receives `state`, `mouthLevel`, `mouthPose`, `avatar` and
 `binding`. `VoiceAvatar` and `useVoiceAvatar` supply generic presentation; an
-application may provide artwork without acquiring audio ownership.
+application may provide artwork without acquiring audio ownership. A `still`
+avatar (`VoiceAvatar`'s `still` prop, or `still: true` in the props given to
+`useVoiceAvatar`), such as a thumbnail, holds its state's expression: it never
+blinks, gestures, cycles expressions or moves its mouth, and `reducedMotion` is
+true for it, so the artwork can stop its own CSS motion too.
 
 ## Authorized speech connection
 

package/guide/agent/app-setup/material-3-migration.md

@@ -0,0 +1,180 @@
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/site/guide/app-setup/material-3-migration.md`. Do not edit manually. -->
+
+---
+title: Move an app to the Material 3 defaults
+description: What an existing JSKIT app changes, and what it deletes, once its JSKIT packages draw exact Material 3 themselves.
+---
+
+# Move an app to the Material 3 defaults
+
+From this release the JSKIT web packages draw exact Material 3 themselves, in
+light and dark, on phone, tablet and desktop: the shell, its app bar and
+navigation, list-detail pages and the CRUD list, view, new and edit screens.
+An app needs no CSS, overrides or patches of its own to look right, so moving
+an existing app is mostly deleting. [Material 3](../framework/material-3.md)
+describes the result; this page lists what changes in an app's source.
+
+Upgrade the JSKIT packages together first ([Upgrade JSKIT](./upgrading-jskit.md)),
+then work through the sections below. Nothing here changes a feature, field,
+action, permission or validation.
+
+## 1. Theme: one seed, from `@jskit-ai/material-web`
+
+Add `@jskit-ai/material-web` to the app's dependencies and build Vuetify from
+it in `src/main.js`:
+
+```js
+import "vuetify/styles";
+import "@jskit-ai/material-web/client/material.css";
+import { createVuetify } from "vuetify";
+import * as components from "vuetify/components";
+import * as directives from "vuetify/directives";
+import { createMaterialVuetifyOptions } from "@jskit-ai/material-web/client";
+import { theme } from "./theme/index.js";
+
+const vuetify = createVuetify({ components, directives, ...createMaterialVuetifyOptions(theme) });
+```
+
+`src/theme/index.js` holds the app's only theme facts:
+
+```js
+export const theme = {
+  seed: "#6750A4",
+  colors: {},
+  icons: {}
+};
+```
+
+- Delete hand-written `themes: { light: {...}, dark: {...} }` blocks and every
+  hand-picked hex colour. Both schemes come from `seed`, with every Material 3
+  role (`primary-container`, `surface-container-high`, `outline-variant`, ...)
+  as a theme colour.
+- A colour the app really owns (a partner brand, a status of its own) goes in
+  `colors` by camelCase name, such as `partner: "#0A7D3E"`. It becomes
+  `partner`, `on-partner`, `partner-container` and `on-partner-container`,
+  harmonized to the seed, in both schemes. `success`, `warning` and `info` are
+  already there.
+- Delete `defaultTheme: "light"`. The app now follows the device's light or
+  dark setting.
+
+## 2. Delete the app's chrome CSS
+
+Delete, rather than port:
+
+- rules that restyle the shell's app bar, drawer, rail, navigation bar or page
+  title, and every `--shell-*` and `--shell-chrome-*` custom property (the shell
+  no longer reads them);
+- `v-sheet border` panels and outlined cards used as page sections: Material 3
+  cards are elevated (`v-card`, the default) or filled
+  (`variant="flat" color="surface-container-highest"`), and a section on the
+  page needs no frame at all;
+- `!important`, Sass variable overrides and component size or radius tweaks.
+  `material.css` sets 40dp buttons with a 48dp touch target, 12dp cards, 28dp
+  dialogs and sheets, 8dp chips and 16dp FABs, and an app's own props still win.
+
+Use colour roles (`color="secondary-container"`, `bg-color="surface-container-high"`,
+the `on-surface-variant` class) instead of colours.
+
+## 3. Icons: `$aliases`, not `mdi-*`
+
+Replace `mdi-*` strings and `@mdi/js` imports with Vuetify aliases, which are
+Material Symbols Rounded glyphs named in camelCase: `mdi-pencil` becomes
+`$edit`, `mdi-delete` `$delete`, `mdi-cog-outline` `$settings`,
+`mdi-account-circle` `$accountCircle`, `mdi-alert-circle` `$error`,
+`mdi-dots-vertical` `$moreVert`. Then remove `@mdi/js` from `package.json`.
+The full list is `@jskit-ai/material-web/client/symbols`; a glyph JSKIT lacks
+goes in `theme.icons` as its 24x24 path data and works as `$name` everywhere.
+
+## 4. Typography: Material 3 type classes
+
+Vuetify 4 has no Material 2 type classes, so text using them is unstyled.
+Rename them:
+
+| Material 2 class | Material 3 class |
+| --- | --- |
+| `text-h1`, `text-h2`, `text-h3` | `text-display-large`, `text-display-medium`, `text-display-small` |
+| `text-h4`, `text-h5`, `text-h6` | `text-headline-large`, `text-headline-small`, `text-title-large` |
+| `text-subtitle-1`, `text-subtitle-2` | `text-title-medium`, `text-title-small` |
+| `text-body-1`, `text-body-2`, `text-caption` | `text-body-large`, `text-body-medium`, `text-body-small` |
+| `text-button`, `text-overline` | `text-label-large`, `text-label-small` |
+| `text-medium-emphasis` | `on-surface-variant` |
+
+## 5. Pages: titles, parents and the Up arrow
+
+Each page declares its app bar title, and each inner page the page it belongs
+to, in its `definePage()` block:
+
+```js
+definePage({ meta: { jskit: { title: "Edit book", parent: "/books/:bookId" } } });
+```
+
+`parent` is a path on the page's own surface, or `{ surface, path }` for
+another one. A main navigation destination declares no parent and shows no
+arrow. The shell's Up arrow returns to the page the person came from, or else
+to the parent, so:
+
+- delete "Back to X" buttons, `router.back()` and `history.back()` calls;
+- delete redirects from a settings or section landing page to its first child.
+  A settings page is a list-detail page (`ShellListDetail`): on wide windows the
+  list stays beside the open section, and on narrow ones the list is the
+  landing page. Its `index.vue`, if it keeps one, is the empty detail
+  placeholder.
+
+## 6. Page actions go in the app bar
+
+A page's own actions (Save, Edit, Delete, Refresh) move from rows of buttons in
+the content into the app bar:
+
+```vue
+<ShellPageActions>
+  <ShellPageAction icon="$edit" label="Edit" :to="editPath" />
+  <ShellPageAction primary label="Save" @click="save" />
+</ShellPageActions>
+```
+
+At most one action is `primary`; on compact windows the others show as icon
+buttons named by their label.
+
+## 7. CRUD screens
+
+The CRUD screens apply all of this themselves. An app that customized them
+changes:
+
+- **List.** The create action is an extended FAB on compact and medium windows
+  and the app bar's primary action on wider ones. Cards and table rows open the
+  record when tapped; their overflow menu holds the other record actions. A
+  table row's Open is a trailing chevron. Cards no longer show the record's id;
+  a list shows names and figures, never ids.
+  `CrudListRecordActionMenu` takes a `title` (the record's title, for its
+  accessible name) instead of `buttonLabel`, `buttonVariant` and `buttonSize`.
+  Filters are one chip row; the Filters chip opens every control in a bottom
+  sheet (compact) or a dialog.
+- **View.** Drop `resource-plural-title` from `CrudViewScreen`. Its `fields`
+  slot is a list of value-first items:
+
+  ```vue
+  <template #fields="{ view }">
+    <v-list-item :title="view.record?.author" subtitle="Author" />
+  </template>
+  ```
+
+- **New and edit.** Cancel and Save are in the app bar. Save, Cancel and delete
+  replace the form's history entry, so Back no longer reopens a finished form.
+  `useCrudDeleteAction()` no longer takes a `router` option.
+- **Translations.** `jskit.http.actions.actions` and `jskit.http.crud.view.backTo`
+  are gone; `jskit.http.crud.list.recordActions` ("Actions for {title}") and
+  `jskit.shell.actions.back` are new.
+
+## 8. The navigation drawer and app tests
+
+The drawer is 360dp wide; `drawerWidth="content"` on `ShellLayout` sizes it to
+its items instead. Medium windows show the navigation rail, whose menu control
+opens the drawer over the page. A modal drawer opens over the app bar, as
+Material 3 draws it, so a browser test that clicked the menu control again to
+close it taps the scrim or presses Escape instead.
+
+## 9. Check it
+
+Look at every screen at 390, 768 and 1280 pixels wide, in light and dark. A
+change that needs app CSS to look right is a JSKIT default to report, not a
+rule to add.

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

@@ -184,6 +184,11 @@ bridges, JSON:API result transformers, `patch-package` patches, and deep
 `.assistant-*` layout overrides that duplicated those framework owners. Keep
 the public assistant surface id and normal page composition unchanged.
 
+The release that makes the JSKIT web packages exact Material 3 also changes
+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.
+
 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