@keenmate/web-components-devkit 0.0.0-stage → 1.0.0-rc02

package/src/config.js

@@ -0,0 +1,279 @@
+/**
+ * `@keenmate/web-components-devkit` — config resolution.
+ *
+ * Every component describes itself ONCE, in the `kmwc` section of its
+ * package.json. The Vite preset, the Playwright preset and every `kmwc` CLI
+ * command read it through `getKmwcConfig()`, so ports, titles, accent colours,
+ * analytics ids and image names can't drift between vite.config.ts, the
+ * Makefile, the Dockerfile and the example pages.
+ *
+ * Plain JSON (not a JS config file) on purpose: the CLI, templates and the
+ * README generator read it without a TS loader, and the registry generator can
+ * read sibling repos without executing their code.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
+
+/** Absolute path of the devkit package root (this repo). */
+export const DEVKIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+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 = [
+  'examples-chapter-nav.js',
+  'examples-copy-link.js',
+  'examples-controls-store.js',
+  'examples-shared.css',
+  'plausible-snippet.html',
+  'scripts/check-variable-manifest.mjs',
+];
+
+/**
+ * Port blocks: every repo owns one block of 100 (components.json `port`):
+ * dev server = block, preview = +1, examples image = +10. Each registry kind
+ * has its own range with headroom, numbered by 100 in registry order, so a new
+ * component lands next to the other components.
+ */
+export const PORT_BLOCK_SIZE = 100;
+export const PREVIEW_PORT_OFFSET = 1;
+export const IMAGE_PORT_OFFSET = 10;
+export const PORT_RANGES = [
+  { kinds: ['component'], firstBlock: 12100, lastBlock: 14900 },
+  { kinds: ['library'], firstBlock: 15000, lastBlock: 15900 },
+  { kinds: ['showcase', 'docs'], firstBlock: 16000, lastBlock: 16900 },
+  { kinds: ['test'], firstBlock: 17000, lastBlock: 17900 },
+];
+
+export function getPortsForBlock(portBlock) {
+  return { dev: portBlock, preview: portBlock + PREVIEW_PORT_OFFSET, image: portBlock + IMAGE_PORT_OFFSET };
+}
+
+export function getPortRange(kind) {
+  const portRange = PORT_RANGES.find((range) => range.kinds.includes(kind));
+  if (!portRange) throw new Error(`kmwc: no port range for registry kind "${kind}"`);
+  return portRange;
+}
+
+/** The next free block in the kind's range (after the highest block used by that range). */
+export function getNextPortBlock(registry = getRegistry(), kind = 'component') {
+  const portRange = getPortRange(kind);
+  const usedBlocks = registry.components
+    .filter((entry) => portRange.kinds.includes(entry.kind) && typeof entry.port === 'number')
+    .map((entry) => entry.port);
+  const nextBlock = usedBlocks.length ? Math.max(...usedBlocks) + PORT_BLOCK_SIZE : portRange.firstBlock;
+  if (nextBlock > portRange.lastBlock) throw new Error(`kmwc: the ${portRange.kinds.join('/')} port range ${portRange.firstBlock}–${portRange.lastBlock} is full`);
+  return nextBlock;
+}
+
+/**
+ * Files that must never reach a consumer's node_modules (`kmwc doctor` checks
+ * the `npm pack` file list). AI-assistant guidance (CLAUDE.md / .claude/)
+ * slips in whenever a `files` entry is a directory glob like `src/css`, so the
+ * scaffold's allowlist excludes it with PACKAGE_FILES_EXCLUSIONS.
+ */
+export const PACKAGE_LEAK_RULES = [
+  { pattern: /(^|\/)CLAUDE\.md$/i, label: 'CLAUDE.md (AI-assistant guidance)' },
+  { pattern: /(^|\/)\.claude\//, label: '.claude/ (AI-assistant commands)' },
+  { pattern: /^(test|tests|e2e)\//, label: 'test / e2e sources' },
+  { pattern: /\.(spec|test)\.[cm]?[jt]sx?$/, label: '*.spec / *.test files' },
+  { pattern: /^(examples-[^/]*\.html|index\.html|partials\/)/, label: 'example pages' },
+  { pattern: /^(dist-examples|test-results|playwright-report)\//, label: 'build / test output' },
+  { pattern: /(^|\/)(\.makefile\.env|Makefile\.local)$/, label: 'local make config' },
+];
+
+/** Negated `files` entries the scaffold adds (npm applies them after the globs). */
+export const PACKAGE_FILES_EXCLUSIONS = ['!**/CLAUDE.md', '!**/.claude'];
+
+/** Root-level HTML files that are fragments, not pages (never built as entries). */
+export const NON_PAGE_HTML_FILES = ['plausible-snippet.html'];
+
+/**
+ * Peer dependencies (vite, @playwright/test) must come from the COMPONENT's
+ * node_modules, not the devkit's: when the devkit is a `file:`/`npm link`
+ * symlink, Node resolves bare imports from the devkit's real path, which would
+ * load a second copy (or none). Playwright in particular breaks if the config
+ * and the specs see different instances.
+ */
+export function getPeerModule(root, moduleId) {
+  return createRequire(join(resolve(root), 'package.json'))(moduleId);
+}
+
+export async function loadPeerModule(root, moduleId) {
+  const requireFromRoot = createRequire(join(resolve(root), 'package.json'));
+  return import(pathToFileURL(requireFromRoot.resolve(moduleId)).href);
+}
+
+export function getJsonFile(filePath) {
+  return JSON.parse(readFileSync(filePath, 'utf8'));
+}
+
+export function getDevkitPackageJson() {
+  return getJsonFile(join(DEVKIT_ROOT, 'package.json'));
+}
+
+export function getRegistry() {
+  return getJsonFile(join(DEVKIT_ROOT, 'components.json'));
+}
+
+/** Strip the npm scope: `@keenmate/web-multiselect` → `web-multiselect`. */
+export function getUnscopedName(packageName) {
+  return String(packageName || '').replace(/^@[^/]+\//, '');
+}
+
+/** `web-multiselect` → `Web Multiselect` (fallback title only — set `kmwc.title`). */
+export function mapToTitleCase(id) {
+  return id
+    .split(/[-_]/)
+    .filter(Boolean)
+    .map((word) => word[0].toUpperCase() + word.slice(1))
+    .join(' ');
+}
+
+/** `web-multiselect` → `WebMultiselect`. */
+export function mapToPascalCase(id) {
+  return mapToTitleCase(id).replace(/\s+/g, '');
+}
+
+function getRepositoryUrl(packageJson) {
+  const rawUrl = typeof packageJson.repository === 'string' ? packageJson.repository : packageJson.repository?.url;
+  if (!rawUrl) return '';
+  return rawUrl.replace(/^git\+/, '').replace(/\.git$/, '');
+}
+
+/**
+ * Read and resolve `package.json#kmwc` for the component rooted at `root`.
+ * Every field has a default, so a component only states what's specific to it.
+ *
+ * @param {string} [root] component root (defaults to `process.cwd()`)
+ * @returns {import('./config.js').KmwcConfig}
+ */
+export function getKmwcConfig(root = process.cwd()) {
+  root = resolve(root);
+  const packageJsonPath = join(root, 'package.json');
+  if (!existsSync(packageJsonPath)) throw new Error(`kmwc: no package.json in ${root}`);
+  return mapKmwcConfig(getJsonFile(packageJsonPath), root);
+}
+
+/** Map a parsed package.json to the resolved config (pure — used by tests). */
+export function mapKmwcConfig(packageJson, root = process.cwd()) {
+  const packageConfig = packageJson.kmwc || {};
+  const id = packageConfig.id || getUnscopedName(packageJson.name) || 'component';
+  const library = 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 || {};
+  const rulebook = packageConfig.rulebook || {};
+  const devPort = ports.dev ?? 5173;
+
+  return {
+    root,
+    hasPackageConfig: !!packageJson.kmwc,
+    packageJson,
+    id,
+    packageName: packageJson.name || id,
+    version: packageJson.version || '0.1.0',
+    title: packageConfig.title || mapToTitleCase(id),
+    tagline: packageConfig.tagline || packageJson.description || '',
+    tag: packageConfig.tag || id,
+    prefix: packageConfig.prefix || '',
+    repository: getRepositoryUrl(packageJson),
+    homepage: packageJson.homepage || '',
+    author: typeof packageJson.author === 'string' ? packageJson.author : packageJson.author?.name || 'Keenmate s.r.o.',
+    license: packageJson.license || 'MIT',
+    library: {
+      entry: library.entry || 'src/index.ts',
+      globalName: library.globalName || mapToPascalCase(id),
+      fileName: library.fileName || id,
+      formats: library.formats || ['es', 'umd'],
+      // Vite 6+ names lib CSS after the package; keep the historical `style.css`
+      // so consumers importing `dist/style.css` don't break on the Vite 7 move.
+      cssFileName: library.cssFileName || 'style',
+      shouldEmitTypes: library.shouldEmitTypes ?? true,
+      typesPluginConfig: library.typesPluginConfig || {},
+      shouldEmitSourcemap: library.shouldEmitSourcemap ?? false,
+      external: library.external || [],
+    },
+    ports: {
+      dev: devPort,
+      preview: devPort + PREVIEW_PORT_OFFSET,
+      image: ports.image ?? devPort + IMAGE_PORT_OFFSET,
+    },
+    theme: {
+      accentColor: theme.accentColor || '',
+      accentEndColor: theme.accentEndColor || '',
+    },
+    examples: {
+      outDir: examples.outDir || 'dist-examples',
+      canonicalOrigin: examples.canonicalOrigin || '',
+      staticPaths: examples.staticPaths || [],
+      excludedPages: examples.excludedPages || [],
+      storagePrefix: examples.storagePrefix || id,
+    },
+    analytics: {
+      plausibleSiteId: analytics.plausibleSiteId || '',
+      plausibleHostUrl: analytics.plausibleHostUrl || 'https://stats.keenmate.services',
+    },
+    image: {
+      name: image.name || `registry.km8.es/${id}-examples:prod`,
+      container: image.container || `${id}-examples`,
+      runner: image.runner || 'podman',
+      nodeImage: image.nodeImage || '24-alpine',
+      packageJsonPaths: image.packageJsonPaths || ['package.json'],
+      installCommand: image.installCommand || 'npm install --no-audit --no-fund',
+    },
+    cssVariables: {
+      manifest: cssVariables.manifest || 'component-variables.manifest.json',
+      sources: cssVariables.sources || ['src/css'],
+      internalVariables: cssVariables.internalVariables || [],
+      checkMode: cssVariables.checkMode || 'declared',
+    },
+    rulebook: {
+      path:
+        process.env.KMWC_RULEBOOK_PATH ||
+        (rulebook.path ? resolve(root, rulebook.path) : getRulebookPath(root) ?? DEFAULT_RULEBOOK_PATH),
+      skippedChecks: rulebook.skippedChecks || [],
+    },
+    sync: {
+      skippedFiles: packageConfig.sync?.skippedFiles || [],
+    },
+  };
+}
+
+/** Build-time constants every component's source may reference (`__VERSION__` …). */
+export function generateBuildDefines(config) {
+  return {
+    __VERSION__: JSON.stringify(config.version),
+    __PACKAGE_NAME__: JSON.stringify(config.packageName),
+    __AUTHOR__: JSON.stringify(config.author),
+    __LICENSE__: JSON.stringify(config.license),
+    __REPOSITORY__: JSON.stringify(config.repository),
+    __HOMEPAGE__: JSON.stringify(config.homepage),
+  };
+}

package/src/examples/auto.js

@@ -0,0 +1,20 @@
+/**
+ * Side-effect entry injected into every example page by the kmwc Vite plugin
+ * (as `virtual:kmwc-examples`). Mounts the page-level helpers. The shared
+ * styles are NOT imported here: the plugin loads them render-blocking (a
+ * <link> in <head> in dev, an extracted stylesheet in builds), because a CSS
+ * import in a module script only applies after the script runs — a flash of
+ * unstyled page on every reload. Using this entry without the plugin? Import
+ * `@keenmate/web-components-devkit/examples/style.css` yourself.
+ *
+ * Mounting is deferred one task past DOM-ready on purpose: in the production
+ * build Vite hoists this import INTO the page's entry module, so it evaluates
+ * BEFORE the page's own inline script (the reverse of dev order). Waiting a
+ * task lets a page that builds its sections / registry in script (e.g.
+ * `renderExamplesIndex`) finish first — in dev and build alike. Content
+ * rendered later still (after a fetch) → call `mountExamplesKit()`.
+ */
+import { attachDomReadyHandler } from './page-config.js';
+import { mountExamplesKit } from './kit.js';
+
+attachDomReadyHandler(() => setTimeout(mountExamplesKit, 0));

package/src/examples/chapter-nav.js

@@ -0,0 +1,246 @@
+/**
+ * CHAPTER NAV — floating "on this page" jump navigator.
+ *
+ * A tab pinned to the right edge (~1/3 down the viewport) that expands into a
+ * scroll-spied list of the page's chapters (every section <h2>, see
+ * sections.js). Pages with fewer than two chapters render nothing.
+ *
+ * Cross-page mode: if `navConfig.items` is passed (or
+ * `window.CHAPTER_NAV_ITEMS` is set — the examples index does this from its
+ * page registry) the list jumps between pages instead, with no scroll-spy.
+ *
+ * The open panel is anchored to the tab with Floating UI (bundled by Vite);
+ * if it fails to load, a viewport-clamped fixed placement takes over.
+ * Styles: css/chapter-nav.css.
+ */
+import { ensureSectionAnchors } from './sections.js';
+import { ACTIVE_CHAPTER_OFFSET_PX, CHAPTER_NAV_CLASSES, CHAPTER_NAV_PANEL_ID, DEFAULT_INDEX_HREF } from './constants.js';
+
+let floatingUiPromise = null;
+function loadFloatingUi() {
+  floatingUiPromise ??= import('@floating-ui/dom').catch(() => null);
+  return floatingUiPromise;
+}
+
+const TOGGLE_ICON_HTML =
+  '<svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">' +
+  '<line x1="8" y1="6" x2="20" y2="6"></line>' +
+  '<line x1="8" y1="12" x2="20" y2="12"></line>' +
+  '<line x1="8" y1="18" x2="20" y2="18"></line>' +
+  '<circle cx="4" cy="6" r="1.4"></circle>' +
+  '<circle cx="4" cy="12" r="1.4"></circle>' +
+  '<circle cx="4" cy="18" r="1.4"></circle>' +
+  '</svg>';
+
+/** The mounted nav — mounting again replaces it (pages that render sections late remount). */
+let mountedChapterNav = null;
+
+/**
+ * Mount (or remount) the nav from the page's current sections.
+ * @param {object} [navConfig]
+ * @param {Array<{label: string, href: string}>} [navConfig.items] cross-page list
+ * @param {string} [navConfig.indexHref] "Back to Examples" target ('' hides it)
+ * @returns {{ unmount(): void } | null}
+ */
+export function mountChapterNav(navConfig = {}) {
+  mountedChapterNav?.unmount();
+  mountedChapterNav = null;
+
+  const crossPageItems = navConfig.items || (Array.isArray(window.CHAPTER_NAV_ITEMS) ? window.CHAPTER_NAV_ITEMS : null);
+  const isCrossPage = !!crossPageItems;
+  const indexHref = navConfig.indexHref ?? DEFAULT_INDEX_HREF;
+
+  const chapters = isCrossPage
+    ? crossPageItems
+        .filter((item) => item && item.href)
+        .map((item, itemIndex) => ({ id: null, section: null, label: item.label || `Item ${itemIndex + 1}`, href: item.href }))
+    : ensureSectionAnchors().map((section) => ({ ...section, href: `#${section.id}` }));
+  if (chapters.length < 2) return null;
+
+  // Warm the import so the panel can anchor on first open.
+  loadFloatingUi();
+
+  // ── build ────────────────────────────────────────────────────────────────
+  const rootElement = document.createElement('div');
+  rootElement.className = CHAPTER_NAV_CLASSES.root;
+
+  const panelElement = document.createElement('nav');
+  panelElement.className = CHAPTER_NAV_CLASSES.panel;
+  panelElement.id = CHAPTER_NAV_PANEL_ID;
+  panelElement.setAttribute('aria-label', isCrossPage ? 'Examples' : 'On this page');
+
+  if (!isCrossPage && indexHref) {
+    const backLink = document.createElement('a');
+    backLink.className = CHAPTER_NAV_CLASSES.back;
+    backLink.href = indexHref;
+    backLink.textContent = '← Back to Examples';
+    panelElement.appendChild(backLink);
+  }
+
+  const titleElement = document.createElement('div');
+  titleElement.className = CHAPTER_NAV_CLASSES.title;
+  titleElement.textContent = isCrossPage ? 'Examples' : 'On this page';
+  panelElement.appendChild(titleElement);
+
+  const listElement = document.createElement('ul');
+  listElement.className = CHAPTER_NAV_CLASSES.list;
+  const itemElementsById = Object.create(null);
+  for (const chapter of chapters) {
+    const listItem = document.createElement('li');
+    const itemLink = document.createElement('a');
+    itemLink.className = CHAPTER_NAV_CLASSES.item;
+    itemLink.href = chapter.href;
+    itemLink.textContent = chapter.label;
+    itemLink.addEventListener('click', () => {
+      if (chapter.id) activateChapter(chapter.id);
+      closePanel();
+    });
+    listItem.appendChild(itemLink);
+    listElement.appendChild(listItem);
+    if (chapter.id) itemElementsById[chapter.id] = itemLink;
+  }
+  panelElement.appendChild(listElement);
+
+  const toggleButton = document.createElement('button');
+  toggleButton.type = 'button';
+  toggleButton.className = CHAPTER_NAV_CLASSES.toggle;
+  toggleButton.setAttribute('aria-expanded', 'false');
+  toggleButton.setAttribute('aria-controls', CHAPTER_NAV_PANEL_ID);
+  toggleButton.setAttribute('aria-label', isCrossPage ? 'Jump to an example page' : 'Jump to a section on this page');
+  toggleButton.innerHTML = TOGGLE_ICON_HTML;
+
+  rootElement.append(toggleButton, panelElement);
+  document.body.appendChild(rootElement);
+
+  // Keep the wheel inside the panel even when it can't scroll further (or
+  // doesn't overflow at all) — `overscroll-behavior` only covers the former.
+  const handlePanelWheel = (event) => {
+    const isAtTop = panelElement.scrollTop <= 0;
+    const isAtBottom = panelElement.scrollTop + panelElement.clientHeight >= panelElement.scrollHeight - 1;
+    if ((event.deltaY < 0 && isAtTop) || (event.deltaY > 0 && isAtBottom)) event.preventDefault();
+    event.stopPropagation();
+  };
+  panelElement.addEventListener('wheel', handlePanelWheel, { passive: false });
+
+  // ── positioning ──────────────────────────────────────────────────────────
+  let stopAutoUpdateHandler = null;
+  let positioningRequestId = 0;
+
+  function positionPanel() {
+    const requestId = ++positioningRequestId;
+    loadFloatingUi().then((floatingUi) => {
+      if (requestId !== positioningRequestId || !isPanelOpen) return; // closed before the import resolved
+      if (!floatingUi) return positionPanelFallback();
+      stopAutoUpdateHandler = floatingUi.autoUpdate(toggleButton, panelElement, () => {
+        floatingUi
+          .computePosition(toggleButton, panelElement, {
+            placement: 'left-start',
+            strategy: 'fixed',
+            middleware: [
+              floatingUi.offset(8),
+              floatingUi.flip({ fallbackPlacements: ['right-start', 'bottom-end', 'top-end'] }),
+              floatingUi.shift({ padding: 8 }),
+            ],
+          })
+          .then((position) => {
+            panelElement.style.left = `${position.x}px`;
+            panelElement.style.top = `${position.y}px`;
+          });
+      });
+    });
+  }
+
+  function positionPanelFallback() {
+    const toggleRect = toggleButton.getBoundingClientRect();
+    panelElement.style.left = 'auto';
+    panelElement.style.right = `${window.innerWidth - toggleRect.left + 8}px`;
+    panelElement.style.top = `${Math.max(8, Math.min(toggleRect.top, window.innerHeight - panelElement.offsetHeight - 8))}px`;
+  }
+
+  function stopPanelPositioning() {
+    positioningRequestId++;
+    if (stopAutoUpdateHandler) {
+      stopAutoUpdateHandler();
+      stopAutoUpdateHandler = null;
+    }
+  }
+
+  // ── open / close ─────────────────────────────────────────────────────────
+  let isPanelOpen = false;
+  function openPanel() {
+    isPanelOpen = true;
+    rootElement.classList.add(CHAPTER_NAV_CLASSES.rootOpen);
+    toggleButton.setAttribute('aria-expanded', 'true');
+    positionPanel();
+  }
+  function closePanel() {
+    isPanelOpen = false;
+    rootElement.classList.remove(CHAPTER_NAV_CLASSES.rootOpen);
+    toggleButton.setAttribute('aria-expanded', 'false');
+    stopPanelPositioning();
+  }
+  toggleButton.addEventListener('click', () => (isPanelOpen ? closePanel() : openPanel()));
+
+  const handleDocumentKeydown = (event) => {
+    if (event.key === 'Escape' && isPanelOpen) {
+      closePanel();
+      toggleButton.focus();
+    }
+  };
+  const handleDocumentClick = (event) => {
+    if (isPanelOpen && !rootElement.contains(event.target)) closePanel();
+  };
+  document.addEventListener('keydown', handleDocumentKeydown);
+  document.addEventListener('click', handleDocumentClick);
+
+  // ── scroll-spy (in-page chapters only) ───────────────────────────────────
+  let activeChapterId = null;
+  function activateChapter(chapterId) {
+    if (chapterId === activeChapterId) return;
+    itemElementsById[activeChapterId]?.classList.remove(CHAPTER_NAV_CLASSES.itemActive);
+    activeChapterId = chapterId;
+    const itemLink = itemElementsById[chapterId];
+    if (itemLink) {
+      itemLink.classList.add(CHAPTER_NAV_CLASSES.itemActive);
+      itemLink.scrollIntoView?.({ block: 'nearest' });
+    }
+  }
+  function reconcileActiveChapter() {
+    // At the bottom of the page the last chapters may never reach the top
+    // threshold (short page / short trailing sections) — the last one wins.
+    const isAtPageBottom = window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - 2;
+    if (isAtPageBottom && window.scrollY > 0) return activateChapter(chapters[chapters.length - 1].id);
+    let currentChapterId = chapters[0].id;
+    for (const chapter of chapters) {
+      if (chapter.section.getBoundingClientRect().top <= ACTIVE_CHAPTER_OFFSET_PX) currentChapterId = chapter.id;
+      else break;
+    }
+    activateChapter(currentChapterId);
+  }
+  let isFrameScheduled = false;
+  const handleScroll = () => {
+    if (isFrameScheduled) return;
+    isFrameScheduled = true;
+    requestAnimationFrame(() => {
+      reconcileActiveChapter();
+      isFrameScheduled = false;
+    });
+  };
+  if (!isCrossPage) {
+    window.addEventListener('scroll', handleScroll, { passive: true });
+    window.addEventListener('resize', handleScroll, { passive: true });
+    reconcileActiveChapter();
+  }
+
+  mountedChapterNav = {
+    unmount() {
+      stopPanelPositioning();
+      document.removeEventListener('keydown', handleDocumentKeydown);
+      document.removeEventListener('click', handleDocumentClick);
+      window.removeEventListener('scroll', handleScroll);
+      window.removeEventListener('resize', handleScroll);
+      rootElement.remove();
+    },
+  };
+  return mountedChapterNav;
+}

package/src/examples/constants.js

@@ -0,0 +1,80 @@
+/**
+ * Side layer: every class name, selector, id and storage key the examples kit
+ * emits or reads. Kit-generated DOM follows the rulebook's prefix + BEM rule
+ * (`kmwc__element--modifier` shape, block `kmwc-<feature>`); the page
+ * vocabulary authors write (`.card`, `.controls`, …) is deliberately NOT here
+ * — it's styled by the kit but owned by the pages.
+ */
+
+export const CHAPTER_NAV_CLASSES = {
+  root: 'kmwc-chapter-nav',
+  rootOpen: 'kmwc-chapter-nav--open',
+  toggle: 'kmwc-chapter-nav__toggle',
+  panel: 'kmwc-chapter-nav__panel',
+  back: 'kmwc-chapter-nav__back',
+  title: 'kmwc-chapter-nav__title',
+  list: 'kmwc-chapter-nav__list',
+  item: 'kmwc-chapter-nav__item',
+  itemActive: 'kmwc-chapter-nav__item--active',
+};
+
+export const CHAPTER_NAV_PANEL_ID = 'kmwc-chapter-nav-panel';
+
+export const COPY_LINK_CLASSES = {
+  root: 'kmwc-copy-link',
+  rootCopied: 'kmwc-copy-link--copied',
+  rootFailed: 'kmwc-copy-link--failed',
+  icon: 'kmwc-copy-link__icon',
+  iconLink: 'kmwc-copy-link__icon--link',
+  iconCheck: 'kmwc-copy-link__icon--check',
+  label: 'kmwc-copy-link__label',
+};
+
+export const INDEX_PAGE_CLASSES = {
+  body: 'kmwc-index',
+  page: 'kmwc-index__page',
+  header: 'kmwc-index__header',
+  tagline: 'kmwc-index__tagline',
+  version: 'kmwc-index__version',
+  cards: 'kmwc-index__cards',
+  card: 'kmwc-index__card',
+  icon: 'kmwc-index__icon',
+  cardTitle: 'kmwc-index__card-title',
+  cardDescription: 'kmwc-index__card-description',
+  badge: 'kmwc-index__badge',
+  footer: 'kmwc-index__footer',
+  devkit: 'kmwc-index__devkit',
+};
+
+/** <kmwc-demo> output (rendered at build time by page-composer.js) + the kit's copy button. */
+export const DEMO_CLASSES = {
+  root: 'kmwc-demo',
+  preview: 'kmwc-demo__preview',
+  code: 'kmwc-demo__code',
+  copyButton: 'kmwc-demo__copy',
+  copyButtonCopied: 'kmwc-demo__copy--copied',
+};
+
+export const THEME_SWITCH_CLASSES = {
+  root: 'kmwc-theme-switch',
+  icon: 'kmwc-theme-switch__icon',
+};
+
+/** Section containers and the chips that must not leak into a heading label. */
+export const SECTION_CONTAINER_SELECTOR = '.container';
+export const SECTION_SELECTOR = '.card, .example-section';
+export const HEADING_CHIP_SELECTOR = `.badge, .${COPY_LINK_CLASSES.root}`;
+
+export const VERSION_BADGE_SELECTOR = '[data-kmwc-version], #version-badge';
+
+export const DEFAULT_INDEX_HREF = 'index.html';
+
+/** Page theme: `data-theme` on <html> — the same signal components react to. */
+export const THEME_ATTRIBUTE = 'theme';
+export const THEME_STORAGE_KEY = 'kmwc:examples:theme';
+export const THEMES = ['light', 'dark', 'auto'];
+export const DEFAULT_THEME = 'light';
+
+/** A chapter counts as "current" once its top is within this many px of the viewport top. */
+export const ACTIVE_CHAPTER_OFFSET_PX = 120;
+export const COPY_FEEDBACK_DURATION_MS = 1600;