@keenmate/web-components-devkit 1.0.0-rc05 → 1.0.0-rc07

package/CHANGELOG.md

@@ -1,5 +1,119 @@
 # Changelog
 
+## [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
+
+- **`<kbd>` and `<mark>`** — every component documents a keyboard map and most highlight
+  search matches, and pages either left them in the browser's look (core's Interaction page:
+  18 bare `<kbd>`s) or styled them locally (core's Search page). A `<kbd>` now looks like the
+  spotlight's key hints and a `<mark>` like its match highlight. Widgets page WG08.
+- **Field widths** — a native field is ~20 characters wide, so pages set inline widths (core:
+  14). A number field is now 7rem (six digits and the spin buttons; a `.form-group` still
+  stretches it), and `.w-xs` / `.w-sm` / `.w-md` / `.w-lg` (4 / 6 / 9 / 12rem) size a short
+  field. `.push-end` moves an item to the end of a `.controls` row. Form controls page FC12.
+- **`kmwc.library: false`** — for a repo that builds its package itself (core: `tsc`) or ships
+  none. Plain `vite build`, the devkit's library mode, refuses to run instead of emptying
+  `dist/`; `vite build --mode examples` still builds the site, and sync no longer proposes a
+  `build: vite build` script. `{ "shouldBuild": false, "entry": … }` keeps the pages' entry.
+- **`kmwc.cssVariables: false`** (or `checkMode: "off"`) — sync stopped re-adding `check:vars`
+  only when there was no manifest; now it can be switched off (core builds its variable names
+  by interpolation, which the checker can't see). `kmwc check-vars` then skips.
+- **Doctor knows libraries** — a repo whose registry entry (or `kmwc.kind`) is `library` runs
+  only the rulebook suites that apply to it: naming-conventions, readme-structure,
+  publish-command, example-pages. The CSS, Custom Elements Manifest, overlay and
+  component-structure suites check what a custom element ships; on core they gave 12 errors
+  and 4 "suite could not run" warnings. No prefix warning for a library.
+
+### Fixed
+
+- **`kmwc <command> --help` ran the command** — only a top-level `--help` was handled and
+  unknown flags were ignored, so `kmwc sync --help` did a full sync (it overwrote core's
+  Makefile). `--help` / `-h` after any command now prints that command's usage and exits 0,
+  and an unknown option is an error (exit 2). Every command declares its flags; a boolean
+  flag no longer swallows the next word as its value.
+- **Inline `<code>` widened a phone page** — a long identifier has no break opportunity, so
+  `resolvePresentation(mode, env, map)` in a heading made core's page 350px wide at 320px.
+  Inline code now breaks anywhere; code in a `<pre>` keeps its lines.
+- **Muted log text failed contrast on the light panel** — `--muted` lines, the seq / time /
+  source cells and the empty placeholder used `--kmwc-text-color-3`: 2.83:1 on the light
+  `.log-panel` in the light theme (WCAG AA wants 4.5:1). They now use `--kmwc-text-color-2`.
+  A spec checks every tone on both panels in both themes.
+- **`.css-readout` sat on the demo above it** — it had no top margin (core carried 8 inline
+  margins); it now has 0.75rem.
+
+- **Timeline log lines on a phone** — the cells (`.log-line__seq`, `__time`, `__source`,
+  `__name`) never shrink and the row never wrapped, so on a narrow panel, or with a long
+  source name, the detail got the few pixels left over: one letter per line. The row now
+  wraps, and the detail wants ~14rem beside the cells; with less room it drops under them at
+  full width. Wide panels are unchanged. A cell is capped at the panel width.
+
 ## [1.0.0-rc05] - 2026-11-01 [PUBLISHED]
 
 ### Changed

package/README.md

@@ -19,18 +19,20 @@ 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-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.
 
-## What's New in v1.0.0-rc04
+## What's New in v1.0.0-rc06
 
-- **Example-page grids — wide content scrolls instead of widening the page** — A `<pre>` or table inside a `.grid`, `.grid-2` or `.card-grid` item still pushed the page wider than a phone: grid items default to `min-width: auto` (their min-content), so the single `1fr` column at ≤ 768 px grew to fit the content instead of letting it scroll. Every item of the three grids now gets `min-width: 0`, the same rule pure-css puts on its `.pc-col-*` columns. Found by two agents migrating web-components-core's example pages, which drop their page-local workaround with this release.
-- **`.controls` — long `<code>` in a button wraps on a phone** — rc03 wrapped `<code>` only inside `.controls` labels, so a button whose label was an unbroken API name (`setAttribute("…")`) still overflowed the row. The wrap rule (`overflow-wrap: anywhere`) now covers any `<code>` in a `.controls` row, and a `.controls` button is capped at the row width. An e2e spec injects both cases at 390 px and checks that the page stays inside the screen.
-- **Playground — a Widgets page for the kit's opt-in helpers** — `.log-panel` (light and `--dark`), the legacy `.event-log`, `.pill` / `.status-dot` tones, `.display-sliders` and `.css-readout` had no demo, so their look was only checked on component pages. The new `examples-widgets.html` (WG01–WG04) shows them as they are today, including the gaps the coming log-tone work fixes (no line tones, leading spaces collapsing in a log line), and gets its own e2e spec.
+- **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.
 
 ## Catalogue
 
@@ -40,8 +42,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 |
@@ -142,7 +144,8 @@ Every field is optional. Defaults are derived from the package.
   "tagline": "Feature-rich multiselect …",       // default: package.json description
   "tag": "web-multiselect",
   "prefix": "ms",                                // reserved CSS prefix (rulebook base-variables.md)
-  "library": {
+  "kind": "component",                           // default: the components.json entry's kind
+  "library": {                                   // false: no library build (see below)
     "entry": "src/index.ts",                     // default
     "globalName": "MultiSelect",                 // UMD global
     "fileName": "multiselect",                   // → dist/multiselect.js + .umd.js
@@ -165,10 +168,12 @@ Every field is optional. Defaults are derived from the package.
     "runner": "podman",
     "packageJsonPaths": ["package.json"]         // monorepos: list workspace package.jsons too
   },
-  "cssVariables": {
-    "sources": ["src/css"],                      // dirs (stylesheets) or explicit files (any type)
+  "cssVariables": {                              // false: no variables manifest, no check:vars
+    "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
@@ -179,6 +184,16 @@ Every field is optional. Defaults are derived from the package.
 }
 ```
 
+**A library** (registry `kind: "library"`, e.g. web-components-core) builds its
+package itself (`tsc`) or ships none. `"library": false` (or `{ "shouldBuild":
+false, "entry": … }` to keep the pages' entry script) makes plain `vite build`
+refuse to run — it is the devkit's library mode and would empty `dist/` — while
+`vite build --mode examples` still builds the site, and `kmwc sync` no longer
+proposes a `build: vite build` script. `"cssVariables": false` turns off the
+manifest check (no `check:vars` script, `kmwc check-vars` skips), for variables
+the checker can't see, such as names built by string interpolation. Doctor runs
+only the rulebook suites that apply to a library (see below).
+
 ### Vite preset
 
 ```ts
@@ -265,7 +280,8 @@ doctor` lists the ones still repeating the head/header boilerplate.
   `.demo-area`, `.demo-card`, `.code-block`, `.note(.warning|.info|.success|.error)`,
   `.grid`/`.card-grid`, `.reference-table` (+ `.table-*` modifiers), `.log-panel`, `.pill`,
   `.status-dot`, `.control-group`, buttons (`.btn-secondary`, `.btn-outline`,
-  `.btn-danger`) — while everything the kit **generates** is prefixed BEM
+  `.btn-danger`), `<kbd>` keys and `<mark>` search matches (the spotlight's look),
+  `.push-end` (to the end of a flex row) — while everything the kit **generates** is prefixed BEM
   (`kmwc-chapter-nav__item--active`, `kmwc-copy-link--copied`, …).
 - **Form controls** look the same on every page without a class: text fields,
   selects and list boxes (`multiple` / `size`), textareas, checkboxes, radios,
@@ -275,7 +291,9 @@ doctor` lists the ones still repeating the head/header boilerplate.
   selects and buttons share `--kmwc-control-height`, so a row of them lines up
   in any container, not only `.controls`. The rules are zero-specificity
   (`:where()`); `kmwc-native` on an element or an ancestor keeps the browser's
-  own controls (a light-DOM component that draws its own inputs). The
+  own controls (a light-DOM component that draws its own inputs). A number field
+  is 7rem wide; `.w-xs` / `.w-sm` / `.w-md` / `.w-lg` (4 / 6 / 9 / 12rem) size a
+  short field without an inline style. The
   playground's `examples-forms.html` shows them all.
 - **Tables:** any `<table>` gets a header fill, row lines and a hover tint;
   `.reference-table` is the full-width, fully bordered API table. Modifiers
@@ -347,12 +365,20 @@ 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
 kmwc readme [--check]         regenerate this README's catalogue (devkit repo only)
+kmwc <command> --help         that command's usage — never runs the command
 ```
 
+An unknown option is an error (exit 2), never ignored — a typo can't run a
+command with its defaults.
+
 Generated files start with a `GENERATED by kmwc sync` header. Repo-specific
 make targets go in `Makefile.local`, which the generated Makefile includes at
 the end. Per-developer overrides (`DOCKER_RUNNER`, `IMAGE_PORT`) go in
@@ -364,9 +390,36 @@ and the e2e suite before building and publishing.
 base-variables, color-scheme, readme-structure, custom-elements-manifest,
 responsive-overlay, publish-command, example-pages) with `bash`, passing `kmwc.prefix`, and
 reports each `FAIL` as an error pointing at the matching `.checks.md` entry.
+A `library` runs only naming-conventions, readme-structure, publish-command
+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.
+
+`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
@@ -429,7 +482,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
@@ -446,10 +503,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-rc05",
+  "version": "1.0.0-rc07",
   "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/args.js

@@ -1,16 +1,39 @@
-/** Tiny flag parser: --flag, --key value, --key=value, positionals. */
-export function parseArgs(args) {
+/**
+ * Flag parser: --flag, --key value, --key=value, positionals. `flagSpec` names
+ * every flag a command takes — `booleans` never take a value, `values` always
+ * do. Anything else is an error: an ignored typo (or `--help` before it was
+ * handled) used to run the command for real.
+ *
+ * @param {string[]} args
+ * @param {{ booleans?: string[], values?: string[] }} [flagSpec]
+ */
+export function parseArgs(args, flagSpec = {}) {
+  const booleanFlags = new Set(flagSpec.booleans || []);
+  const valueFlags = new Set(['root', ...(flagSpec.values || [])]);
   const out = { _: [] };
   for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    if (!a.startsWith('--')) {
-      out._.push(a);
+    const arg = args[i];
+    if (!arg.startsWith('-') || arg === '-') {
+      out._.push(arg);
       continue;
     }
-    const [key, inline] = a.slice(2).split(/=(.*)/s);
-    if (inline !== undefined) out[key] = inline;
-    else if (args[i + 1] && !args[i + 1].startsWith('--')) out[key] = args[++i];
-    else out[key] = true;
+    if (!arg.startsWith('--')) throw new Error(`unknown option "${arg}"`);
+    const [key, inline] = arg.slice(2).split(/=(.*)/s);
+    if (booleanFlags.has(key)) {
+      if (inline !== undefined) throw new Error(`--${key} takes no value`);
+      out[key] = true;
+    } else if (valueFlags.has(key)) {
+      if (inline !== undefined) out[key] = inline;
+      else if (args[i + 1] !== undefined && !args[i + 1].startsWith('--')) out[key] = args[++i];
+      else throw new Error(`--${key} needs a value`);
+    } else {
+      throw new Error(`unknown option "--${key}"`);
+    }
   }
   return out;
 }
+
+/** True when the arguments ask for help (`--help` or `-h` anywhere). */
+export function checkIsHelpRequested(args) {
+  return args.some((arg) => arg === '--help' || arg === '-h');
+}

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;
+}