npm - @keenmate/web-components-devkit - Versions diffs - 1.0.0-rc06 → 1.0.0-rc07 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/CHANGELOG.md +66 -0
package/README.md +53 -17
package/package.json +1 -1
package/src/cli/commands/check-pages.js +189 -0
package/src/cli/commands/check-vars.js +20 -8
package/src/cli/commands/doctor.js +97 -1
package/src/cli/kmwc.js +9 -0
package/src/cli/repo-checks.js +249 -0
package/src/cli/sync-plan.js +1 -0
package/src/examples/css/base.css +28 -0
package/src/examples/css/content.css +4 -1
package/src/examples/css/index-page.css +4 -0
package/src/vite/index.js +2 -6
package/src/vite/page-composer.js +30 -1
package/templates/Makefile.tmpl +4 -1
package/templates/claude-block.md +4 -1

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,71 @@
 # 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

package/README.md CHANGED Viewed

@@ -19,6 +19,14 @@ 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-rc07
+- **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-rc06
 - **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.
@@ -26,13 +34,6 @@ them in the same shape: `@keenmate/web-components-devkit`.
 - **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.
-## What's New in v1.0.0-rc05
-- **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.
 ## Catalogue
 <!-- kmwc:catalogue:start — generated by `npm run readme`, do not edit inside -->
@@ -41,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 |
@@ -168,9 +169,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 +365,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 +395,31 @@ 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
@@ -451,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
@@ -468,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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@keenmate/web-components-devkit",
-  "version": "1.0.0-rc06",
+  "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/commands/check-pages.js ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 = [];

package/src/cli/commands/doctor.js CHANGED Viewed

@@ -19,8 +19,25 @@ import { spawnSync } from 'node:child_process';
 import { getKmwcConfig, getPortsForBlock, getRegistry, LEGACY_FILES, NON_PAGE_HTML_FILES, PACKAGE_LEAK_RULES, PACKAGE_FILES_EXCLUSIONS } from '../../config.js';
 import { getSyncPlan, getScriptsPlan, CLAUDE_BLOCK_START } from '../sync-plan.js';
 import { checkIsFragment } from '../../vite/page-composer.js';
+import {
+  VALIDATION_NOTES_FILE,
+  loadAcceptedCheckIds,
+  getLibraryOutputMismatches,
+  getLibraryOutputPaths,
+  getLegacyGlobalName,
+  getPortBlockRange,
+  getScriptPortMismatches,
+  loadStalePortMentions,
+  loadSiblingPortCollisions,
+  loadOwnPortsOutsideBlock,
+  loadPlausibleSiteId,
+  loadSharedPlausibleSiteIds,
+  loadKitClassNames,
+  getKitDuplicates,
+} from '../repo-checks.js';
 const DEVKIT_PACKAGE_NAME = '@keenmate/web-components-devkit';
+const LOCAL_STYLESHEET_FILE = 'examples-local.css';
 const LEGACY_PAGE_REFERENCES = ['examples-shared.css', 'examples-chapter-nav.js', 'examples-copy-link.js', 'examples-controls-store.js'];
 const VITE_CONFIG_FILES = ['vite.config.ts', 'vite.config.mjs', 'vite.config.js'];
 const PLAYWRIGHT_CONFIG_FILES = ['playwright.config.ts', 'playwright.config.mjs', 'playwright.config.js'];
@@ -114,6 +131,11 @@ export function checkComponent(config, doctorConfig = {}) {
   if (!viteConfigFile) addError('vite', 'no vite.config.*', 'create one: export default defineComponentConfig()');
   else if (!/defineComponentConfig|createExamplesPlugin/.test(readFileSync(join(config.root, viteConfigFile), 'utf8'))) {
     addError('vite', `${viteConfigFile} doesn't use the devkit preset`, "import { defineComponentConfig } from '@keenmate/web-components-devkit/vite'");
+    // Before the switch: the preset derives the UMD global from kmwc — a silent rename breaks script-tag users.
+    const legacyGlobalName = getLegacyGlobalName(readFileSync(join(config.root, viteConfigFile), 'utf8'));
+    if (legacyGlobalName && config.library.shouldBuild && legacyGlobalName !== config.library.globalName) {
+      addError('vite', `the UMD global is "${legacyGlobalName}" today; the preset would make it "${config.library.globalName}"`, `set kmwc.library.globalName to "${legacyGlobalName}"`);
+    }
   } else addPass('vite', `${viteConfigFile} uses the devkit preset`);
   const playwrightConfigFile = getFirstExistingFile(config.root, PLAYWRIGHT_CONFIG_FILES);
@@ -160,6 +182,21 @@ export function checkComponent(config, doctorConfig = {}) {
     );
   }
+  // Page CSS that re-implements the kit (a local .kbd after the kit styled <kbd>, inline widths …).
+  const kitClassNames = loadKitClassNames();
+  const localStylesheetPath = join(config.root, LOCAL_STYLESHEET_FILE);
+  const kitDuplicateSources = [
+    ...pageFiles.map((pageFile) => ({ file: pageFile, duplicates: getKitDuplicates(readFileSync(join(config.root, pageFile), 'utf8'), kitClassNames) })),
+    ...(existsSync(localStylesheetPath)
+      ? [{ file: LOCAL_STYLESHEET_FILE, duplicates: getKitDuplicates(readFileSync(localStylesheetPath, 'utf8'), kitClassNames, { isStylesheet: true }) }]
+      : []),
+  ].filter((source) => source.duplicates.length);
+  for (const { file, duplicates } of kitDuplicateSources) {
+    const shownDuplicates = duplicates.slice(0, 3).map((duplicate) => `${duplicate.found} → ${duplicate.advice}`).join('; ');
+    addWarning('pages', `${file}: ${duplicates.length} rule(s) / style(s) the kit already covers — ${shownDuplicates}${duplicates.length > 3 ? ' …' : ''}`, 'use the kit (devkit README "Examples kit")');
+  }
+  if (pageFiles.length && !kitDuplicateSources.length) addPass('pages', 'no page CSS re-implements the kit');
   // ── generated files ──────────────────────────────────────────────────────
   if (config.hasPackageConfig) {
     for (const planItem of getSyncPlan(config)) {
@@ -195,12 +232,37 @@ export function checkComponent(config, doctorConfig = {}) {
           `set package.json#kmwc.ports to { "dev": ${registryPorts.dev}, "image": ${registryPorts.image} } (components.json port block ${registryEntry.port})`
         );
       } else addPass('registry', `ports match the registry (dev ${config.ports.dev}, image ${config.ports.image})`);
+      checkPorts(config, registryEntry.port, { addPass, addWarning, addError });
     }
     if (registryEntry.prefix && config.prefix && registryEntry.prefix !== config.prefix) {
       addError('registry', `kmwc.prefix "${config.prefix}" ≠ registry prefix "${registryEntry.prefix}"`, 'use the reserved prefix');
     }
   }
+  // ── library output names ─────────────────────────────────────────────────
+  if (config.hasPackageConfig && config.library.shouldBuild) {
+    const outputMismatches = getLibraryOutputMismatches(config.packageJson, config.library);
+    for (const { field, target } of outputMismatches) {
+      addError(
+        'library',
+        `package.json#${field} → ${target}, but the library build emits ${getLibraryOutputPaths(config.library).join(', ')}`,
+        'set kmwc.library.fileName / cssFileName to the published names (or fix the package.json target)'
+      );
+    }
+    if (!outputMismatches.length) addPass('library', 'package.json targets match the library build outputs');
+  }
+  // ── analytics ────────────────────────────────────────────────────────────
+  const plausibleSiteId = loadPlausibleSiteId(config.root);
+  const sharingRepoIds = loadSharedPlausibleSiteIds(config, getRegistry(), plausibleSiteId);
+  if (sharingRepoIds.length) {
+    addError(
+      'analytics',
+      `Plausible site id ${plausibleSiteId} is also used by ${sharingRepoIds.join(', ')} — one site's traffic is counted as the other's`,
+      "set kmwc.analytics.plausibleSiteId to this site's own id"
+    );
+  } else if (plausibleSiteId) addPass('analytics', `Plausible site id ${plausibleSiteId} is this repo's own`);
   // ── package contents ─────────────────────────────────────────────────────
   if (doctorConfig.shouldCheckPackage !== false) checkPackageContents(config, { addPass, addWarning, addError });
@@ -210,6 +272,33 @@ export function checkComponent(config, doctorConfig = {}) {
   return results;
 }
+/** Ports: script --port flags, own configs and docs outside the block, siblings inside it. */
+function checkPorts(config, portBlock, { addPass, addWarning, addError }) {
+  const [firstPort, lastPort] = getPortBlockRange(portBlock);
+  const blockLabel = `${firstPort}–${lastPort}`;
+  const scriptPortMismatches = getScriptPortMismatches(config.packageJson.scripts, config.ports);
+  for (const { scriptName, port, expectedPort } of scriptPortMismatches) {
+    addError('ports', `script "${scriptName}" pins --port ${port}; kmwc.ports gives ${expectedPort}`, `drop the --port flag (the preset reads kmwc.ports)`);
+  }
+  const ownStrayPorts = loadOwnPortsOutsideBlock(config, portBlock).filter(({ file }) => !file.startsWith('package.json#scripts.'));
+  for (const { port, file } of ownStrayPorts) addError('ports', `${file} uses port ${port}, outside this repo's block ${blockLabel}`, 'take ports from kmwc.ports (the devkit presets do)');
+  const siblingCollisions = loadSiblingPortCollisions(config, getRegistry());
+  for (const { id, port, file } of siblingCollisions) {
+    addError('ports', `${id} uses port ${port} (${file}) — inside this repo's block ${blockLabel}`, `move ${id} to its own components.json block`);
+  }
+  const stalePortMentions = loadStalePortMentions(config.root, portBlock);
+  if (stalePortMentions.length) {
+    addWarning(
+      'ports',
+      `docs mention ports outside ${blockLabel}: ${stalePortMentions.map(({ file, port }) => `${file} ${port}`).join(', ')}`,
+      `update them to ${getPortsForBlock(portBlock).dev} (dev) / ${getPortsForBlock(portBlock).image} (image)`
+    );
+  }
+  if (!scriptPortMismatches.length && !ownStrayPorts.length && !siblingCollisions.length && !stalePortMentions.length) {
+    addPass('ports', `scripts, configs, docs and sibling repos keep to block ${blockLabel}`);
+  }
+}
 /** Packed paths that break PACKAGE_LEAK_RULES → [{ path, label }]. Pure — exported for tests. */
 export function getPackageLeaks(packedPaths) {
   return packedPaths
@@ -260,6 +349,7 @@ function checkRulebook(config, { addPass, addWarning, addError }) {
     return;
   }
   const skippedSuites = new Set(config.rulebook.skippedChecks);
+  const acceptedCheckIds = loadAcceptedCheckIds(config.root);
   const suites = getRulebookSuites(config.kind);
   if (suites.length < RULEBOOK_SUITES.length) {
     const componentOnlySuiteNames = RULEBOOK_SUITES.filter((suite) => !suites.includes(suite)).map((suite) => suite.name);
@@ -280,7 +370,11 @@ function checkRulebook(config, { addPass, addWarning, addError }) {
       continue;
     }
     const failures = getSuiteFailures(suiteResult.stdout);
-    for (const failure of failures) addError(checkName, `${failure.checkId} ${failure.reason}`, `see ${suite.name}.checks.md → ${failure.checkId}`);
+    for (const failure of failures) {
+      // An architectural decision recorded in VALIDATION-NOTES.md (the rulebook's accepted-deviation file).
+      if (acceptedCheckIds.has(failure.checkId)) addPass(checkName, `${failure.checkId} accepted deviation (${VALIDATION_NOTES_FILE}): ${failure.reason}`);
+      else addError(checkName, `${failure.checkId} ${failure.reason}`, `see ${suite.name}.checks.md → ${failure.checkId}`);
+    }
     if (!failures.length) addPass(checkName, suiteResult.status === 0 ? 'all auto checks pass' : `exit ${suiteResult.status}`);
   }
 }
@@ -302,6 +396,8 @@ export async function run(args) {
     if (result.level === 'pass' && !args.verbose) continue;
     console.log(`${LEVEL_ICONS[result.level]} [${result.checkName}] ${result.message}${result.fixHint ? `\n    → ${result.fixHint}` : ''}`);
   }
+  const acceptedCount = results.filter((result) => result.level === 'pass' && result.message.includes(`accepted deviation (${VALIDATION_NOTES_FILE})`)).length;
+  if (acceptedCount && !args.verbose) console.log(`ℹ ${acceptedCount} rulebook failure(s) accepted in ${VALIDATION_NOTES_FILE} (--verbose lists them)`);
   console.log(`\n${errorCount ? '✗' : '✓'} ${errorCount} error(s), ${warningCount} warning(s)${args.verbose ? '' : ' (--verbose lists passing checks)'}`);
   return errorCount ? 1 : 0;
 }

package/src/cli/kmwc.js CHANGED Viewed

@@ -5,6 +5,7 @@
  *   kmwc sync [--check]               regenerate devkit-owned files from package.json#kmwc
  *   kmwc doctor [--json]              check this repo against the devkit + rulebook standard
  *   kmwc check-vars [--strict]        validate component-variables.manifest.json against the CSS
+ *   kmwc check-pages [--url <u>]      every example page in Chromium: errors, undefined elements, overflow
  *   kmwc check-release --tag <tag>    gate a publish (version ⇔ dist-tag, not yet on npm)
  *   kmwc new <name> [options]         scaffold a new component repo next to the devkit
  *   kmwc readme [--check]             regenerate the devkit README catalogue (devkit repo only)
@@ -38,6 +39,14 @@ const COMMANDS = {
     flags: { booleans: ['strict'] },
     usage: `check-vars [--strict]     Validate component-variables.manifest.json against the CSS.`,
   },
+  'check-pages': {
+    load: () => import('./commands/check-pages.js'),
+    flags: { values: ['url', 'widths'] },
+    usage: `check-pages [--url <u>]   Load every example page in Chromium at 1440 / 390 / 320px and report
+                            page/console errors, failed requests, undefined elements and a page
+                            wider than the viewport. Starts the dev server unless --url is given.
+                            --widths 1440,390,320.`,
+  },
   'check-release': {
     load: () => import('./commands/check-release.js'),
     flags: { booleans: ['offline'], values: ['tag'] },

package/src/cli/repo-checks.js ADDED Viewed

@@ -0,0 +1,249 @@
+/**
+ * Repo checks behind `kmwc doctor` that read a component's own files (and its
+ * registry siblings): accepted rulebook deviations, library output names, ports,
+ * analytics ids and page CSS the kit already covers. Each check is a pure
+ * function over text / config where it can be (unit-tested), plus a thin
+ * file-reading wrapper.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { DEVKIT_ROOT } from '../config.js';
+export const VALIDATION_NOTES_FILE = 'VALIDATION-NOTES.md';
+const PORT_BLOCK_SIZE = 100;
+const PLAUSIBLE_SNIPPET_FILE = 'plausible-snippet.html';
+const DOC_FILES = ['README.md', 'CLAUDE.md'];
+const DOCS_DIR = 'docs';
+const SIBLING_PORT_FILES = ['vite.config.ts', 'vite.config.mjs', 'vite.config.js', 'playwright.config.ts', 'playwright.config.mjs', 'playwright.config.js', 'Makefile', 'make.bat'];
+const PORTED_SCRIPTS = { dev: 'dev', preview: 'preview', 'preview:examples': 'preview' };
+const CHECK_ID_PATTERN = /\bC-[A-Z]+-\d+\b/g;
+const readText = (filePath) => (existsSync(filePath) ? readFileSync(filePath, 'utf8') : null);
+const getUniqueSorted = (values) => [...new Set(values)].sort((left, right) => (left > right ? 1 : left < right ? -1 : 0));
+// ── accepted deviations ──────────────────────────────────────────────────────
+/**
+ * Check ids accepted in VALIDATION-NOTES.md: every `C-XX-N` in a `##` heading
+ * (`## C-CST-4 / C-CST-10 — …` accepts both). Only headings count, so prose that
+ * merely mentions a check doesn't accept it.
+ */
+export function getAcceptedCheckIds(notesText) {
+  if (!notesText) return new Set();
+  const headings = notesText.split(/\r?\n/).filter((line) => /^##\s/.test(line));
+  return new Set(headings.flatMap((heading) => heading.match(CHECK_ID_PATTERN) || []));
+}
+export function loadAcceptedCheckIds(root) {
+  return getAcceptedCheckIds(readText(join(root, VALIDATION_NOTES_FILE)));
+}
+// ── library output names ─────────────────────────────────────────────────────
+/** The dist/ files the library build emits for a resolved `config.library`. */
+export function getLibraryOutputPaths(library) {
+  const outputPaths = library.formats.map((format) => `dist/${library.fileName}.${format === 'es' ? 'js' : `${format}.js`}`);
+  outputPaths.push(`dist/${library.cssFileName}.css`);
+  if (library.shouldEmitTypes) outputPaths.push('dist/index.d.ts');
+  return outputPaths;
+}
+/** Every `./dist/…` target package.json points at, as [{ field, target }] (globs skipped). */
+export function getPackageDistTargets(packageJson) {
+  const targets = [];
+  const addTarget = (field, target) => {
+    if (typeof target !== 'string') return;
+    const normalizedTarget = target.replace(/^\.\//, '');
+    if (normalizedTarget.startsWith('dist/') && !normalizedTarget.includes('*') && !normalizedTarget.endsWith('/')) targets.push({ field, target: normalizedTarget });
+  };
+  for (const field of ['main', 'module', 'types', 'typings', 'style', 'browser', 'unpkg', 'jsdelivr']) addTarget(field, packageJson[field]);
+  const visitExports = (value, path) => {
+    if (typeof value === 'string') addTarget(path, value);
+    else if (value && typeof value === 'object') for (const [key, child] of Object.entries(value)) visitExports(child, `${path}[${JSON.stringify(key)}]`);
+  };
+  visitExports(packageJson.exports, 'exports');
+  return targets;
+}
+/**
+ * package.json targets the library build won't produce — a renamed UMD/ES file
+ * or CSS breaks consumers silently (Vite 7 names the CSS after the package
+ * unless kmwc.library.cssFileName says otherwise). Pure.
+ */
+export function getLibraryOutputMismatches(packageJson, library) {
+  const outputPaths = new Set(getLibraryOutputPaths(library));
+  // Types emitted by the repo's own step (`tsc`) aren't the preset's to know.
+  const isOwnTypes = (target) => !library.shouldEmitTypes && target.endsWith('.d.ts');
+  return getPackageDistTargets(packageJson).filter(({ target }) => !outputPaths.has(target) && !target.endsWith('.map') && !isOwnTypes(target));
+}
+/**
+ * A hand-written vite.config's `lib.name` (the UMD global) — migration check: the
+ * preset derives the global from kmwc.library.globalName. null when not found.
+ */
+export function getLegacyGlobalName(viteConfigText) {
+  const libraryBlock = viteConfigText.match(/\blib\s*:\s*\{([\s\S]*?)\}/);
+  return libraryBlock?.[1].match(/\bname\s*:\s*['"]([A-Za-z_$][\w$]*)['"]/)?.[1] || null;
+}
+// ── ports ────────────────────────────────────────────────────────────────────
+/** [first, last] port of a registry block (blocks are numbered by 100). */
+export function getPortBlockRange(portBlock) {
+  return [portBlock, portBlock + PORT_BLOCK_SIZE - 1];
+}
+const checkIsInRange = (port, [firstPort, lastPort]) => port >= firstPort && port <= lastPort;
+/** Scripts that pin a `--port` different from kmwc.ports → [{ scriptName, port, expectedPort }]. Pure. */
+export function getScriptPortMismatches(scripts = {}, ports) {
+  return Object.entries(PORTED_SCRIPTS).flatMap(([scriptName, portName]) => {
+    const port = Number(String(scripts[scriptName] || '').match(/--port[=\s]+(\d+)/)?.[1]);
+    return port && port !== ports[portName] ? [{ scriptName, port, expectedPort: ports[portName] }] : [];
+  });
+}
+/** Ports a text names as `localhost:N`, `--port N`, `port: N`, `port N` or `PORT ?= N`. Pure. */
+export function getMentionedPorts(text) {
+  const patterns = [/localhost:(\d{4,5})\b/g, /--port[=\s]+(\d{4,5})\b/g, /\bport\s*[:=]\s*(\d{4,5})\b/gi, /\bport\s+(\d{4,5})\b/gi, /PORT\s*\??=\s*(\d{4,5})\b/g];
+  return getUniqueSorted(patterns.flatMap((pattern) => [...text.matchAll(pattern)].map((match) => Number(match[1]))));
+}
+/** Mentions in README.md / CLAUDE.md / docs/*.md of ports outside the repo's block → [{ file, port }]. */
+export function loadStalePortMentions(root, portBlock) {
+  const blockRange = getPortBlockRange(portBlock);
+  const docsDir = join(root, DOCS_DIR);
+  const docFiles = [...DOC_FILES, ...(existsSync(docsDir) ? readdirSync(docsDir).filter((name) => name.endsWith('.md')).map((name) => `${DOCS_DIR}/${name}`) : [])];
+  return docFiles.flatMap((file) => {
+    const text = readText(join(root, file));
+    return text ? getMentionedPorts(text).filter((port) => !checkIsInRange(port, blockRange)).map((port) => ({ file, port })) : [];
+  });
+}
+/** Ports a repo listens on: kmwc.ports (+ preview), script --port flags, ports in its vite / playwright configs and Makefile. */
+export function loadRepoPorts(repoRoot) {
+  const repoPorts = [];
+  const packageJson = JSON.parse(readText(join(repoRoot, 'package.json')) || '{}');
+  const kmwcPorts = packageJson.kmwc?.ports || {};
+  if (kmwcPorts.dev) repoPorts.push({ port: kmwcPorts.dev, file: 'package.json#kmwc.ports.dev' }, { port: kmwcPorts.dev + 1, file: 'package.json#kmwc.ports (preview)' });
+  if (kmwcPorts.image) repoPorts.push({ port: kmwcPorts.image, file: 'package.json#kmwc.ports.image' });
+  for (const [scriptName, command] of Object.entries(packageJson.scripts || {})) {
+    for (const port of getMentionedPorts(command)) repoPorts.push({ port, file: `package.json#scripts.${scriptName}` });
+  }
+  for (const file of SIBLING_PORT_FILES) {
+    const text = readText(join(repoRoot, file));
+    if (text) for (const port of getMentionedPorts(text)) repoPorts.push({ port, file });
+  }
+  return repoPorts;
+}
+/**
+ * A sibling's checkout, resolved next to this repo. Registry paths are relative
+ * to the devkit checkout, which sits beside the components — so `../<id>` works
+ * from any component root. Entries inside the devkit (`.`, `playground`) and the
+ * repo itself are not siblings.
+ */
+function getSiblingRoot(root, registryEntry) {
+  if (!registryEntry.path?.startsWith('../')) return null;
+  const siblingRoot = resolve(root, registryEntry.path);
+  return siblingRoot === resolve(root) ? null : siblingRoot;
+}
+/** Sibling repos listening on a port inside this repo's block → [{ id, port, file }]. */
+export function loadSiblingPortCollisions(config, registry) {
+  const ownEntry = registry.components.find((entry) => entry.id === config.id);
+  if (!ownEntry?.port) return [];
+  const blockRange = getPortBlockRange(ownEntry.port);
+  return registry.components
+    .filter((entry) => entry.id !== config.id)
+    .flatMap((entry) => {
+      const siblingRoot = getSiblingRoot(config.root, entry);
+      if (!siblingRoot || !existsSync(join(siblingRoot, 'package.json'))) return [];
+      return loadRepoPorts(siblingRoot)
+        .filter(({ port }) => checkIsInRange(port, blockRange))
+        .map(({ port, file }) => ({ id: entry.id, port, file }));
+    });
+}
+/** This repo's own configs naming a port outside its block (a hand-written vite.config before migration). */
+export function loadOwnPortsOutsideBlock(config, portBlock) {
+  const blockRange = getPortBlockRange(portBlock);
+  return loadRepoPorts(config.root).filter(({ port, file }) => !checkIsInRange(port, blockRange) && !file.startsWith('package.json#kmwc'));
+}
+// ── analytics ────────────────────────────────────────────────────────────────
+/** A repo's Plausible site id: kmwc.analytics.plausibleSiteId, else the legacy snippet's `pa-…` script. */
+export function loadPlausibleSiteId(repoRoot) {
+  const packageJson = JSON.parse(readText(join(repoRoot, 'package.json')) || '{}');
+  if (packageJson.kmwc?.analytics?.plausibleSiteId) return packageJson.kmwc.analytics.plausibleSiteId;
+  return readText(join(repoRoot, PLAUSIBLE_SNIPPET_FILE))?.match(/\/js\/(pa-[\w-]+)\.js/)?.[1] || null;
+}
+/** Siblings using the same Plausible site id (their traffic would be counted as this site's) → [id]. */
+export function loadSharedPlausibleSiteIds(config, registry, siteId) {
+  if (!siteId) return [];
+  return registry.components
+    .filter((entry) => entry.id !== config.id)
+    .filter((entry) => {
+      const siblingRoot = getSiblingRoot(config.root, entry);
+      return siblingRoot && existsSync(join(siblingRoot, 'package.json')) && loadPlausibleSiteId(siblingRoot) === siteId;
+    })
+    .map((entry) => entry.id);
+}
+// ── page CSS the kit already covers ──────────────────────────────────────────
+/** Page-local selectors with a kit replacement (key → advice). */
+export const KIT_REPLACED_SELECTORS = {
+  '.kbd': 'use <kbd> — the kit styles it',
+  kbd: 'the kit styles <kbd>',
+  mark: 'the kit styles <mark>',
+  '.mt-1': 'the kit has .mt-1',
+  '.push-end': 'the kit has .push-end',
+  '.mono': 'the kit has .mono',
+};
+/** The kit's page vocabulary — every unprefixed class its stylesheets define. */
+export function loadKitClassNames() {
+  const cssDir = join(DEVKIT_ROOT, 'src', 'examples', 'css');
+  const cssText = readdirSync(cssDir).map((name) => readFileSync(join(cssDir, name), 'utf8')).join('\n');
+  return new Set([...cssText.replace(/\/\*[\s\S]*?\*\//g, '').matchAll(/\.([a-z][a-z0-9-]*)/g)].map((match) => match[1]).filter((name) => !name.startsWith('kmwc')));
+}
+/** Top-level selectors of a stylesheet (one per comma part, comments and at-rule wrappers ignored). Pure. */
+export function getRuleSelectors(cssText) {
+  const plainText = cssText.replace(/\/\*[\s\S]*?\*\//g, '');
+  return [...plainText.matchAll(/(^|[{};])\s*([^{};@]+?)\s*\{/g)].flatMap((match) => match[2].split(',').map((part) => part.trim())).filter(Boolean);
+}
+/** Map an inline width to the nearest kit width helper (4 / 6 / 9 / 12rem). */
+function getWidthClass(value, unit) {
+  const rem = unit === 'px' ? value / 16 : value;
+  return rem <= 5 ? 'w-xs' : rem <= 7.5 ? 'w-sm' : rem <= 10.5 ? 'w-md' : 'w-lg';
+}
+/**
+ * What in one page (or examples-local.css) re-implements the kit: rules on a
+ * kit-owned selector and single-declaration inline styles a kit class covers.
+ * Returns [{ found, advice }]. Pure — `kitClassNames` from loadKitClassNames().
+ */
+export function getKitDuplicates(pageText, kitClassNames, { isStylesheet = false } = {}) {
+  const duplicates = [];
+  const styleText = isStylesheet ? pageText : [...pageText.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)].map((match) => match[1]).join('\n');
+  for (const selector of getUniqueSorted(getRuleSelectors(styleText))) {
+    if (KIT_REPLACED_SELECTORS[selector]) duplicates.push({ found: `${selector} { … }`, advice: KIT_REPLACED_SELECTORS[selector] });
+    else if (/^\.[a-z][a-z0-9-]*$/.test(selector) && kitClassNames.has(selector.slice(1))) {
+      duplicates.push({ found: `${selector} { … }`, advice: `restyles the kit's ${selector} for this page — scope it (e.g. .my-demo ${selector}) or drop it` });
+    }
+  }
+  if (isStylesheet) return duplicates;
+  for (const match of pageText.matchAll(/<(\w+)\b[^>]*\sstyle="\s*([^";]+?)\s*;?\s*"/g)) {
+    const [, tagName, declaration] = match;
+    const width = declaration.match(/^width\s*:\s*(\d+(?:\.\d+)?)(rem|px)$/i);
+    if (width && /^(input|select)$/i.test(tagName)) duplicates.push({ found: `<${tagName} style="${declaration}">`, advice: `class="${getWidthClass(Number(width[1]), width[2])}"` });
+    else if (/^margin-(left|inline-start)\s*:\s*auto$/i.test(declaration)) duplicates.push({ found: `style="${declaration}"`, advice: 'class="push-end"' });
+    else if (/^margin-top\s*:\s*1rem$/i.test(declaration)) duplicates.push({ found: `style="${declaration}"`, advice: 'class="mt-1"' });
+  }
+  return duplicates;
+}

package/src/cli/sync-plan.js CHANGED Viewed

@@ -84,6 +84,7 @@ export function getStandardScripts(config) {
       'test:e2e:ui': 'playwright test --ui',
       'test:e2e:headed': 'playwright test --headed',
       'test:e2e:install': 'playwright install chromium',
+      'check:pages': 'kmwc check-pages',
     });
   }
   return scripts;

package/src/examples/css/base.css CHANGED Viewed

@@ -161,6 +161,15 @@
         margin-bottom: 0.75rem;
     }
+    /* A heading naming an API (`EV05 · getMonthDataCallback & beforeMonthChangeCallback`)
+       has no break opportunity — let it break rather than widen the page on a phone. */
+    h1,
+    h2,
+    h3,
+    h4 {
+        overflow-wrap: anywhere;
+    }
     ul {
         line-height: 1.8;
     }
@@ -207,6 +216,25 @@
         }
     }
+    /* A small phone (320–400px): a component with a fixed minimum width — an inline
+       calendar is ~250px — still fits inside a card. */
+    @media (max-width: 400px) {
+        body {
+            padding: 0.75rem;
+        }
+        .card,
+        .example-section {
+            padding: 1rem;
+        }
+        /* Boxes nested in a card (a demo card holding a demo area) add up. */
+        .demo-card,
+        .demo-area {
+            padding: 0.75rem;
+        }
+    }
     @media (prefers-reduced-motion: reduce) {
         html {
             scroll-behavior: auto;

package/src/examples/css/content.css CHANGED Viewed

@@ -157,8 +157,11 @@
         background-color: var(--kmwc-accent-light-bg-hover);
         color: var(--kmwc-accent-color);
         font-weight: 600;
-        padding: 0 2px;
+        /* No padding: a match inside a word ("Town|send") must not split it. */
+        padding: 0;
         border-radius: var(--kmwc-radius-sm);
+        box-decoration-break: clone;
+        -webkit-box-decoration-break: clone;
     }
     /* ==========================================================================

package/src/examples/css/index-page.css CHANGED Viewed

@@ -114,5 +114,9 @@
         .kmwc-index__header {
             padding: 1.75rem 1.5rem;
         }
+        .kmwc-index__header h1 {
+            font-size: 2rem;
+        }
     }
 }

package/src/vite/index.js CHANGED Viewed

@@ -20,7 +20,7 @@ import { readdirSync, existsSync, cpSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { getKmwcConfig, getDevkitPackageJson, generateBuildDefines, loadPeerModule, DEVKIT_ROOT, NON_PAGE_HTML_FILES } from '../config.js';
 import { renderThemeBootstrapScript } from '../examples/theme-switch.js';
-import { composePage } from './page-composer.js';
+import { composePage, insertIntoHead, insertBeforeBodyEnd } from './page-composer.js';
 import { generateChapterIndex } from './chapter-index.js';
 const AUTO_ENTRY_PATH = join(DEVKIT_ROOT, 'src', 'examples', 'auto.js');
@@ -162,11 +162,7 @@ export function createExamplesPlugin(pluginConfig = {}) {
         const kitImports = isBuild ? `import '${KIT_STYLESHEET_PATH}'; import '${VIRTUAL_AUTO_ID}';` : `import '${VIRTUAL_AUTO_ID}';`;
         const bodyHtml = `<script type="module">${kitImports}</script>\n`;
-        html = /<head[^>]*>/i.test(html)
-          ? html.replace(/<head[^>]*>/i, (headTag) => `${headTag}\n${headHtml}`)
-          : headHtml + html;
-        html = /<\/body>/i.test(html) ? html.replace(/<\/body>/i, `${bodyHtml}</body>`) : html + bodyHtml;
-        return html;
+        return insertBeforeBodyEnd(insertIntoHead(html, headHtml), bodyHtml);
       },
     },

package/src/vite/page-composer.js CHANGED Viewed

@@ -64,7 +64,36 @@ export function mapOutsideComments(html, mapper, skippedPattern = HTML_COMMENT_P
   return mappedHtml + mapper(html.slice(lastIndex));
 }
-const mapToCamelCase = (kebabName) => kebabName.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+// The real tag only — `<head[^>]*>` also matches `<header>`.
+const HEAD_TAG_PATTERN = /<head(?=[\s>])[^>]*>/i;
+const BODY_END_TAG = '</body>';
+/**
+ * Insert `headHtml` right after the page's <head> tag (prepend when there is none).
+ * The first <head> outside comments is the real one: the text "<head>" in a tooltip
+ * or a script comment comes later, and a snippet landing there breaks the page
+ * (an HTML comment inside a module script throws).
+ */
+export function insertIntoHead(html, headHtml) {
+  let isInserted = false;
+  const insertedHtml = mapOutsideComments(html, (text) => {
+    if (isInserted || !HEAD_TAG_PATTERN.test(text)) return text;
+    isInserted = true;
+    return text.replace(HEAD_TAG_PATTERN, (headTag) => `${headTag}\n${headHtml}`);
+  });
+  return isInserted ? insertedHtml : headHtml + html;
+}
+/**
+ * Insert `bodyHtml` before the LAST </body> (append when there is none): an
+ * earlier one is text — e.g. a comment inside an inline script.
+ */
+export function insertBeforeBodyEnd(html, bodyHtml) {
+  const bodyEndIndex = html.toLowerCase().lastIndexOf(BODY_END_TAG);
+  return bodyEndIndex < 0 ? html + bodyHtml : html.slice(0, bodyEndIndex) + bodyHtml + html.slice(bodyEndIndex);
+}
+const mapToCamelCase =(kebabName) => kebabName.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
 const HTML_ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' };
 const mapToEscapedHtml = (text) => String(text).replace(/[&<>"]/g, (character) => HTML_ESCAPES[character]);

package/templates/Makefile.tmpl CHANGED Viewed

@@ -4,7 +4,7 @@
 # redefined there wins, with a make "overriding recipe" warning). Per-developer
 # overrides (container runner, image name, port) go in .makefile.env.
-.PHONY: help setup dev kill-port build build-examples preview-examples package publish-dry publish publish-rc clean check-version check-vars doctor sync test test-e2e test-e2e-ui test-e2e-headed test-e2e-install image-build image-run image-stop image-clean
+.PHONY: help setup dev kill-port build build-examples preview-examples package publish-dry publish publish-rc clean check-version check-vars doctor check-pages sync test test-e2e test-e2e-ui test-e2e-headed test-e2e-install image-build image-run image-stop image-clean
 -include .makefile.env
 DOCKER_RUNNER  ?= {{RUNNER}}
@@ -91,6 +91,9 @@ check-vars: ## Validate component-variables.manifest.json against the CSS
 doctor: ## Check this repo against the Keenmate component standard
 	npx kmwc doctor
+check-pages: ## Load every example page at 1440/390/320px: errors, undefined elements, overflow
+	npx kmwc check-pages
 sync: ## Regenerate devkit-owned files (Dockerfile, nginx.conf, Makefile, …)
 	npx kmwc sync

package/templates/claude-block.md CHANGED Viewed

@@ -48,4 +48,7 @@ locally — every local fork is how they drifted apart.
   otherwise published with it).
 - Before finishing: `npx kmwc doctor` must pass — it runs the devkit checks,
   checks the `npm pack` file list for dev-only files, and runs the rulebook's
-  `*.checks.sh` suites.
+  `*.checks.sh` suites. A rulebook failure that is a real architectural decision
+  goes into `VALIDATION-NOTES.md` under a `## C-XX-N — …` heading (deferrals
+  don't count). After changing a page, `npx kmwc check-pages` loads every page at
+  desktop and phone widths and reports errors and horizontal overflow.