@keenmate/web-components-devkit 1.0.0-rc06 → 1.0.0-rc08

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # Changelog
 
+## [1.0.0-rc08] - 2026-11-04 [PUBLISHED]
+
+### Added
+
+- **Doctor: hard-coded colours in page CSS** (warning). A colour literal (`#hex`, `rgb()` / `hsl()` /
+  `oklch()`, a named colour) on a colour property in a page `<style>`, a `style="…"` or
+  `examples-local.css` stays the same when the theme switch flips the kit to dark. web-treeview's
+  migration kept 10 pages' own `<style>` blocks, and 8 of them had search bars, status bars, badges and
+  panels that didn't follow dark mode. rc07 only flagged rules that restyle a kit class, so nothing
+  reported them. `var()` fallbacks and `light-dark()` pairs pass. A block that shows fixed colours on
+  purpose (a theme gallery, an iOS mockup) opts out with `<style data-kmwc-fixed-colors>`, or one
+  rule with a `/* kmwc-fixed-colors: why */` comment before it (the playground's e2e fixture red).
+- **Doctor: the loader class matches the installed core** (error). Core 6d6b768 renamed the default
+  loader's class from `<prefix>-loader` to `<prefix>__loader`, with no release that emits both. A
+  component that renames its selector before the core bump, or forgets to after it, ships an unstyled
+  loader. No rulebook check sees that, and a VALIDATION-NOTES `## C-NC-8` hides a leftover `.x-loader`
+  (drp has one for other classes). Doctor reads which class the installed core's `render-loader.js`
+  draws and fails on a `src/**/*.css` selector for the other one.
+
+### Fixed
+
+- **Inline `<code>` in dark mode** was the accent colour on a neutral `#2b2b2b` chip: about 3:1, and
+  web-treeview's `#059669` green read dim in prose and tables. The chip is now a step up from the main
+  surface (`oklch(from --kmwc-main-bg calc(l + 0.07) …)`, slate on slate), and the text is a new
+  `--kmwc-inline-code-color`: the accent hue at a lightness of at least 0.8 in dark, the accent as-is in
+  light. An e2e spec checks 4.5:1 for the default, green, navy and amber accents.
+
+## [1.0.0-rc07] - 2026-11-03 [PUBLISHED]
+
+Found migrating web-treeview — each item is something doctor missed or got wrong there.
+
+### Added
+
+- **`kmwc check-pages`** — loads every example page in Chromium at 1440 / 390 / 320px and
+  reports page and console errors, failed requests, custom elements that never get defined and a
+  page wider than the viewport (with the widest elements named). treeview's iOS-Files mockup
+  (`width: 420px`) and theme gallery (`minmax(500px, 1fr)`) pushed a phone sideways and only a
+  browser could tell. Starts the repo's dev server, or `--url` for one already running (the built
+  site on the preview port); `--widths`. It looks inside shadow roots and at text (a long word
+  sticking out of a box that fits), and skips what can't widen the page (code blocks and other
+  scrolling boxes, hidden or fixed layers such as a closed chapter-nav panel). `kmwc sync` adds a
+  `check:pages` script and a `make check-pages` target.
+- **Doctor: accepted deviations** — a rulebook failure whose id heads a section of
+  `VALIDATION-NOTES.md` (`## C-CST-4 / C-CST-10 — …`) is an architectural decision recorded per the
+  rulebook and counts as a pass (`--verbose` lists them). treeview's documented C-CST-4 / C-CSS-1 /
+  C-NC-6 showed as errors.
+- **Doctor: library outputs** — every `./dist/…` target in package.json (`main`, `module`, `types`,
+  `style`, `exports`) must be a file the library build emits, and before the switch the old
+  `lib.name` must equal `kmwc.library.globalName`. The preset's defaults would have renamed
+  treeview's UMD global (`WebTreeView` → `WebTreeview`) and its CSS (`web-treeview.css` →
+  `style.css`) without a word.
+- **Doctor: ports** — a script that pins its own `--port`, a config / Makefile / doc port outside the
+  repo's registry block, and a sibling checkout listening inside it are reported. treeview ran on
+  21111 (docs too), and web-daterangepicker hardcoded treeview's 12300; the check also finds
+  web-multiselect and web-dropzone on 12200 and web-component-framework-test on 12300.
+- **Doctor: analytics** — a Plausible site id another repo also uses is an error (treeview's
+  snippet borrowed web-multiselect's, so its traffic was counted as multiselect's).
+- **Doctor: page CSS the kit covers** — page `<style>` / `examples-local.css` rules on kit-owned
+  selectors (`.kbd`, `kbd`, `mark`, `.pill` …) and one-declaration inline styles a kit class covers
+  (`width` on a field → `.w-*`, `margin-left: auto` → `.push-end`, `margin-top: 1rem` → `.mt-1`)
+  are warnings.
+
+### Changed
+
+- **check-vars: input variables** — in the default mode a component variable is present when it is
+  declared **or** read. A knob that is read but never declared is an input, unset by design:
+  treeview forwards `--wtv-context-menu-*` to core's private `--_km-menu-*` so a page-wide
+  `--km-menu-*` still applies, and declaring them would break that chain — check-vars called all 26
+  dead. A read-with-fallback that isn't in the manifest is now reported as undocumented.
+  `cssVariables.sources` also takes a package path (`@keenmate/web-components-core/dist/menu/styles.js`)
+  for the `--base-*` reads of a core module the component renders.
+
+### Fixed
+
+- **The text "&lt;head&gt;" / "&lt;/body&gt;" on a page no longer receives the injected snippets** —
+  the plugin put the theme / page-config / analytics block after the first `<head…>` match,
+  which also matched `<header>` (a page without `<head>`), and the kit's module script before
+  the first `</body>`, which can be text inside a page's inline script (the kit then landed
+  in that script and broke it). Now: the first real `<head>` tag outside HTML comments, and
+  the last `</body>`. Same failure as web-multiselect's live action-buttons page, where its
+  own Dockerfile's `sed '/<head>/r …'` put the Plausible snippet (an HTML comment) into the
+  page's module script, so no picker got its options.
+- **Headings break instead of widening a phone** — a chapter heading naming an API outside
+  `<code>` (drp's `EV05 · getMonthDataCallback & beforeMonthChangeCallback`) and the examples index
+  title ("Web DateRangePicker" at 2.5rem) had no break opportunity at 320px. `h1`–`h4` get
+  `overflow-wrap: anywhere`; the index title is 2rem on a phone.
+- **A 250px widget fits a 320px phone** — body + card padding left 240px, so an inline calendar
+  widened the page. Below 400px the body pads 0.75rem, cards and example sections 1rem, demo cards
+  and demo areas 0.75rem (264px inside a card).
+- **`mark` no longer splits a word** — the 2px side padding cut a match inside a word apart
+  (core's Search page: "Town send"); `padding: 0`, and a match that wraps keeps its look on both
+  lines (`box-decoration-break: clone`).
+
 ## [1.0.0-rc06] - 2026-11-01 [PUBLISHED]
 
 ### Added

package/README.md

@@ -19,19 +19,18 @@ them in the same shape: `@keenmate/web-components-devkit`.
 > positioning) lives in [`@keenmate/web-components-core`](../web-components-core).
 > Nothing here ships inside a component's bundle.
 
-## What's New in v1.0.0-rc06
+## What's New in v1.0.0-rc08
 
-- **Example pages — `<kbd>`, `<mark>`, field widths and `.push-end`** — Every component documents a keyboard map and most highlight search matches. Pages either left `<kbd>` in the browser's look (core's Interaction page had 18 bare keys) or styled `<mark>` themselves. A `<kbd>` now looks like the spotlight's key hints and a `<mark>` like its match highlight. Native fields are about 20 characters wide, so pages set inline widths; core had 14. A number field is now 7rem by default. `.w-xs` / `.w-sm` / `.w-md` / `.w-lg` (4 / 6 / 9 / 12rem) size a short field, and a `.form-group` still stretches it to the row. `.push-end` moves an item to the end of a `.controls` row. See the playground's WG08 and FC12.
-- **Example pages — phone and contrast fixes** — Inline `<code>` now breaks anywhere. Before, a long identifier such as `resolvePresentation(mode, env, map)` in a heading made a page 350px wide on a 320px screen; code inside a `<pre>` keeps its lines. Muted log text on the light `.log-panel` (`--muted` lines, the seq / time / source cells, the empty placeholder) measured 2.83:1 in the light theme. It now uses `--kmwc-text-color-2`, and a spec checks every tone on both panels in both themes against WCAG AA's 4.5:1. Timeline rows wrap, so on a phone or with a long source name the detail drops under the cells instead of showing one letter per line. `.css-readout` gets a top margin after the demo it measures.
-- **CLI — `kmwc <command> --help` no longer runs the command** — Only a top-level `--help` was handled, and unknown flags were silently ignored, so `kmwc sync --help` did a full sync and overwrote core's hand-written Makefile. Every command now lists the flags it accepts. `--help` / `-h` after any command prints that command's usage and exits 0, and an unknown option is an error (exit 2). A boolean flag no longer takes the next word as its value.
-- **Libraries — `library: false`, `cssVariables: false`, and a doctor that knows the kind** — A repo like web-components-core builds its package with `tsc`. A plain `vite build` (the devkit's library mode) would empty its `dist/`, so `"kmwc": { "library": false }` now makes it refuse to run, while `vite build --mode examples` still builds the site. `"cssVariables": false` turns off the variables-manifest check, so sync stops re-adding `check:vars`. Doctor reads the registry kind (or `kmwc.kind`): a `library` runs only naming-conventions, readme-structure, publish-command and example-pages. On core that drops 12 errors and 4 "suite could not run" warnings that didn't apply to a library.
+- **Doctor — hard-coded colours in example pages** — web-treeview's devkit migration kept each page's own `<style>` block, and on 8 of its 14 pages the search bars, status bars, badges and panels kept their light colours when the theme switch went dark. rc07 only flagged page CSS that restyles a kit class, so nothing reported them. Doctor now warns about a colour literal (`#hex`, `rgb()` / `hsl()` / `oklch()`, a named colour) on any colour property in a page `<style>`, a `style="…"` attribute or `examples-local.css`. `var()` fallbacks, `light-dark()` pairs, custom properties and `rgb(from var(…))` pass, because they follow the theme. A block that shows fixed colours on purpose, such as a theme gallery or a mockup, opts out with `<style data-kmwc-fixed-colors>`, and a single rule with a `/* kmwc-fixed-colors: why */` comment before it.
+- **Doctor — the loader class matches the installed core** — Core 6d6b768 renamed its default loader's class from `<prefix>-loader` to `<prefix>__loader`, with no release that emits both. A component that renames its selector before the core bump, or forgets to after it, ships a loader with no styles. No rulebook check sees that, and a `## C-NC-8` heading in VALIDATION-NOTES.md would hide a leftover `.x-loader` from the BEM check. Doctor reads which class the installed core's `dist/dom/render-loader.js` draws and fails on any selector in the component's `src/**/*.css` that styles the other one. The error names the file and says which side should change.
 
-## What's New in v1.0.0-rc05
+## What's New in v1.0.0-rc07
 
-- **Log panels — one tone set for every log line** — web-components-core's example pages each coloured their log lines with their own classes (`.warn`, `.lv-error`, `data-kind="hook"` …), four schemes mixing severity with "what happened". A `.log-line` now takes one of five tones — `--ok`, `--info`, `--warn`, `--err`, `--muted`, the same names as `.pill` and `.status-dot` (which gain `--info` / `--muted`) — and `--action` marks a "▶ you clicked X" line. Kinds such as hook or callback map onto those tones; the kind itself goes in a cell as text. On `.log-panel--dark` the tones switch to fixed light tints (`--kmwc-console-ok|info|warn|err-color`), so they stay readable on the console in both themes, while a light `.log-panel` follows the page theme. Every line keeps its line breaks and indentation.
-- **Log panels — timeline columns, text logs and an empty placeholder** — The cells `.log-line__seq`, `__time`, `__source` and `__name` turn a line into aligned columns, with the detail after them wrapping in its own column; the name takes the line's tone. A log fed by `textContent` is a `<pre class="log-panel">`, `data-empty="(nothing yet)"` shows while a panel is empty, and `--log-max-height: none` lets a log grow. This replaces the page-local timeline CSS core's Lifecycle and Interaction pages carried.
-- **`.event-log` — the legacy console now renders as `.log-panel--dark`** — Many component pages (web-grid, web-dropzone, web-treeview, the showcases) still use `.event-log` / `.event-entry` / `.event-time` / `.event-name`, which differed slightly from the newer panel (grey base text, 0.8rem, a 200px cap, no columns). It is now the same panel, and an `.event-entry` holding `.event-time` / `.event-name` is a timeline row with an aligned time column and tones, so old and new logs look the same. Other `.event-log` markup — lines without `.event-entry`, page-own classes — only gets the panel look, so existing layouts don't break.
-- **Small helpers — `.mono`, `td.is-highlight`, `.check-list`** — `.mono` sets the monospace font without the code chip, and `textarea.mono` makes a JSON or config editor. `td.is-highlight` (or `th`) tints one table cell, where only whole rows could be highlighted before. `.check-list` stacks checkbox / radio options one per line, a long label wrapping beside its box, with room for a trailing `.pill`. The playground shows everything on the Widgets (WG01–WG07), Form controls (FC11) and Tables (TB06) pages.
+- **CLI — `kmwc check-pages` finds what only a browser can see** — Migrating web-treeview turned up pages that pushed a phone sideways: an iOS-Files mockup 420px wide and a theme gallery built on `minmax(500px, 1fr)`. No static check could have caught that. `kmwc check-pages` loads every example page in Chromium at 1440, 390 and 320px. It reports page and console errors, failed requests, custom elements that never get defined, and pages wider than the viewport, naming the widest elements. It looks inside shadow roots and at long words that overflow their box. It ignores layers that can't widen a page: scrolling code blocks, hidden or fixed layers, a closed chapter-nav panel. It starts the repo's dev server, or `--url` points it at one already running (for example the built site on the preview port), and `--widths` changes the widths. `kmwc sync` adds a `check:pages` script and a `make check-pages` target.
+- **Doctor — catches what the treeview and daterangepicker migrations got wrong** — Doctor now checks that every `./dist/…` target in package.json is a file the library build actually emits, and that the old UMD name matches `kmwc.library.globalName`. Without that, the preset's defaults would quietly have renamed treeview's global (`WebTreeView` → `WebTreeview`) and its CSS (`web-treeview.css` → `style.css`). Doctor also reports scripts that pin their own `--port`, config, Makefile and doc ports outside the repo's registry block, and sibling repos that listen inside it. This found web-daterangepicker on treeview's 12300 and web-multiselect / web-dropzone on daterangepicker's 12200. A Plausible site id that another repo also uses is an error, because treeview's traffic was being counted as web-multiselect's. Page CSS that duplicates kit classes (`.kbd`, `mark`, inline field widths, `margin-left: auto`) is a warning.
+- **Doctor — `VALIDATION-NOTES.md` records accepted deviations** — The rulebook lets a component record an architectural decision instead of following a rule. Doctor still reported those as errors (treeview's C-CST-4, C-CSS-1 and C-NC-6). A rulebook check id used as a `##` heading in `VALIDATION-NOTES.md` (`## C-CST-4 / C-CST-10 — …`) now counts as a pass, and `--verbose` lists them. A mention in plain prose doesn't count.
+- **check-vars — input variables are not dead** — Some component variables are public knobs that are read with a fallback and never declared. Treeview forwards `--wtv-context-menu-*` to core's private `--_km-menu-*` so a page-wide `--km-menu-*` still applies, and declaring them would break that chain. check-vars called all 26 of them dead. In the default mode a variable now counts as present when it is declared or read, and a read-with-fallback missing from the manifest is reported as undocumented. `cssVariables.sources` also takes a package path (`@keenmate/web-components-core/dist/menu/styles.js`) for the `--base-*` reads of a core module the component renders.
+- **Example pages — fit a 320px phone, and injected scripts land in the right place** — A chapter heading that names an API outside `<code>` now breaks instead of widening the page. On a phone the index title is 2rem. Below 400px, body, card and demo padding shrink, so a 250px inline calendar fits inside a card. `mark` no longer splits a word. The Vite plugin now puts its head block after the real `<head>` tag (not `<header>` or the text "<head>"). It puts the kit script before the last `</body>`, so it can no longer land inside a page's inline script and break it. That's the failure web-multiselect's sed-based Dockerfile caused on its live action-buttons page.
 
 ## Catalogue
 
@@ -41,8 +40,8 @@ them in the same shape: `@keenmate/web-components-devkit`.
 | Component | Package | Prefix | Dev port | Links | Devkit | About |
 |---|---|---|---:|---|:---:|---|
 | **web-multiselect** | `@keenmate/web-multiselect` | `ms` | 12100 | [repo](https://github.com/keenmate/web-multiselect) · [examples](https://examples.web-multiselect.keenmate.dev) · [docs](https://web-multiselect.keenmate.dev) · `web-multiselect-showcase` · `web-multiselect-docs` | — | Lightweight multiselect web component with typeahead search, rich content support, and excellent keyboard… |
-| **web-daterangepicker** | `@keenmate/web-daterangepicker` | `drp` | 12200 | [repo](https://github.com/keenmate/web-daterangepicker) · [docs](https://web-daterangepicker.keenmate.dev) · `web-daterangepicker-showcase` | — | Lightweight date picker web component with excellent keyboard navigation and range selection |
-| **web-treeview** | `@keenmate/web-treeview` | `wtv` | 12300 | [repo](https://github.com/keenmate/web-treeview) · `web-treeview-showcase` | — | Lightweight treeview web component with hierarchical data display, search, expand/collapse, drag-drop, and… |
+| **web-daterangepicker** | `@keenmate/web-daterangepicker` | `drp` | 12200 | [repo](https://github.com/keenmate/web-daterangepicker) · [docs](https://web-daterangepicker.keenmate.dev) · `web-daterangepicker-showcase` | ✅ | Lightweight date picker web component with excellent keyboard navigation and range selection |
+| **web-treeview** | `@keenmate/web-treeview` | `wtv` | 12300 | [repo](https://github.com/keenmate/web-treeview) · `web-treeview-showcase` | ✅ | Lightweight treeview web component with hierarchical data display, search, expand/collapse, drag-drop, and… |
 | **web-commandpalette** | `@keenmate/web-commandpalette` | `cp` | 12400 | [repo](https://github.com/keenmate/web-commandpalette) · [examples](https://examples.web-commandpalette.keenmate.dev) | ✅ | Framework-agnostic command-palette web component — modes, multi-step commands, scoped + global search,… |
 | **web-dropzone** | `@keenmate/web-dropzone` | `dz` | 12500 | [repo](https://github.com/keenmate/web-dropzone) | — | Lightweight file dropzone web component with drag-drop, previews, validation, and multiple display modes. |
 | **web-grid** | `@keenmate/web-grid` | `wg` | 12600 | [repo](https://github.com/keenmate/web-grid) · [docs](https://web-grid.keenmate.com) · [showcase](https://web-grid.keenmate.com) | — | Framework-agnostic data grid web component with sorting, filtering, inline editing, and keyboard navigation |
@@ -168,9 +167,11 @@ Every field is optional. Defaults are derived from the package.
     "packageJsonPaths": ["package.json"]         // monorepos: list workspace package.jsons too
   },
   "cssVariables": {                              // false: no variables manifest, no check:vars
-    "sources": ["src/css"],                      // dirs (stylesheets) or explicit files (any type)
+    "sources": ["src/css"],                      // dirs (stylesheets) or explicit files (any type); a package
+                                                 // path (e.g. a core module's CSS) resolves from node_modules
     "internalVariables": ["ms-input-current-width"], // runtime internals, not theming knobs
-    "checkMode": "declared"                      // or "consumed" (var() reads)
+    "checkMode": "declared"                      // declared OR read (an input knob may be read, never set);
+                                                 // "consumed": var() reads only
   },
   "rulebook": {
     "path": "../BlissFramework/guidelines/web-components", // relative to the component; default: the nearest
@@ -362,6 +363,10 @@ kmwc doctor [--json]          devkit checks + package contents + the rulebook's
                               (exit 1 on errors). --verbose lists passes, --no-rulebook skips the
                               suites, --no-pack skips the package-contents check
 kmwc check-vars [--strict]    component-variables.manifest.json ⇔ CSS
+kmwc check-pages [--url u]    every example page in Chromium at 1440 / 390 / 320px: page and console
+                              errors, failed requests, never-defined elements, a page wider than the
+                              viewport. Starts the dev server unless --url (e.g. the built site);
+                              --widths 1440,390,320
 kmwc check-release --tag t    latest ⇔ release version, rc ⇔ -rcN, version not yet on npm
 kmwc new web-<name>           scaffold a component (--prefix, --title, --tag, --dir, --port, --minimal, --register)
                               --adopt: scaffold an ALREADY registered component (its port/prefix) to migrate into
@@ -388,7 +393,41 @@ and example-pages; the others check what a custom element ships (its CSS,
 manifest, overlay).
 When the rulebook isn't checked out (or there's no bash) the suites are
 skipped with a warning — the rulebook stays the single source of truth; the
-devkit never copies its rules.
+devkit never copies its rules. A failure whose check id heads a section of
+`VALIDATION-NOTES.md` (`## C-CSS-1 — Lean strategy`, `## C-CST-4 / C-CST-10 — …`)
+is an accepted deviation — an architectural decision recorded per the rulebook —
+and counts as a pass (`--verbose` lists them).
+
+**What else doctor checks.** Beyond the presets, legacy files, fragment pages and
+generated files:
+
+- **Library outputs** — every `./dist/…` target in package.json (`main`,
+  `module`, `types`, `style`, `exports`) is a file the library build emits. Before
+  the switch to the preset it also compares the old `lib.name` with
+  `kmwc.library.globalName` — a renamed UMD global or CSS file breaks consumers
+  silently.
+- **Ports** — no script pins a `--port` of its own, the repo's configs, Makefile
+  and docs stay inside its registry block, and no sibling checkout (a registry
+  entry at `../<id>`) listens on a port inside it.
+- **Analytics** — no other repo uses the same Plausible site id.
+- **Page CSS** — a page `<style>` or `examples-local.css` rule on a kit-owned
+  selector (`.kbd`, `kbd`, `mark`, `.pill`, `.card` …) and single-declaration
+  inline styles a kit class covers (`width` on a field → `.w-*`,
+  `margin-left: auto` → `.push-end`, `margin-top: 1rem` → `.mt-1`) are warnings.
+  So is a hard-coded colour (`#hex`, `rgb()`, `white` …) in page CSS or a `style="…"`:
+  it stays put when the theme switch flips the kit to dark. `var()` fallbacks and
+  `light-dark()` pairs follow the theme. Fixed colours on purpose (a theme gallery, a
+  mockup, a test fixture) go in a `<style data-kmwc-fixed-colors>` block, or one rule
+  gets a `/* kmwc-fixed-colors: why */` comment right before it.
+- **Loader class** — the component CSS styles the class the *installed* core gives
+  its default loader (`<prefix>__loader` from core 6d6b768 on, `<prefix>-loader`
+  before). Renaming the selector on one side of the core bump leaves the loader
+  unstyled, and a VALIDATION-NOTES `## C-NC-8` would hide the old class from the
+  rulebook.
+
+`kmwc check-pages` is the browser half: it loads every example page and reports
+what doctor can't see in the source — a script error, a 404, a fixed width that
+pushes a phone sideways.
 
 **Package contents.** Doctor runs `npm pack --dry-run` and fails on anything
 dev-only that would reach a consumer's `node_modules`: `CLAUDE.md` at any
@@ -451,7 +490,11 @@ registry edits), and move the component's own code into that layout with
    runner from the old Makefile, the canonical origin from the old
    `examples-copy-link.js`, and internals from the old
    `check-variable-manifest.mjs` (`cssVariables.internalVariables`).
-3. Replace `vite.config.ts` (and any `vite.examples.config.ts`) with
+3. Run `npx kmwc doctor` **before** replacing `vite.config.ts`: it compares the
+   old `lib.name` with `kmwc.library.globalName` and package.json's `dist/`
+   targets with the preset's outputs — set `library.globalName` / `fileName` /
+   `cssFileName` to the published names so nothing gets renamed. Then replace
+   `vite.config.ts` (and any `vite.examples.config.ts`) with
    `defineComponentConfig()`. Move genuinely specific bits to `plugins` and
    `overrides`. Do the same for `playwright.config.ts`.
 4. Pages: delete the `<link href="examples-shared.css">` and the
@@ -468,10 +511,11 @@ registry edits), and move the component's own code into that layout with
 7. Set `"check:vars": "kmwc check-vars"` and run it.
 8. `npx kmwc sync`, then review the diff. Repo-specific Makefile targets move
    to `Makefile.local`.
-9. Check it runs: `npm run dev`, `npm run build`, `npm run build:examples`,
-   `npm run preview:examples`, the e2e tests, and finally `npx kmwc doctor`
-   (devkit + rulebook — rulebook failures are real findings to fix or to
-   document under `## Known limitations`, per the rulebook).
+9. Check it runs: `npm run dev`, `npm run build` (compare `dist/` with the old
+   build), `npm run build:examples`, `npm run preview:examples`, the e2e tests,
+   `npx kmwc check-pages` (and `--url` on the preview port for the built site),
+   and finally `npx kmwc doctor` (devkit + rulebook — rulebook failures are real
+   findings to fix, or architectural decisions to record in `VALIDATION-NOTES.md`).
 
 ### Developing the devkit
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keenmate/web-components-devkit",
-  "version": "1.0.0-rc06",
+  "version": "1.0.0-rc08",
   "description": "Shared dev, example-site and build infrastructure for Keenmate web components: Vite preset, examples kit (chapter nav, copy-link, controls store, shared styles), Playwright preset and the `kmwc` CLI (sync, doctor, check-vars, new, readme).",
   "type": "module",
   "license": "MIT",

package/src/cli/commands/check-pages.js

@@ -0,0 +1,189 @@
+/**
+ * kmwc check-pages — load every example page in a real browser and report what
+ * a reader would hit: page errors, console errors, failed requests, custom
+ * elements that never get defined, and a page wider than the viewport (a fixed
+ * width or a long word that pushes a phone sideways).
+ *
+ * Runs against the repo's own dev server (started here on kmwc.ports.dev), or a
+ * server you already have (--url, e.g. the built site on the preview port).
+ * Widths default to desktop + two phones. Uses the component's own
+ * @playwright/test (see getPeerModule) — `npx playwright install chromium` once.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { getKmwcConfig, getPeerModule, loadPeerModule } from '../../config.js';
+import { getExamplePages } from '../../vite/index.js';
+
+export const DEFAULT_WIDTHS = [1440, 390, 320];
+const VIEWPORT_HEIGHT = 900;
+const SETTLE_MS = 600;
+const VITE_CONFIG_FILES = ['vite.config.ts', 'vite.config.mts', 'vite.config.mjs', 'vite.config.js'];
+const MAX_OFFENDERS = 3;
+// Requests a page doesn't control (favicon probes, analytics in a built site).
+const IGNORED_REQUEST_PATTERN = /favicon\.ico|stats\.keenmate\.services|plausible/;
+
+/** `--widths 1440,390` → [1440, 390]. Pure. */
+export function parseWidths(widthsText) {
+  if (!widthsText) return DEFAULT_WIDTHS;
+  const widths = String(widthsText).split(',').map((width) => Number(width.trim()));
+  if (!widths.length || widths.some((width) => !Number.isInteger(width) || width < 200)) throw new Error(`--widths: "${widthsText}" is not a list of pixel widths ≥ 200`);
+  return widths;
+}
+
+/**
+ * Problems in one page load's report → [string]. Pure — exported for tests.
+ * @param {{ width: number, errors: string[], undefinedElements: string[], scrollWidth: number, clientWidth: number, offenders: string[] }} pageReport
+ */
+export function getPageProblems(pageReport) {
+  const problems = [...pageReport.errors];
+  if (pageReport.undefinedElements.length) problems.push(`never defined: <${pageReport.undefinedElements.join('>, <')}>`);
+  if (pageReport.scrollWidth > pageReport.clientWidth) {
+    const offenderText = pageReport.offenders.length ? ` — widest: ${pageReport.offenders.join(', ')}` : '';
+    problems.push(`page is ${pageReport.scrollWidth}px wide in a ${pageReport.clientWidth}px viewport${offenderText}`);
+  }
+  return problems;
+}
+
+/**
+ * Runs in the page: overflow, undefined custom elements. A culprit is the deepest
+ * element — or the text — past the right edge, outside anything that scrolls or
+ * clips on purpose (a code block, a table wrapper) and outside hidden or fixed
+ * layers (a closed nav panel, a toast), which don't widen the page.
+ */
+function inspectPage(maxOffenders) {
+  const viewportWidth = document.documentElement.clientWidth;
+  // Shadow roots count: a component's own internals can widen the page too.
+  const getParent = (element) => element.parentElement || element.getRootNode().host || null;
+  const describeOne = (element) => `${element.tagName.toLowerCase()}${element.id ? `#${element.id}` : ''}${[...element.classList].slice(0, 2).map((name) => `.${name}`).join('')}`;
+  const describe = (element) => {
+    const host = element.getRootNode().host;
+    return host ? `${describe(host)} › ${describeOne(element)}` : describeOne(element);
+  };
+  const getAllElements = (root) => [...root.querySelectorAll('*')].flatMap((element) => (element.shadowRoot ? [element, ...getAllElements(element.shadowRoot)] : [element]));
+  const checkIsContained = (element) => {
+    for (let current = element; current && current !== document.body; current = getParent(current)) {
+      const style = getComputedStyle(current);
+      if (style.position === 'fixed' || style.visibility === 'hidden' || style.display === 'none') return true;
+      if (current !== element && ['auto', 'scroll', 'hidden', 'clip'].includes(style.overflowX)) return true;
+    }
+    return false;
+  };
+  const allElements = getAllElements(document.body);
+  const pastEdge = allElements.filter((element) => {
+    const box = element.getBoundingClientRect();
+    return box.width > 0 && box.right > viewportWidth + 1 && !checkIsContained(element);
+  });
+  const checkContainsDeep = (element, other) => {
+    for (let current = other; current; current = getParent(current)) if (current === element) return true;
+    return false;
+  };
+  const offenders = pastEdge.filter((element) => !pastEdge.some((other) => other !== element && checkContainsDeep(element, other))).map(describe);
+  // Text past the edge inside a box that fits: a long word with no break opportunity.
+  const textRoots = [document.body, ...allElements.filter((element) => element.shadowRoot).map((element) => element.shadowRoot)];
+  const textNodes = textRoots.flatMap((root) => {
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+    const nodes = [];
+    for (let node = walker.nextNode(); node; node = walker.nextNode()) nodes.push(node);
+    return nodes;
+  });
+  for (const textNode of textNodes) {
+    const parent = textNode.parentElement;
+    if (!textNode.textContent.trim() || !parent || pastEdge.includes(parent)) continue;
+    const range = document.createRange();
+    range.selectNodeContents(textNode);
+    const box = range.getBoundingClientRect();
+    const parentStyle = getComputedStyle(parent);
+    if (box.right > viewportWidth + 1 && !['hidden', 'clip', 'auto', 'scroll'].includes(parentStyle.overflowX) && !checkIsContained(parent)) {
+      offenders.push(`${describe(parent)} "${textNode.textContent.trim().slice(0, 40)}"`);
+    }
+  }
+  const undefinedElements = [...new Set([...document.querySelectorAll(':not(:defined)')].map((element) => element.localName).filter((name) => name.includes('-')))];
+  return {
+    scrollWidth: document.documentElement.scrollWidth,
+    clientWidth: viewportWidth,
+    offenders: [...new Set(offenders)].slice(0, maxOffenders),
+    undefinedElements,
+  };
+}
+
+async function loadPageReport(browser, pageUrl, width) {
+  const page = await browser.newPage({ viewport: { width, height: VIEWPORT_HEIGHT } });
+  const errors = [];
+  page.on('pageerror', (error) => errors.push(`page error: ${error.message.split('\n')[0]}`));
+  page.on('console', (message) => {
+    if (message.type() === 'error') errors.push(`console error: ${message.text().split('\n')[0]}`);
+  });
+  page.on('response', (response) => {
+    if (response.status() >= 400 && !IGNORED_REQUEST_PATTERN.test(response.url())) errors.push(`HTTP ${response.status()}: ${response.url()}`);
+  });
+  page.on('requestfailed', (request) => {
+    if (!IGNORED_REQUEST_PATTERN.test(request.url())) errors.push(`request failed: ${request.url()} (${request.failure()?.errorText})`);
+  });
+  try {
+    await page.goto(pageUrl, { waitUntil: 'networkidle', timeout: 30_000 });
+    await page.waitForTimeout(SETTLE_MS);
+    const inspection = await page.evaluate(inspectPage, MAX_OFFENDERS);
+    return { width, errors: [...new Set(errors)], ...inspection };
+  } catch (error) {
+    return { width, errors: [...new Set([...errors, `load failed: ${error.message.split('\n')[0]}`])], scrollWidth: 0, clientWidth: 0, offenders: [], undefinedElements: [] };
+  } finally {
+    await page.close();
+  }
+}
+
+async function startDevServer(config) {
+  const viteModule = await loadPeerModule(config.root, 'vite');
+  // Vite < 6 resolves to its CJS build here: the API sits on `default`.
+  const createServer = viteModule.createServer || viteModule.default?.createServer;
+  // Run like `npm run dev` in the repo: the preset reads package.json#kmwc from the cwd,
+  // and Vite looks for vite.config there too.
+  process.chdir(config.root);
+  const configFile = VITE_CONFIG_FILES.map((fileName) => join(config.root, fileName)).find((filePath) => existsSync(filePath));
+  const server = await createServer({ root: config.root, configFile: configFile || false, logLevel: 'error', server: { port: config.ports.dev, strictPort: true } });
+  try {
+    await server.listen();
+  } catch (error) {
+    await server.close();
+    throw new Error(
+      `port ${config.ports.dev} is busy (${error.code || error.message}). If that is this repo's dev server, run: kmwc check-pages --url http://localhost:${config.ports.dev}`
+    );
+  }
+  return server;
+}
+
+export async function run(args) {
+  const config = getKmwcConfig(args.root);
+  const widths = parseWidths(args.widths);
+  const pageFiles = Object.values(getExamplePages(config)).map((pagePath) => pagePath.replace(/\\/g, '/').split('/').pop());
+  if (!pageFiles.length) {
+    console.log('kmwc check-pages: no example pages — nothing to check.');
+    return 0;
+  }
+  let chromium;
+  try {
+    ({ chromium } = getPeerModule(config.root, '@playwright/test'));
+  } catch {
+    throw new Error('@playwright/test is not installed in this repo — npm i -D @playwright/test && npx playwright install chromium');
+  }
+
+  const server = args.url ? null : await startDevServer(config);
+  const baseUrl = (args.url || `http://localhost:${config.ports.dev}`).replace(/\/$/, '');
+  const browser = await chromium.launch();
+  let problemCount = 0;
+  try {
+    console.log(`kmwc check-pages — ${pageFiles.length} page(s) × ${widths.join(' / ')}px on ${baseUrl}\n`);
+    for (const pageFile of pageFiles) {
+      const pageProblems = [];
+      for (const width of widths) {
+        for (const problem of getPageProblems(await loadPageReport(browser, `${baseUrl}/${pageFile}`, width))) pageProblems.push(`@${width}px ${problem}`);
+      }
+      problemCount += pageProblems.length;
+      console.log(`${pageProblems.length ? '✗' : '✓'} ${pageFile}${pageProblems.map((problem) => `\n    ${problem}`).join('')}`);
+    }
+  } finally {
+    await browser.close();
+    if (server) await server.close();
+  }
+  console.log(`\n${problemCount ? '✗' : '✓'} ${problemCount} problem(s)`);
+  return problemCount ? 1 : 0;
+}

package/src/cli/commands/check-vars.js

@@ -8,10 +8,12 @@
  *
  * Contract (prefix = kmwc.prefix or manifest.prefix, e.g. `ms`):
  *   - every `--base-*` read via var() must be in baseVariables, and vice versa
- *   - checkMode "declared" (default): every `--<prefix>-*` DECLARED (`--x:`)
- *     must be in componentVariables, and vice versa
- *   - checkMode "consumed": the same, but against `var(--<prefix>-*)` reads (for
- *     components whose public knobs are read-with-fallback, never declared)
+ *   - checkMode "declared" (default): every `--<prefix>-*` DECLARED (`--x:`) or
+ *     READ (`var(--x)`) must be in componentVariables, and vice versa. A read
+ *     without a declaration is an input variable — a public knob that is unset by
+ *     design, e.g. one forwarded to core's menu so a page-wide value still applies
+ *   - checkMode "consumed": only `var(--<prefix>-*)` reads count (for components
+ *     whose knobs are all read-with-fallback; a declared-but-unread name is dead)
  *   - names in kmwc.cssVariables.internalVariables are runtime internals — exempt
  *
  * Undocumented component variables are a warning unless --strict; everything else errors.
@@ -25,7 +27,9 @@ const STYLESHEET_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less', '.pcss
 /**
  * Directories are scanned for stylesheets; a file listed explicitly is read
  * whatever its type — e.g. a built bundle that inlines the compiled CSS, for
- * components whose SCSS generates variable names via interpolation.
+ * components whose SCSS generates variable names via interpolation, or a core
+ * module whose CSS the component renders (`@keenmate/web-components-core/dist/menu/styles.js`
+ * — a package path resolves from node_modules).
  */
 function getStylesheetTexts(sourcePath, stylesheetTexts, isExplicit = true) {
   if (!existsSync(sourcePath)) throw new Error(`cssVariables source not found: ${sourcePath}`);
@@ -37,6 +41,14 @@ function getStylesheetTexts(sourcePath, stylesheetTexts, isExplicit = true) {
   return stylesheetTexts;
 }
 
+/** A source relative to the repo, else a package path (`@scope/pkg/dist/x.js`) under node_modules. */
+function resolveSourcePath(root, sourcePath) {
+  const repoPath = resolve(root, sourcePath);
+  if (existsSync(repoPath) || sourcePath.startsWith('.')) return repoPath;
+  const packagePath = resolve(root, 'node_modules', sourcePath);
+  return existsSync(packagePath) ? packagePath : repoPath;
+}
+
 const mapToRegExpSource = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
 /** Pure verdict — exported for tests. */
@@ -48,7 +60,7 @@ export function checkManifestVariables({ cssText, manifest, prefix, internalVari
   const consumedVariables = new Set([...cssText.matchAll(new RegExp(`var\\(\\s*--(${prefixSource}-[a-z0-9-]+)`, 'gi'))].map((match) => match[1]));
   const consumedBaseVariables = new Set([...cssText.matchAll(/var\(\s*--(base-[a-z0-9-]+)/gi)].map((match) => match[1]));
 
-  const componentVariablesInCss = checkMode === 'consumed' ? consumedVariables : declaredVariables;
+  const componentVariablesInCss = checkMode === 'consumed' ? consumedVariables : new Set([...declaredVariables, ...consumedVariables]);
   const internalVariableSet = new Set(internalVariables);
   const manifestComponentVariables = new Set((manifest.componentVariables || []).map((entry) => entry.name));
   const manifestBaseVariables = new Set((manifest.baseVariables || []).map((entry) => entry.name));
@@ -81,7 +93,7 @@ export async function run(args) {
   const prefix = config.prefix || manifest.prefix;
   if (!prefix) throw new Error('no variable prefix — set kmwc.prefix or "prefix" in the manifest');
 
-  const cssText = config.cssVariables.sources.flatMap((sourcePath) => getStylesheetTexts(resolve(config.root, sourcePath), [])).join('\n');
+  const cssText = config.cssVariables.sources.flatMap((sourcePath) => getStylesheetTexts(resolveSourcePath(config.root, sourcePath), [])).join('\n');
   const verdict = checkManifestVariables({
     cssText,
     manifest,
@@ -90,7 +102,7 @@ export async function run(args) {
     checkMode: config.cssVariables.checkMode,
   });
 
-  const presenceWord = config.cssVariables.checkMode === 'consumed' ? 'consumed via var()' : 'declared';
+  const presenceWord = config.cssVariables.checkMode === 'consumed' ? 'consumed via var()' : 'declared or read';
   const renderSection = (title, names) => `${title} (${names.length}):\n` + names.map((name) => `  --${name}`).join('\n');
   const errors = [];
   const warnings = [];