@jskit-ai/agent-docs 0.1.289 → 0.1.291

package/reference/autogen/tooling/jskit-catalog.md

@@ -66,6 +66,19 @@ Local functions
 - `buildCatalog({ repoRoot, packagesRoot, outputPath })`
 - `main()`
 
+### `scripts/data-access-files.mjs`
+Exports
+- `ROOT`
+- `lintIgnores({ governed, config })`
+- `sourceFiles(root)`
+Local functions
+- `skipsDirectory(name)`
+- `walk(root, directory, files)`
+- `frameworkPackages(root)`
+- `appEslint(root)`
+- `lintConfigs(root, files)`
+- `skippedPaths(files, skipped)`
+
 ### `scripts/data-access.mjs`
 Exports
 - `checkDataAccess({ projectRoot = process.cwd() } = {})`
@@ -73,7 +86,6 @@ Exports
 - `readTableResourceSources({ projectRoot = process.cwd() } = {})`
 Local functions
 - `escapeRegExp(text)`
-- `skipsDirectory(name)`
 - `blank(text)`
 - `maskStrings(code)`
 - `closingOffset(masked, start)`
@@ -98,16 +110,12 @@ Local functions
 - `readLintDisables(file, source, position)`
 - `readRuntimeCapabilities(file, { code, masked, position })`
 - `isError(setting)`
-- `appEslint(root)`
-- `checkLintConfig(root, files, baseline, report)`
+- `checkLintConfig({ configs, error }, baseline, report)`
 - `checkCapabilities(baseline, uses, report)`
 - `readBaseline(root, report)`
 - `checkBaseline(baseline, excuses, scopes, report)`
-- `walk(root, directory, files)`
-- `frameworkPackages(root)`
 - `checkTables(resources, report)`
 - `checkSystemScopes(scopes, report)`
-- `sourceFiles(root)`
 
 ### `scripts/files.mjs`
 Exports
@@ -188,9 +196,8 @@ Local functions
 ### `scripts/material3.mjs`
 Exports
 - `MATERIAL3_RULES`
-- `checkMaterial3({ projectRoot = process.cwd(), paths = [], navigationOnly = false } = {})`
+- `checkMaterial3({ projectRoot = process.cwd(), paths = [] } = {})`
 - `formatMaterial3Report(result)`
-- `formatNavigationReport(result)`
 Local functions
 - `hexPattern()`
 - `channelColour()`
@@ -201,8 +208,8 @@ Local functions
 - `isFrameworkPackage(projectRoot, directory)`
 - `walk(projectRoot, directory, files, wholeApp = false)`
 - `collectFiles(projectRoot, paths)`
-- `createReporter(file, source, { navigationOnly = false } = {})`
-- `checkCode(code, offset, { report, themed })`
+- `createReporter(file, source)`
+- `checkCode(code, offset, context)`
 - `checkScript(code, offset, context)`
 - `checkCss(css, offset, context)`
 - `checkDeclaration(declaration, context)`
@@ -386,10 +393,23 @@ Local functions
 - `seconds(ms)`
 - `readTestTimeBounds(cwd)`
 
+### `scripts/ui-components.mjs`
+Exports
+- `checkRemovedProps(tags, script, removedProps, report)`
+- `checkVuetifyByNameAttribute(tag, entry, context)`
+- `checkVuetifyByNameCode(code, offset, context)`
+- `readRemovedProps(root)`
+- `readVuetifyComponents(root)`
+Local functions
+- `readExportNames(file, names = new Set(), seen = new Set())`
+- `readComponentImports(script)`
+- `reportByName({ report, vuetifyComponents }, offset, name, how)`
+
 ### `scripts/verify-packages.mjs`
 Exports
 - `main()`
 - `validateApiSummarySurfaces(packageJson)`
+- `validateRemovedProps(packageJson)`
 - `validateCapabilityClosure(packages, { builtinCapabilities = BUILTIN_CAPABILITIES } = {})`
 - `validateMigrations(packageRecord, migrationOwners)`
 - `validateProviderExport(value, label)`

package/skills/jskit/references/data-access.md

@@ -30,8 +30,9 @@ through its handle's calls, and every call takes the call's `options` last:
 | --- | --- |
 | `query({ filters, sort, page, include }, options)` | one page: `{ records, page }` |
 | `queryAll({ filters, sort, include }, options)` | every matching row, for jobs, id lists and one parent's rows |
+| `queryPages({ filters, sort, include }, options)` | every matching row, a page at a time, for work over many rows |
 | `get(id, params, options)` | one record |
-| `aggregate({ measures, groupBy, filters, sort }, options)` | totals, grouped by fields or date buckets |
+| `aggregate({ measures, groupBy, filters, sort, page }, options)` | totals, grouped by fields or date buckets |
 | `create(data, options)`, `findOrCreate({ id, ...data }, options)` | one record; a keyed one, created once |
 | `patch(id, changes, options)`, `delete(id, options)` | one record |
 | `createMany(rows, options)` | many records, or an upsert with `onConflict` |
@@ -55,6 +56,14 @@ function totalsByMonth(options) {
 }
 ```
 
+A grouped `aggregate` answers its groups from one statement, at most
+`pageLimits().request` of them (the resource's `queryMaxLimit`). When there
+are more it throws a 400 coded `RESOURCE_GROUP_LIMIT` instead of answering
+part of them. Narrow the filters, or read the groups in pages, `page: { size,
+number }` with `number` from 1, until a page answers fewer than `size` rows.
+Page numbers are offsets, so read every page before work that changes what
+the filters match.
+
 ## Words
 
 | Word | Meaning |
@@ -152,6 +161,44 @@ whole number exactly, so json-rest-api answers those digits as text rather
 than a rounded number. A value that can grow that large gets a decimal field
 (`precision` and `scale`), whose digits stay text.
 
+A `type: "blob"` field holds bytes the process reads and writes whole, so it
+names `maxBytes`, the most bytes a value holds, and its column holds that much
+too: MySQL's and MariaDB's `BLOB` holds 64 KiB and `MEDIUMBLOB` 16 MiB, while
+PostgreSQL's `bytea` and SQLite's `BLOB` hold more than any limit you would
+name. A blob takes no `search`, `indexed`, `unique`, `sortable`, `defaultTo` or
+`belongsTo`. A write takes a Buffer or a Uint8Array of at most `maxBytes`, or
+null, and refuses anything else with a validation error on the field (422)
+before any statement, a transaction's or a lock's included. A read leaves a
+blob out unless its `fields` names it, and answers it as a Buffer, holding at
+most 16 MiB of the blobs it names, or one record's: `get(id, { fields:
+["image"] }, options)` and `lock()` read one record's; a page of `query()` and
+the ids of `lockMany()` are refused past the records whose `maxBytes` fit 16
+MiB, and each page of `queryPages()` holds no more. `queryAll()`, `lockWhere()`
+and `claim()` read every matching row at once, so they refuse to name a blob,
+and no read names an included table's blob, since an include holds any number
+of records: read it through that table's handle. A join source carries no
+blob. JSON holds no binary, so a JSON:API read and a CRUD contract refuse a
+blob, and a route of its own serves one as the response body. A file people upload (a photo, a
+document) goes to storage through `runtime.uploads` and the table keeps its
+key; a blob is for the few bytes the record itself needs, such as a thumbnail
+or a signature.
+
+```js
+const signatureResource = defineTableResource({
+  name: "signatures",
+  tableName: "signatures",
+  ownership: "workspace",
+  schema: {
+    signedBy: { type: "string", required: true },
+    // MEDIUMBLOB on MySQL and MariaDB
+    image: { type: "blob", maxBytes: 256 * 1024, required: true }
+  }
+});
+
+// One signature's image, read where a route answers it.
+const imageOf = async (id, options) => (await signatures.get(id, { fields: ["image"] }, options)).image;
+```
+
 A package whose features own tables or declare `systemScope` lists
 `runtime.resources` in its descriptor's `capabilities.requires`, or boot
 refuses it; the feature never requires it itself, since it receives its
@@ -197,7 +244,17 @@ A filter on another table's field (`searchSchema: { supplierName: { type:
 "string", actualField: "suppliers.name" } }`) needs that field declared
 `indexed: true` on its own table resource, with a database index on its column,
 even when the join is on the other table's id; `own()` refuses it at startup
-otherwise, naming both.
+otherwise, naming both. That `indexed: true` is the other table's owner letting
+filters search the field. The filter reads that table as the table's own read
+in the caller's scope: its ownership, its owner's row policy and the policies
+contributed to it decide which of its rows can match, in `query`, `queryAll`,
+`queryPages` and `aggregate` alike, and each row matches once, through a
+has-many path too (suppliers filtered by their items' names). `own()` also
+refuses two filters no scope guards: one that reads a `system` table from a
+table that is not `system`, since a request would read it, and one on a field
+the other table hides, which would tell a caller which rows hold a value it
+may not read. For either, the other table's owner answers the ids it matches
+through its owner API, and the filter takes the list: `filters: { supplierIds }`.
 
 A table keyed by a `uuid` or `string` primary key takes its ids as text; an
 `owns` entry's `normalizeId` is only for an id written some other way.
@@ -313,7 +370,11 @@ request, `{ kind: "anonymous" }` for one by no one, and `{ kind: "system" }` or
 `{ kind: "job" }` (a context `forWorkspace` and its kin derived), each with its
 `reason`, for background work. A job names a user only as `actorId`, the
 person it works for ([below](#background-work)), so never read a missing actor
-as an anonymous request.
+as an anonymous request. The owner's policy also receives the capabilities its
+feature requires (and its optional ones), by local name, as `requires`, the
+same ones its setup receives: a policy that needs another feature's answer
+declares that feature's capability in `requires` and reads `requires.<name>`.
+It runs on every read, so what it asks there must be cheap.
 
 ```js
 // good: one predicate on the row being read
@@ -487,8 +548,10 @@ Every filter takes `id`, one id or a list, so `patchWhere({ id: ids },
 changes, options)` and `deleteWhere({ id: ids }, options)` change a known
 list. Each checks every row against the resource first, reads which of the
 rows the caller may touch, then writes each chunk with one statement, in one
-transaction. Audits and change events run once for the batch, so the
-statements are the same for 10 rows as for 200. `patchWhere` and
+transaction. A chunk is 500 rows unless the call passes `chunkSize`, which is
+at least 100: a smaller chunk would send a statement every few rows, as a loop
+does, and is refused before any statement. Audits and change events run once
+for the batch, so the statements are the same for 10 rows as for 200. `patchWhere` and
 `deleteWhere` check the scope and filters on each row once they hold its lock,
 so a row gone meanwhile, or changed so that it no longer matches, is skipped,
 and they take no `missing`. That makes them a compare-and-set on their filters
@@ -559,6 +622,31 @@ or a counter row taken with `lock(id)`. Every lock needs a transaction; SQLite
 runs one transaction at a time, so there is no row lock to take. Take locks in
 one order on every path, a parent before its children.
 
+A lock answers only the rows it locks, with the fields `fields` names, and
+refuses `include` before any statement. Read the locked rows' related records
+after the lock, in the same transaction: `queryAll({ filters: { id: ids },
+include }, txOptions)`, or the related table's read by id list. On PostgreSQL
+every statement sees what had committed when it began, so that read is current.
+On MySQL and MariaDB a plain read inside a transaction sees the snapshot of the
+transaction's first plain read, and a lock that waited does not move it. So
+take the lock before any plain read in the transaction: the reads after it then
+see what the lock's previous holder committed. A related row the work decides
+on (is this seat already booked?) is locked itself, or read after a lock
+that every writer of it takes first.
+
+```js
+// good: the lock is the transaction's first read, so the bookings read after it are current
+const reserve = (seatId, options) => seats.withTransaction(options, async (txOptions) => {
+  await seats.lock(seatId, { ...txOptions, fields: ["status"] });
+  const taken = await bookings.queryAll({ filters: { seatIds: [seatId] } }, txOptions);
+  return taken.length > 0 ? null : bookings.create({ seatId }, { ...txOptions, returning: "id" });
+});
+
+// bad: the read before the lock fixed the snapshot, so a booking committed while the lock waited is missed
+const free = await bookings.queryAll({ filters: { seatIds: [seatId] } }, txOptions);
+await seats.lock(seatId, txOptions);
+```
+
 On MySQL and MariaDB a locking read locks every row it examines, so two rules
 apply there. Lock ids taken from your own scoped reads, never a list straight
 from a request: every id listed is locked, a hidden one too, before it is left
@@ -671,8 +759,10 @@ async function activeDays(memberIds, options) {
   other features, answers `{ query, column }`: the caller's scoped rows under
   that alias (ownership, the row policy and the filters applied) with the
   columns a read answers and the ownership fields (`workspaceId`, `userId`),
-  hidden or not, as join keys; never another hidden column. `column(field)`
-  names each under the alias. The builder comes wrapped, since a builder is
+  hidden or not, as join keys; never another hidden column, and never a blob,
+  so a report's `select("k.*")` holds no unbounded bytes. `column(field)`
+  names each under the alias. A report on the owner's own `scopedQuery()`
+  names the columns it selects, never a blob's. The builder comes wrapped, since a builder is
   thenable and an async function would run it. The report shapes it (select,
   group), names it with `.as()` and joins it, so every owner's scope and row
   policy stay applied. The report lives with the main table's owner, or in a
@@ -702,6 +792,25 @@ async function activeDays(memberIds, options) {
   }
   ```
 
+- A report that asks which of its rows have, or lack, another owner's rows
+  puts that owner's join source in `whereExists` or `whereNotExists`, tied to
+  its own row with `whereColumn`; one that counts them joins the source grouped,
+  as `projectSummary` does. Rows matched by a related row's value ("items
+  whose supplier is named Acme") need no report: a cross-table search filter
+  answers them in a plain read ([Layer 1](#layer-1-the-table-resource)).
+
+  ```js
+  // Knex: report - the caller's projects with no task the caller sees
+  async function idleProjects(options) {
+    const task = await tasks.joinSource({ alias: "k" }, options);
+    const { query } = await projects.scopedQuery({ alias: "p" }, options);
+    const projectId = projects.column("id", "p");
+    return query
+      .whereNotExists(task.query.select(task.column("id")).whereColumn(task.column("projectId"), projectId))
+      .select({ id: projectId, name: projects.column("name", "p") });
+  }
+  ```
+
 - When each owner can answer on its own (keys in, grouped totals out), the
   report is a feature of its own that calls each owner's method and merges the
   answers in memory: one statement per owner, never a call per row.
@@ -721,11 +830,26 @@ async function activeDays(memberIds, options) {
   another field) or `include`, grouped in memory. Never a query per row, however
   the loop is spelled (`for`, `map` with `Promise.all`, a helper called per
   item).
-- `queryAll` reads every matching row, in cursor pages that skip and repeat
-  none. Use it for id lists, one parent's rows and jobs: a read its callers
+- `queryAll` reads every matching row, in cursor pages that each start after
+  the sort values of the page before, so no row is skipped or read twice
+  unless a write moves a row's sort value (the id, by default) past the page
+  while the read runs. Use it for id lists, one parent's rows and jobs: a read its callers
   treat as complete, which a `query` would silently cut at one page. In a
-  request it stops past the request row limit (10,000 rows) with a 400 coded
-  `RESOURCE_ROW_LIMIT`.
+  request it stops past the request row limit (`pageLimits().requestRows`,
+  10,000 rows) with a 400 coded `RESOURCE_ROW_LIMIT`, and never answers part
+  of the rows. A job reads without that limit and holds every row in memory.
+- Work over many rows reads `queryPages` and handles one page at a time:
+  `for await (const records of handle.queryPages(params, options))`. Each
+  page is one statement of up to `pageLimits().server` rows (fewer when its
+  fields name blobs, so it holds at most 16 MiB of them), plus the reads of
+  its includes and of the hidden fields it names, and starts after the sort
+  values of the last row of the page before. So the work may change what the
+  filters match as it goes, and no row still to come is skipped or read twice,
+  as long as it leaves the sort fields' values alone (the id, by default): a
+  row whose sort value moves past the page is read again or not at all. In a
+  request it throws at the same row limit, before the page that passes it.
+  `expectFlatQueries` allows each later page's own statements, as it allows
+  a many-row write's later chunks; work the path does for each page counts.
 
 ```js
 // good: one page of invoices, then all of that page's lines in one read
@@ -741,6 +865,11 @@ for (const invoice of records) {
 // good: a delivery job reads every active subscriber
 const subscribers = await subscriptions.queryAll({ filters: { newsletterId, status: "active" } }, options);
 
+// good: a job over a table of any size marks each page as it reads it
+for await (const records of reminders.queryPages({ filters: { status: "due" } }, txOptions)) {
+  await reminders.patchWhere({ id: records.map((reminder) => reminder.id) }, { status: "sent" }, txOptions);
+}
+
 // bad: the first page only, whatever its size
 const { records: firstPage } = await subscriptions.query({ filters: { newsletterId, status: "active" }, page: { size: 20 } }, options);
 ```
@@ -832,14 +961,21 @@ const SettlementFeature = defineFeature({
   request's `caller.userId`, so a job for a person sees what that person may
   see, and a job for no one its whole scope. Work on one person's rows only
   takes their scope (`forUser`, `forWorkspaceUser`) or filters its reads.
-- A job finds its units with one `aggregate` grouped by the ownership field,
+- A job finds its units with an `aggregate` grouped by the ownership field,
   which a system context may group by (and count distinct) even when the table
-  hides it, then runs each unit scoped to it. A request's aggregate still
-  refuses a hidden field:
+  hides it, then runs each unit scoped to it. It reads the units in pages, all
+  of them before the first runs, since settling a unit changes what the
+  filters match. A request's aggregate still refuses a hidden field:
 
   ```js
   async function settleDue(options) {
-    const due = await cohorts.aggregate({ measures: { cohorts: { count: "id" } }, groupBy: ["workspaceId"], filters: { status: "finished" } }, options);
+    const size = cohorts.pageLimits().request;
+    const due = [];
+    for (let number = 1; ; number += 1) {
+      const page = await cohorts.aggregate({ measures: { cohorts: { count: "id" } }, groupBy: ["workspaceId"], filters: { status: "finished" }, page: { size, number } }, options);
+      due.push(...page);
+      if (page.length < size) break;
+    }
     for (const { workspaceId } of due) {
       await settleWorkspace({ context: systemContext("settle finished weekly leagues for every user").forWorkspace(workspaceId) });
     }
@@ -948,7 +1084,10 @@ participants) reads them with `users.profiles.listByIds(ids, options)`: every
 profile in one call, however many ids, never `query` pages of 100 walked by
 hand or one `findById` per person. `users.settings.listByUserIds(ids, options)`
 does the same for their settings, and `workspaces.listByIds(ids, options)` for
-workspaces.
+workspaces. A report that reads people, their settings, workspaces or
+memberships beside its own rows joins `joinSource({ alias, filters },
+options)` of `users.profiles`, `users.settings`, `workspaces` or
+`workspaces.memberships` ([Layer 5](#layer-5-reports-the-resource-cannot-express)).
 
 An app that had a table resource of its own over a JSKIT table (such as
 `users`) deletes it: its CRUD contract is built on the package's table resource
@@ -1001,6 +1140,38 @@ named with no value, such as `lockVersion: record.lockVersion` on a field
 called `version`, is refused (`options.lockVersion is undefined`), never run
 without it.
 
+### Capability cycles
+
+A capability cycle is a ring of requires: feature A requires a capability that
+feature B provides while B, directly or through others, requires one that A
+provides. An `optional` require closes a ring as a required one does. The
+kernel sets features up in the order their requires give, so it cannot start a
+ring: boot fails before any setup, naming it,
+`Provider capability cycle detected: children -> parents -> children.`
+`startTestFeatures` orders features the same way, so a feature test meets the
+ring before the server does. The same ring between packages, each listing the
+other in its `package.json` dependencies (as importing the other's shared
+table resource needs), fails as
+`Package dependency cycle detected: @local/jobs -> @local/checklists -> @local/jobs`.
+
+Data access makes them easy to write: a parent's owner reads its children
+through their owners while each child's owner checks or advances the parent.
+Keep every require pointing one way:
+
+- The table nearest the root requires none of the owners below it. It provides
+  a small owner API, and the owners below require that.
+- Work that reads several owners together (a parent with its children, a
+  report across them) is a feature of its own that requires each of them, as
+  above and in [Layer 5](#layer-5-reports-the-resource-cannot-express).
+- A package imports another package's shared table resource only when that
+  package does not depend on it back. When two packages need each other's
+  definitions, move those table resources into a package of their own that
+  holds only shared definitions and depends on neither.
+- Never break a ring with a value handed over later (a setter, a capability
+  looked up at call time): a call's destination then depends on what ran
+  before. A setter kept until the split carries typed features' `cycle:`
+  exception ([Optional tokens](typed-features.md#optional-tokens)).
+
 ## Check and judge
 
 Before calling data work done, apply the
@@ -1024,7 +1195,11 @@ test("allocation is flat", () => expectFlatQueries({ environment: process.env, k
 `expectFlatQueries` (from `@jskit-ai/resource-runtime/test`) seeds each size,
 counts the statements the path sends, and fails when a larger size sends more,
 with the counts and the statements repeated most; the later chunks a many-row
-write reports are allowed. `expectScoped` runs the path as owner A before and
+write reports, and the statements of each later page `queryPages()` reads, are
+allowed. It counts only the path's own statements, those
+`run` and the async work it starts send, so another test or a background loop
+using the same Knex meanwhile changes nothing; work a loop started earlier does
+on the path's behalf is not counted either. `expectScoped` runs the path as owner A before and
 after seeding owner B and fails when the answer changes, so it catches a report
 that sums, counts or joins B's rows, not only one that returns them; it also
 fails when the path changed or removed a row of B's. The path runs twice, so it
@@ -1205,5 +1380,11 @@ it. Check and judge, for each file:
   `/* eslint ... */` config that sets one, outside client code;
 - an app file that the app's ESLint config lints without every data-access
   rule as an error (`"jskit/no-direct-knex": "off"`, `dataAccessConfig(files,
-  "off")`), or server code (`src/server`, `src/shared`, `server/`) that it
-  ignores, until `infrastructure` lists that file and rule.
+  "off")`), or server code that it ignores, until `infrastructure` lists
+  that file and rule. Server code is what the base config lints, at the app's
+  root or a package's: its files (`server.js`), `src/` (an app's whole `src/`,
+  `src/jobs/` with it), `server/`, `scripts/`, `bin/` and `config/`.
+
+It reads none of what the app's ESLint config ignores outside server code,
+such as a vendored copy of old code kept beside the app, since no lint reads
+it either, and lists each directory and file it skipped.

package/skills/jskit/references/existing-application-migration.md

@@ -208,7 +208,7 @@ write goes through that table's handle
 | a field's `default:` | `defaultTo:` (`default` is refused, since json-rest-api never read it) |
 | a `createdAt` or `updatedAt` default of now | nothing: drop it, since every handle write stamps them |
 | a CRUD contract that showed every column | a contract shows only its `fields`, so list every field the API showed |
-| reading every row | `queryAll`, which refuses above 10,000 rows, so page with `query()` |
+| reading every row | `queryAll`, which refuses above 10,000 rows in a request; a job over more reads `queryPages()` a page at a time |
 | an app's own wrappers around old calls | the handle method they wrapped, then delete the wrapper |
 
 Handles answer records, `{ id, ...fields }`, with a belongs-to field as the

package/skills/jskit/references/heuristics/placements.md

@@ -60,7 +60,7 @@ Runtime behavior:
 - Runtime resolves the component token as `entry.componentToken || variant.renderers[entry.kind]`.
 - Entries without a resolvable component token do not render.
 - `when()` receives placement context including `app`, `surface`, `target`, `layoutClass`, runtime context, local outlet context, and context contributors.
-- The standard `ShellLayout` uses Material's 12px outer item inset and one `navigationItemSpacing` value (12px by default) for the icon-to-label gap and widest label's logical-end gap. It remeasures its content-aware width after placement, locale, font, surface, spacing, and layout changes. The surface label belongs once in the top app bar; do not add or restore a duplicate drawer subheader. Use `drawerWidth` only when a product needs a fixed width; do not add consumer `.v-navigation-drawer` overrides.
+- The standard `ShellLayout` uses Material's 12px outer item inset and one `navigationItemSpacing` value (12px by default) for the icon-to-label gap and widest label's logical-end gap. Its drawer fits its labels and identity by default, up to Material 3's 360dp, and remeasures that width after placement, locale, font, surface, spacing, and layout changes. The surface label belongs once in the top app bar; do not add or restore a duplicate drawer subheader. Use `drawerWidth` only when a product needs a fixed width (a number) or Material 3's full 360dp (`"material"`); do not wrap `ShellLayout` or add consumer `.v-navigation-drawer` overrides to narrow it.
 - On medium and expanded layouts, closing the standard drawer produces an 80px Material navigation rail by default. Expanded and collapsed icons share one centreline. Use `railWidth` to configure an intentionally denser rail, or `desktopDrawerClosedMode="hidden"` only when another discoverable navigation surface exists.
 - The shell link renderers own rail centring, selected-state treatment, and opaque theme-aware tooltips. Applications should keep supplying the same semantic placement records rather than creating rail-only links or tooltip CSS.
 

package/skills/jskit/references/material-3.md

@@ -179,9 +179,9 @@ Exactly this, and nothing more:
   `createVuetify(createMaterialVuetifyOptions(theme))` with
   `createMaterialVuetifyOptions` from `@jskit-ai/material-web/client`, importing
   `@jskit-ai/material-web/client/material.css`. JSKIT generates the light and
-  dark schemes from the seed at startup (Material Color Utilities
-  `SchemeTonalSpot`, every role in kebab-case such as `surface-container-low`,
-  plus success, warning and info with their containers), with
+  dark schemes from the seed at startup (every role in kebab-case such as
+  `surface-container-low`, plus success, warning and info with their
+  containers), with
   `defaultTheme: "system"` so the person's light, dark or system preference
   applies. The `md3` blueprint and JSKIT's Material 3 Vuetify defaults live in
   material-web; an app keeps no defaults file and never hand-picks a colour. The
@@ -205,6 +205,12 @@ Exactly this, and nothing more:
   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.
+- **Components:** a Vuetify component chosen at run time is imported and
+  passed: `import { VDialog } from "vuetify/components"`, then `:is="VDialog"`
+  or `h(VDialog)`. A JSKIT app registers none globally, so one named as a
+  string (`resolveComponent("v-dialog")`, `is="v-dialog"`) renders nothing
+  (`ui/vuetify-by-name`). A prop a JSKIT package lists as removed (its
+  `jskit.metadata.ui.removedProps` and CHANGELOG) fails `ui/removed-prop`.
 
 ## Exact sizes
 
@@ -254,12 +260,10 @@ dialog, chip or FAB.
   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.
+  widths the bar shows the single `primary` action (a form's Save) and puts
+  the other actions, and the top-right items that don't fit beside the title,
+  in 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), read from
   `useShellWindowSizeClass()`
@@ -272,12 +276,17 @@ dialog, chip or FAB.
   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.
+  destination; placed in a page it draws a section tab. material.css draws an
+  app's own `v-bottom-navigation` the same way, keeping its colour props.
 
 ## Colour
 
 - Use semantic roles through Vuetify props, classes and
   `rgb(var(--v-theme-<role>))`; never a raw colour value in a component.
+- Text in an `on-*` role uses its class or a `color` prop
+  (`class="text-on-surface-variant"`, `<v-icon color="on-surface-variant">`);
+  an app colour's is `class="on-partner"`, which `bg-partner` already sets.
+  Never lower text emphasis with an opacity or `text-medium-emphasis`.
 - Status chips use `color="success"` (or `warning`, `info`, `error`) or the
   container roles (`success-container` with `on-success-container`), and each
   status meaning has its own hue. Never communicate status, selection, validation, or permission through
@@ -310,9 +319,11 @@ dialog, chip or FAB.
   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:** 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
+- **Form:** the bar's close (X) cancels and Save is its filled action. A
+  field keeps its message line (no `hide-details`, no margin under it), so an
+  error appears in place; a field outside a form (search, filter) sets
+  `hide-details`. 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.
@@ -346,11 +357,9 @@ dialog, chip or FAB.
   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.
+- A snackbar never covers the FAB or the actions it reports on: `ShellErrorHost`
+  places it, and a FAB takes layout room (`<v-fab app layout>`, as
+  `ShellPrimaryAction`'s does), so the snackbar shows above it.
 
 ## Adaptive layout
 
@@ -366,16 +375,14 @@ Two commands read application source (no server, no browser) and print each
 finding with its file, line, rule and the section of this page:
 
 ```bash
-npx jskit check                          # in every app's verify: fails on any nav/* rule
-npx jskit check m3                       # the whole app: src/ and packages/
+npx jskit check                          # in every app's verify: fails on any nav/*, m3/* or ui/* finding
+npx jskit check m3                       # these rules alone, the whole app: src/ and packages/
 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).
-`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:
+Both fail on the [navigation rules](#forbidden-in-app-code) and on these;
+nothing excuses a `ui/*` finding:
 
 | Rule | Finds |
 |---|---|
@@ -385,12 +392,12 @@ that makes plain `jskit check`, and so every app's verify, fail on them too:
 | `m3/outlined-card` | `variant="outlined"` or `border` on a card or sheet |
 | `m3/mdi-icon` | `mdi-*` icon strings and `@mdi/js` imports |
 | `m3/fixed-button-height` | `height`/`min-height` on buttons, in props, styles or CSS |
+| `ui/vuetify-by-name` | a Vuetify component named as a string for Vue to resolve |
+| `ui/removed-prop` | a prop the installed JSKIT package lists as removed from that component |
 
 Tests, fixtures, server code and migrations are not checked. A clean check is
-necessary, not sufficient: it cannot see layout, spacing or contrast. A
-[UI pass](ui-pass.md) is the guard for those, because it looks at every
-affected screen at three widths in light and dark; an editor that runs one
-automatically after each plan keeps that guard on every change.
+necessary, not sufficient: layout, spacing and contrast need a
+[UI pass](ui-pass.md), every affected screen at three widths in light and dark.
 
 ### Exceptions
 
@@ -399,16 +406,13 @@ Take the approved route first; none needs an exception:
 - **Brand or partner colours** are theme custom colours, used by name:
   `colors: { partner: "#0A7D3E" }` in `src/theme/index.js`, then
   `<v-chip color="partner">`. A hex string is harmonized toward the seed; a
-  colour that must keep its hue is `{ value: "#F5C518", blend: false }`
-  (Material Theme Builder's Blend switched off), with the same four roles.
+  colour that must keep its hue is `{ value: "#F5C518", blend: false }`, with
+  the same four roles.
 - **Content colours**, colours that are content rather than UI, keep one
-  value in both schemes: an identity palette a person picks and the server
-  stores, avatar and illustration artwork, brand marks (a language's
-  file-type tint), fixed chart series, QR codes, colours written into
-  exported files. They are named exports of plain hex values in
-  `src/theme/palettes.js`, used as they are, never for UI chrome (a theme
-  colour is toned per scheme, so it can't keep an identity the same).
-  Components read them through bindings:
+  value in both schemes: an identity palette a person picks, artwork, brand
+  marks, fixed chart series, QR codes, colours in exported files. They are
+  named exports of plain hex values in `src/theme/palettes.js`, used as they
+  are, never for UI chrome. Components read them through bindings:
 
   ```vue
   <script setup>