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

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [1.0.0-rc09] - 2026-11-04 [PUBLISHED]
+
+### Added
+
+- **check-pages: page CSS that only matches inside a shadow root.** A page's own rules (its `<style>`
+  blocks and `examples-local.css`) are matched against the loaded page. A rule whose element (the last
+  compound, pseudo-classes dropped) exists nowhere in the document but inside a component's shadow root
+  never applies — page CSS stops at the shadow boundary. web-treeview styled the rows its
+  `renderNodeCallback` draws that way (custom-layout: `.file-icon`, `.node-badge`, `.badge-new` …;
+  responsive: `.isco-row`, `.dev-badge` …, 18 rules); against its pre-fix pages the check reports
+  exactly those. Checked once per page (first width).
+
+### Fixed
+
+- **The grey secondary button in dark mode** (`button.secondary` / `.btn-secondary`) had white text on
+  `#9ca3af` at 2.54:1. That grey sits just under the on-colour formula's 0.34 luminance switch, so the
+  formula picked white. It showed on 9 web-treeview pages ("Clear", "Reset", "Move up" …) and on every
+  other site's grey buttons. The button now has its own fill, `--kmwc-neutral-fill-color`
+  (`#6b7280` light / `#4b5563` dark, white text ≥ 4.5:1 in both, hovered too), and
+  `--kmwc-neutral-fill-color-hover`. Muted dots and pills keep the light `--kmwc-neutral-color`.
+
 ## [1.0.0-rc08] - 2026-11-04 [PUBLISHED]
 
 ### Added

package/README.md

@@ -19,19 +19,16 @@ 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-rc09
+
+- **check-pages — page CSS that can't reach into a shadow root** — web-treeview's custom-layout and responsive pages styled the rows their `renderNodeCallback` draws with page CSS (`.file-icon`, `.node-badge`, `.isco-row`, `.dev-badge` …, 18 rules). Those rows live in the tree's shadow root, and page CSS stops at the shadow boundary, so none of the rules ever applied. Nothing in the source shows where a render callback's output ends up, so this needs the loaded page. `kmwc check-pages` now reads the page's own rules (its `<style>` blocks and `examples-local.css`) and finds what each one styles: the last part of the selector, without pseudo-classes. It reports a rule when that element exists nowhere in the document but does exist inside a component's shadow root, and names the component. Run against treeview's pages from before its fix, it lists exactly those 18 rules. The fix is a CSS variable, `::part`, or the component's styles hook (`getCustomStylesCallback`).
+- **Examples kit — the grey secondary button in dark mode** — `button.secondary` / `.btn-secondary` had white text on `#9ca3af` in dark mode, at 2.54:1. That grey sits just under the 0.34 luminance switch in the formula that picks a button's text colour, so the formula chose white. It showed on 9 web-treeview pages ("Clear", "Reset", "Move up" …) and on every other component site's grey buttons. The button now has its own fill, `--kmwc-neutral-fill-color` (`#6b7280` light / `#4b5563` dark), plus a hover token, so white text stays at 4.5:1 or better in both themes, hovered too. Muted status dots and pills keep the lighter `--kmwc-neutral-color`. An e2e spec checks the contrast in both themes.
+
 ## What's New in v1.0.0-rc08
 
 - **Doctor — hard-coded colours in example pages** — web-treeview's devkit migration kept each page's own `<style>` block, and on 8 of its 14 pages the search bars, status bars, badges and panels kept their light colours when the theme switch went dark. rc07 only flagged page CSS that restyles a kit class, so nothing reported them. Doctor now warns about a colour literal (`#hex`, `rgb()` / `hsl()` / `oklch()`, a named colour) on any colour property in a page `<style>`, a `style="…"` attribute or `examples-local.css`. `var()` fallbacks, `light-dark()` pairs, custom properties and `rgb(from var(…))` pass, because they follow the theme. A block that shows fixed colours on purpose, such as a theme gallery or a mockup, opts out with `<style data-kmwc-fixed-colors>`, and a single rule with a `/* kmwc-fixed-colors: why */` comment before it.
 - **Doctor — the loader class matches the installed core** — Core 6d6b768 renamed its default loader's class from `<prefix>-loader` to `<prefix>__loader`, with no release that emits both. A component that renames its selector before the core bump, or forgets to after it, ships a loader with no styles. No rulebook check sees that, and a `## C-NC-8` heading in VALIDATION-NOTES.md would hide a leftover `.x-loader` from the BEM check. Doctor reads which class the installed core's `dist/dom/render-loader.js` draws and fails on any selector in the component's `src/**/*.css` that styles the other one. The error names the file and says which side should change.
 
-## What's New in v1.0.0-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.
-
 ## Catalogue
 
 <!-- kmwc:catalogue:start — generated by `npm run readme`, do not edit inside -->
@@ -365,7 +362,7 @@ kmwc doctor [--json]          devkit checks + package contents + the rulebook's
 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);
+                              viewport, page CSS that only matches inside a shadow root. 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)
@@ -427,7 +424,11 @@ generated files:
 
 `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.
+pushes a phone sideways, and page CSS that can never apply: a rule (in the page's
+`<style>` or `examples-local.css`) whose element exists only inside a component's
+shadow root, such as the rows a `renderNodeCallback` draws. Page CSS stops at the
+shadow boundary — style those through a CSS variable, `::part` or the component's
+styles hook (`getCustomStylesCallback`).
 
 **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keenmate/web-components-devkit",
-  "version": "1.0.0-rc08",
+  "version": "1.0.0-rc09",
   "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

@@ -1,24 +1,28 @@
 /**
  * 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).
+ * elements that never get defined, a page wider than the viewport (a fixed
+ * width or a long word that pushes a phone sideways), and page CSS that can
+ * never apply because what it targets lives only inside a shadow root (classes
+ * a render callback puts into the component).
  *
  * 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 { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { getKmwcConfig, getPeerModule, loadPeerModule } from '../../config.js';
 import { getExamplePages } from '../../vite/index.js';
+import { getRuleSelectors } from '../repo-checks.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;
+const LOCAL_STYLESHEET_FILE = 'examples-local.css';
 // Requests a page doesn't control (favicon probes, analytics in a built site).
 const IGNORED_REQUEST_PATTERN = /favicon\.ico|stats\.keenmate\.services|plausible/;
 
@@ -30,12 +34,68 @@ export function parseWidths(widthsText) {
   return widths;
 }
 
+/**
+ * The element a selector styles, as a selector of its own: the last compound with
+ * pseudo-classes / -elements dropped (`.tree .badge:hover::after` → `.badge`), or
+ * null when there's no class / id / attribute to look for (`:root`, `div`, `from`). Pure.
+ */
+export function getSelectorSubject(selector) {
+  let depth = 0;
+  let start = 0;
+  for (let index = 0; index < selector.length; index++) {
+    const character = selector[index];
+    if (character === '(' || character === '[') depth++;
+    else if (character === ')' || character === ']') depth--;
+    else if (depth === 0 && /[\s>+~]/.test(character)) start = index + 1;
+  }
+  const subject = selector.slice(start).replace(/::?[\w-]+(\([^()]*\))?/g, '').trim();
+  return /[.#[]/.test(subject) ? subject : null;
+}
+
+/** A page's own CSS rules (its `<style>` blocks + examples-local.css) → [{ selector, subject }]. */
+export function loadPageRules(root, pagePath) {
+  const pageText = readFileSync(pagePath, 'utf8');
+  const localStylesheetPath = join(root, LOCAL_STYLESHEET_FILE);
+  const styleText = [
+    ...[...pageText.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)].map((match) => match[1]),
+    existsSync(localStylesheetPath) ? readFileSync(localStylesheetPath, 'utf8') : '',
+  ].join('\n');
+  const selectors = [...new Set(getRuleSelectors(styleText))];
+  return selectors.map((selector) => ({ selector, subject: getSelectorSubject(selector) })).filter((rule) => rule.subject);
+}
+
+/**
+ * Runs in the page: page rules whose subject matches nothing in the document but
+ * something inside a shadow root → [{ selector, host }]. Page CSS stops at the
+ * shadow boundary, so such a rule never applies.
+ */
+export function findShadowOnlyRules(rules) {
+  const getShadowRoots = (root) =>
+    [...root.querySelectorAll('*')].filter((element) => element.shadowRoot).flatMap((element) => [element.shadowRoot, ...getShadowRoots(element.shadowRoot)]);
+  const shadowRoots = getShadowRoots(document);
+  const safeQuery = (root, selector) => {
+    try {
+      return root.querySelector(selector);
+    } catch {
+      return null;
+    }
+  };
+  return rules.flatMap(({ selector, subject }) => {
+    if (safeQuery(document, subject)) return [];
+    const shadowRoot = shadowRoots.find((root) => safeQuery(root, subject));
+    return shadowRoot ? [{ selector, host: shadowRoot.host.localName }] : [];
+  });
+}
+
 /**
  * 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
+ * @param {{ width: number, errors: string[], undefinedElements: string[], scrollWidth: number, clientWidth: number, offenders: string[], shadowOnlyRules?: { selector: string, host: string }[] }} pageReport
  */
 export function getPageProblems(pageReport) {
   const problems = [...pageReport.errors];
+  for (const { selector, host } of pageReport.shadowOnlyRules || []) {
+    problems.push(`page CSS "${selector}" only matches inside <${host}>'s shadow root — page styles can't reach it (use a CSS variable, ::part or the component's styles hook)`);
+  }
   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(', ')}` : '';
@@ -106,7 +166,7 @@ function inspectPage(maxOffenders) {
   };
 }
 
-async function loadPageReport(browser, pageUrl, width) {
+async function loadPageReport(browser, pageUrl, width, pageRules = []) {
   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]}`));
@@ -123,7 +183,8 @@ async function loadPageReport(browser, pageUrl, width) {
     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 };
+    const shadowOnlyRules = pageRules.length ? await page.evaluate(findShadowOnlyRules, pageRules) : [];
+    return { width, errors: [...new Set(errors)], ...inspection, shadowOnlyRules };
   } catch (error) {
     return { width, errors: [...new Set([...errors, `load failed: ${error.message.split('\n')[0]}`])], scrollWidth: 0, clientWidth: 0, offenders: [], undefinedElements: [] };
   } finally {
@@ -154,7 +215,8 @@ async function startDevServer(config) {
 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());
+  const pagePaths = Object.values(getExamplePages(config));
+  const pageFiles = pagePaths.map((pagePath) => pagePath.replace(/\\/g, '/').split('/').pop());
   if (!pageFiles.length) {
     console.log('kmwc check-pages: no example pages — nothing to check.');
     return 0;
@@ -172,10 +234,13 @@ export async function run(args) {
   let problemCount = 0;
   try {
     console.log(`kmwc check-pages — ${pageFiles.length} page(s) × ${widths.join(' / ')}px on ${baseUrl}\n`);
-    for (const pageFile of pageFiles) {
+    for (const [pageIndex, pageFile] of pageFiles.entries()) {
       const pageProblems = [];
-      for (const width of widths) {
-        for (const problem of getPageProblems(await loadPageReport(browser, `${baseUrl}/${pageFile}`, width))) pageProblems.push(`@${width}px ${problem}`);
+      const pageRules = loadPageRules(config.root, pagePaths[pageIndex]);
+      for (const [widthIndex, width] of widths.entries()) {
+        // Shadow-only rules don't depend on the width: check them on the first load only.
+        const report = await loadPageReport(browser, `${baseUrl}/${pageFile}`, width, widthIndex === 0 ? pageRules : []);
+        for (const problem of getPageProblems(report)) pageProblems.push(`@${width}px ${problem}`);
       }
       problemCount += pageProblems.length;
       console.log(`${pageProblems.length ? '✗' : '✓'} ${pageFile}${pageProblems.map((problem) => `\n    ${problem}`).join('')}`);

package/src/examples/css/controls.css

@@ -213,13 +213,13 @@
 
     button.secondary,
     button.btn-secondary {
-        background: var(--kmwc-neutral-color);
+        background: var(--kmwc-neutral-fill-color);
         color: var(--kmwc-text-color-on-neutral);
     }
 
     button.secondary:hover,
     button.btn-secondary:hover {
-        background: color-mix(in srgb, var(--kmwc-neutral-color) 80%, black);
+        background: var(--kmwc-neutral-fill-color-hover);
     }
 
     button.btn-outline {

package/src/examples/css/tokens.css

@@ -137,10 +137,15 @@
         --kmwc-danger-fill-color-hover: var(--base-danger-color-hover, light-dark(color-mix(in srgb, black 15%, var(--kmwc-danger-fill-color)), color-mix(in srgb, white 15%, var(--kmwc-danger-fill-color))));
         --kmwc-text-color-on-danger: var(--base-on-danger-text-color, color(from color(from var(--kmwc-danger-fill-color) srgb calc(0.21 * r * r * (0.4 + r * (0.82 - 0.22 * r)) + 0.72 * g * g * (0.4 + g * (0.82 - 0.22 * g)) + 0.07 * b * b * (0.4 + b * (0.82 - 0.22 * b))) 0 0) srgb clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1)));
         --kmwc-neutral-color: light-dark(#6b7280, #9ca3af);
+        /* A grey button needs its own fill: the dark-mode neutral (#9ca3af) sits just under the
+           on-colour formula's 0.34 switch, so it got white text at 2.5:1. Dots and pills keep the
+           light grey; the button takes a dark one (white text ≥ 4.5:1 in both themes). */
+        --kmwc-neutral-fill-color: light-dark(#6b7280, #4b5563);
+        --kmwc-neutral-fill-color-hover: light-dark(color-mix(in srgb, black 15%, var(--kmwc-neutral-fill-color)), color-mix(in srgb, white 12%, var(--kmwc-neutral-fill-color)));
         --kmwc-badge-new-bg: light-dark(#e53e3e, #f56565);
         /* Text on the neutral / badge fills: the contract's on-colour formula on
            their own background, not on the accent (a light primary would turn it black). */
-        --kmwc-text-color-on-neutral: color(from color(from var(--kmwc-neutral-color) srgb calc(0.21 * r * r * (0.4 + r * (0.82 - 0.22 * r)) + 0.72 * g * g * (0.4 + g * (0.82 - 0.22 * g)) + 0.07 * b * b * (0.4 + b * (0.82 - 0.22 * b))) 0 0) srgb clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1));
+        --kmwc-text-color-on-neutral: color(from color(from var(--kmwc-neutral-fill-color) srgb calc(0.21 * r * r * (0.4 + r * (0.82 - 0.22 * r)) + 0.72 * g * g * (0.4 + g * (0.82 - 0.22 * g)) + 0.07 * b * b * (0.4 + b * (0.82 - 0.22 * b))) 0 0) srgb clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1));
         --kmwc-text-color-on-badge-new: color(from color(from var(--kmwc-badge-new-bg) srgb calc(0.21 * r * r * (0.4 + r * (0.82 - 0.22 * r)) + 0.72 * g * g * (0.4 + g * (0.82 - 0.22 * g)) + 0.07 * b * b * (0.4 + b * (0.82 - 0.22 * b))) 0 0) srgb clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1) clamp(0, (0.34 - r) * 1e9, 1));
 
         /* ======================================================================

package/templates/claude-block.md

@@ -54,4 +54,6 @@ locally — every local fork is how they drifted apart.
   `*.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.
+  desktop and phone widths and reports errors, horizontal overflow and page CSS
+  that only matches inside a shadow root (markup a render callback draws there is
+  out of page CSS's reach — style it through the component's styles hook).