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

package/src/cli/commands/doctor.js

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

package/src/cli/kmwc.js

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

package/src/cli/repo-checks.js

@@ -0,0 +1,366 @@
+/**
+ * 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;
+}
+
+// ── hard-coded colours in page CSS ───────────────────────────────────────────
+
+/**
+ * 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.
+ */
+export const FIXED_COLORS_ATTRIBUTE = 'data-kmwc-fixed-colors';
+export const FIXED_COLORS_MARKER = 'kmwc-fixed-colors';
+const MARKED_RULE_PATTERN = new RegExp(`/\\*[^*]*${FIXED_COLORS_MARKER}[\\s\\S]*?\\*/\\s*[^{}]*\\{[^{}]*\\}`, 'g');
+const COLOR_PROPERTY_PATTERN = /color|background|border|outline|shadow|fill|stroke|text-decoration/i;
+const COLOR_LITERAL_PATTERN =
+  /#[0-9a-f]{3,8}\b|\b(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch)\(\s*(?!from\b)|\b(?:white|black|red|green|blue|gray|grey|silver|orange|yellow|purple|pink|navy|teal|maroon|olive|lime|aqua|fuchsia|gold|crimson)\b/i;
+
+/** A declaration value with every `var(…)` collapsed — a literal fallback never shows while the kit token exists. */
+function mapWithoutVarFallbacks(value) {
+  let previous;
+  let current = value;
+  do {
+    previous = current;
+    current = current.replace(/var\([^()]*\)/gi, 'var()');
+  } while (current !== previous);
+  return current;
+}
+
+/** True when a colour declaration's value is a literal that ignores dark mode. Pure. */
+export function checkIsHardcodedColor(property, value) {
+  if (!COLOR_PROPERTY_PATTERN.test(property) || property.startsWith('--')) return false;
+  const plainValue = mapWithoutVarFallbacks(value);
+  return !/light-dark\(/i.test(plainValue) && COLOR_LITERAL_PATTERN.test(plainValue);
+}
+
+/**
+ * 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.
+ */
+export function getHardcodedColors(pageText, { isStylesheet = false } = {}) {
+  const styleText = isStylesheet
+    ? pageText
+    : [...pageText.matchAll(/<style\b([^>]*)>([\s\S]*?)<\/style>/gi)]
+        .filter((match) => !match[1].includes(FIXED_COLORS_ATTRIBUTE))
+        .map((match) => match[2])
+        .join('\n');
+  const hardcodedColors = [];
+  const checkedText = styleText.replace(MARKED_RULE_PATTERN, '').replace(/\/\*[\s\S]*?\*\//g, '');
+  for (const [, selector, body] of checkedText.matchAll(/([^{};@]+?)\s*\{([^{}]*)\}/g)) {
+    for (const declaration of body.split(';')) {
+      const [property, ...valueParts] = declaration.split(':');
+      const value = valueParts.join(':').trim();
+      if (value && checkIsHardcodedColor(property.trim(), value)) hardcodedColors.push({ found: `${selector.trim().replace(/\s+/g, ' ')} { ${property.trim()}: ${value} }` });
+    }
+  }
+  if (isStylesheet) return hardcodedColors;
+  for (const [, inlineStyle] of pageText.matchAll(/\sstyle="([^"]*)"/g)) {
+    for (const declaration of inlineStyle.split(';')) {
+      const [property, ...valueParts] = declaration.split(':');
+      const value = valueParts.join(':').trim();
+      if (value && checkIsHardcodedColor(property.trim(), value)) hardcodedColors.push({ found: `style="${property.trim()}: ${value}"` });
+    }
+  }
+  return hardcodedColors;
+}
+
+// ── core's default loader class ──────────────────────────────────────────────
+
+const CORE_PACKAGE_PATH = join('node_modules', '@keenmate', 'web-components-core');
+const CORE_RENDER_LOADER_FILE = join('dist', 'dom', 'render-loader.js');
+const SOURCE_DIR = 'src';
+const SKIPPED_SOURCE_DIRS = new Set(['node_modules', 'dist']);
+
+/**
+ * The separator in the class core's default loader gets: `'__'` (`<prefix>__loader`),
+ * `'-'` (`<prefix>-loader`, before core 6d6b768), or null when the build doesn't say. Pure.
+ */
+export function getCoreLoaderSeparator(renderLoaderText) {
+  const match =
+    renderLoaderText.match(/\$\{\s*[\w$.]+\s*\}(__|-)loader(?![\w-])/) || renderLoaderText.match(/\+\s*["'`](__|-)loader["'`]/);
+  return match ? match[1] : null;
+}
+
+/** The loader classes a stylesheet styles: [{ className, separator }]. Pure. */
+export function getStyledLoaderClasses(cssText, prefix) {
+  const pattern = new RegExp(`\.(${prefix}(__|-)loader)(?![\w-])`, 'g');
+  const plainText = cssText.replace(/\/\*[\s\S]*?\*\//g, '');
+  const classes = new Map([...plainText.matchAll(pattern)].map((match) => [match[1], match[2]]));
+  return [...classes].map(([className, separator]) => ({ className, separator }));
+}
+
+/** The installed core (walking up for hoisted installs): { version, separator } or null. */
+export function loadCoreLoader(root) {
+  for (let directory = resolve(root); ; directory = resolve(directory, '..')) {
+    const packageText = readText(join(directory, CORE_PACKAGE_PATH, 'package.json'));
+    if (packageText) {
+      const renderLoaderText = readText(join(directory, CORE_PACKAGE_PATH, CORE_RENDER_LOADER_FILE));
+      return { version: JSON.parse(packageText).version, separator: renderLoaderText ? getCoreLoaderSeparator(renderLoaderText) : null };
+    }
+    if (resolve(directory, '..') === directory) return null;
+  }
+}
+
+function getSourceStylesheets(directory, relativeDirectory = SOURCE_DIR) {
+  if (!existsSync(directory)) return [];
+  return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const relativePath = `${relativeDirectory}/${entry.name}`;
+    if (entry.isDirectory()) return SKIPPED_SOURCE_DIRS.has(entry.name) ? [] : getSourceStylesheets(join(directory, entry.name), relativePath);
+    return entry.name.endsWith('.css') ? [relativePath] : [];
+  });
+}
+
+/** 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) =>
+    getStyledLoaderClasses(readFileSync(join(root, file), 'utf8'), prefix).map((styledClass) => ({ file, ...styledClass }))
+  );
+}

package/src/cli/sync-plan.js

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

package/src/examples/css/base.css

@@ -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;