@viglet/viglet-design-system 2026.3.10 → 2026.3.12

package/README.md

@@ -11,11 +11,13 @@ component, its variants and its props, rebuilt on each commit to `2026.3`. Look
 there before writing a component: the catalogue is the answer to "does this
 already exist".
 
-The six applications that install this package are the consumers it holds itself
+The nine applications that install this package are the consumers it holds itself
 to, declared in [`consumers.json`](consumers.json) rather than remembered: each
-entry names its framework, its chrome, the accent it renders with and the
-subpaths it takes, and CI refuses prose that names a subset as though it were
-the whole set. An eighth is one entry there, and the checks widen with it.
+entry names its framework, its chrome, the accent it renders with, where its
+source is and the subpaths it takes, and CI refuses prose that names a subset as
+though it were the whole set. A tenth is one entry there, and the checks widen
+with it. The file ships in the package, and a consumer holds its own entry to its
+source with [`viglet-ds-consumer-entries`](#keeping-your-entry-in-the-register-true).
 
 Three are Vite consoles (Turing, Shio, Dumont), one is a Vite platform home
 (the Cloud Home), one is a Vite desktop shell (the Roadkeep GUI), one is a Vite
@@ -43,28 +45,29 @@ install to one copy — `npm ls react-hook-form` should say `deduped`.
 A change here is a change to shared chrome, so the question is always what it
 does to Shio, Turing, Dumont, the Cloud Console, the Cloud Home, Schools,
 the Roadkeep GUI, the Openviglet Website and Viglet Docs — and the answer should
-not require a publish. `use:local` walks a products root, so it reaches the first
-three; the other six are checked out elsewhere and `npm pack` into them is the
-loop until that changes (VDS73). The last two take the package by caret range
-rather than pinning it, so they also receive each release the moment they
-install one. From this checkout:
+not require a publish. The last two take the package by caret range rather than
+pinning it, so they also receive each release the moment they install one. From
+this checkout:
 
 ```bash
-pnpm use:local           # build, then push dist into every 2026.3 product on disk
+pnpm use:local           # build, then push dist into every consumer checked out here
 pnpm use:local --list    # show what it would write to, and stop
 ```
 
-It finds the consumers by reading their `package.json`, and finds where each one
-keeps the installed copy by following the link its own package manager made, so
-neither a version bump nor a switch of package manager breaks the loop. Nothing
-in the product's manifest or lockfile changes: `pnpm install` in the product puts
-the published build back.
+It finds each consumer at the `checkout` its entry in `consumers.json` declares,
+relative to this repository, with `{line}` standing for this checkout's version
+line, so a 2026.2 worktree pushes into the 2026.2 products. A declared checkout
+that is not there is named, not skipped in silence, and finding none at all is an
+error. It finds where each consumer keeps the installed copy by following the
+link its own package manager made, so neither a version bump nor a switch of
+package manager breaks the loop. Nothing in the product's manifest or lockfile
+changes: `pnpm install` in the product puts the published build back.
 
-Pass directories to narrow it, and `--no-build` to reuse the `dist` already on
-disk:
+Pass consumer ids or directories to narrow it, and `--no-build` to reuse the
+`dist` already on disk:
 
 ```bash
-pnpm use:local ../shio/2026.3/shio-react --no-build
+pnpm use:local shio --no-build
 ```
 
 One thing it refuses to do: push over a tree whose dependencies are behind. It
@@ -88,8 +91,8 @@ viglet-ds-check-duplicates src
 It fails, naming the import that replaces each local copy:
 
 ```
-src/components/page-header.tsx:18  declares PageHeader
-    replace it with:  import { PageHeader } from "@viglet/viglet-design-system/router"
+src/components/bento-hero.tsx:18  declares BentoHero
+    replace it with:  import { BentoHero } from "@viglet/viglet-design-system/bento"
 ```
 
 One-line re-export shims are the sanctioned pattern and are skipped. When a
@@ -112,6 +115,114 @@ worked through, and drop it once the count is zero. `--json` prints the findings
 for a bot to read; `--manifest <path>` checks against an export list other than
 the installed one.
 
+## Linting a page against the shell
+
+Two rules in [docs/BENTO-AUTHORING.md](docs/BENTO-AUTHORING.md) pass every other
+gate when broken: a page that sets its own width, gutter or vertical rhythm, and a
+stylesheet that sets `--vg-primary` directly instead of through its
+`--vg-primary-*-base` inputs. `viglet-ds-page-lint` checks both. Point it at the
+directories whose pages render inside `BentoShell`:
+
+```bash
+viglet-ds-page-lint src
+```
+
+```
+src/app/home.page.tsx:125  page.column  the page's outermost element sets max-w-7xl px-6 pb-12
+    remove them: BentoShell sets the column, and column="narrow" or "wide" names the other widths
+src/index.css:14  primary.direct  sets --vg-primary
+    claim it through the --vg-primary-base and --vg-primary-foreground-base inputs, light and -dark, at :root
+```
+
+A page is a file ending in `.page.tsx` or `.page.jsx`, and the lint checks the
+outermost element its default export returns. `--page-pattern <regex>` names your
+own convention. It reads pages with the TypeScript compiler, so `typescript` must
+be installed in the product. A deliberate exception takes a reason, in the file:
+
+```ts
+// viglet-ds-allow-page-column -- a kiosk rendered outside the shell
+```
+
+`viglet-ds-allow-primary -- <reason>` does the same for the second rule.
+`--warn` and `--json` work as they do for `viglet-ds-check-duplicates`.
+
+Pass the stylesheet where you re-key the palette to also measure it:
+
+```bash
+viglet-ds-page-lint src --contrast src/index.css
+```
+
+It lays your stylesheet over the preset the way the two cascade and measures every
+token pair your stylesheet changes on both grounds: each `--vg-X` with its
+`--vg-X-foreground`, text and muted text on the page, the accented label on the
+page, and the white label on the accent fill. A pair under 4.5:1 on either ground
+is a finding at the line that declares the token, with both grounds' ratios:
+
+```
+src/index.css:41  contrast.pair  --vg-accent-fg on --vg-background is 3.59:1 on the light ground and 7.53:1 on the dark ground; 4.5:1 needed
+```
+
+It reads `oklch()`, hex, `rgb()`, `hsl()`, `var()` chains and
+`color-mix(in oklab, …)`. Anything else is reported as unread rather than
+guessed. `viglet-ds-allow-contrast -- <reason>` in the stylesheet keeps a pair
+you have signed off.
+
+## Keeping your entry in the register true
+
+`consumers.json` records the subpaths each product takes, and this package's
+guards read it. `viglet-ds-consumer-entries` measures what your source actually imports and
+compares it with your entry there, in both directions. Run it from the product's
+package root, in its own test step:
+
+```bash
+viglet-ds-consumer-entries
+```
+
+It finds your entry by the `name` in your `package.json` (`--consumer <id>`
+names it outright), scans the `sourceRoots` that entry declares, and fails on a
+subpath you import and do not declare, or one you declare and import nowhere:
+
+```
+consumer-entries: shio's source and its entry in consumers.json disagree
+
+  imported, and not declared:
+    ./router  first at src/components/dialog.delete.tsx:17
+```
+
+Tests, stories and comments inside the roots are not counted. A failure means
+the entry here is wrong, so the fix is a change to `consumers.json` in this
+repository. `--json` prints the measurement; `--root <dir>` measures a checkout
+other than the current directory.
+
+## Using it from Claude Code
+
+This repository publishes a Claude Code plugin, `viglet-ds`, for a product that
+installs the package. It serves the component catalogue over MCP, loads a skill
+that points a session at it, adds `/viglet-ds-check` to run the CLIs above
+against the working tree, and denies a write that declares a component the
+package already exports, naming the import to use instead.
+
+The catalogue server is a bin of its own, `viglet-ds-mcp`, so any MCP client can
+start it from a product's install. It has two tools: `find_component` ranks the
+components that do a job, and `read_component` returns one component's purpose,
+props, the contract sections that govern it and an import to start from. The
+authoring contract, the boundary and the token reference are resources
+(`viglet-ds://authoring`, `viglet-ds://boundary`, `viglet-ds://tokens`). The data
+is `dist/catalogue.json`, generated at build time from the declarations you
+compile against and also exported as `./catalogue.json`. A component's purpose is
+its own doc comment, and every exported component has one: the build refuses a
+component that arrives without it.
+
+```
+/plugin marketplace add openviglet/viglet-design-system
+/plugin install viglet-ds@viglet-design-system
+```
+
+With the plugin enabled in a repository's `.claude/settings.json`,
+`viglet-ds-page-reference` writes only the artboards and leaves the skill to the
+plugin. [claude-plugin/README.md](claude-plugin/README.md) has the settings to
+commit and the package range the plugin supports.
+
 ## Setup
 
 ### 1. Import styles
@@ -305,6 +416,14 @@ import {
 } from "@viglet/viglet-design-system";
 ```
 
+`Button` and `GradientButton` take `loading` for an action in flight. The button
+shows a spinner, sets `aria-busy`, ignores a second press (including a form's
+submit) and keeps keyboard focus. Do not pass `disabled` for that: a disabled
+button drops the focus of the control just pressed, just as the result is
+announced. For a control that is unavailable for now, such as a Save with nothing
+to save, pass `aria-disabled="true"`. It stays focusable and ignores activation.
+Keep `disabled` for a control that is genuinely unavailable.
+
 ### App Components
 
 ```tsx
@@ -319,16 +438,25 @@ import {
 ```
 
 A page's chrome — its header, its list, its sidebar — comes from the
-[bento layer](#the-bento-layer) rather than from here. Read the next section
-before reaching for `PageHeader`, `GridList` or `InternalSidebar`.
+[bento layer](#the-bento-layer). It is the only page vocabulary this package
+ships; if you are upgrading from a release that still had `PageHeader`,
+`GridList` or `InternalSidebar`, read the next section.
 
-### Two eras, and which one a new page should use
+### Moving off the console era
 
-This package exports two complete page vocabularies. The **console era** is what the consoles ship on today; the **[bento layer](#the-bento-layer)** is the current one, and Turing has cut over to it. Every console-era export is marked `@deprecated` in its own types, so an editor strikes it through and offers the swap.
+This package used to export two complete page vocabularies. The **console era**
+is gone: `pnpm chrome:census` counts, per consumer checked out beside this
+repository, the source files taking a console-era component — directly or
+through a re-export shim — and it reads zero across all nine, so the eleven
+components below were removed. The **[bento layer](#the-bento-layer)** is what
+remains, and with one chrome left there is nothing to choose between: the
+`SectionCardChromeProvider` that used to declare which one a page rendered in
+went with them.
 
-Nothing is being removed. No product has started cutting over, and a removal will get its own roadmap line rather than arriving as a side effect of this notice — so existing pages keep working and need no rush.
+Each row is a swap rather than a rename: the replacement takes its own props,
+and the note says where the two differ.
 
-| Console era | Use instead | |
+| Removed | Use instead | |
 |---|---|---|
 | `PageHeader` | `BentoHero` | Same title/subtitle/icon, plus a tone — the chip follows the product accent. |
 | `SubPageHeader` | `BentoHero` | With `BentoBackLink` for the back target and `BentoActionsMenu` for the menu. |
@@ -339,9 +467,9 @@ Nothing is being removed. No product has started cutting over, and a removal wil
 | `NavMain` | `BentoNavRail` | |
 | `NavUser` | `BentoUserMenu` | Routes and feature flags arrive as props. |
 | `SubPage` | `BentoEntityShell` | Renders through a render prop, so the shell never learns what an entity is. |
-| `Page`, `PageContent` | — | No single replacement, deliberately: the shell is where a product is itself. Compose `BentoNavRail`, `BentoUserMenu` and `BentoCommandPalette`. |
+| `Page`, `PageContent` | `BentoShell` | Takes the rail, the header's two edges and the page; it owns `main` and the reading column, so a page sets no width. |
 
-`DialogDelete`, `LoadProvider` and `GradientButtonLink` are **not** console-era — the bento layer uses them itself, and they are not deprecated.
+`DialogDelete`, `LoadProvider` and `GradientButtonLink` were never console-era — the bento layer uses them itself, and they are the whole of `./router` now.
 
 ### The mascot
 
@@ -415,8 +543,44 @@ messages={[{
 }]}
 ```
 
+**What the system reports is a `report`, not an assistant message.** A publish,
+a failure or an arrival has a `tone` (one of the mascot's five states), a time,
+a `read` flag and up to three `actions`, and it renders apart from the
+conversation. It never opens a composer, so a dock with no `onSend` lists reports
+on their own. You own the list, as you own the messages:
+
+```tsx
+<VigletAssistant
+  messages={reports}
+  onRead={(id) => markRead(id)}
+  onDismiss={(id) => dismiss(id)}
+/>
+
+const reports = [{
+  id: "publish-q3",
+  role: "report",
+  tone: "error",
+  text: "Could not publish /q3-results.",
+  at: failedAt,
+  actions: [
+    { label: "Retry", onSelect: retry },
+    { label: "Open the page", onSelect: openPage },
+  ],
+}];
+```
+
+Collapsed, the orb counts the unread reports, and the caption is the newest one
+unless you pass `caption`. The mascot's state follows that report's tone unless
+you pass `state`. Pass `unread` a number to count something else. `onRead` fires
+for each unread report when the dock opens or closes, since it was on screen,
+and a dismiss button appears on each report once you pass `onDismiss`. A report
+is announced once, when it arrives, and not again when the dock opens or
+re-renders.
+
 It pins itself to the bottom-right of the viewport; pass `inline` to render it
-in flow and place it yourself. `open` / `onOpenChange` make it controlled,
+in flow and place it yourself. In a bento product, pass it to `BentoShell` as
+`dock` instead: the shell holds the corner, stacks `BentoBackToTop` above the
+dock, and keeps either from covering the other. `open` / `onOpenChange` make it controlled,
 Escape collapses it, and the caption is typed for everyone while a screen reader
 is handed the whole sentence at once.
 
@@ -524,15 +688,23 @@ import type {
 
 ## What's Included
 
-### UI Primitives (41 components)
+### UI Primitives (49 components)
+
+Accordion, Avatar, Badge, Breadcrumb, Button, Card, Checkbox, Dialog, Drawer, DropdownMenu, FloatingFormulasBg, Form, FormActions, FormItemTwoColumns, GlassCard, GradientButton, GradientSwitch, HoverCard, IconPickerDialog, Input, Label, NavigationMenu, Pagination, Popover, Progress, PulseRing, Resizable, SectionCard, Select, Separator, Sheet, Sidebar, Skeleton, Slider, Stepper, StickySaveBar, Switch, Table, Tabs, Textarea, Toaster (sonner), Toggle, ToggleGroup, Tooltip, Tree, UserAvatar, UserMenu, VigletAssistant ([the dock](#the-assistant-dock)), VigletAvatar ([the mascot](#the-mascot))
+
+### App Components (19 components)
+
+AppFooter, AppSwitcher, BackendStatusBanner, BackendStatusProvider, BadgeColorful, BadgeLocale, DialogDelete, ErrorBoundary, GradientButtonLink, LanguageSelect, LanguageSwitcher, LoadProvider, Login, ModeToggle, ModeToggleSidebar, NavSecondary, StartupFirst, ThemeProvider, VigletAppSwitcher
+
+`DialogDelete`, `GradientButtonLink` and `LoadProvider` are imported from `@viglet/viglet-design-system/router`; every other name above comes from the package root. `Login` and `StartupFirst` are compounds — each is a root with named parts on it, the way `Card` is.
 
-Accordion, Avatar, Badge, Breadcrumb, Button, Card, Checkbox, Dialog, Drawer, DropdownMenu, Form, FormActions, FormItemTwoColumns, GradientButton, GradientSwitch, HoverCard, Input, Label, NavigationMenu, Pagination, Popover, Progress, Resizable, SectionCard, Select, Separator, Sheet, Sidebar, Skeleton, Slider, Sonner (Toaster), Stepper, Switch, Table, Tabs, Textarea, Toggle, ToggleGroup, Tooltip, VigletAssistant ([the dock](#the-assistant-dock)), VigletAvatar ([the mascot](#the-mascot))
+### Bento Layer (31 components)
 
-### App Components (23 components)
+AdaptiveSectionCard, BentoActionsMenu, BentoBackLink, BentoBackToTop, BentoCommandPalette, BentoCountTile, BentoDataTable, BentoDiff, BentoEmptyState, BentoEntityShell, BentoEntityTile, BentoFilterBar, BentoFormHero, BentoFormSection, BentoHero, BentoHeroIconPicker, BentoInlineEdit, BentoListPage, BentoNavRail, BentoPaletteTrigger, BentoPanel, BentoSaveBar, BentoScrollSaveBar, BentoSection, BentoShell, BentoShortcutsDialog, BentoStatusMarker, BentoTile, BentoTileGrid, BentoUserMenu, BentoVersionRail
 
-AppFooter, BadgeColorful, BadgeLocale, DialogDelete, GradientButtonLink, LanguageSelect, LoadProvider, ModeToggle, NavSecondary, ThemeProvider
+All from `@viglet/viglet-design-system/bento`, with `@viglet/viglet-design-system/bento.css` beside it. [The bento layer](#the-bento-layer) is what each one is for and how a page composes them; this is the inventory.
 
-Console-era, `@deprecated`, still exported — see [the swap table](#two-eras-and-which-one-a-new-page-should-use): BlankSlate, GridList, InternalSidebar, NavMain, NavUser, Page, PageContent, PageHeader, StickyPageHeader, SubPage, SubPageHeader
+Removed with the console era — see [where each one went](#moving-off-the-console-era): BlankSlate, GridList, InternalSidebar, NavMain, NavUser, Page, PageContent, PageHeader, StickyPageHeader, SubPage, SubPageHeader
 
 ### Hooks
 
@@ -623,6 +795,7 @@ of it:
 ```ts
 import "@viglet/viglet-design-system/bento.css";
 import {
+  BentoShell,
   BentoEntityShell,
   BentoListPage,
   BentoFormHero,
@@ -635,6 +808,104 @@ The stylesheet is a separate import from the components, so a consumer taking
 only the layout maths does not pull CSS it never renders. It reads the preset's
 tokens, so import the preset too.
 
+`BentoShell` is the page frame. It reserves the gutter for the rail you pass,
+lays out the header's leading and trailing edges, holds the corner (the
+`VigletAssistant` you pass as `dock`, with `BentoBackToTop` stacked above it;
+`backToTop={false}` drops the button), and owns `main`: the width, the gutters
+and the vertical rhythm. A page
+inside it sets none of those. Choose the width by name with `column`: `default`,
+`narrow` for a single-question form, `wide` for a table, or `full` for a tool
+that fills the viewport. Each width is a custom property
+(`--bento-column-default`, `--bento-column-narrow`, `--bento-column-wide`) that
+you can redefine at `:root`.
+
+```tsx
+<BentoShell
+  column={isForm ? "narrow" : "default"}
+  rail={<BentoNavRail groups={groups} homeRoute={ROUTES.HOME} />}
+  headerStart={<ProductMark />}
+  headerEnd={<BentoUserMenu accountRoute={ROUTES.ACCOUNT} logoutUrl={ROUTES.LOGOUT} />}
+>
+  <Outlet />
+</BentoShell>
+```
+
+`BentoDataTable` is the list a curator sorts, range-selects and acts on at scale.
+It mounts only the rows in view, so ten thousand cost what twenty do. Pass `rows`,
+`getRowId`, `columns` (a header, a `cell`, and a `sortValue` to make it sortable),
+and optionally `rowActions` for a per-row menu and `selectionActions` for the bar
+that appears over a selection. The arrows move between rows, Shift with an arrow
+or a click extends a selection, and Enter calls `onRowOpen`. The column picker
+reports `onLayoutChange`, and you store the layout, as you do for `BentoListPage`.
+
+```tsx
+<BentoDataTable
+  rows={posts}
+  getRowId={(p) => p.id}
+  getRowLabel={(p) => p.title}
+  label={t("posts")}
+  columns={[
+    { id: "title", header: t("title"), cell: (p) => p.title, sortValue: (p) => p.title, hideable: false },
+    { id: "updated", header: t("updated"), cell: (p) => format(p.updated), sortValue: (p) => p.updated },
+  ]}
+  rowActions={[{ id: "trash", label: t("trash"), icon: IconTrash, tone: "destructive", onSelect: trash }]}
+  selectionActions={[{ id: "trash", label: t("trash"), icon: IconTrash, onSelect: trash }]}
+  onRowOpen={(p) => navigate(p.url)}
+/>
+```
+
+`AdaptiveSectionCard` renders the console's compound form markup — a `Header`
+child and a `Content` child — as a frosted bento section, so a form written that
+way moves without being rewritten. That compound API is the whole difference
+from `BentoFormSection`, which takes the same icon, title and description as
+props. A section whose header it cannot read keeps the frosted surface and all
+of its children; a frosted box that is not part of a form is `BentoPanel`.
+
+**`SectionCardChromeProvider`, `useSectionChrome`, the `SectionChrome` type and
+the `defaultOpen` prop were removed in this release.** They picked between the
+console card and the frosted section, and every consumer finished its cutover —
+so every remaining call site passed `chrome="bento"`, the value it would have got
+anyway. Delete the provider and the hook; the sections beneath render as they
+already did. A `useSectionChrome()` call that drove a product's own branch can be
+replaced by the bento arm of that branch.
+
+**Give every `BentoActionsMenu` item an `id`**, a stable name for the verb such as
+`"post.delete"`, and the same for `BentoEntityShell`'s `extraActions`. It is
+rendered as `data-action-id` and means nothing to the package, but it lets a
+product check its console verbs against its agent's, since a menu item is
+otherwise an anonymous `onSelect`. An item without one warns outside production
+in this release and stops type-checking in the next.
+
+`BentoFilterBar` is the query row above a list: a search field, the facets you
+declare (a `choice` of options, single or `multiple`, or a `date` range), the
+active filters as removable chips, and a clear-all. It holds no state. You pass
+`value` and get one `onChange` per action, typing included once it pauses, so the
+value can live in the URL and a filtered view is a link. Pass it to a
+`BentoDataTable` as `selectionScope` too, and a selection clears when the filters
+change the rows:
+
+```tsx
+<BentoFilterBar
+  value={filters}
+  onChange={setFilters}
+  facets={[
+    { id: "state", kind: "choice", label: t("state"), multiple: true, options: states },
+    { id: "updated", kind: "date", label: t("updated") },
+  ]}
+/>
+<BentoDataTable rows={filtered} selectionScope={JSON.stringify(filters)} … />
+```
+
+`BentoDiff` compares two versions of structured content field by field, for
+revision history, a review of what an agent changed, or a translation against its
+source. Pass `before`, `after` and the `fields` to compare. A field is `text`
+(compared by word), `rich` (HTML, compared on the blocks it renders, so markup
+alone is no change) or `value` (compared whole). Unchanged fields collapse behind
+a count. A side that is `null` renders the other whole, as a created or deleted
+item. Every change is named in text as well as coloured. `BentoVersionRail` lists
+the revisions (author, person or agent, time) as a listbox a reader picks two
+from, by keyboard or pointer. Neither fetches anything.
+
 `BentoCommandPalette` takes a second group whose items the product supplies per
 query, beside the nav items it matches itself. Pass `onQueryChange` to hear the
 query as typed and `group` to answer it:
@@ -654,11 +925,27 @@ already ranked them by relevance it understands, and a substring match here
 would only undo that. Set `pending` while the query is in flight so the dialog
 says so rather than showing an empty list that is not empty yet.
 
+Bind the shell's keys with `useBentoShellShortcuts` rather than a keydown listener
+of your own. ⌘K on macOS, Ctrl+K elsewhere, or `/` calls `onPalette`, and `?`
+calls `onShortcuts`. A bare key typed into an input, a textarea, a select or an
+editable node is left to the field. `BentoPaletteTrigger` is the header button,
+with the same chord as its hint, and `BentoShortcutsDialog` lists the same set
+(`BENTO_SHELL_SHORTCUTS`), so the guide shows exactly the keys that work:
+
+```tsx
+useBentoShellShortcuts({
+  onPalette: () => setPaletteOpen((open) => !open),
+  onShortcuts: () => setShortcutsOpen((open) => !open),
+});
+
+<BentoShell headerStart={<><ProductMark /><BentoPaletteTrigger onClick={() => setPaletteOpen(true)} /></>}>
+```
+
 "Carries none of it" is measured rather than claimed. `pnpm run build` ends by
 bundling three fixtures through this package's own `exports` map, and fails if a
 bento module, a bento class name or a run of `bento.css`'s selectors reaches a
 consumer that imported only the root entry. `size-budget.json` records what each
-entry costs: today the whole root entry is 87 KB gzipped and `./bento` 22 KB,
+entry costs: today the whole root entry is 91 KB gzipped and `./bento` 31 KB,
 measured with everything the build externalises left out, so the numbers
 describe this package rather than its dependencies. The preset's
 `--vg-bento-tone-*` tokens are deliberately not counted as the layer: they ship
@@ -672,7 +959,7 @@ correct rather than a leak. The subpath is for a consumer who wants only that
 background.
 
 Every subpath in the table above is also **imported, required and type-checked
-as you would use it** on each build: one fixture pulls all fifteen through the
+as you would use it** on each build: one fixture pulls all seventeen through the
 real `exports` map, a CommonJS probe requires the seven that offer it, and a
 generated TypeScript probe imports a value from each typed entry and uses it —
 so a `types` field resolving to the wrong declarations fails here rather than

package/consumers.json

@@ -0,0 +1,186 @@
+{
+  "why": [
+    "The consumers this package holds itself to, declared rather than remembered.",
+    "The roadmap named Shio and Turing throughout while dumont-react sat on the",
+    "same 2026.3 line consuming the same entries, so one-look claims were being",
+    "checked against two of three. This file is the one place that set lives:",
+    "prose that names a subset as though it were the whole is a test failure,",
+    "not a style note.",
+    "",
+    "VDS73 widened it again, and by more than the line predicted. It expected two",
+    "Next installs; three consumers were absent, because cloud-frontend is a Vite",
+    "SPA nobody had written down either. Being outside the products root that",
+    "`use:local` walks is what kept all three invisible: the loop this package",
+    "offers instead of a publish could not reach them, so nothing ever asked.",
+    "",
+    "`framework` is why the membership could not just grow. A Next consumer takes",
+    "a different set: no `./router`, because the App Router is what replaces",
+    "react-router-dom, and no `./vite`. A guard that assumes every consumer",
+    "resolves `./router` asserts something three of six cannot do.",
+    "",
+    "`chrome` says which surface, and `console` stopped covering it: a platform",
+    "home and a public admissions front door are neither consoles nor bento.",
+    "",
+    "VDS144 made it a measurement. `pnpm chrome:census` counts the source files that",
+    "take a console-era component, from the package or through a product's own",
+    "re-export shim, and holds the field to that count: `console` for a consumer",
+    "that takes one and not ./bento, `mixed` for one that takes both, and anything",
+    "else only at zero. The first reading moved three: Turing had been called",
+    "`bento` with sixteen files still on console-era headers and empty states,",
+    "Dumont `console` while taking ./bento too, and the Cloud Console `console` with",
+    "no console-era import at all. The non-goals that wait for every console to cut",
+    "over are waiting for no entry to say `console` or `mixed`.",
+    "",
+    "VDS147 is that reading arriving. Turing and Dumont finished their cutover, the",
+    "census counted zero console-era imports in all nine, and both entries moved from",
+    "`mixed` to `bento` — which is what allowed the eleven console-era components to",
+    "be removed. The field stays measured rather than retired: it is how the next",
+    "chrome, whatever it is, gets counted instead of remembered.",
+    "",
+    "VDS146 took `console` and `mixed` out of the vocabulary. They named a chrome a",
+    "consumer could still be rendering, and there is no longer one to render: the",
+    "components are gone and so is the provider that picked between them. So the",
+    "census stopped asking a consumer to agree with its own measurement and now",
+    "reports a counted console-era import on its own, which is the only thing left",
+    "that could put one there — a name coming back, in a product, where this",
+    "repository's own removal guard cannot see it.",
+    "",
+    "`accent` is the token set a consumer renders with, and today every one of",
+    "them says `cool`. That is worth recording rather than assuming: VDS23 made",
+    "the brand accent a token so a product could re-key without forking a header,",
+    "and no product has re-keyed yet. The parity digest reads this, so the day one",
+    "does, the digest is required to carry that set.",
+    "",
+    "VDS122 widened it a third time, to nine, and the two it added were invisible",
+    "for a third reason: both take the package by caret range rather than pinning",
+    "it, so each receives a release the moment it installs one, and neither is a",
+    "product — a marketing site and a docs site are not what a guard here goes",
+    "looking for. Both were reached by reading their imports, not by being",
+    "remembered. `viglet-docs` is also the first consumer on a third framework;",
+    "it takes no root entry at all, only `./preset` and the background.",
+    "",
+    "`entries` is what each product imports, and VDS129 is why that is measured",
+    "rather than copied in. A snapshot drifted exactly as it was expected to: the",
+    "Shio entry listed three of the six subpaths its source takes and still said",
+    "`console`, and five other entries had gained or lost a subpath too, while the",
+    "only guard asked whether a declared entry exists and never whether an",
+    "imported one is declared.",
+    "",
+    "`sourceRoots` says where a product's own source is, relative to its package",
+    "root, so the measure is declared rather than guessed. `viglet-ds-consumer-entries`",
+    "reads them from a consumer's checkout and fails in both directions: a subpath",
+    "imported and not declared, and one declared and imported nowhere. Tests and",
+    "stories inside those roots are skipped, since a census test that greps for a",
+    "subpath is counting pages, not taking the entry. This file ships in the package",
+    "so a consumer can run that from its own suite.",
+    "",
+    "`checkout` is where `use:local` finds a consumer, relative to this repository's",
+    "root, with `{line}` standing for the version line this checkout is cut from.",
+    "The loop used to walk the directory above this checkout, which stopped being a",
+    "products root once this repository moved to one worktree per version, and it",
+    "found nothing (VDS130). A consumer not checked out beside this one says",
+    "`offMachine: true` instead, so on a developer's machine a checkout that is not",
+    "there is a failing test rather than a sentence nobody reads."
+  ],
+  "consumers": [
+    {
+      "id": "shio",
+      "name": "Shio",
+      "package": "shio-react",
+      "checkout": "../../shio/{line}/shio-react",
+      "framework": "vite",
+      "chrome": "bento",
+      "accent": "cool",
+      "sourceRoots": ["src", "vite.config.ts"],
+      "entries": [".", "./bento", "./bento.css", "./i18n", "./router", "./styles", "./vite"]
+    },
+    {
+      "id": "turing",
+      "name": "Turing",
+      "package": "turing-app",
+      "checkout": "../../turing/{line}/frontend/apps/turing-app",
+      "framework": "vite",
+      "chrome": "bento",
+      "accent": "cool",
+      "sourceRoots": ["src", "vite.config.ts"],
+      "entries": [".", "./bento", "./bento.css", "./i18n", "./router", "./styles", "./vite"]
+    },
+    {
+      "id": "dumont",
+      "name": "Dumont",
+      "package": "dumont-react",
+      "checkout": "../../dumont/{line}/dumont-react",
+      "framework": "vite",
+      "chrome": "bento",
+      "accent": "cool",
+      "sourceRoots": ["src", "vite.config.ts"],
+      "entries": [".", "./bento", "./bento.css", "./i18n", "./router", "./styles", "./vite"]
+    },
+    {
+      "id": "cloud-console",
+      "name": "Cloud Console",
+      "package": "@viglet/cloud-console",
+      "checkout": "../../cloud/console",
+      "framework": "next",
+      "chrome": "platform-console",
+      "accent": "cool",
+      "sourceRoots": ["src", "next.config.ts"],
+      "entries": [".", "./assets", "./i18n", "./styles"]
+    },
+    {
+      "id": "cloud-frontend",
+      "name": "Cloud Home",
+      "package": "@viglet/cloud-frontend",
+      "checkout": "../../cloud/cloud-frontend",
+      "framework": "vite",
+      "chrome": "platform-home",
+      "accent": "cool",
+      "sourceRoots": ["src", "vite.config.ts"],
+      "entries": [".", "./assets", "./i18n", "./styles", "./vite"]
+    },
+    {
+      "id": "schools",
+      "name": "Schools",
+      "package": "schools",
+      "checkout": "../../../japode/schools",
+      "framework": "next",
+      "chrome": "front-door",
+      "accent": "cool",
+      "sourceRoots": ["src", "next.config.ts"],
+      "entries": [".", "./fonts", "./preset", "./styles"]
+    },
+    {
+      "id": "roadkeep-gui",
+      "name": "Roadkeep GUI",
+      "package": "@rk/ui",
+      "checkout": "../../../alegauss/roadkeep-gui/packages/ui",
+      "framework": "vite",
+      "chrome": "bento",
+      "accent": "amber",
+      "sourceRoots": ["src", "vite.config.ts"],
+      "entries": [".", "./bento", "./bento.css", "./fonts", "./i18n", "./styles"]
+    },
+    {
+      "id": "openviglet-website",
+      "name": "Openviglet Website",
+      "package": "openviglet-website",
+      "checkout": "../../site",
+      "framework": "vite",
+      "chrome": "marketing-site",
+      "accent": "cool",
+      "sourceRoots": ["src", "vite.config.ts"],
+      "entries": [".", "./floating-formulas-bg.css", "./preset", "./styles"]
+    },
+    {
+      "id": "viglet-docs",
+      "name": "Viglet Docs",
+      "package": "viglet-docs",
+      "checkout": "../../vigletdocs/vigletdocs.github.io",
+      "framework": "docusaurus",
+      "chrome": "docs-site",
+      "accent": "cool",
+      "sourceRoots": ["src", "docusaurus.config.ts"],
+      "entries": ["./floating-formulas-bg", "./floating-formulas-bg.css", "./preset"]
+    }
+  ]
+}