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

package/src/examples/theme-switch.js

@@ -0,0 +1,72 @@
+/**
+ * THEME SWITCH — a small fixed button cycling the page theme light → dark →
+ * auto (follow the OS). It sets `data-theme` on <html>: the kit's tokens flip
+ * via `color-scheme`, and components react through their own
+ * `:host-context([data-theme="dark"])` selectors and inherited `color-scheme`
+ * (rulebook color-scheme.md signals #3/#4) — so every example page doubles as
+ * a dark-mode smoke test of the component.
+ *
+ * The plugin also injects a tiny inline script into <head> that applies the
+ * saved theme before first paint (see `renderThemeBootstrapScript`), so a
+ * reload doesn't flash light. Styles: css/theme-switch.css.
+ */
+import { DEFAULT_THEME, THEME_ATTRIBUTE, THEME_STORAGE_KEY, THEMES, THEME_SWITCH_CLASSES } from './constants.js';
+
+const THEME_ICONS = { light: '☀', dark: '☾', auto: '◐' };
+const THEME_LABELS = { light: 'Light theme', dark: 'Dark theme', auto: 'Follow system theme' };
+
+export function getSavedTheme() {
+  try {
+    const savedTheme = localStorage.getItem(THEME_STORAGE_KEY);
+    return THEMES.includes(savedTheme) ? savedTheme : DEFAULT_THEME;
+  } catch {
+    return DEFAULT_THEME;
+  }
+}
+
+export function applyTheme(theme) {
+  document.documentElement.dataset[THEME_ATTRIBUTE] = theme;
+  try {
+    localStorage.setItem(THEME_STORAGE_KEY, theme);
+  } catch {
+    /* storage unavailable — theme still applies for this page view */
+  }
+}
+
+/** Inline <head> script source that applies the saved theme before first paint. */
+export function renderThemeBootstrapScript() {
+  return `try{var t=localStorage.getItem(${JSON.stringify(THEME_STORAGE_KEY)});document.documentElement.dataset.${THEME_ATTRIBUTE}=${JSON.stringify(THEMES)}.indexOf(t)>-1?t:${JSON.stringify(DEFAULT_THEME)}}catch(e){document.documentElement.dataset.${THEME_ATTRIBUTE}=${JSON.stringify(DEFAULT_THEME)}}`;
+}
+
+let mountedThemeSwitch = null;
+
+/** @returns {{ unmount(): void }} */
+export function mountThemeSwitch() {
+  mountedThemeSwitch?.unmount();
+  if (!document.documentElement.dataset[THEME_ATTRIBUTE]) applyTheme(getSavedTheme());
+
+  const button = document.createElement('button');
+  button.type = 'button';
+  button.className = THEME_SWITCH_CLASSES.root;
+  const iconElement = document.createElement('span');
+  iconElement.className = THEME_SWITCH_CLASSES.icon;
+  iconElement.setAttribute('aria-hidden', 'true');
+  button.appendChild(iconElement);
+
+  const renderButton = () => {
+    const theme = document.documentElement.dataset[THEME_ATTRIBUTE];
+    iconElement.textContent = THEME_ICONS[theme] || THEME_ICONS[DEFAULT_THEME];
+    button.title = `${THEME_LABELS[theme]} (click to switch)`;
+    button.setAttribute('aria-label', button.title);
+  };
+  button.addEventListener('click', () => {
+    const currentTheme = document.documentElement.dataset[THEME_ATTRIBUTE];
+    applyTheme(THEMES[(THEMES.indexOf(currentTheme) + 1) % THEMES.length]);
+    renderButton();
+  });
+  renderButton();
+  document.body.appendChild(button);
+
+  mountedThemeSwitch = { unmount: () => button.remove() };
+  return mountedThemeSwitch;
+}

package/src/examples/version-badge.js

@@ -0,0 +1,23 @@
+/**
+ * Fill version badges from the injected page config. Any `[data-kmwc-version]`
+ * element (and the legacy `#version-badge`) gets `v1.2.3` in dev and
+ * `v1.2.3 (built 2026-10-12T19:49Z)` in a built examples site.
+ */
+import { getPageConfig } from './page-config.js';
+import { VERSION_BADGE_SELECTOR } from './constants.js';
+
+export function getVersionLabel(pageConfig = getPageConfig()) {
+  if (!pageConfig.version) return '';
+  return pageConfig.buildTimestamp ? `v${pageConfig.version} (built ${pageConfig.buildTimestamp})` : `v${pageConfig.version}`;
+}
+
+export function renderVersionBadges(root = document) {
+  const pageConfig = getPageConfig();
+  const versionLabel = getVersionLabel(pageConfig);
+  if (!versionLabel) return;
+  for (const badge of root.querySelectorAll(VERSION_BADGE_SELECTOR)) {
+    if (badge.textContent.trim()) continue; // page put its own text — leave it
+    badge.textContent = versionLabel;
+    if (pageConfig.buildTimestamp) badge.title = `Built ${pageConfig.buildTimestamp}`;
+  }
+}

package/src/playwright/index.d.ts

@@ -0,0 +1,15 @@
+import type { PlaywrightTestConfig, Project } from '@playwright/test';
+
+export interface PlaywrightPresetConfig extends Omit<PlaywrightTestConfig, 'projects' | 'use' | 'webServer'> {
+  /** Component root; defaults to `process.cwd()`. */
+  root?: string;
+  /** Replaces the default single desktop-chromium project. */
+  projects?: Project[];
+  /** Merged over the default `use` (baseURL is derived from kmwc.ports.dev). */
+  use?: PlaywrightTestConfig['use'];
+  /** Merged over the default webServer (`npm run dev` on kmwc.ports.dev); an array replaces it. */
+  webServer?: Partial<NonNullable<Exclude<PlaywrightTestConfig['webServer'], unknown[]>>> | PlaywrightTestConfig['webServer'];
+}
+
+export function definePlaywrightConfig(presetConfig?: PlaywrightPresetConfig): PlaywrightTestConfig;
+export const devices: typeof import('@playwright/test').devices;

package/src/playwright/index.js

@@ -0,0 +1,66 @@
+/**
+ * `@keenmate/web-components-devkit/playwright` — the shared Playwright preset.
+ *
+ *     import { definePlaywrightConfig } from '@keenmate/web-components-devkit/playwright';
+ *     export default definePlaywrightConfig();
+ *
+ * Specs live in e2e/ and target fixture pages under test/*.html, served by the
+ * component's own dev server on kmwc.ports.dev (read from package.json, so the
+ * port can't drift from vite.config / the Makefile). Pass `projects` to add
+ * e.g. a touch-only mobile project; anything else is shallow-merged on top.
+ */
+import { getKmwcConfig, getPeerModule } from '../config.js';
+
+/** The component's own @playwright/test (see getPeerModule). */
+function getPlaywright(root = process.cwd()) {
+  return getPeerModule(root, '@playwright/test');
+}
+
+/** Playwright's device descriptors, from the component's install. */
+export const devices = new Proxy({}, { get: (_, deviceName) => getPlaywright().devices[deviceName] });
+
+/** @param {import('./index.js').PlaywrightPresetConfig} [presetConfig] */
+export function definePlaywrightConfig(presetConfig = {}) {
+  const { root, projects, use, webServer, ...restConfig } = presetConfig;
+  const config = getKmwcConfig(root);
+  const { defineConfig, devices: playwrightDevices } = getPlaywright(config.root);
+  const baseUrl = `http://localhost:${config.ports.dev}`;
+  const isCi = !!process.env.CI;
+
+  return defineConfig({
+    testDir: './e2e',
+    timeout: 30_000,
+    expect: { timeout: 5_000 },
+    fullyParallel: true,
+    forbidOnly: isCi,
+    retries: isCi ? 2 : 0,
+    workers: isCi ? 1 : undefined,
+    reporter: isCi ? 'github' : 'list',
+    use: {
+      baseURL: baseUrl,
+      trace: 'on-first-retry',
+      screenshot: 'only-on-failure',
+      video: 'retain-on-failure',
+      ...use,
+    },
+    projects: projects || [
+      {
+        name: 'chromium',
+        use: { ...playwrightDevices['Desktop Chrome'], viewport: { width: 1440, height: 1024 } },
+      },
+    ],
+    // An array (e.g. dev server + examples preview) is taken as-is.
+    webServer: Array.isArray(webServer)
+      ? webServer
+      : {
+          command: 'npm run dev',
+          url: baseUrl,
+          reuseExistingServer: !isCi,
+          timeout: 60_000,
+          stdout: 'ignore',
+          stderr: 'pipe',
+          ...webServer,
+        },
+    ...restConfig,
+  });
+}

package/src/template.js

@@ -0,0 +1,11 @@
+/**
+ * Side layer: the one placeholder syntax the devkit uses for its own templates
+ * (generated files, the scaffold, the examples layout) — `{{UPPER_CASE}}`.
+ * An unknown placeholder is an error, never silently empty.
+ */
+export function renderTemplate(templateText, variables) {
+  return templateText.replace(/\{\{([A-Z_]+)\}\}/g, (placeholder, variableName) => {
+    if (!(variableName in variables)) throw new Error(`kmwc: template variable ${variableName} is not defined`);
+    return String(variables[variableName]);
+  });
+}

package/src/vite/index.d.ts

@@ -0,0 +1,28 @@
+import type { ConfigEnv, Plugin, PluginOption, UserConfig, UserConfigFnPromise } from 'vite';
+import type { KmwcConfig, KmwcPackageConfig } from '../config.js';
+
+export interface VitePresetConfig {
+  /** Component root; defaults to `process.cwd()`. */
+  root?: string;
+  /** Extra plugins, appended after the kmwc examples plugin. */
+  plugins?: PluginOption[];
+  /** Per-config override of `package.json#kmwc.library`. */
+  library?: KmwcPackageConfig['library'];
+  /** Deep-merged last via Vite's `mergeConfig`. */
+  overrides?: UserConfig;
+  /** Env-dependent overrides; its return is deep-merged after `overrides`. */
+  getOverridesCallback?: (env: ConfigEnv, config: KmwcConfig) => UserConfig | Promise<UserConfig>;
+}
+
+export interface ExamplesPluginConfig {
+  /** Component root; defaults to `process.cwd()`. */
+  root?: string;
+  /** Force the analytics snippet on/off (default: on for `vite build` only). */
+  shouldInjectAnalytics?: boolean;
+}
+
+export function defineComponentConfig(presetConfig?: VitePresetConfig): UserConfigFnPromise;
+
+export function createExamplesPlugin(pluginConfig?: ExamplesPluginConfig): Plugin;
+
+export function getExamplePages(config: KmwcConfig): Record<string, string>;

package/src/vite/index.js

@@ -0,0 +1,243 @@
+/**
+ * `@keenmate/web-components-devkit/vite` — the shared Vite preset.
+ *
+ * A component's whole vite.config.ts becomes:
+ *
+ *     import { defineComponentConfig } from '@keenmate/web-components-devkit/vite';
+ *     export default defineComponentConfig();
+ *
+ * Everything else comes from package.json#kmwc. Three modes:
+ *
+ *   vite                          dev server on kmwc.ports.dev (strict — no port hopping)
+ *   vite build                    library build → dist/<fileName>.js + .umd.js + style.css (+ .d.ts)
+ *   vite build --mode examples    static example site → dist-examples/ (every root *.html is a page)
+ *
+ * The examples plugin injects the shared kit (styles, chapter nav, copy-link,
+ * version badge) into every root-level page, so pages carry only their own
+ * content — no per-repo copies of the helper scripts or the shared stylesheet.
+ */
+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';
+
+const AUTO_ENTRY_PATH = join(DEVKIT_ROOT, 'src', 'examples', 'auto.js');
+const VIRTUAL_AUTO_ID = 'virtual:kmwc-examples';
+const KIT_STYLESHEET_PATH = join(DEVKIT_ROOT, 'src', 'examples', 'css', 'style.css').replace(/\\/g, '/');
+// Vite's dev-server URL for a file outside the project root.
+const KIT_STYLESHEET_DEV_URL = `/@fs/${KIT_STYLESHEET_PATH.replace(/^\//, '')}`;
+const EXAMPLES_MODE = 'examples';
+
+/** Root-level HTML pages to build as the examples site. */
+export function getExamplePages(config) {
+  const skippedPages = new Set([...NON_PAGE_HTML_FILES, ...config.examples.excludedPages]);
+  return Object.fromEntries(
+    readdirSync(config.root)
+      .filter((fileName) => fileName.endsWith('.html') && !skippedPages.has(fileName))
+      .map((fileName) => [fileName.replace(/\.html$/, ''), resolve(config.root, fileName)])
+  );
+}
+
+function getBuildTimestamp() {
+  return new Date().toISOString().slice(0, 16) + 'Z';
+}
+
+const mapToScriptSafeJson = (json) => json.replace(/</g, '\\u003c');
+
+/** Plausible snippet for the given site id (build only). */
+function renderPlausibleSnippet(config) {
+  const scriptUrl = `${config.analytics.plausibleHostUrl.replace(/\/$/, '')}/js/${config.analytics.plausibleSiteId}.js`;
+  return (
+    `<!-- Privacy-friendly analytics by Plausible (injected by kmwc at build time) -->\n` +
+    `<script async src="${scriptUrl}"></script>\n` +
+    `<script>window.plausible=window.plausible||function(){(plausible.q=plausible.q||[]).push(arguments)},plausible.init=plausible.init||function(i){plausible.o=i||{}};plausible.init()</script>\n`
+  );
+}
+
+/**
+ * The examples plugin. Usually wired by `defineComponentConfig()`; exported for
+ * repos (monorepos, showcases) that assemble their own Vite config.
+ *
+ * @param {import('./index.js').ExamplesPluginConfig} [pluginConfig]
+ */
+export function createExamplesPlugin(pluginConfig = {}) {
+  const config = getKmwcConfig(pluginConfig.root);
+  let command = 'serve';
+  let mode = 'development';
+  let outDir = config.examples.outDir;
+  const buildTimestamp = process.env.BUILD_TIME || getBuildTimestamp();
+  const devkitPackageJson = getDevkitPackageJson();
+
+  return {
+    name: 'kmwc-examples',
+
+    configResolved(resolvedConfig) {
+      command = resolvedConfig.command;
+      mode = resolvedConfig.mode;
+      outDir = resolvedConfig.build.outDir;
+    },
+
+    resolveId(moduleId) {
+      return moduleId === VIRTUAL_AUTO_ID ? AUTO_ENTRY_PATH : null;
+    },
+
+    // A partial isn't a module, so Vite doesn't know which pages use it —
+    // reload the page on any non-root HTML change (partials/…).
+    handleHotUpdate({ file, server }) {
+      const relativePath = file.replace(/\\/g, '/').replace(config.root.replace(/\\/g, '/') + '/', '');
+      if (relativePath.endsWith('.html') && relativePath.includes('/') && !relativePath.startsWith('test/')) {
+        server.ws.send({ type: 'full-reload' });
+        return [];
+      }
+      return undefined;
+    },
+
+    transformIndexHtml: {
+      // `pre`: run before Vite processes the HTML, so the injected module script
+      // is bundled exactly like an authored one (dev and build alike).
+      order: 'pre',
+      handler(html, context) {
+        // Only root-level pages are example pages — test fixtures under test/
+        // (Playwright) stay bare. A page can opt out with <html data-kmwc="off">.
+        if (context.path.split('/').filter(Boolean).length > 1) return html;
+        if (/<html[^>]*\sdata-kmwc=["']?off/i.test(html)) return html;
+
+        // Includes, demos and — for fragment pages — the shared layout
+        // (page-composer.js). Full documents pass through untouched.
+        html = composePage(html, { config, pagePath: context.path });
+
+        const isBuild = command === 'build';
+        const pageConfig = {
+          id: config.id,
+          title: config.title,
+          tagline: config.tagline,
+          version: config.version,
+          packageName: config.packageName,
+          buildTimestamp: isBuild ? buildTimestamp : null,
+          mode: isBuild ? 'build' : 'dev',
+          canonicalOrigin: config.examples.canonicalOrigin,
+          storagePrefix: config.examples.storagePrefix,
+          repository: config.repository,
+          homepage: config.homepage,
+          devkitVersion: devkitPackageJson.version,
+          devkitHomepage: devkitPackageJson.homepage,
+        };
+
+        let headHtml =
+          `<script>${renderThemeBootstrapScript()}</script>\n` +
+          `<script>window.__KMWC__=${mapToScriptSafeJson(JSON.stringify(pageConfig))};</script>\n`;
+        const accentDeclarations = [
+          config.theme.accentColor && `--kmwc-accent-color:${config.theme.accentColor}`,
+          config.theme.accentEndColor && `--kmwc-accent-end-color:${config.theme.accentEndColor}`,
+        ].filter(Boolean);
+        if (accentDeclarations.length) headHtml += `<style>:root{${accentDeclarations.join(';')}}</style>\n`;
+
+        const shouldInjectAnalytics = pluginConfig.shouldInjectAnalytics ?? isBuild;
+        if (shouldInjectAnalytics && config.analytics.plausibleSiteId) headHtml = renderPlausibleSnippet(config) + headHtml;
+
+        // The kit stylesheet must block first paint, or every reload flashes an
+        // unstyled page (FOUC). Dev: a real <link> in <head> — a CSS import in a
+        // module script only applies once the script has run. Build: a CSS
+        // import, which Vite extracts into a hashed <link> in <head>.
+        if (!isBuild) headHtml += `<link rel="stylesheet" href="${KIT_STYLESHEET_DEV_URL}">\n`;
+        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;
+      },
+    },
+
+    // Runtime-fetched assets (demo JSON, docs) aren't in the module graph —
+    // copy them verbatim next to the built pages.
+    closeBundle() {
+      if (command !== 'build' || mode !== EXAMPLES_MODE) return;
+      for (const staticPath of config.examples.staticPaths) {
+        const sourcePath = resolve(config.root, staticPath);
+        if (!existsSync(sourcePath)) {
+          this.warn?.(`kmwc: examples.staticPaths entry "${staticPath}" does not exist — skipped`);
+          continue;
+        }
+        cpSync(sourcePath, resolve(config.root, outDir, staticPath), { recursive: true });
+      }
+    },
+  };
+}
+
+/**
+ * The full preset. `presetConfig.overrides` is deep-merged last; for values
+ * that depend on the Vite env, use `getOverridesCallback(env, config)`. A repo
+ * keeps its genuinely-specific bits — extra plugins, aliases, optimizeDeps —
+ * without forking the base.
+ *
+ * @param {import('./index.js').VitePresetConfig} [presetConfig]
+ */
+export function defineComponentConfig(presetConfig = {}) {
+  return async (env) => {
+    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 isExamplesMode = env.mode === EXAMPLES_MODE;
+    const isLibraryBuild = env.command === 'build' && !isExamplesMode;
+
+    const plugins = [createExamplesPlugin({ root: config.root }), ...(presetConfig.plugins || [])];
+
+    if (isLibraryBuild && library.shouldEmitTypes) {
+      const { default: createTypesPlugin } = await import('vite-plugin-dts');
+      plugins.push(createTypesPlugin({ rollupTypes: true, ...library.typesPluginConfig }));
+    }
+
+    const baseConfig = {
+      root: config.root,
+      appType: 'mpa',
+      // Relative asset URLs in the examples build, so the site works from any
+      // sub-path (or a plain file preview), not just a domain root.
+      ...(isExamplesMode && env.command === 'build' ? { base: './' } : {}),
+      define: generateBuildDefines(config),
+      plugins,
+      server: {
+        port: config.ports.dev,
+        strictPort: true,
+        fs: {
+          // The devkit may be a sibling checkout (file: link) — let the dev
+          // server read its example-kit files.
+          allow: [searchForWorkspaceRoot(config.root), DEVKIT_ROOT],
+        },
+      },
+      preview: {
+        port: config.ports.preview,
+        strictPort: true,
+      },
+      build: isExamplesMode
+        ? {
+            outDir: config.examples.outDir,
+            emptyOutDir: true,
+            rollupOptions: { input: getExamplePages(config) },
+          }
+        : {
+            sourcemap: library.shouldEmitSourcemap,
+            lib: {
+              entry: resolve(config.root, library.entry),
+              name: library.globalName,
+              formats: library.formats,
+              cssFileName: library.cssFileName,
+              fileName: (format) => `${library.fileName}.${format === 'es' ? 'js' : `${format}.js`}`,
+            },
+            rollupOptions: {
+              external: library.external,
+            },
+          },
+    };
+
+    let mergedConfig = presetConfig.overrides ? mergeConfig(baseConfig, presetConfig.overrides) : baseConfig;
+    if (presetConfig.getOverridesCallback) {
+      mergedConfig = mergeConfig(mergedConfig, await presetConfig.getOverridesCallback(env, config));
+    }
+    return mergedConfig;
+  };
+}

package/src/vite/page-composer.js

@@ -0,0 +1,209 @@
+/**
+ * Page composition for example pages — the "one copy of every repeated line"
+ * half of the examples kit. Runs inside the kmwc Vite plugin (dev and build),
+ * before the kit is injected:
+ *
+ *   1. <kmwc-include src="partials/x.html" any-param="…">inner</kmwc-include>
+ *      → the partial, with {{anyParam}} / {{content}} substituted. Nested
+ *      includes are fine; cycles are an error.
+ *   2. <kmwc-demo>…markup…</kmwc-demo>
+ *      → the live markup AND a code block of that exact markup, so a snippet
+ *      can never drift from its demo. <script data-kmwc-show> inside a demo is
+ *      executed and shown too.
+ *   3. A page without <html> is a FRAGMENT: it gets the devkit layout (head,
+ *      header with back link / title / subtitle, container, component entry
+ *      script), driven by <meta name="kmwc:…"> tags:
+ *        kmwc:title       page title (h1 + <title>)          — required
+ *        kmwc:subtitle    header subtitle
+ *        kmwc:layout      page (default) | bare (no header / container — e.g. the index)
+ *        kmwc:entry       component entry script; default /<library.entry>, "none" to skip
+ *        kmwc:body-class  classes for <body> (e.g. dark-output)
+ *      <link> and <style> elements anywhere in a fragment move into <head>.
+ *   Full documents (<html …>) are left as they are — pages migrate one at a time.
+ *
+ * Pure string work on purpose: unit-testable, no HTML parser dependency. The
+ * tag shapes are deliberately strict (no nesting of a tag inside itself).
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { DEVKIT_ROOT } from '../config.js';
+import { renderTemplate } from '../template.js';
+
+const LAYOUT_TEMPLATE_PATH = join(DEVKIT_ROOT, 'templates', 'examples-layout.html');
+const MAX_INCLUDE_DEPTH = 10;
+const DEFAULT_LAYOUT = 'page';
+const LAYOUTS = ['page', 'bare'];
+
+const INCLUDE_PATTERN = /<kmwc-include\b([^>]*?)(?:\/>|>([\s\S]*?)<\/kmwc-include>)/g;
+const DEMO_PATTERN = /<kmwc-demo\b([^>]*)>([\s\S]*?)<\/kmwc-demo>/g;
+const SHOWN_SCRIPT_PATTERN = /<script\b([^>]*\bdata-kmwc-show\b[^>]*)>([\s\S]*?)<\/script>/g;
+const PAGE_META_PATTERN = /<meta\s+name="kmwc:([a-z-]+)"\s+content="([^"]*)"\s*\/?>\s*/g;
+const HEAD_ELEMENT_PATTERN = /<link\b[^>]*>\s*|<style\b[^>]*>[\s\S]*?<\/style>\s*/g;
+const ATTRIBUTE_PATTERN = /([a-zA-Z][\w-]*)(?:\s*=\s*"([^"]*)")?/g;
+
+const HTML_COMMENT_PATTERN = /<!--[\s\S]*?-->/g;
+// A full document STARTS with a doctype or <html> (after a BOM, whitespace, comments). Matching
+// `<html>` anywhere would misread a fragment whose script or code sample mentions it.
+const DOCUMENT_START_PATTERN = /^?(?:\s|<!--[\s\S]*?-->)*<(?:!doctype\b|html[\s>])/i;
+
+/**
+ * Apply `mapper` to the text OUTSIDE HTML comments only, so a usage example in
+ * a comment (`<!-- <kmwc-include src="…"> -->`) is never expanded.
+ */
+export function mapOutsideComments(html, mapper) {
+  let mappedHtml = '';
+  let lastIndex = 0;
+  for (const comment of html.matchAll(HTML_COMMENT_PATTERN)) {
+    mappedHtml += mapper(html.slice(lastIndex, comment.index)) + comment[0];
+    lastIndex = comment.index + comment[0].length;
+  }
+  return mappedHtml + mapper(html.slice(lastIndex));
+}
+
+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]);
+
+/** `preview-class="x" code` → { previewClass: 'x', code: '' } */
+export function getAttributes(attributeText) {
+  const attributes = {};
+  for (const match of attributeText.matchAll(ATTRIBUTE_PATTERN)) {
+    attributes[mapToCamelCase(match[1])] = match[2] ?? '';
+  }
+  return attributes;
+}
+
+/** Strip the common leading indentation and surrounding blank lines. */
+export function mapToDedentedText(text) {
+  const lines = text.replace(/\t/g, '    ').split(/\r?\n/);
+  while (lines.length && !lines[0].trim()) lines.shift();
+  while (lines.length && !lines[lines.length - 1].trim()) lines.pop();
+  const indentation = Math.min(...lines.filter((line) => line.trim()).map((line) => line.match(/^ */)[0].length));
+  return lines.map((line) => line.slice(Number.isFinite(indentation) ? indentation : 0)).join('\n');
+}
+
+/**
+ * Replace every <kmwc-include> (recursively). Parameters are the tag's
+ * attributes (kebab → camel: `note-title` → {{noteTitle}}) plus {{content}}
+ * (the tag's inner HTML). Unknown {{placeholders}} are left untouched — a
+ * partial may legitimately show template syntax.
+ */
+export function resolveIncludes(html, { root, includeChain = [], readFile = defaultReadFile }) {
+  if (includeChain.length > MAX_INCLUDE_DEPTH) throw new Error(`kmwc: includes nested deeper than ${MAX_INCLUDE_DEPTH}: ${includeChain.join(' → ')}`);
+  return mapOutsideComments(html, (text) =>
+    text.replace(INCLUDE_PATTERN, (includeTag, attributeText, innerHtml = '') => {
+      const { src: partialPath, ...parameters } = getAttributes(attributeText);
+      if (!partialPath) throw new Error(`kmwc: <kmwc-include> without src: ${includeTag.slice(0, 80)}`);
+      if (includeChain.includes(partialPath)) throw new Error(`kmwc: include cycle: ${[...includeChain, partialPath].join(' → ')}`);
+      const partialHtml = readFile(resolve(root, partialPath), partialPath);
+      const variables = { ...parameters, content: innerHtml.trim() };
+      const filledHtml = partialHtml.replace(/\{\{\s*([a-zA-Z][\w]*)\s*\}\}/g, (placeholder, name) => (name in variables ? variables[name] : placeholder));
+      return resolveIncludes(filledHtml, { root, includeChain: [...includeChain, partialPath], readFile });
+    })
+  );
+}
+
+function defaultReadFile(absolutePath, displayPath) {
+  if (!existsSync(absolutePath)) throw new Error(`kmwc: <kmwc-include src="${displayPath}"> — file not found (${absolutePath})`);
+  return readFileSync(absolutePath, 'utf8');
+}
+
+function renderCodeBlock(codeText, language) {
+  return `<div class="code-block kmwc-demo__code" data-language="${language}"><pre><code>${mapToEscapedHtml(codeText)}</code></pre></div>`;
+}
+
+/**
+ * Turn every <kmwc-demo> into live markup + the code that produced it.
+ * Attributes: `preview-class` (default "demo-area"), `markup-hidden` (show
+ * only the scripts' code), `code-hidden` (live only — rarely what you want).
+ */
+export function renderDemos(html) {
+  return mapOutsideComments(html, (text) => text.replace(DEMO_PATTERN, renderDemo));
+}
+
+function renderDemo(demoTag, attributeText, innerHtml) {
+  const attributes = getAttributes(attributeText);
+  const shownScripts = [];
+  const markupHtml = innerHtml.replace(SHOWN_SCRIPT_PATTERN, (scriptTag, scriptAttributeText, scriptBody) => {
+    shownScripts.push({ attributeText: scriptAttributeText.replace(/\s*\bdata-kmwc-show\b(="[^"]*")?/, ''), body: scriptBody });
+    return '';
+  });
+  const codeBlocks = [];
+  if (!('markupHidden' in attributes) && markupHtml.trim()) codeBlocks.push(renderCodeBlock(mapToDedentedText(markupHtml), 'html'));
+  for (const script of shownScripts) codeBlocks.push(renderCodeBlock(mapToDedentedText(script.body), 'js'));
+
+  const previewClass = attributes.previewClass ?? 'demo-area';
+  const scriptsHtml = shownScripts.map((script) => `<script${script.attributeText}>${script.body}</script>`).join('\n');
+  return (
+    `<div class="kmwc-demo">\n` +
+    `<div class="kmwc-demo__preview ${previewClass}">${markupHtml}</div>\n` +
+    ('codeHidden' in attributes ? '' : codeBlocks.join('\n')) +
+    `\n</div>\n${scriptsHtml}`
+  );
+}
+
+/** Read and remove the page's <meta name="kmwc:…"> tags (`kmwc:body-class` → `bodyClass`). */
+export function getPageMeta(html) {
+  const pageMeta = {};
+  const htmlWithoutMeta = mapOutsideComments(html, (text) =>
+    text.replace(PAGE_META_PATTERN, (metaTag, name, content) => {
+      pageMeta[mapToCamelCase(name)] = content;
+      return '';
+    })
+  );
+  return { pageMeta, htmlWithoutMeta };
+}
+
+export const checkIsFragment = (html) => !DOCUMENT_START_PATTERN.test(html);
+
+/** Wrap a fragment page in the devkit layout. */
+export function renderLayout(fragmentHtml, { config, pagePath }) {
+  const { pageMeta, htmlWithoutMeta } = getPageMeta(fragmentHtml);
+  const layout = pageMeta.layout || DEFAULT_LAYOUT;
+  if (!LAYOUTS.includes(layout)) throw new Error(`kmwc: ${pagePath}: unknown kmwc:layout "${layout}" (${LAYOUTS.join(' | ')})`);
+  if (layout === 'page' && !pageMeta.title) throw new Error(`kmwc: ${pagePath}: a fragment page needs <meta name="kmwc:title" content="…">`);
+
+  const headElements = [];
+  const bodyContent = mapOutsideComments(htmlWithoutMeta, (text) =>
+    text.replace(HEAD_ELEMENT_PATTERN, (element) => {
+      headElements.push(`    ${element.trim()}`);
+      return '';
+    })
+  );
+
+  const entry = pageMeta.entry ?? `/${config.library.entry.replace(/^\.?\//, '')}`;
+  const pageTitle = pageMeta.title || config.title;
+  const bodyHtml =
+    layout === 'bare'
+      ? bodyContent.trim()
+      : [
+          '<div class="container">',
+          '    <header>',
+          '        <a href="index.html" class="back-link">← Back to Examples</a>',
+          `        <h1>${pageTitle}</h1>`,
+          pageMeta.subtitle ? `        <p class="subtitle">${pageMeta.subtitle}</p>` : '',
+          '    </header>',
+          bodyContent.trim(),
+          '</div>',
+        ]
+          .filter(Boolean)
+          .join('\n');
+
+  return renderTemplate(readFileSync(LAYOUT_TEMPLATE_PATH, 'utf8'), {
+    DOCUMENT_TITLE: layout === 'bare' ? pageTitle : `${pageTitle} — ${mapToEscapedHtml(config.title)}`,
+    HEAD_HTML: headElements.join('\n'),
+    BODY_ATTRIBUTES: pageMeta.bodyClass ? ` class="${pageMeta.bodyClass}"` : '',
+    BODY_HTML: bodyHtml,
+    // In <head>: module scripts run in document order, so the element is
+    // defined before the page's own scripts run.
+    ENTRY_SCRIPT_HTML: entry === 'none' ? '' : `    <script type="module" src="${entry}"></script>`,
+  });
+}
+
+/** The whole pipeline: includes → demos → layout (fragments only). */
+export function composePage(html, { config, pagePath, readFile }) {
+  let composedHtml = resolveIncludes(html, { root: config.root, readFile });
+  composedHtml = renderDemos(composedHtml);
+  return checkIsFragment(composedHtml) ? renderLayout(composedHtml, { config, pagePath }) : composedHtml;
+}