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

package/components.json

@@ -1,189 +1,206 @@
-{
-  "$comment": "Registry of Keenmate web components — source for the README catalogue (`npm run readme`). `port` is the repo's block: dev server = port, preview = port + 1, examples image = port + 10. Each kind has its own range with headroom (components 12100–14900, libraries 15000–15900, showcases/docs 16000–16900, tests 17000–17900), numbered by 100 in registry order; `kmwc doctor` checks package.json#kmwc.ports against it and `kmwc new` takes the next block. `prefix` mirrors the reserved-prefix table in BlissFramework guidelines/web-components/base-variables.md (the authority).",
-  "components": [
-    {
-      "id": "web-multiselect",
-      "kind": "component",
-      "prefix": "ms",
-      "port": 12100,
-      "path": "../web-multiselect",
-      "npm": "@keenmate/web-multiselect",
-      "repo": "https://github.com/keenmate/web-multiselect",
-      "examples": "https://examples.web-multiselect.keenmate.dev",
-      "docs": "https://web-multiselect.keenmate.dev",
-      "showcase": "web-multiselect-showcase"
-    },
-    {
-      "id": "web-daterangepicker",
-      "kind": "component",
-      "prefix": "drp",
-      "port": 12200,
-      "path": "../web-daterangepicker",
-      "npm": "@keenmate/web-daterangepicker",
-      "repo": "https://github.com/keenmate/web-daterangepicker",
-      "docs": "https://web-daterangepicker.keenmate.dev",
-      "showcase": "web-daterangepicker-showcase"
-    },
-    {
-      "id": "web-treeview",
-      "kind": "component",
-      "prefix": "wtv",
-      "port": 12300,
-      "path": "../web-treeview",
-      "npm": "@keenmate/web-treeview",
-      "repo": "https://github.com/keenmate/web-treeview",
-      "showcase": "web-treeview-showcase"
-    },
-    {
-      "id": "web-commandpalette",
-      "kind": "component",
-      "prefix": "cp",
-      "port": 12400,
-      "path": "../web-commandpalette",
-      "npm": "@keenmate/web-commandpalette",
-      "repo": "https://github.com/keenmate/web-commandpalette",
-      "examples": "https://examples.web-commandpalette.keenmate.dev"
-    },
-    {
-      "id": "web-dropzone",
-      "kind": "component",
-      "prefix": "dz",
-      "port": 12500,
-      "path": "../web-dropzone",
-      "npm": "@keenmate/web-dropzone",
-      "repo": "https://github.com/keenmate/web-dropzone",
-      "monorepo": true,
-      "note": "Monorepo: renderer + headless core."
-    },
-    {
-      "id": "web-grid",
-      "kind": "component",
-      "prefix": "wg",
-      "port": 12600,
-      "path": "../web-grid",
-      "npm": "@keenmate/web-grid",
-      "repo": "https://github.com/keenmate/web-grid",
-      "docs": "https://web-grid.keenmate.com",
-      "showcase": "web-grid-showcase",
-      "monorepo": true
-    },
-    {
-      "id": "web-editor",
-      "kind": "component",
-      "port": 12700,
-      "path": "../web-editor",
-      "npm": "@keenmate/web-editor",
-      "examples": "https://examples.web-editor.keenmate.dev",
-      "monorepo": true,
-      "note": "Monorepo: ProseMirror-based WYSIWYG / Markdown editor."
-    },
-    {
-      "id": "web-switch",
-      "kind": "component",
-      "port": 12800,
-      "path": "../web-switch",
-      "npm": "@keenmate/web-switch",
-      "repo": "https://github.com/keenmate/web-switch",
-      "note": "Svelte-based wrapper around @keenmate/svelte-switch."
-    },
-    {
-      "id": "web-timepicker",
-      "kind": "component",
-      "port": 12900,
-      "path": "../web-timepicker",
-      "note": "Vanilla-JS prototypes (spiral / slider time pickers); no package yet."
-    },
-    {
-      "id": "web-wysiwyg",
-      "kind": "component",
-      "port": 13000,
-      "path": "../web-wysiwyg",
-      "note": "ProseMirror exploration; superseded by web-editor."
-    },
-    {
-      "id": "web-components-core",
-      "kind": "library",
-      "port": 15000,
-      "path": "../web-components-core",
-      "npm": "@keenmate/web-components-core",
-      "note": "Runtime foundation: BlissElement, reactive input table, converters, logging, positioning, CEM preset."
-    },
-    {
-      "id": "web-components",
-      "kind": "library",
-      "port": 15100,
-      "path": ".",
-      "npm": "@keenmate/web-components-devkit",
-      "repo": "https://github.com/keenmate/web-components",
-      "note": "This repo — dev/demo/build tooling (Vite preset, examples kit, kmwc CLI)."
-    },
-    {
-      "id": "web-multiselect-showcase",
-      "kind": "showcase",
-      "port": 16000,
-      "path": "../web-multiselect-showcase",
-      "for": "web-multiselect"
-    },
-    {
-      "id": "web-daterangepicker-showcase",
-      "kind": "showcase",
-      "port": 16100,
-      "path": "../web-daterangepicker-showcase",
-      "for": "web-daterangepicker"
-    },
-    {
-      "id": "web-treeview-showcase",
-      "kind": "showcase",
-      "port": 16200,
-      "path": "../web-treeview-showcase",
-      "for": "web-treeview"
-    },
-    {
-      "id": "web-grid-showcase",
-      "kind": "showcase",
-      "port": 16300,
-      "path": "../web-grid-showcase",
-      "for": "web-grid",
-      "url": "https://web-grid.keenmate.com"
-    },
-    {
-      "id": "web-multiselect-docs",
-      "kind": "docs",
-      "port": 16400,
-      "path": "../web-multiselect-docs",
-      "for": "web-multiselect",
-      "note": "Content-only docs (keendocs)."
-    },
-    {
-      "id": "web-component-framework-test",
-      "kind": "test",
-      "port": 17000,
-      "path": "../web-component-framework-test",
-      "note": "Smoke + contrast tests inside CSS host frameworks (plain / Bootstrap / …)."
-    },
-    {
-      "id": "web-multiselect-test",
-      "kind": "test",
-      "port": 17100,
-      "path": "../web-multiselect-test",
-      "for": "web-multiselect",
-      "note": "npm-install vs direct-file consumption checks before publishing."
-    },
-    {
-      "id": "web-multiselect-positioning-demo",
-      "kind": "test",
-      "port": 17200,
-      "path": "../web-multiselect-positioning-demo",
-      "for": "web-multiselect",
-      "note": "Single-page positioning repro."
-    },
-    {
-      "id": "web-playground",
-      "kind": "test",
-      "port": 17300,
-      "path": "playground",
-      "for": "web-components",
-      "note": "Devkit e2e test bed — a component scaffolded with `kmwc new`, linked to this repo."
-    }
-  ]
-}
+{
+  "$comment": "Registry of Keenmate web components — source for the README catalogue (`npm run readme`). `port` is the repo's block: dev server = port, preview = port + 1, examples image = port + 10. Each kind has its own range with headroom (components 12100–14900, libraries 15000–15900, showcases/docs 16000–16900, tests 17000–17900), numbered by 100 in registry order; `kmwc doctor` checks package.json#kmwc.ports against it and `kmwc new` takes the next block. `prefix` mirrors the reserved-prefix table in BlissFramework guidelines/web-components/base-variables.md (the authority).",
+  "components": [
+    {
+      "id": "web-multiselect",
+      "kind": "component",
+      "prefix": "ms",
+      "port": 12100,
+      "path": "../web-multiselect",
+      "npm": "@keenmate/web-multiselect",
+      "repo": "https://github.com/keenmate/web-multiselect",
+      "examples": "https://examples.web-multiselect.keenmate.dev",
+      "docs": "https://web-multiselect.keenmate.dev",
+      "showcase": "web-multiselect-showcase"
+    },
+    {
+      "id": "web-daterangepicker",
+      "kind": "component",
+      "prefix": "drp",
+      "port": 12200,
+      "path": "../web-daterangepicker",
+      "npm": "@keenmate/web-daterangepicker",
+      "repo": "https://github.com/keenmate/web-daterangepicker",
+      "docs": "https://web-daterangepicker.keenmate.dev",
+      "showcase": "web-daterangepicker-showcase"
+    },
+    {
+      "id": "web-treeview",
+      "kind": "component",
+      "prefix": "wtv",
+      "port": 12300,
+      "path": "../web-treeview",
+      "npm": "@keenmate/web-treeview",
+      "repo": "https://github.com/keenmate/web-treeview",
+      "showcase": "web-treeview-showcase"
+    },
+    {
+      "id": "web-commandpalette",
+      "kind": "component",
+      "prefix": "cp",
+      "port": 12400,
+      "path": "../web-commandpalette",
+      "npm": "@keenmate/web-commandpalette",
+      "repo": "https://github.com/keenmate/web-commandpalette",
+      "examples": "https://examples.web-commandpalette.keenmate.dev"
+    },
+    {
+      "id": "web-dropzone",
+      "kind": "component",
+      "prefix": "dz",
+      "port": 12500,
+      "path": "../web-dropzone",
+      "npm": "@keenmate/web-dropzone",
+      "repo": "https://github.com/keenmate/web-dropzone",
+      "monorepo": true,
+      "note": "Monorepo: renderer + headless core."
+    },
+    {
+      "id": "web-grid",
+      "kind": "component",
+      "prefix": "wg",
+      "port": 12600,
+      "path": "../web-grid",
+      "npm": "@keenmate/web-grid",
+      "repo": "https://github.com/keenmate/web-grid",
+      "docs": "https://web-grid.keenmate.com",
+      "showcase": "web-grid-showcase",
+      "monorepo": true
+    },
+    {
+      "id": "web-editor",
+      "kind": "component",
+      "prefix": "km",
+      "port": 12700,
+      "path": "../web-editor",
+      "npm": "@keenmate/web-editor",
+      "examples": "https://examples.web-editor.keenmate.dev",
+      "note": "ProseMirror-based WYSIWYG / Markdown editor."
+    },
+    {
+      "id": "web-switch",
+      "kind": "component",
+      "port": 12800,
+      "path": "../web-switch",
+      "npm": "@keenmate/web-switch",
+      "repo": "https://github.com/keenmate/web-switch",
+      "note": "Svelte-based wrapper around @keenmate/svelte-switch."
+    },
+    {
+      "id": "web-timepicker",
+      "kind": "component",
+      "port": 12900,
+      "path": "../web-timepicker",
+      "note": "Vanilla-JS prototypes (spiral / slider time pickers); no package yet."
+    },
+    {
+      "id": "web-wysiwyg",
+      "kind": "component",
+      "port": 13000,
+      "path": "../web-wysiwyg",
+      "note": "ProseMirror exploration; superseded by web-editor."
+    },
+    {
+      "id": "web-components-core",
+      "kind": "library",
+      "port": 15000,
+      "path": "../web-components-core",
+      "npm": "@keenmate/web-components-core",
+      "note": "Runtime foundation: BlissElement, reactive input table, converters, logging, positioning, CEM preset."
+    },
+    {
+      "id": "web-components",
+      "kind": "library",
+      "port": 15100,
+      "path": ".",
+      "npm": "@keenmate/web-components-devkit",
+      "repo": "https://github.com/keenmate/web-components",
+      "note": "This repo — dev/demo/build tooling (Vite preset, examples kit, kmwc CLI)."
+    },
+    {
+      "id": "pure-css",
+      "kind": "library",
+      "port": 15200,
+      "path": "../pure-css",
+      "npm": "@keenmate/pure-css",
+      "note": "CSS framework mirroring the base-css-variables token contract (demo site + e2e on the dev port)."
+    },
+    {
+      "id": "base-css-variables",
+      "kind": "library",
+      "port": 15300,
+      "path": "../base-css-variables",
+      "npm": "@keenmate/base-css-variables",
+      "repo": "https://github.com/keenmate/base-css-variables",
+      "note": "The shared --base-* token contract (base-variables.css) + base-contract-check; examples site + e2e on the dev port."
+    },
+    {
+      "id": "web-multiselect-showcase",
+      "kind": "showcase",
+      "port": 16000,
+      "path": "../web-multiselect-showcase",
+      "for": "web-multiselect"
+    },
+    {
+      "id": "web-daterangepicker-showcase",
+      "kind": "showcase",
+      "port": 16100,
+      "path": "../web-daterangepicker-showcase",
+      "for": "web-daterangepicker"
+    },
+    {
+      "id": "web-treeview-showcase",
+      "kind": "showcase",
+      "port": 16200,
+      "path": "../web-treeview-showcase",
+      "for": "web-treeview"
+    },
+    {
+      "id": "web-grid-showcase",
+      "kind": "showcase",
+      "port": 16300,
+      "path": "../web-grid-showcase",
+      "for": "web-grid",
+      "url": "https://web-grid.keenmate.com"
+    },
+    {
+      "id": "web-multiselect-docs",
+      "kind": "docs",
+      "port": 16400,
+      "path": "../web-multiselect-docs",
+      "for": "web-multiselect",
+      "note": "Content-only docs (keendocs)."
+    },
+    {
+      "id": "web-component-framework-test",
+      "kind": "test",
+      "port": 17000,
+      "path": "../web-component-framework-test",
+      "note": "Smoke + contrast tests inside CSS host frameworks (plain / Bootstrap / …)."
+    },
+    {
+      "id": "web-multiselect-test",
+      "kind": "test",
+      "port": 17100,
+      "path": "../web-multiselect-test",
+      "for": "web-multiselect",
+      "note": "npm-install vs direct-file consumption checks before publishing."
+    },
+    {
+      "id": "web-multiselect-positioning-demo",
+      "kind": "test",
+      "port": 17200,
+      "path": "../web-multiselect-positioning-demo",
+      "for": "web-multiselect",
+      "note": "Single-page positioning repro."
+    },
+    {
+      "id": "web-playground",
+      "kind": "test",
+      "port": 17300,
+      "path": "playground",
+      "for": "web-components",
+      "note": "Devkit e2e test bed — a component scaffolded with `kmwc new`, linked to this repo."
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keenmate/web-components-devkit",
-  "version": "1.0.0-rc01",
+  "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",
@@ -47,6 +47,8 @@
     "readme:check": "node src/cli/kmwc.js readme --check",
     "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"
@@ -65,6 +67,7 @@
     }
   },
   "devDependencies": {
+    "@keenmate/base-css-variables": "^2.0.0-rc07",
     "typescript": "^5.9.3",
     "vite": "^7.3.7"
   },

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/cli/commands/new.js

@@ -3,6 +3,7 @@
  *
  *   kmwc new web-colorpicker --prefix cpk [--title "Web Color Picker"] [--tag web-colorpicker]
  *        [--dir ../web-colorpicker] [--port 13200] [--minimal] [--register] [--offline]
+ *   kmwc new web-editor --adopt --dir /tmp/web-editor [--prefix …]
  *
  * Default: a small working sample (a toggle with `label` / `active` inputs and
  * a `change` event) to rename or replace. `--minimal`: an empty skeleton — no
@@ -21,6 +22,12 @@
  * `.claude/commands/publish.md`, examples, fixtures + e2e specs, then the
  * `kmwc sync` files. The port block (dev = block, image = +10) is the next free
  * one in the component range (see PORT_RANGES in config.js; `--port` overrides).
+ *
+ * `--adopt` is for MIGRATING a component that is already registered: the id must
+ * be in components.json, the port block (and prefix, unless the entry has none —
+ * then `--prefix`) come from its entry, the npm-name check is skipped (the package
+ * may exist), and the registry is left alone. Scaffold into a scratch `--dir`,
+ * then move the component's own code into the generated shape.
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
@@ -184,7 +191,7 @@ export function generatePackageJson({ componentId, packageName, tagline, tag, pr
 export async function run(args) {
   const requestedName = args._[0];
   if (!requestedName) {
-    throw new Error('usage: kmwc new <name> --prefix <2-4 letters> [--title "…"] [--tag …] [--dir …] [--port …] [--register] [--offline]');
+    throw new Error('usage: kmwc new <name> --prefix <2-4 letters> [--title "…"] [--tag …] [--dir …] [--port …] [--register] [--offline] [--adopt]');
   }
 
   const unscopedName = getUnscopedName(requestedName);
@@ -201,24 +208,35 @@ export async function run(args) {
 
   // ── intake ───────────────────────────────────────────────────────────────
   const registry = getRegistry();
-  if (registry.components.some((entry) => entry.id === componentId)) throw new Error(`"${componentId}" is already in components.json`);
+  const isAdopting = !!args.adopt;
+  const adoptedEntry = registry.components.find((entry) => entry.id === componentId);
+  if (isAdopting && !adoptedEntry) throw new Error(`--adopt: "${componentId}" is not in components.json — register it, or drop --adopt for a new component`);
+  if (!isAdopting && adoptedEntry) throw new Error(`"${componentId}" is already in components.json (migrating it? add --adopt)`);
+  if (isAdopting && args.register) throw new Error('--adopt never edits the registry — drop --register');
   if (existsSync(targetPath) && readdirSync(targetPath).length) throw new Error(`${targetPath} exists and is not empty`);
 
-  const prefix = args.prefix || generatePrefix(componentId);
+  if (isAdopting && adoptedEntry.prefix && args.prefix && args.prefix !== adoptedEntry.prefix) {
+    throw new Error(`--prefix ${args.prefix} ≠ the registered prefix "${adoptedEntry.prefix}"`);
+  }
+  const prefix = (isAdopting && adoptedEntry.prefix) || args.prefix || generatePrefix(componentId);
   if (!prefix) {
     throw new Error(
       `cannot derive a CSS prefix for "${componentId}" — is "${featureName}" one English word or several? ` +
         `Pass --prefix (initials of each word, e.g. daterangepicker → drp; component-intake.md "C — CSS prefix derivation").`
     );
   }
-  const prefixError = checkPrefix(prefix, getReservedPrefixes(registry));
+  // An adopted component's own registered prefix isn't a clash with itself.
+  const reservedPrefixes = getReservedPrefixes(registry);
+  if (isAdopting && adoptedEntry.prefix) reservedPrefixes.delete(adoptedEntry.prefix);
+  const prefixError = checkPrefix(prefix, reservedPrefixes);
   if (prefixError) throw new Error(prefixError);
 
-  if (!args.offline && checkIsPackageNameTaken(packageName)) throw new Error(`${packageName} already exists on npm (component-intake.md "B")`);
+  if (!isAdopting && !args.offline && checkIsPackageNameTaken(packageName)) throw new Error(`${packageName} already exists on npm (component-intake.md "B")`);
 
-  const devPort = Number(args.port) || getNextPortBlock(registry);
+  if (isAdopting && args.port && Number(args.port) !== adoptedEntry.port) throw new Error(`--port ${args.port} ≠ the registered port block ${adoptedEntry.port}`);
+  const devPort = isAdopting ? adoptedEntry.port : Number(args.port) || getNextPortBlock(registry);
   if (devPort % PORT_BLOCK_SIZE !== 0) throw new Error(`--port ${devPort} is not a port block (a multiple of ${PORT_BLOCK_SIZE})`);
-  const portOwner = registry.components.find((entry) => entry.port === devPort);
+  const portOwner = registry.components.find((entry) => entry.port === devPort && entry.id !== componentId);
   if (portOwner) throw new Error(`port block ${devPort} belongs to ${portOwner.id} — omit --port to take the next free block`);
   const corePackageJsonPath = join(DEVKIT_ROOT, '..', 'web-components-core', 'package.json');
   const coreVersion = existsSync(corePackageJsonPath) ? getJsonFile(corePackageJsonPath).version : '1.0.0-rc12';
@@ -279,7 +297,10 @@ export async function run(args) {
     repo: `https://github.com/keenmate/${componentId}`,
     port: devPort,
   };
-  if (args.register) {
+  if (isAdopting) {
+    if (!adoptedEntry.prefix) console.log(`
+The registry entry has no prefix — add "prefix": "${prefix}" to its components.json entry.`);
+  } else if (args.register) {
     const registryPath = join(DEVKIT_ROOT, 'components.json');
     const registryJson = getJsonFile(registryPath);
     const lastComponentIndex = registryJson.components.map((entry) => entry.kind).lastIndexOf('component');

package/src/cli/kmwc.js

@@ -41,6 +41,7 @@ Usage: kmwc <command> [options]
   new <name>                Scaffold a new component (e.g. \`kmwc new web-colorpicker --prefix cpk\`).
                             --title "…" --tag … --prefix … --dir … --port … --register
                             --minimal: empty skeleton (no inputs/events) instead of the sample
+                            --adopt: an already registered component (migration scratch scaffold)
   readme [--check]          Regenerate the README catalogue from components.json (devkit repo).
 
 Global: --root <dir>        Act on <dir> instead of the current directory.`);

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: {
@@ -123,6 +126,8 @@ export interface KmwcConfig {
 
 export const DEVKIT_ROOT: string;
 export const DEFAULT_RULEBOOK_PATH: string;
+/** The nearest `<ancestor>/BlissFramework/guidelines/web-components` above `startPath`, or null. */
+export function getRulebookPath(startPath: string): string | null;
 export const LEGACY_FILES: string[];
 export const PACKAGE_LEAK_RULES: Array<{ pattern: RegExp; label: string }>;
 export const PACKAGE_FILES_EXCLUSIONS: string[];

package/src/config.js

@@ -19,8 +19,28 @@ import { createRequire } from 'node:module';
 /** Absolute path of the devkit package root (this repo). */
 export const DEVKIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
-/** Default rulebook location: a BlissFramework checkout next to the KM folder. */
-export const DEFAULT_RULEBOOK_PATH = resolve(DEVKIT_ROOT, '..', '..', 'BlissFramework', 'guidelines', 'web-components');
+const RULEBOOK_RELATIVE_PATH = join('BlissFramework', 'guidelines', 'web-components');
+
+/**
+ * The nearest BlissFramework rulebook checkout: `<ancestor>/BlissFramework/
+ * guidelines/web-components` for the first ancestor of `startPath` that has one
+ * (e.g. C:\Git\KM\web-editor → C:\Git\BlissFramework\…), or null. Searching
+ * from the component (not a fixed path from the devkit) is what keeps it
+ * working when the devkit is installed into node_modules from npm.
+ */
+export function getRulebookPath(startPath) {
+  let directory = resolve(startPath);
+  for (;;) {
+    const candidatePath = join(directory, RULEBOOK_RELATIVE_PATH);
+    if (existsSync(candidatePath)) return candidatePath;
+    const parentDirectory = dirname(directory);
+    if (parentDirectory === directory) return null;
+    directory = parentDirectory;
+  }
+}
+
+/** Fallback rulebook location: the nearest checkout above the devkit, else next to the KM folder. */
+export const DEFAULT_RULEBOOK_PATH = getRulebookPath(DEVKIT_ROOT) ?? resolve(DEVKIT_ROOT, '..', '..', RULEBOOK_RELATIVE_PATH);
 
 /** Files the devkit now owns — finding one of these in a component is a doctor error. */
 export const LEGACY_FILES = [
@@ -215,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 || '',
@@ -235,7 +256,9 @@ export function mapKmwcConfig(packageJson, root = process.cwd()) {
       checkMode: cssVariables.checkMode || 'declared',
     },
     rulebook: {
-      path: process.env.KMWC_RULEBOOK_PATH || rulebook.path || DEFAULT_RULEBOOK_PATH,
+      path:
+        process.env.KMWC_RULEBOOK_PATH ||
+        (rulebook.path ? resolve(root, rulebook.path) : getRulebookPath(root) ?? DEFAULT_RULEBOOK_PATH),
       skippedChecks: rulebook.skippedChecks || [],
     },
     sync: {

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());
+}