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

package/src/cli/repo-checks.js

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

package/src/cli/sync-plan.js

@@ -69,14 +69,14 @@ const hasAnyFile = (root, fileNames) => fileNames.some((fileName) => existsSync(
 export function getStandardScripts(config) {
   const scripts = {
     dev: 'vite',
-    build: 'vite build',
+    ...(config.library.shouldBuild ? { build: 'vite build' } : {}),
     'build:examples': 'vite build --mode examples',
     'preview:examples': 'vite preview --mode examples',
     'clean:dist': generateRemoveCommand(['dist']),
     clean: generateRemoveCommand(['dist', config.examples.outDir]),
     doctor: 'kmwc doctor',
   };
-  if (existsSync(join(config.root, config.cssVariables.manifest))) scripts['check:vars'] = 'kmwc check-vars';
+  if (config.cssVariables.isEnabled && existsSync(join(config.root, config.cssVariables.manifest))) scripts['check:vars'] = 'kmwc check-vars';
   if (existsSync(join(config.root, CEM_CONFIG_FILE))) scripts.analyze = 'cem analyze';
   if (hasAnyFile(config.root, PLAYWRIGHT_CONFIG_FILES)) {
     Object.assign(scripts, {
@@ -84,6 +84,7 @@ export function getStandardScripts(config) {
       'test:e2e:ui': 'playwright test --ui',
       'test:e2e:headed': 'playwright test --headed',
       'test:e2e:install': 'playwright install chromium',
+      'check:pages': 'kmwc check-pages',
     });
   }
   return scripts;

package/src/config.d.ts

@@ -10,7 +10,12 @@ export interface KmwcPackageConfig {
   tag?: string;
   /** Reserved CSS prefix (base-variables.md "Existing prefixes"), e.g. `ms`. */
   prefix?: string;
-  library?: {
+  /** Registry kind; defaults to the components.json entry's kind (else `component`). A `library` runs only the doctor checks that apply to it. */
+  kind?: 'component' | 'library' | 'showcase' | 'docs' | 'test';
+  /** The library build (`vite build`). `false` = the repo builds its package itself or ships none: plain `vite build` refuses to run, only `--mode examples` builds. */
+  library?: false | {
+    /** `false` = same as `library: false`, keeping `entry` for the example pages. */
+    shouldBuild?: boolean;
     entry?: string;
     /** UMD global name. */
     globalName?: string;
@@ -51,14 +56,15 @@ export interface KmwcPackageConfig {
     packageJsonPaths?: string[];
     installCommand?: string;
   };
-  cssVariables?: {
+  /** `false` (or `checkMode: 'off'`): no variables manifest check — sync adds no `check:vars`, `kmwc check-vars` skips. */
+  cssVariables?: false | {
     manifest?: string;
     /** Directories (stylesheets scanned) or explicit files (any type, e.g. a built bundle). */
     sources?: string[];
     /** Prefixed names (without `--`) that are runtime internals, not theming knobs. */
     internalVariables?: string[];
     /** `declared`: manifest ⇔ `--x:` declarations; `consumed`: manifest ⇔ `var(--x)` reads. */
-    checkMode?: 'declared' | 'consumed';
+    checkMode?: 'declared' | 'consumed' | 'off';
   };
   rulebook?: {
     /** Path to BlissFramework `guidelines/web-components` (env KMWC_RULEBOOK_PATH wins). */
@@ -75,6 +81,7 @@ export interface KmwcConfig {
   packageJson: Record<string, any>;
   id: string;
   packageName: string;
+  kind: string;
   version: string;
   title: string;
   tagline: string;
@@ -85,6 +92,7 @@ export interface KmwcConfig {
   author: string;
   license: string;
   library: {
+    shouldBuild: boolean;
     entry: string;
     globalName: string;
     fileName: string;
@@ -118,7 +126,8 @@ export interface KmwcConfig {
     manifest: string;
     sources: string[];
     internalVariables: string[];
-    checkMode: 'declared' | 'consumed';
+    checkMode: 'declared' | 'consumed' | 'off';
+    isEnabled: boolean;
   };
   rulebook: { path: string; skippedChecks: string[] };
   sync: { skippedFiles: string[] };
@@ -137,6 +146,7 @@ export const PORT_RANGES: Array<{ kinds: string[]; firstBlock: number; lastBlock
 export const PREVIEW_PORT_OFFSET: number;
 export const IMAGE_PORT_OFFSET: number;
 export function getPortsForBlock(portBlock: number): { dev: number; preview: number; image: number };
+export function getRegistryKind(id: string, registry?: { components: Array<{ id: string; kind: string }> }): string;
 export function getPortRange(kind: string): { kinds: string[]; firstBlock: number; lastBlock: number };
 export function getNextPortBlock(registry?: { components: Array<Record<string, any>> }, kind?: string): number;
 export function getPeerModule(root: string, moduleId: string): any;

package/src/config.js

@@ -139,6 +139,11 @@ export function getRegistry() {
   return getJsonFile(join(DEVKIT_ROOT, 'components.json'));
 }
 
+/** The registry kind of `id` (`component`, `library` …); `component` when it isn't registered. */
+export function getRegistryKind(id, registry = getRegistry()) {
+  return registry.components.find((entry) => entry.id === id)?.kind || 'component';
+}
+
 /** Strip the npm scope: `@keenmate/web-multiselect` → `web-multiselect`. */
 export function getUnscopedName(packageName) {
   return String(packageName || '').replace(/^@[^/]+\//, '');
@@ -182,13 +187,16 @@ export function getKmwcConfig(root = process.cwd()) {
 export function mapKmwcConfig(packageJson, root = process.cwd()) {
   const packageConfig = packageJson.kmwc || {};
   const id = packageConfig.id || getUnscopedName(packageJson.name) || 'component';
-  const library = packageConfig.library || {};
+  // `library: false` — the repo builds its package itself (tsc …) or ships none;
+  // Vite serves and builds only the examples site.
+  const library = packageConfig.library === false ? { shouldBuild: false } : packageConfig.library || {};
   const examples = packageConfig.examples || {};
   const ports = packageConfig.ports || {};
   const image = packageConfig.image || {};
   const theme = packageConfig.theme || {};
   const analytics = packageConfig.analytics || {};
-  const cssVariables = packageConfig.cssVariables || {};
+  // `cssVariables: false` — no variables manifest to check (no check:vars script).
+  const cssVariables = packageConfig.cssVariables === false ? { checkMode: 'off' } : packageConfig.cssVariables || {};
   const rulebook = packageConfig.rulebook || {};
   const devPort = ports.dev ?? 5173;
 
@@ -198,6 +206,7 @@ export function mapKmwcConfig(packageJson, root = process.cwd()) {
     packageJson,
     id,
     packageName: packageJson.name || id,
+    kind: packageConfig.kind || getRegistryKind(id),
     version: packageJson.version || '0.1.0',
     title: packageConfig.title || mapToTitleCase(id),
     tagline: packageConfig.tagline || packageJson.description || '',
@@ -208,6 +217,7 @@ export function mapKmwcConfig(packageJson, root = process.cwd()) {
     author: typeof packageJson.author === 'string' ? packageJson.author : packageJson.author?.name || 'Keenmate s.r.o.',
     license: packageJson.license || 'MIT',
     library: {
+      shouldBuild: library.shouldBuild ?? true,
       entry: library.entry || 'src/index.ts',
       globalName: library.globalName || mapToPascalCase(id),
       fileName: library.fileName || id,
@@ -254,6 +264,7 @@ export function mapKmwcConfig(packageJson, root = process.cwd()) {
       sources: cssVariables.sources || ['src/css'],
       internalVariables: cssVariables.internalVariables || [],
       checkMode: cssVariables.checkMode || 'declared',
+      isEnabled: cssVariables.checkMode !== 'off',
     },
     rulebook: {
       path:

package/src/examples/css/base.css

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

package/src/examples/css/content.css

@@ -120,6 +120,9 @@
         font-size: 0.9em;
         color: var(--kmwc-accent-color);
         font-family: var(--kmwc-mono-font-family);
+        /* A long identifier has no break opportunity — break it anywhere
+           rather than widen the page on a phone. */
+        overflow-wrap: anywhere;
     }
 
     pre code,
@@ -130,6 +133,35 @@
         border-radius: 0;
         color: inherit;
         font-size: inherit;
+        overflow-wrap: inherit;
+    }
+
+    /* A key in a keyboard map — the spotlight's key-hint look. */
+    kbd {
+        display: inline-block;
+        padding: 0.1rem 0.35rem;
+        background-color: var(--kmwc-elevated-bg);
+        color: var(--kmwc-text-color-1);
+        border: 1px solid var(--kmwc-border-color);
+        border-bottom-width: 2px;
+        border-radius: var(--kmwc-radius-sm);
+        font-family: var(--kmwc-font-family);
+        font-weight: 600;
+        font-size: 0.8em;
+        line-height: 1.2;
+        white-space: nowrap;
+    }
+
+    /* A search match — the spotlight's match highlight. */
+    mark {
+        background-color: var(--kmwc-accent-light-bg-hover);
+        color: var(--kmwc-accent-color);
+        font-weight: 600;
+        /* No padding: a match inside a word ("Town|send") must not split it. */
+        padding: 0;
+        border-radius: var(--kmwc-radius-sm);
+        box-decoration-break: clone;
+        -webkit-box-decoration-break: clone;
     }
 
     /* ==========================================================================
@@ -228,6 +260,18 @@
         margin-top: 1rem;
     }
 
+    /* Push an item to the end of a flex row (`.controls`, `.btn-group` …). */
+    .push-end {
+        margin-inline-start: auto;
+    }
+
+    /* Field widths: a native field is ~20 characters wide; these size a short
+       one (a page size, a caption) without an inline style. */
+    .w-xs { width: 4rem; max-width: 100%; }
+    .w-sm { width: 6rem; max-width: 100%; }
+    .w-md { width: 9rem; max-width: 100%; }
+    .w-lg { width: 12rem; max-width: 100%; }
+
     @media (max-width: 768px) {
         .grid,
         .grid-2,

package/src/examples/css/form-controls.css

@@ -74,7 +74,11 @@
         cursor: not-allowed;
     }
 
+    /* A number is short: 7rem holds six digits and the spin buttons (a
+       .form-group still stretches it to the row; .w-* sizes it). */
     :where(input[type="number"]):not(:where(.kmwc-native, .kmwc-native *)) {
+        width: 7rem;
+        max-width: 100%;
         padding-inline-end: 0.25rem;  /* room for the spin buttons */
     }
 

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

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

package/src/examples/css/widgets.css

@@ -29,7 +29,8 @@
         --kmwc-log-info-color: var(--kmwc-info-color);
         --kmwc-log-warn-color: var(--kmwc-warning-color);
         --kmwc-log-err-color: var(--kmwc-danger-color);
-        --kmwc-log-muted-color: var(--kmwc-text-color-3);
+        /* text-color-3 is 2.8:1 on the light panel — under WCAG AA's 4.5. */
+        --kmwc-log-muted-color: var(--kmwc-text-color-2);
         --kmwc-log-name-color: var(--kmwc-accent-color);
         --kmwc-log-rule-color: var(--kmwc-border-color);
         font-family: var(--kmwc-mono-font-family);
@@ -94,7 +95,9 @@
     }
 
     /* Timeline: a line with cells is a row; the cells keep their width and the
-       detail after them wraps in its own column. */
+       detail after them wraps in its own column. When the cells leave the detail
+       less than ~14rem (a phone, a long source name) it drops under them at full
+       width instead of being squeezed to a letter per line. */
     .log-line:has(> :is(.log-line__seq, .log-line__time, .log-line__source, .log-line__name)),
     .event-entry:has(> :is(.event-time, .event-name)) {
         display: flex;
@@ -103,8 +106,12 @@
         border-bottom: 1px solid var(--kmwc-log-rule-color);
     }
 
+    .log-line:has(> :is(.log-line__seq, .log-line__time, .log-line__source, .log-line__name)) {
+        flex-wrap: wrap;
+    }
+
     .log-line:has(> :is(.log-line__seq, .log-line__time, .log-line__source, .log-line__name)) > :last-child:not(.log-line__name) {
-        flex: 1 1 0;
+        flex: 1 1 14rem;
         min-width: 0;
     }
 
@@ -115,6 +122,7 @@
     .event-time,
     .event-name {
         flex: none;
+        max-width: 100%;
     }
 
     .log-line__seq,
@@ -179,7 +187,7 @@
         display: flex;
         flex-wrap: wrap;
         gap: 0.4rem;
-        margin: 0.25rem 0 1rem;
+        margin: 0.75rem 0 1rem;  /* it follows the demo it measures */
     }
 
     .css-readout code { font-size: 0.78rem; }

package/src/vite/index.js

@@ -20,7 +20,7 @@ import { readdirSync, existsSync, cpSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { getKmwcConfig, getDevkitPackageJson, generateBuildDefines, loadPeerModule, DEVKIT_ROOT, NON_PAGE_HTML_FILES } from '../config.js';
 import { renderThemeBootstrapScript } from '../examples/theme-switch.js';
-import { composePage } from './page-composer.js';
+import { composePage, insertIntoHead, insertBeforeBodyEnd } from './page-composer.js';
 import { generateChapterIndex } from './chapter-index.js';
 
 const AUTO_ENTRY_PATH = join(DEVKIT_ROOT, 'src', 'examples', 'auto.js');
@@ -162,11 +162,7 @@ export function createExamplesPlugin(pluginConfig = {}) {
         const kitImports = isBuild ? `import '${KIT_STYLESHEET_PATH}'; import '${VIRTUAL_AUTO_ID}';` : `import '${VIRTUAL_AUTO_ID}';`;
         const bodyHtml = `<script type="module">${kitImports}</script>\n`;
 
-        html = /<head[^>]*>/i.test(html)
-          ? html.replace(/<head[^>]*>/i, (headTag) => `${headTag}\n${headHtml}`)
-          : headHtml + html;
-        html = /<\/body>/i.test(html) ? html.replace(/<\/body>/i, `${bodyHtml}</body>`) : html + bodyHtml;
-        return html;
+        return insertBeforeBodyEnd(insertIntoHead(html, headHtml), bodyHtml);
       },
     },
 
@@ -199,9 +195,16 @@ export function defineComponentConfig(presetConfig = {}) {
     const config = getKmwcConfig(presetConfig.root);
     // The component's own vite — the one running this config (see loadPeerModule).
     const { mergeConfig, searchForWorkspaceRoot } = await loadPeerModule(config.root, 'vite');
-    const library = { ...config.library, ...(presetConfig.library || {}) };
+    const library = { ...config.library, ...(presetConfig.library === false ? { shouldBuild: false } : presetConfig.library || {}) };
     const isExamplesMode = env.mode === EXAMPLES_MODE;
     const isLibraryBuild = env.command === 'build' && !isExamplesMode;
+    if (isLibraryBuild && !library.shouldBuild) {
+      // The library build empties dist/ — it would wipe a package the repo builds itself.
+      throw new Error(
+        `${config.id}: kmwc.library is false — plain \`vite build\` has nothing to build. ` +
+          'Build the package with its own script (npm run build), the examples site with `vite build --mode examples`.'
+      );
+    }
 
     const plugins = [createExamplesPlugin({ root: config.root }), ...(presetConfig.plugins || [])];
 

package/src/vite/page-composer.js

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