@keenmate/web-components-devkit 1.0.0-rc02 → 1.0.0-rc03

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## [1.0.0-rc03] - 2026-11-01 [PUBLISHED]
+
+### Fixed
+
+- **Example pages no longer widen the page on a phone** — on screens ≤ 768 px a
+  `.reference-table` scrolls inside its card, a long `.controls` label (or `<code>` in it)
+  wraps and a `.controls` select is capped at the row, instead of overflowing. Besides the sideways scroll, an over-wide page made mobile
+  browsers grow the layout viewport (a 390 px phone reporting ~600 px), so pages that
+  demo device / breakpoint detection showed the wrong class.
+- **The scaffold's component CSS no longer sets `box-sizing` on the host page** — the
+  `*, *::before, *::after { box-sizing: inherit }` reset in `templates/new/src/css/base.css`
+  (also in the `--minimal` scaffold and the playground) reached the page through the light-DOM stylesheet, in a layer that beats
+  `@layer kmwc`, so every page control rendered content-box (the spotlight input overflowed, a
+  36 px input came out 38 px). It is scoped to `:host *` now; components scaffolded with an
+  earlier devkit should make the same one-line change. A unit test now rejects any universal or
+  bare-element selector in the scaffold CSS.
+
+### Added
+
+- **Form controls: one look for native inputs on every example page** — text fields, selects
+  and list boxes, textareas, checkboxes (incl. indeterminate), radios, switches
+  (`<input type="checkbox" role="switch">`), ranges, colour and file inputs and fieldsets are
+  styled without a class, modelled on pure-admin's forms: inputs, selects and buttons share
+  `--kmwc-control-height`, so a row of them lines up in any container (not only `.controls`);
+  the focus border and halo, placeholder, disabled tone, the checkbox size and the
+  `--base-icon-check` / `-indeterminate` tick read the `--base-*` contract. Rules are
+  zero-specificity (`:where()`); `kmwc-native` on an element or an ancestor keeps the
+  browser's own controls. Outline buttons are as tall as filled ones now (transparent border).
+  The playground's new `examples-forms.html` shows them all.
+- **Tables: every `<table>` on an example page is styled** — a header fill, row lines, hover
+  tint, caption and footer, as pure-admin's `.pa-table`. `.reference-table` looks as before;
+  new modifiers combine with it or a bare table: `.table-full`, `.table-bordered`,
+  `.table-striped`, `.table-compact` (tighter cells, and the inputs / selects / buttons in it
+  shrink with them via `--kmwc-control-height`), plus `tr.is-highlight` on any table and a
+  `.num` cell (right-aligned, tabular figures). Every table, not only `.reference-table`,
+  scrolls inside its card on a phone. Pages no longer need their own table CSS with fixed light
+  colours (core's `.rs-table`, which breaks in dark mode). New playground page
+  `examples-tables.html`.
+- **Spotlight: Ctrl/⌘+K chapter search across every example page** — matches a chapter whose
+  section code or heading text contains the query (`th7` finds `TH07`; uncoded `Summary` /
+  reference sections by title), grouped by page with the current page first; Enter jumps,
+  Ctrl/⌘+Enter opens a new tab. The Vite plugin builds the index (`virtual:kmwc-chapters`)
+  from every page's `<h2>`s; `kmwc.examples.isSpotlightEnabled: false` turns it off. It mirrors
+  web-commandpalette's markup, matching, keyboard map, open/close and CSS without depending on
+  it — `npm run check:spotlight-mirror` lists what changed there since the last alignment.
+  New page tokens `--kmwc-overlay-bg` and `--kmwc-focused-bg` / `-text-color` / `-outline`
+  read the same `--base-*` hooks as wcp, so both look alike under a theme.
+- **Short chapter links** — `#th07`, `#th7` or the slug of an uncoded heading scroll to that
+  chapter on arrival.
+- **`make dev` (and `kill-port`, `build-examples`, `preview-examples`) at the repo root** — the
+  standard targets, run against the playground; `make playground` is gone.
+- **`kmwc doctor` runs the rulebook's new `example-pages` suite** — every example `<h2>`
+  carries a permanent section code (`TH07 · Title`), a prefix belongs to one page, no code
+  is used twice. The generated CLAUDE.md block points at the rule. The convention was
+  already in the scaffold and the playground but written down nowhere, so sessions
+  building new pages didn't know it.
+
+### Known issues
+
+- **Opening the spotlight shifts the page sideways** on systems with classic scrollbars: the
+  mirrored core `lockBodyScroll()` only sets `overflow: hidden`, so the scrollbar disappears
+  (wcp has the same jump). pure-admin / pure-css avoid it with a `position: fixed` lock and
+  width compensation; the proposal to bring that into core is in web-commandpalette's CLAUDE.md.
+
 ## [1.0.0-rc02] - 2026-10-31 [PUBLISHED]
 
 ### Added

package/README.md

@@ -19,6 +19,15 @@ 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-rc03
+
+- **Spotlight — Ctrl/⌘+K chapter search across every example page** — Example sites grew to dozens of chapters over several pages, and the per-page chapter nav only knew its own page. The Vite plugin now builds an index of every page's `<h2>`s (`virtual:kmwc-chapters`), coded and uncoded, and Ctrl/⌘+K opens a search that matches the section code or the heading text (`th7` finds `TH07`), grouped by page with the current one first. Enter jumps, Ctrl/⌘+Enter opens a new tab. It mirrors web-commandpalette's markup, matching, keyboard map and CSS without depending on it; `npm run check:spotlight-mirror` lists what changed there since the last alignment. Turn it off with `kmwc.examples.isSpotlightEnabled: false`.
+- **Form controls — one look for native inputs on every example page** — Pages styled their own selects and inputs, or got the browser default, so a select next to the kit's buttons came out shorter and in the platform's style (a `.controls` row was the only place the kit reached). Text fields, selects and list boxes, textareas, checkboxes, radios, `role="switch"` switches, ranges, colour and file inputs are now styled with no class, modelled on pure-admin's forms. Inputs, selects and buttons share `--kmwc-control-height`, so a mixed row lines up in any container. Focus, placeholder, disabled tone, checkbox size and the tick read the `--base-*` contract. The rules are zero-specificity, and `kmwc-native` opts an element out.
+- **Tables — every table styled, `.reference-table` plus modifiers** — Only `.reference-table` had a look; a bare table was unstyled and pages wrote their own table CSS with fixed light colours that break in dark mode. Any `<table>` now gets a header fill, row lines and a hover tint, and modifiers combine: `.table-full`, `.table-bordered`, `.table-striped`, and `.table-compact`, whose inputs and buttons shrink with the rows. Add `tr.is-highlight` and `.num` (tabular figures). Every wide table scrolls inside its card on a phone.
+- **Scaffold — component CSS no longer restyles the host page** — The `*, *::before, *::after { box-sizing: inherit }` reset in the `kmwc new` and `--minimal` templates also reached the page through the component's light-DOM stylesheet, in a layer that beats `@layer kmwc`, so page controls rendered content-box (a 36 px input came out 38 px). It is scoped to `:host *` now, and a unit test rejects any universal or bare-element selector in scaffold CSS. Components scaffolded on rc01/rc02 should make the same one-line change in `src/css/base.css`.
+- **Example pages — short chapter links, phones and the example-pages suite** — `#th07`, `#th7` or an uncoded heading's slug now scroll to that chapter on arrival. On a phone, example pages no longer grow wider than the screen, which made mobile browsers report a wrong viewport to pages that demo breakpoints. `kmwc doctor` runs the rulebook's new `example-pages` suite: every example `<h2>` carries a permanent section code.
+- **`make dev` at the devkit root** — the standard `dev` / `kill-port` / `build-examples` / `preview-examples` targets, run against the playground.
+
 ## What's New in v1.0.0-rc02
 
 - **Theming — kit and scaffolds follow base-css-variables 2.0** — base-css-variables 2.0 dropped `--base-accent-color*`, `--base-text-color-on-accent` and `--base-input-color`, so a theme's primary colour silently stopped reaching the example pages and every newly scaffolded component. The `--kmwc-*` tokens in `src/examples/css/tokens.css` and the `templates/new*` `variables.css` now read `--base-primary-color` (with `-hover` / `-active` / `-bg-subtle`), `--base-on-primary-text-color` and `--base-input-text-color`, and the theming pages, docs and manifests set the new names. Standalone fallbacks are now the contract's own values, so a page looks the same with or without the contract loaded: a blue-500 primary instead of the old purple, slate surfaces, and on-colours computed from their fill. Re-run `kmwc new` output or diff your `variables.css` if you scaffolded on rc01.
@@ -26,16 +35,6 @@ them in the same shape: `@keenmate/web-components-devkit`.
 - **`kmwc new --adopt` — migrate a component that's already registered** — Brings an existing repo onto the devkit with the same rulebook-shaped scaffold, using the registry entry's port block and CSS prefix, skipping the npm-name check (the package already exists) and leaving `components.json` untouched. Scaffold into a scratch `--dir` and move the component's code in. web-editor's one-package monorepo was flattened this way.
 - **`kmwc doctor` — rulebook suites run from an npm install** — With the devkit installed from npm instead of linked, doctor looked for the BlissFramework rulebook at a path relative to the devkit, which ended up inside `node_modules`, and silently skipped every suite. It now uses the nearest `BlissFramework/guidelines/web-components` above the component (then above the devkit), and `kmwc.rulebook.path` resolves against the component root.
 
-## What's New in v1.0.0-rc01
-
-- **Devkit — one shared toolchain for every Keenmate web component** — Each `web-*` repo used to carry its own copy of the example helpers, the shared stylesheet, the Vite/Playwright configs and the deploy files, and every session "fixed" its own copy until they drifted apart. `@keenmate/web-components-devkit` owns all of it now: a component describes itself once in `package.json#kmwc` (title, prefix, ports, accent colours, analytics, image) and `defineComponentConfig()`, `definePlaywrightConfig()` and the `kmwc` CLI read it from there. A shared concern is fixed once in the devkit and every component picks it up on the next install.
-- **Vite preset — dev, library and examples-site builds from one config** — `defineComponentConfig()` (Vite 7) runs the dev server on the repo's registry port with `strictPort`, builds the library (`es` + `umd`, `style.css` kept under its historical name, rolled-up `.d.ts`) and, with `--mode examples`, builds every root `*.html` into a static multi-page site in `dist-examples/` with relative asset URLs. The examples plugin injects the kit into each page and loads its stylesheet render-blocking, so pages don't flash unstyled on reload.
-- **Examples kit — one design system and set of page helpers instead of six forks** — The `@layer kmwc` stylesheet merges six diverged `examples-shared.css` copies; its `--kmwc-*` tokens read the rulebook's `--base-*` taxonomy with `light-dark()` fallbacks, so a theme-designer theme restyles the demo page together with the component. Every page gets a light / dark / auto theme switch (it sets `data-theme` on `<html>`, the signal components react to), a chapter nav and copy-link buttons that share one slug algorithm, a version badge with the build stamp, and build-only Plausible. `attachControlsPersistence()` and `renderExamplesIndex()` replace the per-repo controls store and the 150-line inline index page.
-- **Fragment pages — no more copied page boilerplate** — A page without `<html>` is a fragment: `<meta name="kmwc:title">` and friends drive the shared layout (head, entry script, header with back link, container), `<kmwc-include>` pulls parameterised partials (nesting, cycle detection), and `<kmwc-demo>` renders live markup plus a code block of exactly that markup, so a snippet can no longer drift from its demo. Full documents pass through untouched, so pages migrate one at a time.
-- **`kmwc` CLI — generate, check and gate instead of hand-edit** — `kmwc sync` writes the Dockerfile, nginx.conf, Makefile (repo targets in `Makefile.local`), .dockerignore and a managed CLAUDE.md block from templates. `kmwc doctor` runs the devkit checks, an `npm pack` contents check (no CLAUDE.md, tests or example pages in the package) and every BlissFramework rulebook `*.checks.sh` suite. `kmwc check-vars` replaces three diverged manifest scripts (declared or consumed mode), and `kmwc check-release` gates `make publish*` on the dist-tag ⇔ version rule.
-- **`kmwc new` — a rulebook-shaped component on the first commit** — The scaffold runs the rulebook intake (npm name free, CSS prefix 2–4 letters and not reserved, next free port block) and generates the Element / Logic / types / logger layers, the canonical eight-file CSS set with Strategy-B dark mode, a Custom Elements Manifest, README + `docs/`, CHANGELOG, `/publish`, fragment example pages and smoke + dark-mode e2e specs. It passes every rulebook suite as generated; `--minimal` gives an empty skeleton instead of the sample toggle.
-- **Catalogue and port registry — every component listed, no port collisions** — `components.json` registers every Keenmate repo with its CSS prefix and a 100-port block (dev = block, preview = +1, image = +10), numbered inside a range per kind (components 12100–14900, libraries 15000–, showcases 16000–, tests 17000–), so any number of repos run side by side. The README catalogue is generated from it, with a ✅ for each repo on the devkit; web-commandpalette is the first.
-
 ## Catalogue
 
 <!-- kmwc:catalogue:start — generated by `npm run readme`, do not edit inside -->
@@ -267,10 +266,26 @@ doctor` lists the ones still repeating the head/header boilerplate.
   Re-theme a site with `kmwc.theme.accentColor`. The page vocabulary is
   unchanged from the old shared CSS — `.card`, `.example-section`, `.controls`,
   `.demo-area`, `.demo-card`, `.code-block`, `.note(.warning|.info|.success|.error)`,
-  `.grid`/`.card-grid`, `.reference-table`, `.log-panel`, `.pill`,
+  `.grid`/`.card-grid`, `.reference-table` (+ `.table-*` modifiers), `.log-panel`, `.pill`,
   `.status-dot`, `.control-group`, buttons (`.btn-secondary`, `.btn-outline`,
   `.btn-danger`) — while everything the kit **generates** is prefixed BEM
   (`kmwc-chapter-nav__item--active`, `kmwc-copy-link--copied`, …).
+- **Form controls** look the same on every page without a class: text fields,
+  selects and list boxes (`multiple` / `size`), textareas, checkboxes, radios,
+  switches (`<input type="checkbox" role="switch">`), ranges, colour and file
+  inputs, fieldsets — modelled on pure-admin's forms and read through the
+  `--base-input-*` / `--base-checkbox-*` / `--base-icon-check` contract. Inputs,
+  selects and buttons share `--kmwc-control-height`, so a row of them lines up
+  in any container, not only `.controls`. The rules are zero-specificity
+  (`:where()`); `kmwc-native` on an element or an ancestor keeps the browser's
+  own controls (a light-DOM component that draws its own inputs). The
+  playground's `examples-forms.html` shows them all.
+- **Tables:** any `<table>` gets a header fill, row lines and a hover tint;
+  `.reference-table` is the full-width, fully bordered API table. Modifiers
+  combine — `.table-full`, `.table-bordered`, `.table-striped`, `.table-compact`
+  (tighter cells; the controls in it shrink via `--kmwc-control-height`) — plus
+  `tr.is-highlight` and a `.num` cell (right-aligned, tabular figures). On a phone
+  a wide table scrolls inside its card. See the playground's `examples-tables.html`.
 - **Theme switch** (top right) cycles light → dark → auto and sets
   `data-theme` on `<html>` — the same signal components react to via
   `:host-context([data-theme])`, so every example page is a dark-mode smoke
@@ -278,6 +293,22 @@ doctor` lists the ones still repeating the head/header boilerplate.
 - **Chapter nav and copy-link** share one section/slug algorithm, so the
   jump-list hashes and copied links always match. Floating UI is bundled (no
   CDN). At the bottom of a short page, the last chapter gets highlighted.
+- **Spotlight (Ctrl/⌘+K)** searches every chapter of every example page: a
+  chapter matches when its section code or heading text contains the query
+  (`th7` finds `TH07`; uncoded `Summary` / reference sections are found by
+  title), results are grouped by page with the current page first, ↑↓ / PgUp
+  / PgDn / Home / End pick, Enter jumps, Ctrl/⌘+Enter opens a new tab. The
+  Vite plugin builds the index from every page's `<h2>`s (includes resolved)
+  as `virtual:kmwc-chapters`; the current page's chapters are read live, so
+  script-rendered sections count too. Off with
+  `kmwc.examples.isSpotlightEnabled: false` (a component that owns Ctrl+K
+  itself; a page handler calling `preventDefault()` also keeps the key). It
+  **mirrors** [web-commandpalette](https://github.com/keenmate/web-commandpalette)
+  — markup, matching, keyboard map, open/close, CSS — without depending on it;
+  see *Developing the devkit*.
+- **Short chapter links**: `examples-theming.html#th07` (or `#th7`, or the
+  slug of an uncoded heading, `#summary`) scrolls to that chapter on arrival
+  — the codes from the rulebook's `example-pages.md` work as URLs.
 - **Version badge**: any `[data-kmwc-version]` (or legacy `#version-badge`)
   shows `v1.2.3`, or `v1.2.3 (built …)` in a built site.
 - **Landing page**: `renderExamplesIndex({ pages })` renders the header, cards,
@@ -325,7 +356,7 @@ and the e2e suite before building and publishing.
 **`kmwc doctor` and the rulebook.** Doctor runs every suite in the rulebook
 (component-structure, naming-conventions, css-structure, theme-container,
 base-variables, color-scheme, readme-structure, custom-elements-manifest,
-responsive-overlay, publish-command) with `bash`, passing `kmwc.prefix`, and
+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.
 When the rulebook isn't checked out (or there's no bash) the suites are
 skipped with a warning — the rulebook stays the single source of truth; the
@@ -421,8 +452,18 @@ 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 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
 ```
 
+**The spotlight mirrors web-commandpalette.** `src/examples/spotlight.js`,
+`chapter-search.js` and `css/spotlight.css` keep wcp's structure block for
+block (devkit naming), each marked `mirrors <file> <function>`;
+[`scripts/spotlight-mirror.json`](scripts/spotlight-mirror.json) lists every
+pair and the wcp / core commit they're aligned to. A bug fixed in one gets
+ported to the other: run `npm run check:spotlight-mirror` (add `-- --diff`
+for the patches), port what applies, bump `alignedCommit`.
+
 [`playground/`](playground) is a real component scaffolded with `kmwc new` and
 linked to this checkout. It's the reference for "what a component looks like",
 the e2e target for every kit feature, and `npx kmwc doctor` inside it must

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keenmate/web-components-devkit",
-  "version": "1.0.0-rc02",
+  "version": "1.0.0-rc03",
   "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",
@@ -48,6 +48,7 @@
     "test": "node --test \"test/**/*.test.js\"",
     "test:e2e": "cd playground && npx playwright test",
     "check:contract": "base-contract-check src templates playground",
+    "check:spotlight-mirror": "node scripts/check-spotlight-mirror.js",
     "playground": "cd playground && vite",
     "playground:build": "cd playground && vite build --mode examples",
     "playground:lib": "cd playground && vite build"

package/src/cli/commands/doctor.js

@@ -37,6 +37,7 @@ export const RULEBOOK_SUITES = [
   { name: 'custom-elements-manifest', isPrefixed: false },
   { name: 'responsive-overlay', isPrefixed: true },
   { name: 'publish-command', isPrefixed: false },
+  { name: 'example-pages', isPrefixed: false },
 ];
 
 function getMajorVersion(versionRange) {

package/src/config.d.ts

@@ -38,6 +38,8 @@ export interface KmwcPackageConfig {
     excludedPages?: string[];
     /** localStorage namespace for the controls persistence; defaults to `id`. */
     storagePrefix?: string;
+    /** The Ctrl/Cmd+K chapter spotlight (search every page's chapters); default true. */
+    isSpotlightEnabled?: boolean;
   };
   analytics?: { plausibleSiteId?: string; plausibleHostUrl?: string };
   image?: {
@@ -101,6 +103,7 @@ export interface KmwcConfig {
     staticPaths: string[];
     excludedPages: string[];
     storagePrefix: string;
+    isSpotlightEnabled: boolean;
   };
   analytics: { plausibleSiteId: string; plausibleHostUrl: string };
   image: {

package/src/config.js

@@ -235,6 +235,7 @@ export function mapKmwcConfig(packageJson, root = process.cwd()) {
       staticPaths: examples.staticPaths || [],
       excludedPages: examples.excludedPages || [],
       storagePrefix: examples.storagePrefix || id,
+      isSpotlightEnabled: examples.isSpotlightEnabled ?? true,
     },
     analytics: {
       plausibleSiteId: analytics.plausibleSiteId || '',

package/src/examples/chapter-links.js

@@ -0,0 +1,35 @@
+/**
+ * CHAPTER LINKS — make every chapter reachable by a short link.
+ *
+ * Anchor ids are assigned by the kit after the page loads (sections.js), so the
+ * browser can't scroll to them on arrival by itself. This resolves the hash
+ * once the anchors exist, and on every hash change, accepting:
+ *
+ *   #bu02-declarative-markup   the anchor id (chapter nav, copy-link)
+ *   #bu02  /  #bu2             the section code — the link the codes exist for
+ *   #summary                   the slug of an uncoded heading
+ *
+ * A hash that names some other element on the page is left to the browser.
+ */
+import { ensureSectionAnchors, findSectionByHash } from './sections.js';
+
+let isHashChangeAttached = false;
+
+/**
+ * Scroll to the chapter `hash` points at.
+ * @returns {boolean} whether a chapter was found
+ */
+export function scrollToChapterHash(hash = location.hash) {
+  const section = findSectionByHash(hash, ensureSectionAnchors());
+  if (!section) return false;
+  section.section.scrollIntoView({ block: 'start' });
+  return true;
+}
+
+/** Resolve the current hash now, and every later hash change. Idempotent. */
+export function attachChapterLinks() {
+  if (location.hash) scrollToChapterHash();
+  if (isHashChangeAttached) return;
+  isHashChangeAttached = true;
+  window.addEventListener('hashchange', () => scrollToChapterHash());
+}

package/src/examples/chapter-search.js

@@ -0,0 +1,84 @@
+/**
+ * Chapter search for the spotlight. MIRRORS web-commandpalette — see
+ * scripts/spotlight-mirror.json for the files and the commit it is aligned to;
+ * `npm run check:spotlight-mirror` lists what changed there since. A block
+ * marked `mirrors …` keeps the wcp structure line for line (devkit naming): fix
+ * a bug in one, port it to the other.
+ *
+ * Matching is wcp's: lower-cased substring of the whole query against any
+ * field — here the section code and the heading text. On top (spotlight only):
+ * a query that is a section code finds it without the zero padding (`th7` →
+ * TH07), and the order is exact code, then codes starting with the query, then
+ * the rest — each in index order. Pure, so it is unit-tested.
+ */
+import { mapToCodeKey } from './sections.js';
+
+const RANK_EXACT_CODE = 0;
+const RANK_CODE_PREFIX = 1;
+const RANK_TEXT = 2;
+
+// mirrors web-commandpalette src/filter.ts `norm`
+const mapToNormalizedText = (value) => (value == null ? '' : String(value)).toLowerCase();
+
+// mirrors web-commandpalette src/icons.ts escapeHtml()
+export function mapToEscapedHtml(value) {
+  return String(value ?? '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/** Substring match of `needle` against any of `fields`. Empty needle matches all. */
+// mirrors web-commandpalette src/filter.ts matchesAny()
+export function checkMatchesAny(fields, needle) {
+  const query = mapToNormalizedText(needle).trim();
+  if (!query) return true;
+  return fields.some((field) => mapToNormalizedText(field).includes(query));
+}
+
+/** The fields a chapter is searched by (wcp: commandFields()). */
+export function getChapterFields(chapter) {
+  return [chapter.code, chapter.title];
+}
+
+/**
+ * @param {Array<{ code: string | null, title: string }>} chapters
+ * @param {string} query
+ * @returns the matching chapters, best first (all of them for an empty query)
+ */
+export function searchChapters(chapters, query) {
+  const needle = mapToNormalizedText(query).trim();
+  if (!needle) return chapters.slice();
+  const queryCodeKey = mapToCodeKey(needle);
+
+  const rankedChapters = [];
+  chapters.forEach((chapter, chapterIndex) => {
+    const code = mapToNormalizedText(chapter.code);
+    const isExactCode = code !== '' && mapToCodeKey(code) === queryCodeKey;
+    if (!isExactCode && !checkMatchesAny(getChapterFields(chapter), needle)) return;
+    const rank = isExactCode ? RANK_EXACT_CODE : code.startsWith(needle) ? RANK_CODE_PREFIX : RANK_TEXT;
+    rankedChapters.push({ chapter, rank, chapterIndex });
+  });
+
+  return rankedChapters
+    .sort((first, second) => first.rank - second.rank || first.chapterIndex - second.chapterIndex)
+    .map((rankedChapter) => rankedChapter.chapter);
+}
+
+/** Escape `text`, wrapping case-insensitive occurrences of `needle` in `<mark>`. */
+// mirrors web-commandpalette src/render.ts highlight()
+export function renderHighlightedText(text, needle) {
+  const query = needle.trim();
+  if (!query) return mapToEscapedHtml(text);
+  const lowerText = text.toLowerCase();
+  const lowerQuery = query.toLowerCase();
+  let html = '';
+  let index = 0;
+  for (let matchIndex = lowerText.indexOf(lowerQuery); matchIndex !== -1; matchIndex = lowerText.indexOf(lowerQuery, index)) {
+    html += mapToEscapedHtml(text.slice(index, matchIndex)) + '<mark>' + mapToEscapedHtml(text.slice(matchIndex, matchIndex + lowerQuery.length)) + '</mark>';
+    index = matchIndex + lowerQuery.length;
+  }
+  return html + mapToEscapedHtml(text.slice(index));
+}

package/src/examples/constants.js

@@ -20,6 +20,57 @@ export const CHAPTER_NAV_CLASSES = {
 
 export const CHAPTER_NAV_PANEL_ID = 'kmwc-chapter-nav-panel';
 
+/**
+ * Spotlight: the cross-page chapter search (spotlight.js). Element names
+ * mirror web-commandpalette's `pa-command-palette__*` shell (pure-admin's
+ * canonical command-palette snippet) under the kit prefix; `trigger` and
+ * `itemCode` are the spotlight's own.
+ */
+export const SPOTLIGHT_CLASSES = {
+  root: 'kmwc-spotlight',
+  rootActive: 'kmwc-spotlight--active',
+  rootFullscreen: 'kmwc-spotlight--fullscreen',
+  backdrop: 'kmwc-spotlight__backdrop',
+  container: 'kmwc-spotlight__container',
+  fullscreenBar: 'kmwc-spotlight__fullscreen-bar',
+  fullscreenTitle: 'kmwc-spotlight__fullscreen-title',
+  close: 'kmwc-spotlight__close',
+  search: 'kmwc-spotlight__search',
+  inputWrapper: 'kmwc-spotlight__input-wrapper',
+  input: 'kmwc-spotlight__input',
+  results: 'kmwc-spotlight__results',
+  homeSection: 'kmwc-spotlight__home-section',
+  homeHeading: 'kmwc-spotlight__home-heading',
+  item: 'kmwc-spotlight__item',
+  itemActive: 'kmwc-spotlight__item--active',
+  itemCode: 'kmwc-spotlight__item-code',
+  itemContent: 'kmwc-spotlight__item-content',
+  itemTitle: 'kmwc-spotlight__item-title',
+  empty: 'kmwc-spotlight__empty',
+  footer: 'kmwc-spotlight__footer',
+  hint: 'kmwc-spotlight__hint',
+  key: 'kmwc-spotlight__key',
+  live: 'kmwc-spotlight__live',
+  trigger: 'kmwc-spotlight__trigger',
+  triggerKey: 'kmwc-spotlight__trigger-key',
+};
+
+export const SPOTLIGHT_RESULTS_ID = 'kmwc-spotlight-results';
+export const SPOTLIGHT_ITEM_ID_PREFIX = 'kmwc-spotlight-item-';
+/** The Ctrl/⌘ + letter that toggles the spotlight (wcp: `openKey`, default `k`). */
+export const SPOTLIGHT_OPEN_KEY = 'k';
+/** PgUp / PgDn step (wcp palette.ts PAGE_STEP). */
+export const SPOTLIGHT_PAGE_STEP = 8;
+/** Touch phone → fullscreen sheet (wcp: core's device classification, approximated in CSS terms). */
+export const SPOTLIGHT_FULLSCREEN_MEDIA = '(pointer: coarse) and (max-width: 768px)';
+
+/**
+ * A section code at the start of a heading label: `TH07 · Title` (rulebook
+ * example-pages.md). Forgiving on purpose — `EV4b` counts; enforcing the
+ * format is the rulebook check's job.
+ */
+export const CHAPTER_CODE_PATTERN = /^([A-Z]{2,3}\d+[a-z]?)\s*·\s*/;
+
 export const COPY_LINK_CLASSES = {
   root: 'kmwc-copy-link',
   rootCopied: 'kmwc-copy-link--copied',

package/src/examples/css/content.css

@@ -1,7 +1,7 @@
 /* ==============================================================================
    EXAMPLES KIT — CONTENT
    ==============================================================================
-   Output panels, code, notes, grids, reference tables, badges. */
+   Output panels, code, notes, grids, badges. Tables are tables.css. */
 @layer kmwc {
     /* ==========================================================================
        OUTPUT
@@ -99,8 +99,10 @@
         position: absolute;
         top: 0.5rem;
         right: 0.5rem;
+        min-height: 0;  /* not the control height (button rule) */
         padding: 0.25rem 0.75rem;
         font-size: 0.75rem;
+        line-height: normal;
         background: color-mix(in srgb, var(--kmwc-code-text-color) 10%, transparent);
         color: var(--kmwc-code-text-color);
         border: 1px solid color-mix(in srgb, var(--kmwc-code-text-color) 20%, transparent);
@@ -184,40 +186,8 @@
     }
 
     /* ==========================================================================
-       REFERENCE TABLE & BADGES
+       BADGES & HELPERS
        ========================================================================== */
-    .reference-table {
-        width: 100%;
-        border-collapse: collapse;
-        font-size: 0.875rem;
-        margin-bottom: 2rem;
-    }
-
-    .reference-table th,
-    .reference-table td {
-        padding: 0.75rem 1rem;
-        text-align: left;
-        border: 1px solid var(--kmwc-border-color);
-    }
-
-    .reference-table th {
-        background: var(--kmwc-elevated-bg);
-        font-weight: 600;
-    }
-
-    .reference-table tbody tr:hover {
-        background: var(--kmwc-hover-bg);
-    }
-
-    .reference-table tr.is-highlight {
-        background: var(--kmwc-accent-light-bg);
-    }
-
-    .reference-table code {
-        padding: 0.125rem 0.375rem;
-        font-size: 0.75rem;
-    }
-
     /* Section-header badge pill (e.g. a "NEW" tag beside an h2). */
     .badge {
         display: inline-block;

package/src/examples/css/controls.css

@@ -1,7 +1,8 @@
 /* ==============================================================================
    EXAMPLES KIT — CONTROLS
    ==============================================================================
-   Demo forms, the `.controls` switch rows, demo areas and buttons. */
+   Demo forms, the `.controls` switch rows, demo areas and buttons. How the
+   native controls themselves look is form-controls.css. */
 @layer kmwc {
     /* ==========================================================================
        FORMS
@@ -61,30 +62,23 @@
         align-items: center;
         gap: 0.5rem;
         cursor: pointer;
+        /* A long label wraps inside the row instead of pushing the page wider. */
+        flex-wrap: wrap;
+        max-width: 100%;
     }
 
-    .toggle-label {
-        margin-bottom: 0.75rem;
+    .controls label code,
+    .toggle-label code {
+        overflow-wrap: anywhere;
     }
 
-    .controls input[type="checkbox"] {
-        width: 16px;
-        height: 16px;
-        accent-color: var(--kmwc-accent-color);
+    /* A select is as wide as its longest option — cap it at the row. */
+    .controls select {
+        max-width: 100%;
     }
 
-    .controls select,
-    .controls input[type="text"],
-    .controls input[type="number"],
-    .controls input[type="search"],
-    .control-group input,
-    .control-group select {
-        padding: 0.4rem 0.6rem;
-        border: var(--kmwc-input-border);
-        border-radius: var(--kmwc-radius-sm);
-        font-size: 0.875rem;
-        background: var(--kmwc-input-bg);
-        color: var(--kmwc-input-color);
+    .toggle-label {
+        margin-bottom: 0.75rem;
     }
 
     /* Control group — a label stacked over an input/select; rows of them wrap
@@ -155,13 +149,24 @@
         cursor: pointer;
         background: var(--kmwc-accent-color);
         color: var(--kmwc-text-color-on-accent);
-        border: none;
-        padding: 0.5rem 1rem;
+        /* The control height (form-controls.css): a transparent border, so an
+           outline button is as tall as a filled one, and a fixed line box. */
+        border: 1px solid transparent;
+        min-height: var(--kmwc-control-height);
+        padding: calc((var(--kmwc-control-height) - 1.25rem - 2px) / 2) 1rem;
         border-radius: var(--kmwc-radius-sm);
+        font: inherit;
         font-size: 0.875rem;
+        line-height: 1.25rem;
+        vertical-align: middle;
         transition: background 0.2s;
     }
 
+    button:focus-visible {
+        outline: 2px solid var(--kmwc-accent-color);
+        outline-offset: 2px;
+    }
+
     button:hover,
     button.btn-primary:hover {
         background: var(--kmwc-accent-color-hover);

package/src/examples/css/copy-link.css

@@ -9,6 +9,7 @@
         align-items: center;
         gap: 0.35rem;
         font-size: 0.8rem;
+        min-height: 0;  /* not the control height (button rule) */
         line-height: 1;
         padding: 0.25rem 0.4rem;
         margin-inline-start: 0.15rem;

package/src/examples/css/demo.css

@@ -32,8 +32,10 @@
         position: absolute;
         top: 0.5rem;
         right: 0.5rem;
+        min-height: 0;  /* not the control height (button rule) */
         padding: 0.25rem 0.75rem;
         font-size: 0.75rem;
+        line-height: normal;
         background: color-mix(in srgb, var(--kmwc-code-text-color) 10%, transparent);
         color: var(--kmwc-code-text-color);
         border: 1px solid color-mix(in srgb, var(--kmwc-code-text-color) 20%, transparent);