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

package/CHANGELOG.md

@@ -1,5 +1,82 @@
 # Changelog
 
+## [1.0.0-rc11] - 2026-11-06 [PUBLISHED]
+
+### Added
+
+- **Doctor understands monorepos: `kmwc.packages`.** Doctor assumed the repo root was the package.
+  In web-dropzone (npm workspaces: a private root holding the example site,
+  `packages/web-dropzone` the component, `packages/web-dropzone-core` a headless library) that gave
+  113 errors that said little: `npm pack` on the private root "leaked" 101 files npm never publishes,
+  six rulebook suites couldn't find a component at the root, the overlay suite scanned
+  `node_modules`, and the loader check silently skipped — while the component's real findings
+  (129 non-BEM classes, no Custom Elements Manifest setup …) never showed. `"packages": [{ "path",
+  "kind": "component" | "library" }]` lists what the repo publishes: doctor packs each package, runs
+  the rulebook suites for its kind inside it (`rulebook:<suite>@<path>`; publish-command and
+  example-pages stay repo-wide at the root), and checks the loader class per component package.
+  Doctor warns when npm workspaces aren't all listed, errors on a listed path without a
+  package.json, and never packs a private workspace root. Without `packages` a repo is one package
+  at its root, as before.
+- **Every example page gets the footer.** Only the index had one ("Created by Keenmate s.r.o. |
+  GitHub | web-components-devkit vX"); the other pages just ended. The kit now appends the same
+  line to every page but the index (`mountPageFooter()`, `.kmwc-page-footer`), inside the layout's
+  container. The index and the page footer render it from one function (`renderFooterLineHtml()`),
+  so they can't drift.
+
+## [1.0.0-rc10] - 2026-11-05 [PUBLISHED]
+
+### Added
+
+- **Doctor runs the variable-manifest check.** `kmwc check-vars` only ran inside `npm run build`, so a
+  red manifest went unseen until a build: web-treeview's `check:vars` failed on core's
+  non-contract `--base-accent-color` while doctor passed. Doctor now reports the same verdict
+  (`vars`): missing / dead `--base-*` and dead `--<prefix>-*` entries are errors, undocumented
+  `--<prefix>-*` a warning. `loadManifestVerdict()` is shared by both.
+- **Opt-outs for markup that is right on purpose:**
+  - an element whose own `style="…"` sets fixed colours carries `data-kmwc-fixed-colors` (doctor's
+    colour check). Markup a render callback draws inside a shadow root can't be styled by page CSS,
+    so inline is the only way there (web-treeview's context-menu role chips);
+  - `data-kmwc-undefined` on an element a demo leaves undefined on purpose — check-pages no longer
+    reports it (core's PG01 registers its element on a button press). The "never defined" problem
+    names the attribute;
+  - `<!-- kmwc-other-ports: why -->` in a doc that names other repos' ports on purpose (a dated
+    plan, a cross-repo review) — doctor's port scan skips it.
+
+### Changed
+
+- **Doctor: the loader check tells a collision from a rename.** On a core that still draws
+  `<prefix>-loader`, CSS that styles both classes has its own element called `<prefix>__loader`
+  (web-multiselect's loading-state row). That was reported as a rename done too early (error); it is
+  now a warning that core's loader takes the name — and those rules — with the bump, so rename the
+  component's element in the same change.
+
+### Fixed
+
+- **Fragment pages: `<link>` / `<style>` text inside an attribute value stayed put.** The composer
+  moved a `<link>` it found in a tooltip (`title="…the <link> in <head>"`) into `<head>` as an empty
+  element, and the tooltip lost its text (web-multiselect). It now reads whole start tags, quoted
+  attribute values included, and moves only real `<link>` / `<style>` elements.
+- **Inline code in light mode** read at ~3.3:1 — the raw accent on the pale chip. The text keeps the
+  accent hue at most 0.5 lightness (≥ 4.5:1 for every accent the spec tries, light and dark).
+- **Doctor: a rulebook suite that never ran counted as a pass.** Only exit 2 was read as "could
+  not run"; any other exit without `FAIL` lines passed. On Windows a bare `bash` can be WSL's, which
+  can't read `C:/…` paths — every suite exited 127 and doctor reported the rulebook green (found when
+  `make publish-rc` ran the tests from PowerShell). Doctor now runs Git for Windows' bash (from PATH
+  or the install root; `KMWC_BASH` overrides) and warns on any exit but 0, or 1 with `FAIL` lines.
+
+### Internal
+
+- **Tests on the critical paths.** Doctor end to end on fixture repos (a healthy repo is clean, each
+  broken one gets its finding; `doctor.js` 26% → 98% of lines); a real `vite build` of the playground
+  must emit exactly what doctor checks package.json against, with the UMD global and every export
+  `index.d.ts` declares; `kmwc new` (full and `--minimal`) scaffolds a repo doctor finds clean;
+  `kmwc sync` rewrites only what it owns and `--check` writes nothing; `check-release` keeps an rc off
+  `latest`. Composer cases for single-quoted values, `<style>` text and a `>` inside an attribute.
+- **`npm run test:e2e:coverage`** (maintainer) — the dev-server e2e run with line coverage of the
+  kit's browser code (`src/examples/*.js`, 84%), snapshot before every navigation.
+- **README:** a sentence about `data-kmwc-undefined` had landed inside the rc09 What's New bullet;
+  it's back in the check-pages docs.
+
 ## [1.0.0-rc09] - 2026-11-04 [PUBLISHED]
 
 ### Added

package/README.md

@@ -19,15 +19,19 @@ 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
+## What's New in v1.0.0-rc11
 
-- **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.
+- **Doctor — monorepos: `kmwc.packages` lists what the repo publishes** — Doctor used to assume the repo root was the package. In web-dropzone (npm workspaces: a private root that holds the example site, the component in `packages/web-dropzone`, a headless library in `packages/web-dropzone-core`) that produced 113 errors that said little. `npm pack` on the private root "leaked" 101 files npm never publishes, six rulebook suites found no component at the root, and the overlay suite scanned `node_modules`. Meanwhile the component's real findings never showed. Now `"packages": [{ "path", "kind": "component" | "library" }]` in `package.json#kmwc` lists the published packages. Doctor packs each one and runs the rulebook suites for its kind inside it (reported as `rulebook:<suite>@<path>`). The publish-command and example-pages suites stay repo-wide, and the loader check runs per component package. Doctor warns when npm workspaces aren't all listed, errors on a listed path without a `package.json`, and never packs a private workspace root. A repo without `packages` is still one package at its root.
+- **Examples kit — every example page ends with the footer** — Only the index page had the "Created by Keenmate s.r.o. | GitHub | web-components-devkit vX" footer; the other example pages just stopped. The kit now appends the same line to every page except the index (`mountPageFooter()`, `.kmwc-page-footer`), at the end of the layout's container. The index footer and the page footer are rendered by one function, `renderFooterLineHtml()`, so they can't drift apart. The index keeps its own extra links (README, API docs); the page footer carries Keenmate, the repo's GitHub link and the devkit version.
 
-## What's New in v1.0.0-rc08
+## What's New in v1.0.0-rc10
 
-- **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.
+- **Doctor — runs the variable-manifest check** — `kmwc check-vars` only ran inside `npm run build`, so a red manifest stayed invisible until someone built. During the devkit pass, web-treeview's `check:vars` failed on core's `--base-accent-color` (a name outside the base-variables contract) while `kmwc doctor` reported nothing. Doctor now reports the same verdict under `vars`: `--base-*` reads missing from the manifest, manifest entries the CSS no longer reads, and dead `--<prefix>-*` entries are errors; undocumented `--<prefix>-*` variables are a warning. Both commands share one function, `loadManifestVerdict()`, so they can't disagree.
+- **Doctor and check-pages — opt-outs for markup that is right on purpose** — The migrations of web-treeview, web-multiselect and web-components-core hit three findings that could never pass. Markup a render callback draws inside a shadow root can only be coloured inline, so an element whose `style="…"` sets fixed colours on purpose now carries `data-kmwc-fixed-colors` (treeview's context-menu role chips). An element a demo leaves undefined on purpose carries `data-kmwc-undefined`, and check-pages skips it (core's PG01 registers its element on a button press); the "never defined" message names the attribute. A doc that names other repos' ports on purpose, such as a dated plan or a cross-repo review, carries `<!-- kmwc-other-ports: why -->`, and doctor's port scan skips it.
+- **Doctor — the loader check tells a collision from a rename** — web-multiselect has its own loading-state element called `.ms__loader`, next to core rc17's `.ms-loader`. Doctor read it as a rename done before the core bump and reported an error. On a core that still draws `<prefix>-loader`, CSS that styles both classes now gets a warning instead: from core 6d6b768 on, core's default loader takes that class name and picks up the component's rules. The fix is to rename the component's own element in the same change as the core bump.
+- **Fragment pages — text inside attribute values stays put** — The page composer moves a page's `<link>` and `<style>` elements into `<head>`, but it also matched them inside attribute values. web-multiselect's tooltip `title="…the <link> in <head>"` turned into an empty `<link>` in the head, and the tooltip lost its text; a `<style>` written inside an attribute would even have been applied to the whole page. The composer now reads whole start tags, quoted values included, and moves only real elements.
+- **Examples kit — inline code readable in light mode** — Inline `code` used the raw accent colour on its pale chip, which read at about 3.3:1 for the default accent. The text keeps the accent's hue at no more than 0.5 lightness. The e2e spec checks five accents in both themes for at least 4.5:1.
+- **Devkit tests — the critical paths** — The suite now runs a real library build of the playground and checks that the emitted files, the UMD global and every export `index.d.ts` declares are exactly what package.json and doctor expect. It also checks that `kmwc new` scaffolds a repo doctor finds clean, that `kmwc sync` never rewrites a local file or an existing script, and that `check-release` keeps an rc off `latest`. Doctor itself is tested end to end on fixture repos.
 
 ## Catalogue
 
@@ -36,11 +40,11 @@ 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-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-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-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 |
 | **web-editor** | `@keenmate/web-editor` | `km` | 12700 | [examples](https://examples.web-editor.keenmate.dev) | ✅ | Keenmate Web Editor — a framework-agnostic WYSIWYG / Markdown editor built on ProseMirror. |
 | **web-switch** | `@keenmate/web-switch` | — | 12800 | [repo](https://github.com/keenmate/web-switch) | — | Framework-agnostic web component wrapper for @keenmate/svelte-switch. Works with React, Vue, Angular, or… |
@@ -102,7 +106,7 @@ in `package.json#kmwc`, and gets the rest.
 | Piece | Import / command | Replaces |
 |---|---|---|
 | Vite preset | `@keenmate/web-components-devkit/vite` → `defineComponentConfig()` | per-repo `vite.config.ts`, `vite.examples.config.ts` |
-| Examples kit (auto-injected) | shared styles, chapter nav, copy-link buttons, theme switch, version badge, analytics | `examples-shared.css`, `examples-chapter-nav.js`, `examples-copy-link.js`, `plausible-snippet.html`, Dockerfile `sed` |
+| Examples kit (auto-injected) | shared styles, chapter nav, copy-link buttons, theme switch, version badge, page footer, analytics | `examples-shared.css`, `examples-chapter-nav.js`, `examples-copy-link.js`, `plausible-snippet.html`, Dockerfile `sed` |
 | Fragment pages | `<meta name="kmwc:title">` pages + `<kmwc-include>` partials + `<kmwc-demo>` (live markup = snippet) | the head / header / container boilerplate copied into every page, hand-copied `.code-block` snippets |
 | Examples helpers | `@keenmate/web-components-devkit/examples` → `attachControlsPersistence`, `renderExamplesIndex`, `mountExamplesKit` | `examples-controls-store.js`, 150 lines of inline index-page CSS |
 | Playwright preset | `@keenmate/web-components-devkit/playwright` → `definePlaywrightConfig()` | per-repo `playwright.config.ts` |
@@ -175,7 +179,11 @@ Every field is optional. Defaults are derived from the package.
                                                  // BlissFramework checkout above it. env KMWC_RULEBOOK_PATH wins
     "skippedChecks": []                          // e.g. ["responsive-overlay"]
   },
-  "sync": { "skippedFiles": [] }                 // e.g. ["Makefile"] to opt a file out
+  "sync": { "skippedFiles": [] },                // e.g. ["Makefile"] to opt a file out
+  "packages": [                                  // monorepos only (npm workspaces): what doctor checks
+    { "path": "packages/web-dropzone", "kind": "component" },
+    { "path": "packages/web-dropzone-core", "kind": "library" }
+  ]
 }
 ```
 
@@ -189,6 +197,16 @@ manifest check (no `check:vars` script, `kmwc check-vars` skips), for variables
 the checker can't see, such as names built by string interpolation. Doctor runs
 only the rulebook suites that apply to a library (see below).
 
+**A monorepo** (npm workspaces, e.g. web-dropzone: a private root with the example
+site, `packages/web-dropzone` + `packages/web-dropzone-core`) lists its published
+packages in `kmwc.packages`, each with its kind. The root keeps the devkit's
+example site, generated files, ports and registry checks; doctor packs each
+package (`npm pack`), runs the rulebook suites for its kind *in* the package
+(reported as `rulebook:<suite>@<path>`), and checks the loader class in each
+component package. publish-command and example-pages stay repo-wide, at the root.
+Without `packages` the root is the one package — doctor warns when npm workspaces
+exist but aren't listed, and doesn't pack a private workspace root.
+
 ### Vite preset
 
 ```ts
@@ -332,6 +350,9 @@ doctor` lists the ones still repeating the head/header boilerplate.
   shows `v1.2.3`, or `v1.2.3 (built …)` in a built site.
 - **Landing page**: `renderExamplesIndex({ pages })` renders the header, cards,
   footer and cross-page nav from the registry plus `kmwc` config.
+- **Page footer**: every other example page ends with the same line as the
+  index footer — Keenmate, the repo's GitHub link, the devkit version — inside
+  the layout's container (`.kmwc-page-footer`).
 - **Late content**: the kit mounts one task after DOM-ready. Pages that render
   sections after a fetch call `mountExamplesKit()`.
 - **Analytics**: the Plausible snippet goes into **built** pages only, and only
@@ -385,6 +406,9 @@ and the e2e suite before building and publishing.
 base-variables, color-scheme, readme-structure, custom-elements-manifest,
 responsive-overlay, publish-command, example-pages) with `bash`, passing `kmwc.prefix`, and
 reports each `FAIL` as an error pointing at the matching `.checks.md` entry.
+On Windows that is Git for Windows' bash (a bare `bash` may be WSL's, which can't
+read `C:/` paths); `KMWC_BASH` overrides it. A suite that exits with anything but 0,
+or 1 with `FAIL` lines, never ran — a warning, never a pass.
 A `library` runs only naming-conventions, readme-structure, publish-command
 and example-pages; the others check what a custom element ships (its CSS,
 manifest, overlay).
@@ -405,7 +429,9 @@ generated files:
   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.
+  entry at `../<id>`) listens on a port inside it. A doc that names other repos'
+  ports on purpose (a dated plan, a cross-repo review) carries
+  `<!-- kmwc-other-ports: why -->` and isn't scanned.
 - **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
@@ -415,12 +441,19 @@ generated files:
   it stays put when the theme switch flips the kit to dark. `var()` fallbacks and
   `light-dark()` pairs follow the theme. Fixed colours on purpose (a theme gallery, a
   mockup, a test fixture) go in a `<style data-kmwc-fixed-colors>` block, or one rule
-  gets a `/* kmwc-fixed-colors: why */` comment right before it.
+  gets a `/* kmwc-fixed-colors: why */` comment right before it. An element whose
+  `style="…"` sets them on purpose carries the same attribute — markup a render
+  callback draws inside a shadow root can't be reached by page CSS at all.
 - **Loader class** — the component CSS styles the class the *installed* core gives
   its default loader (`<prefix>__loader` from core 6d6b768 on, `<prefix>-loader`
   before). Renaming the selector on one side of the core bump leaves the loader
   unstyled, and a VALIDATION-NOTES `## C-NC-8` would hide the old class from the
-  rulebook.
+  rulebook. On a core that still draws `<prefix>-loader`, CSS that styles both
+  classes has an element of its own called `<prefix>__loader`: a warning, because
+  core's loader takes that name (and those rules) with the bump.
+- **Variable manifest** — the same verdict as `kmwc check-vars`, which otherwise
+  only runs inside `npm run build`: `--base-*` reads and the manifest agree, no
+  dead `--<prefix>-*` entries (errors), no undocumented ones (warning).
 
 `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
@@ -428,7 +461,8 @@ pushes a phone sideways, and page CSS that can never apply: a rule (in the page'
 `<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`).
+styles hook (`getCustomStylesCallback`). An element a demo leaves undefined on
+purpose (registered on a button press) carries `data-kmwc-undefined`.
 
 **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
@@ -524,6 +558,7 @@ registry edits), and move the component's own code into that layout with
 npm install
 npm test                 # unit tests (config, registry, templates, sync, checks, intake, plugin, kit)
 npm run test:e2e         # playground: the kit + scaffold in a real browser, dev server AND built site
+npm run test:e2e:coverage   # the same specs on the dev server + line coverage of the kit's browser code
 npm run readme           # regenerate the catalogue
 npm run check:spotlight-mirror   # what changed in web-commandpalette since the spotlight was aligned
 make dev                 # the playground's dev server

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keenmate/web-components-devkit",
-  "version": "1.0.0-rc09",
+  "version": "1.0.0-rc11",
   "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",
@@ -47,6 +47,7 @@
     "readme:check": "node src/cli/kmwc.js readme --check",
     "test": "node --test \"test/**/*.test.js\"",
     "test:e2e": "cd playground && npx playwright test",
+    "test:e2e:coverage": "node scripts/e2e-coverage.js",
     "check:contract": "base-contract-check src templates playground",
     "check:spotlight-mirror": "node scripts/check-spotlight-mirror.js",
     "playground": "cd playground && vite",

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

@@ -23,6 +23,8 @@ 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';
+// An element a demo leaves undefined on purpose (registered on a button press) opts out.
+export const UNDEFINED_ON_PURPOSE_ATTRIBUTE = 'data-kmwc-undefined';
 // Requests a page doesn't control (favicon probes, analytics in a built site).
 const IGNORED_REQUEST_PATTERN = /favicon\.ico|stats\.keenmate\.services|plausible/;
 
@@ -96,7 +98,7 @@ export function getPageProblems(pageReport) {
   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.undefinedElements.length) problems.push(`never defined: <${pageReport.undefinedElements.join('>, <')}> (left undefined on purpose? add ${UNDEFINED_ON_PURPOSE_ATTRIBUTE})`);
   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}`);
@@ -108,9 +110,10 @@ export function getPageProblems(pageReport) {
  * 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.
+ * layers (a closed nav panel, a toast), which don't widen the page. Undefined elements
+ * carrying `undefinedAttribute` are left undefined on purpose and don't count.
  */
-function inspectPage(maxOffenders) {
+function inspectPage({ maxOffenders, undefinedAttribute }) {
   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;
@@ -157,7 +160,7 @@ function inspectPage(maxOffenders) {
       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('-')))];
+  const undefinedElements = [...new Set([...document.querySelectorAll(`:not(:defined):not([${undefinedAttribute}])`)].map((element) => element.localName).filter((name) => name.includes('-')))];
   return {
     scrollWidth: document.documentElement.scrollWidth,
     clientWidth: viewportWidth,
@@ -182,7 +185,7 @@ async function loadPageReport(browser, pageUrl, width, pageRules = []) {
   try {
     await page.goto(pageUrl, { waitUntil: 'networkidle', timeout: 30_000 });
     await page.waitForTimeout(SETTLE_MS);
-    const inspection = await page.evaluate(inspectPage, MAX_OFFENDERS);
+    const inspection = await page.evaluate(inspectPage, { maxOffenders: MAX_OFFENDERS, undefinedAttribute: UNDEFINED_ON_PURPOSE_ATTRIBUTE });
     const shadowOnlyRules = pageRules.length ? await page.evaluate(findShadowOnlyRules, pageRules) : [];
     return { width, errors: [...new Set(errors)], ...inspection, shadowOnlyRules };
   } catch (error) {

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

@@ -77,18 +77,14 @@ export function checkManifestVariables({ cssText, manifest, prefix, internalVari
   };
 }
 
-export async function run(args) {
-  const config = getKmwcConfig(args.root);
-  const isStrict = !!args.strict;
-  if (!config.cssVariables.isEnabled) {
-    console.log('kmwc check-vars: off (kmwc.cssVariables is false) — nothing to check.');
-    return 0;
-  }
+/**
+ * The repo's manifest checked against its CSS sources → { verdict, prefix }, or { skippedReason }
+ * when there's nothing to check. Shared by `kmwc check-vars` and doctor.
+ */
+export function loadManifestVerdict(config) {
+  if (!config.cssVariables.isEnabled) return { skippedReason: 'off (kmwc.cssVariables is false)' };
   const manifestPath = resolve(config.root, config.cssVariables.manifest);
-  if (!existsSync(manifestPath)) {
-    console.log(`kmwc check-vars: no ${config.cssVariables.manifest} — nothing to check.`);
-    return 0;
-  }
+  if (!existsSync(manifestPath)) return { skippedReason: `no ${config.cssVariables.manifest}` };
   const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
   const prefix = config.prefix || manifest.prefix;
   if (!prefix) throw new Error('no variable prefix — set kmwc.prefix or "prefix" in the manifest');
@@ -101,6 +97,17 @@ export async function run(args) {
     internalVariables: config.cssVariables.internalVariables,
     checkMode: config.cssVariables.checkMode,
   });
+  return { verdict, prefix };
+}
+
+export async function run(args) {
+  const config = getKmwcConfig(args.root);
+  const isStrict = !!args.strict;
+  const { verdict, prefix, skippedReason } = loadManifestVerdict(config);
+  if (skippedReason) {
+    console.log(`kmwc check-vars: ${skippedReason} — nothing to check.`);
+    return 0;
+  }
 
   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');

package/src/cli/commands/doctor.js

@@ -14,11 +14,12 @@
  * Errors fail (exit 1); warnings don't.
  */
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, relative, resolve } from 'node:path';
 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 { loadManifestVerdict } from './check-vars.js';
 import {
   VALIDATION_NOTES_FILE,
   loadAcceptedCheckIds,
@@ -28,6 +29,7 @@ import {
   getPortBlockRange,
   getScriptPortMismatches,
   loadStalePortMentions,
+  OTHER_PORTS_MARKER,
   loadSiblingPortCollisions,
   loadOwnPortsOutsideBlock,
   loadPlausibleSiteId,
@@ -38,6 +40,7 @@ import {
   FIXED_COLORS_MARKER,
   getHardcodedColors,
   loadCoreLoader,
+  getLoaderClassVerdict,
   loadStyledLoaderClasses,
 } from '../repo-checks.js';
 
@@ -63,8 +66,9 @@ export const RULEBOOK_SUITES = [
   { name: 'readme-structure', isPrefixed: false, isComponentOnly: false },
   { name: 'custom-elements-manifest', isPrefixed: false, isComponentOnly: true },
   { name: 'responsive-overlay', isPrefixed: true, isComponentOnly: true },
-  { name: 'publish-command', isPrefixed: false, isComponentOnly: false },
-  { name: 'example-pages', isPrefixed: false, isComponentOnly: false },
+  // Repo-wide: one /publish command and one example site per repo, checked at its root.
+  { name: 'publish-command', isPrefixed: false, isComponentOnly: false, isRepoWide: true },
+  { name: 'example-pages', isPrefixed: false, isComponentOnly: false, isRepoWide: true },
 ];
 
 const LIBRARY_KIND = 'library';
@@ -98,15 +102,40 @@ export function getSuiteFailures(suiteOutput) {
     .map((match) => ({ checkId: match[1], reason: match[2].trim() }));
 }
 
-function runRulebookSuite(config, suite) {
+const GIT_BASH_RELATIVE_PATH = join('bin', 'bash.exe');
+// PATH entries Git for Windows adds — each sits one or two levels under the install root.
+const GIT_PATH_ENTRY_PATTERN = /^(.*[\\/]Git)[\\/](?:cmd|bin|usr[\\/]bin|mingw64[\\/]bin)[\\/]?$/i;
+
+/**
+ * The bash that runs the rulebook scripts. On Windows a bare `bash` can resolve to WSL's
+ * (`System32\bash.exe`, `WindowsApps\bash.exe`), which can't read `C:/…` paths: every suite
+ * exits 127 and the rulebook never runs. So: KMWC_BASH when set, else Git for Windows'
+ * bash (found from PATH or the usual install roots), else `bash`. Exported for tests.
+ */
+export function getBashPath({ platform = process.platform, env = process.env, checkExists = existsSync } = {}) {
+  if (env.KMWC_BASH) return env.KMWC_BASH;
+  if (platform !== 'win32') return 'bash';
+  const pathEntries = (env.PATH || env.Path || '').split(';').filter(Boolean);
+  const gitRoots = [
+    ...pathEntries.map((entry) => entry.match(GIT_PATH_ENTRY_PATTERN)?.[1]).filter(Boolean),
+    ...[env.ProgramFiles, env.ProgramW6432, env.LOCALAPPDATA && join(env.LOCALAPPDATA, 'Programs')].filter(Boolean).map((directory) => join(directory, 'Git')),
+  ];
+  return gitRoots.map((gitRoot) => join(gitRoot, GIT_BASH_RELATIVE_PATH)).find((bashPath) => checkExists(bashPath)) || 'bash';
+}
+
+function runRulebookSuite(config, suite, checkedRoot) {
   const scriptPath = join(config.rulebook.path, `${suite.name}.checks.sh`).replace(/\\/g, '/');
-  const scriptArgs = [scriptPath, config.root.replace(/\\/g, '/')];
+  const scriptArgs = [scriptPath, checkedRoot.replace(/\\/g, '/')];
   if (suite.isPrefixed && config.prefix) scriptArgs.push(config.prefix);
-  return spawnSync('bash', scriptArgs, { encoding: 'utf8', env: { ...process.env, NO_COLOR: '1' } });
+  return spawnSync(getBashPath(), scriptArgs, { encoding: 'utf8', env: { ...process.env, NO_COLOR: '1' } });
 }
 
-/** Run every check; returns [{ level: 'pass'|'warning'|'error', checkName, message, fixHint? }]. */
+/**
+ * Run every check; returns [{ level: 'pass'|'warning'|'error', checkName, message, fixHint? }].
+ * `doctorConfig.registry` replaces components.json (tests use a registry of fixture repos).
+ */
 export function checkComponent(config, doctorConfig = {}) {
+  const registry = doctorConfig.registry || getRegistry();
   const results = [];
   const addPass = (checkName, message) => results.push({ level: 'pass', checkName, message });
   const addWarning = (checkName, message, fixHint) => results.push({ level: 'warning', checkName, message, fixHint });
@@ -240,7 +269,7 @@ export function checkComponent(config, doctorConfig = {}) {
   }
 
   // ── registry cross-check ─────────────────────────────────────────────────
-  const registryEntry = getRegistry().components.find((component) => component.id === config.id);
+  const registryEntry = registry.components.find((component) => component.id === config.id);
   if (!registryEntry) {
     addWarning('registry', `"${config.id}" is not in the devkit components.json`, 'add an entry (README catalogue + port allocation)');
   } else {
@@ -254,7 +283,7 @@ 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 });
+      checkPorts(config, registryEntry.port, registry, { 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');
@@ -274,12 +303,22 @@ export function checkComponent(config, doctorConfig = {}) {
     if (!outputMismatches.length) addPass('library', 'package.json targets match the library build outputs');
   }
 
+  // ── monorepo: the workspace packages doctor checks ───────────────────────
+  checkWorkspacePackages(config, { addPass, addWarning, addError });
+
   // ── core's default loader class ──────────────────────────────────────────
-  if (config.prefix && config.kind !== LIBRARY_KIND) checkLoaderClass(config, { addPass, addWarning, addError });
+  if (config.prefix && config.kind !== LIBRARY_KIND) {
+    for (const checkedPackage of config.packages.filter((packageEntry) => packageEntry.kind === 'component')) {
+      checkLoaderClass(config, checkedPackage, { addPass, addWarning, addError });
+    }
+  }
+
+  // ── variable manifest (what `kmwc check-vars` checks; it only runs in the build) ──
+  if (config.hasPackageConfig) checkVariableManifest(config, { addPass, addWarning, addError });
 
   // ── analytics ────────────────────────────────────────────────────────────
   const plausibleSiteId = loadPlausibleSiteId(config.root);
-  const sharingRepoIds = loadSharedPlausibleSiteIds(config, getRegistry(), plausibleSiteId);
+  const sharingRepoIds = loadSharedPlausibleSiteIds(config, registry, plausibleSiteId);
   if (sharingRepoIds.length) {
     addError(
       'analytics',
@@ -289,7 +328,9 @@ export function checkComponent(config, doctorConfig = {}) {
   } 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 });
+  if (doctorConfig.shouldCheckPackage !== false) {
+    for (const checkedPackage of config.packages) checkPackageContents(checkedPackage, { addPass, addWarning, addError });
+  }
 
   // ── rulebook suites ──────────────────────────────────────────────────────
   if (doctorConfig.shouldRunRulebook !== false) checkRulebook(config, { addPass, addWarning, addError });
@@ -298,7 +339,7 @@ export function checkComponent(config, doctorConfig = {}) {
 }
 
 /** Ports: script --port flags, own configs and docs outside the block, siblings inside it. */
-function checkPorts(config, portBlock, { addPass, addWarning, addError }) {
+function checkPorts(config, portBlock, registry, { addPass, addWarning, addError }) {
   const [firstPort, lastPort] = getPortBlockRange(portBlock);
   const blockLabel = `${firstPort}–${lastPort}`;
   const scriptPortMismatches = getScriptPortMismatches(config.packageJson.scripts, config.ports);
@@ -307,7 +348,7 @@ function checkPorts(config, portBlock, { addPass, addWarning, addError }) {
   }
   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());
+  const siblingCollisions = loadSiblingPortCollisions(config, registry);
   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`);
   }
@@ -316,7 +357,7 @@ function checkPorts(config, portBlock, { addPass, addWarning, addError }) {
     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)`
+      `update them to ${getPortsForBlock(portBlock).dev} (dev) / ${getPortsForBlock(portBlock).image} (image); a doc that names other repos' ports on purpose gets <!-- ${OTHER_PORTS_MARKER}: why -->`
     );
   }
   if (!scriptPortMismatches.length && !ownStrayPorts.length && !siblingCollisions.length && !stalePortMentions.length) {
@@ -330,13 +371,23 @@ function checkPorts(config, portBlock, { addPass, addWarning, addError }) {
  * before (or after) the core bump leaves the default loader unstyled, and no rulebook
  * check sees that (a VALIDATION-NOTES `## C-NC-8` even hides a leftover old class).
  */
-function checkLoaderClass(config, { addPass, addError }) {
-  const coreLoader = loadCoreLoader(config.root);
+function checkLoaderClass(config, checkedPackage, { addPass, addWarning, addError }) {
+  const coreLoader = loadCoreLoader(checkedPackage.root);
   if (!coreLoader?.separator) return;
   const coreClassName = `${config.prefix}${coreLoader.separator}loader`;
-  const styledLoaderClasses = loadStyledLoaderClasses(config.root, config.prefix);
-  const mismatchedClasses = styledLoaderClasses.filter(({ separator }) => separator !== coreLoader.separator);
-  for (const { file, className } of mismatchedClasses) {
+  const styledLoaderClasses = loadStyledLoaderClasses(checkedPackage.root, config.prefix).map((styledClass) => ({
+    ...styledClass,
+    file: getPackageFilePath(checkedPackage, styledClass.file),
+  }));
+  const { isCoreClassStyled, renamedClasses, collidingClasses } = getLoaderClassVerdict(coreLoader.separator, styledLoaderClasses);
+  for (const { file, className } of collidingClasses) {
+    addWarning(
+      'loader',
+      `${file} styles .${className} next to core's .${coreClassName} — from core 6d6b768 on, core draws its default loader as <span class="${className}"> and it picks up these rules`,
+      `rename the component's own .${className} element (e.g. .${config.prefix}__loading) in the same change as the core bump`
+    );
+  }
+  for (const { file, className } of renamedClasses) {
     addError(
       'loader',
       `${file} styles .${className}, but core ${coreLoader.version} draws the default loader as <span class="${coreClassName}"> — it renders unstyled`,
@@ -345,7 +396,30 @@ function checkLoaderClass(config, { addPass, addError }) {
         : `keep .${coreClassName} until the component builds on a core that draws <prefix>__loader, then rename in the same change`
     );
   }
-  if (styledLoaderClasses.length && !mismatchedClasses.length) addPass('loader', `CSS styles .${coreClassName}, the class core ${coreLoader.version} draws`);
+  if (isCoreClassStyled && !renamedClasses.length) addPass('loader', `CSS styles .${coreClassName}, the class core ${coreLoader.version} draws`);
+}
+
+/** The variable manifest matches the CSS — the same verdict as `kmwc check-vars` (undocumented = warning). */
+function checkVariableManifest(config, { addPass, addWarning, addError }) {
+  let manifestVerdict;
+  try {
+    manifestVerdict = loadManifestVerdict(config);
+  } catch (error) {
+    addError('vars', `kmwc check-vars can't run: ${error.message}`, 'fix kmwc.cssVariables (sources / manifest / prefix)');
+    return;
+  }
+  const { verdict, prefix, skippedReason } = manifestVerdict;
+  if (skippedReason) return;
+  const fixHint = 'edit the manifest to match the CSS (npm run check:vars lists every name)';
+  const listNames = (names) => names.map((name) => `--${name}`).join(', ');
+  if (verdict.missingBaseVariables.length) addError('vars', `--base-* read in CSS but missing from the manifest: ${listNames(verdict.missingBaseVariables)}`, fixHint);
+  if (verdict.unusedBaseVariables.length) addError('vars', `--base-* in the manifest but not read in CSS: ${listNames(verdict.unusedBaseVariables)}`, fixHint);
+  if (verdict.unusedComponentVariables.length) addError('vars', `--${prefix}-* in the manifest but not in CSS: ${listNames(verdict.unusedComponentVariables)}`, fixHint);
+  if (verdict.undocumentedComponentVariables.length) {
+    addWarning('vars', `--${prefix}-* in CSS but missing from the manifest: ${listNames(verdict.undocumentedComponentVariables)}`, `${fixHint}; runtime internals go in kmwc.cssVariables.internalVariables`);
+  }
+  const isInSync = !['missingBaseVariables', 'unusedBaseVariables', 'unusedComponentVariables', 'undocumentedComponentVariables'].some((key) => verdict[key].length);
+  if (isInSync) addPass('vars', `variable manifest in sync — ${verdict.counts.base} base, ${verdict.counts.component} component vars`);
 }
 
 /** Packed paths that break PACKAGE_LEAK_RULES → [{ path, label }]. Pure — exported for tests. */
@@ -358,10 +432,56 @@ export function getPackageLeaks(packedPaths) {
     });
 }
 
+/** `src/x.css` in a workspace package → `packages/web-x/src/x.css`; unchanged at the repo root. */
+function getPackageFilePath(checkedPackage, filePath) {
+  return checkedPackage.path === '.' ? filePath : `${checkedPackage.path.replace(/\\/g, '/').replace(/\/$/, '')}/${filePath}`;
+}
+
+/** The workspace directories package.json declares (`packages/*` → each subdirectory with a package.json). */
+function getWorkspaceRoots(config) {
+  const workspaces = config.packageJson.workspaces;
+  const workspacePatterns = Array.isArray(workspaces) ? workspaces : workspaces?.packages || [];
+  return workspacePatterns.flatMap((pattern) => {
+    if (!pattern.endsWith('/*')) return [resolve(config.root, pattern)];
+    const parentPath = resolve(config.root, pattern.slice(0, -2));
+    if (!existsSync(parentPath)) return [];
+    return readdirSync(parentPath)
+      .map((entryName) => join(parentPath, entryName))
+      .filter((entryPath) => existsSync(join(entryPath, 'package.json')));
+  });
+}
+
+/**
+ * A monorepo lists its packages in kmwc.packages, or doctor checks only the root (which a
+ * private workspace root never publishes). Every workspace package is listed; every listed one exists.
+ */
+function checkWorkspacePackages(config, { addPass, addWarning, addError }) {
+  for (const checkedPackage of config.packages) {
+    if (!existsSync(join(checkedPackage.root, 'package.json'))) addError('packages', `kmwc.packages lists ${checkedPackage.path}, which has no package.json`, 'fix the path');
+  }
+  const workspaceRoots = getWorkspaceRoots(config);
+  if (!workspaceRoots.length) return;
+  const toRepoPath = (absolutePath) => relative(config.root, absolutePath).replace(/\\/g, '/');
+  if (!config.packageJson.kmwc?.packages) {
+    addWarning(
+      'packages',
+      `npm workspaces (${workspaceRoots.map(toRepoPath).join(', ')}) but no kmwc.packages — doctor checks the root as the package`,
+      `list them: "packages": [${workspaceRoots.map((workspaceRoot) => `{ "path": "${toRepoPath(workspaceRoot)}", "kind": "component" | "library" }`).join(', ')}]`
+    );
+    return;
+  }
+  const listedRoots = new Set(config.packages.map((checkedPackage) => checkedPackage.root));
+  const unlistedRoots = workspaceRoots.filter((workspaceRoot) => !listedRoots.has(workspaceRoot));
+  for (const workspaceRoot of unlistedRoots) {
+    addWarning('packages', `workspace package ${toRepoPath(workspaceRoot)} is not in kmwc.packages — doctor doesn't check it`, `add { "path": "${toRepoPath(workspaceRoot)}", "kind": … }`);
+  }
+  if (!unlistedRoots.length) addPass('packages', `kmwc.packages lists every workspace package (${config.packages.map((checkedPackage) => `${checkedPackage.path} ${checkedPackage.kind}`).join(', ')})`);
+}
+
 /** The file list `npm publish` would ship (no lifecycle scripts, nothing written). */
-function getPackedPaths(config) {
+function getPackedPaths(packageRoot) {
   const packResult = spawnSync('npm', ['pack', '--dry-run', '--json', '--ignore-scripts'], {
-    cwd: config.root,
+    cwd: packageRoot,
     encoding: 'utf8',
     shell: process.platform === 'win32',
   });
@@ -370,26 +490,37 @@ function getPackedPaths(config) {
   return packReport[0].files.map((file) => file.path);
 }
 
-function checkPackageContents(config, { addPass, addWarning, addError }) {
+/**
+ * One package's `npm pack` list. A private workspace root is skipped: npm never publishes it and,
+ * having no `files`, it would "leak" everything (list the packages in kmwc.packages). A private
+ * single package (the devkit playground) is still checked — it stands in for a real one.
+ */
+function checkPackageContents(checkedPackage, { addPass, addWarning, addError }) {
+  const packageLabel = checkedPackage.path === '.' ? '' : `${checkedPackage.path}: `;
+  const packageJson = JSON.parse(readFileSync(join(checkedPackage.root, 'package.json'), 'utf8'));
+  if (packageJson.private && packageJson.workspaces) {
+    addPass('package', `${packageLabel}private workspace root — never published, contents not checked`);
+    return;
+  }
   let packedPaths;
   try {
-    packedPaths = getPackedPaths(config);
+    packedPaths = getPackedPaths(checkedPackage.root);
   } catch {
     packedPaths = null;
   }
   if (!packedPaths) {
-    addWarning('package', 'npm pack --dry-run failed — package contents not checked');
+    addWarning('package', `${packageLabel}npm pack --dry-run failed — package contents not checked`);
     return;
   }
   const packageLeaks = getPackageLeaks(packedPaths);
   for (const packageLeak of packageLeaks) {
     addError(
       'package',
-      `${packageLeak.path} would be published (${packageLeak.label})`,
-      `exclude it in package.json "files" (e.g. ${PACKAGE_FILES_EXCLUSIONS.map((exclusion) => `"${exclusion}"`).join(', ')}) or narrow the glob`
+      `${getPackageFilePath(checkedPackage, packageLeak.path)} would be published (${packageLeak.label})`,
+      `exclude it in ${packageLabel ? `${checkedPackage.path}/` : ''}package.json "files" (e.g. ${PACKAGE_FILES_EXCLUSIONS.map((exclusion) => `"${exclusion}"`).join(', ')}) or narrow the glob`
     );
   }
-  if (!packageLeaks.length) addPass('package', `${packedPaths.length} packed file(s), no dev-only files`);
+  if (!packageLeaks.length) addPass('package', `${packageLabel}${packedPaths.length} packed file(s), no dev-only files`);
 }
 
 function checkRulebook(config, { addPass, addWarning, addError }) {
@@ -398,39 +529,55 @@ 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);
-    addPass('rulebook', `${config.kind}: component-only suites not run (${componentOnlySuiteNames.join(', ')})`);
+  const isMonorepo = config.packages.some((checkedPackage) => checkedPackage.path !== '.');
+  // [{ suite, checkedRoot, checkName, acceptedCheckIds }]: a package's suites run in the package
+  // (for its kind), the repo-wide ones once at the root. A single-package repo runs all at the root.
+  const suiteRuns = [];
+  for (const checkedPackage of config.packages) {
+    const suites = getRulebookSuites(checkedPackage.kind).filter((suite) => !isMonorepo || !suite.isRepoWide);
+    const packageSuffix = isMonorepo ? `@${checkedPackage.path}` : '';
+    if (suites.length < RULEBOOK_SUITES.filter((suite) => !isMonorepo || !suite.isRepoWide).length) {
+      const componentOnlySuiteNames = RULEBOOK_SUITES.filter((suite) => suite.isComponentOnly).map((suite) => suite.name);
+      addPass(`rulebook${packageSuffix}`, `${checkedPackage.kind}: component-only suites not run (${componentOnlySuiteNames.join(', ')})`);
+    }
+    const acceptedCheckIds = new Set([...loadAcceptedCheckIds(config.root), ...loadAcceptedCheckIds(checkedPackage.root)]);
+    for (const suite of suites) suiteRuns.push({ suite, checkedRoot: checkedPackage.root, checkName: `rulebook:${suite.name}${packageSuffix}`, acceptedCheckIds });
+  }
+  if (isMonorepo) {
+    const acceptedCheckIds = loadAcceptedCheckIds(config.root);
+    for (const suite of RULEBOOK_SUITES.filter((repoSuite) => repoSuite.isRepoWide)) suiteRuns.push({ suite, checkedRoot: config.root, checkName: `rulebook:${suite.name}`, acceptedCheckIds });
   }
-  for (const suite of suites) {
+  for (const { suite, checkedRoot, checkName, acceptedCheckIds } of suiteRuns) {
     if (skippedSuites.has(suite.name)) continue;
     if (!existsSync(join(config.rulebook.path, `${suite.name}.checks.sh`))) continue;
-    const suiteResult = runRulebookSuite(config, suite);
+    const suiteResult = runRulebookSuite(config, suite, checkedRoot);
     if (suiteResult.error) {
       addWarning('rulebook', `cannot run bash (${suiteResult.error.code}) — rulebook checks skipped`, 'install Git Bash / run from a POSIX shell');
       return;
     }
-    const checkName = `rulebook:${suite.name}`;
-    if (suiteResult.status === 2) {
-      const reason = mapToPlainText(suiteResult.stderr || suiteResult.stdout).trim().split(/\r?\n/)[0];
-      addWarning(checkName, `suite could not run: ${reason}`);
+    const failures = getSuiteFailures(suiteResult.stdout);
+    // A suite passes with exit 0 and fails with exit 1 + FAIL lines. Anything else (2 = usage,
+    // 127 = the script wasn't found — WSL's bash on a C:/ path) means it never ran: say so,
+    // never count it as a pass.
+    const hasRun = suiteResult.status === 0 || (suiteResult.status === 1 && failures.length > 0);
+    if (!hasRun) {
+      const reason = mapToPlainText(suiteResult.stderr || suiteResult.stdout).trim().split(/\r?\n/)[0] || 'no output';
+      addWarning(checkName, `suite could not run (exit ${suiteResult.status}): ${reason}`, `bash used: ${getBashPath()} — set KMWC_BASH to Git for Windows' bash.exe if this is WSL's`);
       continue;
     }
-    const failures = getSuiteFailures(suiteResult.stdout);
     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}`);
+    if (!failures.length) addPass(checkName, 'all auto checks pass');
   }
 }
 
-export async function run(args) {
+/** `registry` is for tests (fixture repos); the CLI always uses components.json. */
+export async function run(args, { registry } = {}) {
   const config = getKmwcConfig(args.root);
-  const results = checkComponent(config, { shouldRunRulebook: !args['no-rulebook'], shouldCheckPackage: !args['no-pack'] });
+  const results = checkComponent(config, { shouldRunRulebook: !args['no-rulebook'], shouldCheckPackage: !args['no-pack'], registry });
   const errorCount = results.filter((result) => result.level === 'error').length;
   const warningCount = results.filter((result) => result.level === 'warning').length;
 

package/src/cli/repo-checks.js

@@ -109,6 +109,12 @@ export function getMentionedPorts(text) {
   return getUniqueSorted(patterns.flatMap((pattern) => [...text.matchAll(pattern)].map((match) => Number(match[1]))));
 }
 
+/**
+ * A doc that names other repos' ports on purpose (a dated plan, a cross-repo review) carries
+ * `<!-- kmwc-other-ports: why -->` and isn't scanned.
+ */
+export const OTHER_PORTS_MARKER = 'kmwc-other-ports';
+
 /** 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);
@@ -116,7 +122,7 @@ export function loadStalePortMentions(root, portBlock) {
   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 })) : [];
+    return text && !text.includes(OTHER_PORTS_MARKER) ? getMentionedPorts(text).filter((port) => !checkIsInRange(port, blockRange)).map((port) => ({ file, port })) : [];
   });
 }
 
@@ -252,7 +258,8 @@ export function getKitDuplicates(pageText, kitClassNames, { isStylesheet = false
 
 /**
  * Fixed colours on purpose (a theme gallery, a mockup, a test fixture): a page `<style>`
- * block with the attribute, or one rule right after a `/* kmwc-fixed-colors *\/` comment.
+ * block or an element with a `style="…"` that carries the attribute, or one rule right
+ * after a `/* kmwc-fixed-colors *\/` comment.
  */
 export const FIXED_COLORS_ATTRIBUTE = 'data-kmwc-fixed-colors';
 export const FIXED_COLORS_MARKER = 'kmwc-fixed-colors';
@@ -283,7 +290,7 @@ export function checkIsHardcodedColor(property, value) {
  * Hard-coded colours in one page's `<style>` blocks and `style="…"` attributes (or in
  * examples-local.css): they stay the same in dark mode while the kit around them flips.
  * `var()` fallbacks and `light-dark()` pairs follow the theme; a `<style data-kmwc-fixed-colors>`
- * block and a rule marked `/* kmwc-fixed-colors *\/` are skipped. Returns [{ found }]. Pure.
+ * block, an element carrying the attribute and a rule marked `/* kmwc-fixed-colors *\/` are skipped. Returns [{ found }]. Pure.
  */
 export function getHardcodedColors(pageText, { isStylesheet = false } = {}) {
   const styleText = isStylesheet
@@ -302,7 +309,12 @@ export function getHardcodedColors(pageText, { isStylesheet = false } = {}) {
     }
   }
   if (isStylesheet) return hardcodedColors;
-  for (const [, inlineStyle] of pageText.matchAll(/\sstyle="([^"]*)"/g)) {
+  for (const match of pageText.matchAll(/\sstyle="([^"]*)"/g)) {
+    // The element's own attribute opts its style="…" out: markup a render callback draws
+    // inside a shadow root can't be reached by page CSS, so inline is the only way there.
+    const tagText = pageText.slice(pageText.lastIndexOf('<', match.index), pageText.indexOf('>', match.index + match[0].length) + 1);
+    if (tagText.includes(FIXED_COLORS_ATTRIBUTE)) continue;
+    const inlineStyle = match[1];
     for (const declaration of inlineStyle.split(';')) {
       const [property, ...valueParts] = declaration.split(':');
       const value = valueParts.join(':').trim();
@@ -358,6 +370,24 @@ function getSourceStylesheets(directory, relativeDirectory = SOURCE_DIR) {
   });
 }
 
+/**
+ * Styled loader classes vs the separator core draws → { isCoreClassStyled, renamedClasses,
+ * collidingClasses }. A class with the other separator is a rename done too early / too late —
+ * unless core is still on `-` and its class is styled too: then the `__loader` is the
+ * component's own element (web-multiselect's loading-state row), which collides once core
+ * draws `<prefix>__loader`. Pure.
+ */
+export function getLoaderClassVerdict(coreSeparator, styledLoaderClasses) {
+  const isCoreClassStyled = styledLoaderClasses.some(({ separator }) => separator === coreSeparator);
+  const otherClasses = styledLoaderClasses.filter(({ separator }) => separator !== coreSeparator);
+  const isOwnLoaderElement = coreSeparator === '-' && isCoreClassStyled;
+  return {
+    isCoreClassStyled,
+    renamedClasses: isOwnLoaderElement ? [] : otherClasses,
+    collidingClasses: isOwnLoaderElement ? otherClasses : [],
+  };
+}
+
 /** Loader classes styled in the component's src CSS: [{ file, className, separator }]. */
 export function loadStyledLoaderClasses(root, prefix) {
   return getSourceStylesheets(join(root, SOURCE_DIR)).flatMap((file) =>

package/src/config.d.ts

@@ -73,6 +73,19 @@ export interface KmwcPackageConfig {
     skippedChecks?: string[];
   };
   sync?: { skippedFiles?: string[] };
+  /**
+   * The packages this repo publishes, for a monorepo whose root is not the package (npm
+   * workspaces): doctor runs the package-contents check and the rulebook suites for each one's
+   * kind there. Default: one package, the repo root, with the repo's kind.
+   */
+  packages?: Array<{ path: string; kind: 'component' | 'library' }>;
+}
+
+/** One package doctor checks: `path` as configured, `root` resolved. */
+export interface KmwcPackage {
+  path: string;
+  root: string;
+  kind: 'component' | 'library';
 }
 
 export interface KmwcConfig {
@@ -131,6 +144,7 @@ export interface KmwcConfig {
   };
   rulebook: { path: string; skippedChecks: string[] };
   sync: { skippedFiles: string[] };
+  packages: KmwcPackage[];
 }
 
 export const DEVKIT_ROOT: string;

package/src/config.js

@@ -183,6 +183,23 @@ export function getKmwcConfig(root = process.cwd()) {
   return mapKmwcConfig(getJsonFile(packageJsonPath), root);
 }
 
+const PACKAGE_KINDS = ['component', 'library'];
+
+/**
+ * `kmwc.packages` → [{ path, root, kind }]; without it, one package at the repo root with the
+ * repo's kind (a showcase / docs / test repo checks as a component, as before).
+ */
+function mapPackages(packageEntries, root, repoKind) {
+  if (!packageEntries) return [{ path: '.', root, kind: repoKind === 'library' ? 'library' : 'component' }];
+  if (!Array.isArray(packageEntries) || !packageEntries.length) throw new Error('kmwc.packages: expected a non-empty array of { path, kind }');
+  return packageEntries.map((packageEntry) => {
+    if (!packageEntry?.path || !PACKAGE_KINDS.includes(packageEntry.kind)) {
+      throw new Error(`kmwc.packages: ${JSON.stringify(packageEntry)} needs a "path" and a "kind" (${PACKAGE_KINDS.join(' | ')})`);
+    }
+    return { path: packageEntry.path, root: resolve(root, packageEntry.path), kind: packageEntry.kind };
+  });
+}
+
 /** Map a parsed package.json to the resolved config (pure — used by tests). */
 export function mapKmwcConfig(packageJson, root = process.cwd()) {
   const packageConfig = packageJson.kmwc || {};
@@ -199,6 +216,7 @@ export function mapKmwcConfig(packageJson, root = process.cwd()) {
   const cssVariables = packageConfig.cssVariables === false ? { checkMode: 'off' } : packageConfig.cssVariables || {};
   const rulebook = packageConfig.rulebook || {};
   const devPort = ports.dev ?? 5173;
+  const kind = packageConfig.kind || getRegistryKind(id);
 
   return {
     root,
@@ -206,7 +224,7 @@ export function mapKmwcConfig(packageJson, root = process.cwd()) {
     packageJson,
     id,
     packageName: packageJson.name || id,
-    kind: packageConfig.kind || getRegistryKind(id),
+    kind,
     version: packageJson.version || '0.1.0',
     title: packageConfig.title || mapToTitleCase(id),
     tagline: packageConfig.tagline || packageJson.description || '',
@@ -275,6 +293,7 @@ export function mapKmwcConfig(packageJson, root = process.cwd()) {
     sync: {
       skippedFiles: packageConfig.sync?.skippedFiles || [],
     },
+    packages: mapPackages(packageConfig.packages, root, kind),
   };
 }
 

package/src/examples/constants.js

@@ -97,6 +97,12 @@ export const INDEX_PAGE_CLASSES = {
   devkit: 'kmwc-index__devkit',
 };
 
+/** The footer the kit appends to every example page but the index (page-footer.js). */
+export const PAGE_FOOTER_CLASSES = {
+  root: 'kmwc-page-footer',
+  devkit: 'kmwc-page-footer__devkit',
+};
+
 /** <kmwc-demo> output (rendered at build time by page-composer.js) + the kit's copy button. */
 export const DEMO_CLASSES = {
   root: 'kmwc-demo',

package/src/examples/css/page-footer.css

@@ -0,0 +1,19 @@
+/* ==============================================================================
+   EXAMPLES KIT — PAGE FOOTER
+   ==============================================================================
+   The footer the kit appends to every example page but the index
+   (page-footer.js); the same line as the index footer. */
+@layer kmwc {
+    .kmwc-page-footer {
+        text-align: center;
+        margin-top: 3rem;
+        padding: 1.5rem 0 1rem;
+        border-top: 1px solid var(--kmwc-border-color);
+        color: var(--kmwc-text-color-3);
+        font-size: 0.875rem;
+    }
+
+    .kmwc-page-footer p {
+        margin: 0;
+    }
+}

package/src/examples/css/style.css

@@ -31,3 +31,4 @@
 @import './spotlight.css';
 @import './theme-switch.css';
 @import './index-page.css';
+@import './page-footer.css';

package/src/examples/css/tokens.css

@@ -120,9 +120,10 @@
         --kmwc-console-err-color: #fca5a5;
         /* Dark: the chip is a step up from the main surface (slate on a slate page, not a
            neutral grey), and the text keeps the accent hue but at least 0.8 lightness, so a
-           mid-dark accent (treeview's #059669) stays readable on it. */
+           mid-dark accent (treeview's #059669) stays readable on it. Light: the same hue at
+           most 0.5 lightness — the raw accent read at ~3.3:1 on the pale chip. */
         --kmwc-inline-code-bg: light-dark(#edf2f7, oklch(from var(--kmwc-main-bg) calc(l + 0.07) c h));
-        --kmwc-inline-code-color: light-dark(var(--kmwc-accent-color), oklch(from var(--kmwc-accent-color) max(l, 0.8) c h));
+        --kmwc-inline-code-color: light-dark(oklch(from var(--kmwc-accent-color) min(l, 0.5) c h), oklch(from var(--kmwc-accent-color) max(l, 0.8) c h));
 
         /* ======================================================================
            COLORS — SEMANTIC

package/src/examples/index-page.js

@@ -19,6 +19,7 @@
 import { getPageConfig } from './page-config.js';
 import { getVersionLabel } from './version-badge.js';
 import { INDEX_PAGE_CLASSES } from './constants.js';
+import { renderFooterLineHtml } from './page-footer.js';
 
 const HTML_ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
 const mapToEscapedHtml = (text) => String(text ?? '').replace(/[&<>"']/g, (character) => HTML_ESCAPES[character]);
@@ -32,10 +33,6 @@ export function renderExamplesIndex(indexConfig) {
   const pages = indexConfig.pages || [];
   const title = indexConfig.title ?? pageConfig.title;
   const tagline = indexConfig.tagline ?? pageConfig.tagline;
-  const footerLinks = [
-    ...(pageConfig.repository ? [{ label: 'GitHub', href: pageConfig.repository }] : []),
-    ...(indexConfig.links || []),
-  ];
   const classes = INDEX_PAGE_CLASSES;
 
   document.body.classList.add(classes.body);
@@ -63,13 +60,7 @@ export function renderExamplesIndex(indexConfig) {
         .join('')}
     </div>
     <footer class="${classes.footer}">
-      <p>Created by <a href="https://github.com/keenmate" target="_blank" rel="noopener">Keenmate s.r.o.</a>${footerLinks
-        .map((link) => ` | <a href="${mapToEscapedHtml(link.href)}" target="_blank" rel="noopener">${mapToEscapedHtml(link.label)}</a>`)
-        .join('')}${
-        pageConfig.devkitVersion
-          ? ` | <a class="${classes.devkit}" href="${mapToEscapedHtml(pageConfig.devkitHomepage)}" target="_blank" rel="noopener">web-components-devkit v${mapToEscapedHtml(pageConfig.devkitVersion)}</a>`
-          : ''
-      }</p>
+      ${renderFooterLineHtml(pageConfig, { links: indexConfig.links, devkitClass: classes.devkit })}
     </footer>`;
   containerEl.prepend(pageElement);
 

package/src/examples/index.d.ts

@@ -11,7 +11,7 @@ export interface KmwcPageConfig {
   isSpotlightEnabled: boolean;
   repository: string;
   homepage: string;
-  /** The @keenmate/web-components-devkit version that built the page (shown in the index footer). */
+  /** The @keenmate/web-components-devkit version that built the page (shown in the page footers). */
   devkitVersion: string;
   devkitHomepage: string;
 }
@@ -93,6 +93,10 @@ export function renderVersionBadges(root?: ParentNode): void;
 export function attachDemoCopyButtons(root?: ParentNode): void;
 export function getVersionLabel(pageConfig?: KmwcPageConfig): string;
 
+/** Append the footer (Keenmate | GitHub | devkit version) to an example page; none on the index. */
+export function mountPageFooter(): HTMLElement | null;
+/** The footer line the index and the page footer share. */
+export function renderFooterLineHtml(pageConfig: KmwcPageConfig, footerConfig: { links?: Array<{ label: string; href: string }>; devkitClass: string }): string;
 export function mountThemeSwitch(): { unmount(): void };
 export function applyTheme(theme: Theme): void;
 export function getSavedTheme(): Theme;
@@ -118,6 +122,7 @@ export const SPOTLIGHT_FULLSCREEN_MEDIA: string;
 export const CHAPTER_CODE_PATTERN: RegExp;
 export const COPY_LINK_CLASSES: Record<string, string>;
 export const INDEX_PAGE_CLASSES: Record<string, string>;
+export const PAGE_FOOTER_CLASSES: { root: string; devkit: string };
 export const THEME_SWITCH_CLASSES: Record<string, string>;
 export const DEMO_CLASSES: Record<string, string>;
 export const THEMES: Theme[];

package/src/examples/index.js

@@ -15,6 +15,7 @@ export { searchChapters, checkMatchesAny, renderHighlightedText } from './chapte
 export { attachCopyLinks, copyText, getSectionUrl } from './copy-link.js';
 export { renderVersionBadges, getVersionLabel } from './version-badge.js';
 export { attachDemoCopyButtons } from './demo-code.js';
+export { mountPageFooter, renderFooterLineHtml } from './page-footer.js';
 export { mountThemeSwitch, applyTheme, getSavedTheme } from './theme-switch.js';
 export { ensureSectionAnchors, generateSlug, getHeadingLabel, getChapterCode, mapToCodeKey, findSectionByHash } from './sections.js';
 export { getPageConfig, attachDomReadyHandler } from './page-config.js';

package/src/examples/kit.js

@@ -5,15 +5,16 @@ import { attachCopyLinks } from './copy-link.js';
 import { renderVersionBadges } from './version-badge.js';
 import { mountThemeSwitch } from './theme-switch.js';
 import { attachDemoCopyButtons } from './demo-code.js';
+import { mountPageFooter } from './page-footer.js';
 import { INDEX_PAGE_CLASSES } from './constants.js';
 
 /**
  * (Re)mount the page-level helpers on the current DOM (copy-links, chapter
  * nav, short chapter links, spotlight, version badges, demo copy buttons,
- * theme switch). Runs automatically once per page; call it again after
+ * theme switch, page footer). Runs automatically once per page; call it again after
  * rendering sections asynchronously. Idempotent: copy-link / demo copy buttons
- * skip elements that already have one, the nav, spotlight and theme switch are
- * remounted.
+ * skip elements that already have one, the nav, spotlight, theme switch and
+ * footer are remounted.
  */
 export function mountExamplesKit() {
   // Copy-links before the nav: the nav strips the buttons back out when
@@ -26,4 +27,5 @@ export function mountExamplesKit() {
   renderVersionBadges();
   attachDemoCopyButtons();
   mountThemeSwitch();
+  mountPageFooter();
 }

package/src/examples/page-footer.js

@@ -0,0 +1,44 @@
+/**
+ * The footer every example page ends with — Keenmate, the repo, and the devkit
+ * that built the page. The index page renders the same line in its own footer
+ * (index-page.js); the other pages get it from the kit (mountPageFooter).
+ */
+import { getPageConfig } from './page-config.js';
+import { INDEX_PAGE_CLASSES, PAGE_FOOTER_CLASSES } from './constants.js';
+
+const HTML_ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+const mapToEscapedHtml = (text) => String(text ?? '').replace(/[&<>"']/g, (character) => HTML_ESCAPES[character]);
+
+/**
+ * The footer line: "Created by Keenmate s.r.o. | GitHub | …links | web-components-devkit vX".
+ * @param {import('./index.js').KmwcPageConfig} pageConfig
+ * @param {{ links?: Array<{ label: string, href: string }>, devkitClass: string }} footerConfig
+ */
+export function renderFooterLineHtml(pageConfig, { links = [], devkitClass }) {
+  const footerLinks = [...(pageConfig.repository ? [{ label: 'GitHub', href: pageConfig.repository }] : []), ...links];
+  const linksHtml = footerLinks
+    .map((link) => ` | <a href="${mapToEscapedHtml(link.href)}" target="_blank" rel="noopener">${mapToEscapedHtml(link.label)}</a>`)
+    .join('');
+  const devkitHtml = pageConfig.devkitVersion
+    ? ` | <a class="${devkitClass}" href="${mapToEscapedHtml(pageConfig.devkitHomepage)}" target="_blank" rel="noopener">web-components-devkit v${mapToEscapedHtml(pageConfig.devkitVersion)}</a>`
+    : '';
+  return `<p>Created by <a href="https://github.com/keenmate" target="_blank" rel="noopener">Keenmate s.r.o.</a>${linksHtml}${devkitHtml}</p>`;
+}
+
+/**
+ * Append the footer to an example page — inside the layout's `.container`
+ * when there is one, else at the end of <body>. Remounting replaces it; the
+ * index page keeps its own footer and gets none.
+ * @returns {HTMLElement | null}
+ */
+export function mountPageFooter() {
+  document.querySelector(`.${PAGE_FOOTER_CLASSES.root}`)?.remove();
+  if (document.body.classList.contains(INDEX_PAGE_CLASSES.body)) return null;
+
+  const footerElement = document.createElement('footer');
+  footerElement.className = PAGE_FOOTER_CLASSES.root;
+  footerElement.innerHTML = renderFooterLineHtml(getPageConfig(), { devkitClass: PAGE_FOOTER_CLASSES.devkit });
+  const containerElement = document.querySelector('body > .container');
+  (containerElement || document.body).append(footerElement);
+  return footerElement;
+}

package/src/vite/page-composer.js

@@ -39,7 +39,11 @@ const INCLUDE_PATTERN = /<kmwc-include\b([^>]*?)(?:\/>|>([\s\S]*?)<\/kmwc-includ
 const DEMO_PATTERN = /<kmwc-demo\b([^>]*)>([\s\S]*?)<\/kmwc-demo>/g;
 const SHOWN_SCRIPT_PATTERN = /<script\b([^>]*\bdata-kmwc-show\b[^>]*)>([\s\S]*?)<\/script>/g;
 const PAGE_META_PATTERN = /<meta\s+name="kmwc:([a-z-]+)"\s+content="([^"]*)"\s*\/?>\s*/g;
-const HEAD_ELEMENT_PATTERN = /<link\b[^>]*>\s*|<style\b[^>]*>[\s\S]*?<\/style>\s*/g;
+// A <style> element, or ANY start tag (quoted attribute values may hold `>` and `<link>`):
+// matching whole tags left to right means the text `<link>` inside a tooltip's title=""
+// is consumed with its tag and never read as an element. Only <style> and <link> move.
+const HEAD_ELEMENT_PATTERN = /<style(?=[\s>])(?:"[^"]*"|'[^']*'|[^>"'])*>[\s\S]*?<\/style>\s*|<([a-zA-Z][\w-]*)(?:"[^"]*"|'[^']*'|[^>"'])*>\s*/g;
+const HEAD_ELEMENT_TAGS = ['style', 'link'];
 const ATTRIBUTE_PATTERN = /([a-zA-Z][\w-]*)(?:\s*=\s*"([^"]*)")?/g;
 
 const HTML_COMMENT_PATTERN = /<!--[\s\S]*?-->/g;
@@ -201,7 +205,8 @@ export function renderLayout(fragmentHtml, { config, pagePath }) {
   const bodyContent = mapOutsideComments(
     htmlWithoutMeta,
     (text) =>
-      text.replace(HEAD_ELEMENT_PATTERN, (element) => {
+      text.replace(HEAD_ELEMENT_PATTERN, (element, tagName = 'style') => {
+        if (!HEAD_ELEMENT_TAGS.includes(tagName.toLowerCase())) return element;
         headElements.push(`    ${element.trim()}`);
         return '';
       }),

package/templates/claude-block.md

@@ -31,7 +31,8 @@ locally — every local fork is how they drifted apart.
   too — no inline styles for them. Page colours come from the kit's `--kmwc-*`
   tokens or `light-dark()` — a literal doesn't follow dark mode (doctor warns);
   a demo that shows fixed colours on purpose goes in `<style data-kmwc-fixed-colors>`
-  (one rule: a `/* kmwc-fixed-colors: why */` comment before it).
+  (one rule: a `/* kmwc-fixed-colors: why */` comment before it; an element's own
+  `style="…"`: the attribute on the element).
   If a second component needs a pattern, it belongs in the devkit.
 - **Example pages are fragments:** no `<html>`/`<head>`/`<header>` — start with
   `<meta name="kmwc:title" content="…">`, the devkit layout adds the rest. Shared text