npm - @keenmate/web-components-devkit - Versions diffs - 0.0.0-stage → 1.0.0-rc02 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (109) hide show

package/CHANGELOG.md +126 -0
package/LICENSE +21 -0
package/README.md +434 -2
package/components.json +206 -0
package/package.json +77 -4
package/src/cli/args.js +16 -0
package/src/cli/commands/check-release.js +66 -0
package/src/cli/commands/check-vars.js +116 -0
package/src/cli/commands/doctor.js +289 -0
package/src/cli/commands/new.js +323 -0
package/src/cli/commands/readme.js +111 -0
package/src/cli/commands/sync.js +48 -0
package/src/cli/kmwc.js +73 -0
package/src/cli/sync-plan.js +163 -0
package/src/config.d.ts +149 -0
package/src/config.js +279 -0
package/src/examples/auto.js +20 -0
package/src/examples/chapter-nav.js +246 -0
package/src/examples/constants.js +80 -0
package/src/examples/controls-persistence.js +97 -0
package/src/examples/copy-link.js +89 -0
package/src/examples/css/base.css +215 -0
package/src/examples/css/chapter-nav.css +179 -0
package/src/examples/css/content.css +251 -0
package/src/examples/css/controls.css +205 -0
package/src/examples/css/copy-link.css +82 -0
package/src/examples/css/demo.css +50 -0
package/src/examples/css/index-page.css +118 -0
package/src/examples/css/style.css +30 -0
package/src/examples/css/theme-switch.css +38 -0
package/src/examples/css/tokens.css +124 -0
package/src/examples/css/widgets.css +133 -0
package/src/examples/demo-code.js +30 -0
package/src/examples/index-page.js +78 -0
package/src/examples/index.d.ts +107 -0
package/src/examples/index.js +18 -0
package/src/examples/kit.js +22 -0
package/src/examples/page-config.js +30 -0
package/src/examples/sections.js +53 -0
package/src/examples/theme-switch.js +72 -0
package/src/examples/version-badge.js +23 -0
package/src/playwright/index.d.ts +15 -0
package/src/playwright/index.js +66 -0
package/src/template.js +11 -0
package/src/vite/index.d.ts +28 -0
package/src/vite/index.js +243 -0
package/src/vite/page-composer.js +216 -0
package/templates/Dockerfile.tmpl +39 -0
package/templates/Makefile.tmpl +136 -0
package/templates/claude-block.md +40 -0
package/templates/dockerignore.tmpl +10 -0
package/templates/examples-layout.html +13 -0
package/templates/new/.claude/commands/publish.md +226 -0
package/templates/new/CHANGELOG.md +13 -0
package/templates/new/LICENSE +21 -0
package/templates/new/README.md +71 -0
package/templates/new/_gitignore +7 -0
package/templates/new/component-variables.manifest.json +32 -0
package/templates/new/custom-elements-manifest.config.mjs +23 -0
package/templates/new/docs/accessibility.md +24 -0
package/templates/new/docs/examples.md +33 -0
package/templates/new/docs/theming.md +54 -0
package/templates/new/docs/usage.md +51 -0
package/templates/new/e2e/dark-mode.spec.ts +30 -0
package/templates/new/e2e/smoke.spec.ts +26 -0
package/templates/new/examples-basic.html +57 -0
package/templates/new/examples-theming.html +28 -0
package/templates/new/index.html +16 -0
package/templates/new/partials/note.html +5 -0
package/templates/new/playwright.config.ts +4 -0
package/templates/new/src/__FEATURE__.ts +55 -0
package/templates/new/src/css/animations.css +1 -0
package/templates/new/src/css/base.css +43 -0
package/templates/new/src/css/controls.css +20 -0
package/templates/new/src/css/dark-mode.css +36 -0
package/templates/new/src/css/floating.css +1 -0
package/templates/new/src/css/main.css +27 -0
package/templates/new/src/css/states.css +22 -0
package/templates/new/src/css/variables.css +42 -0
package/templates/new/src/env.d.ts +7 -0
package/templates/new/src/index.ts +17 -0
package/templates/new/src/logger.ts +11 -0
package/templates/new/src/types.ts +25 -0
package/templates/new/src/web-component.ts +73 -0
package/templates/new/test/dark-mode.html +18 -0
package/templates/new/test/fixture.html +11 -0
package/templates/new/tsconfig.json +15 -0
package/templates/new/vite.config.ts +5 -0
package/templates/new-minimal/CHANGELOG.md +13 -0
package/templates/new-minimal/README.md +71 -0
package/templates/new-minimal/component-variables.manifest.json +24 -0
package/templates/new-minimal/docs/accessibility.md +20 -0
package/templates/new-minimal/docs/examples.md +17 -0
package/templates/new-minimal/docs/theming.md +53 -0
package/templates/new-minimal/docs/usage.md +43 -0
package/templates/new-minimal/e2e/smoke.spec.ts +10 -0
package/templates/new-minimal/examples-basic.html +23 -0
package/templates/new-minimal/examples-theming.html +28 -0
package/templates/new-minimal/src/__FEATURE__.ts +37 -0
package/templates/new-minimal/src/css/base.css +48 -0
package/templates/new-minimal/src/css/controls.css +1 -0
package/templates/new-minimal/src/css/states.css +1 -0
package/templates/new-minimal/src/css/variables.css +28 -0
package/templates/new-minimal/src/index.ts +17 -0
package/templates/new-minimal/src/types.ts +10 -0
package/templates/new-minimal/src/web-component.ts +48 -0
package/templates/new-minimal/test/dark-mode.html +18 -0
package/templates/new-minimal/test/fixture.html +11 -0
package/templates/nginx.conf.tmpl +43 -0

package/src/vite/page-composer.js ADDED Viewed

@@ -0,0 +1,216 @@
+/**
+ * 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>
+ *      (not those inside a <script> — there they are strings, e.g. shadow-DOM styles).
+ *   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;
+// Comments plus whole <script> elements: a <style> / <link> inside a script is a string
+// (shadow-DOM styles, an SVG's own <style>), never a page element to move into <head>.
+const COMMENT_OR_SCRIPT_PATTERN = /<!--[\s\S]*?-->|<script\b[^>]*>[\s\S]*?<\/script>/gi;
+// 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, skippedPattern = HTML_COMMENT_PATTERN) {
+  let mappedHtml = '';
+  let lastIndex = 0;
+  for (const skipped of html.matchAll(skippedPattern)) {
+    mappedHtml += mapper(html.slice(lastIndex, skipped.index)) + skipped[0];
+    lastIndex = skipped.index + skipped[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 '';
+      }),
+    COMMENT_OR_SCRIPT_PATTERN
+  );
+  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;
+}

package/templates/Dockerfile.tmpl ADDED Viewed

@@ -0,0 +1,39 @@
+# syntax=docker/dockerfile:1
+{{HEADER}}
+#
+# Examples site for {{PACKAGE_NAME}}: Vite multi-page build → static nginx.
+# ─────────────────────────────────────────────────────────────────────────────
+# Stage 1 — build: `npm run build:examples` (= vite build --mode examples)
+# ─────────────────────────────────────────────────────────────────────────────
+FROM node:{{NODE_IMAGE}} AS build
+WORKDIR /app
+# Latest npm first — the bundled one can lag by weeks; newer npm ships registry
+# hardening that reduces supply-chain exposure. Own layer, cached per base image.
+RUN npm install -g npm@latest
+# NOT `npm ci`: local lockfiles may resolve sibling packages (core, devkit) to
+# file: links that don't exist in this build context. A plain install
+# re-resolves them from the registry. Manifests first so this layer stays
+# cached until dependencies change.
+{{COPY_PACKAGE_JSONS}}
+RUN {{INSTALL_COMMAND}}
+# Source + build. The kmwc Vite plugin bundles each example page, injects the
+# shared kit, stamps the version badge (BUILD_TIME, default: now) and adds the
+# analytics snippet — no post-build sed.
+COPY . .
+ARG BUILD_TIME
+ENV BUILD_TIME=${BUILD_TIME}
+RUN npm run build:examples
+# ─────────────────────────────────────────────────────────────────────────────
+# Stage 2 — serve
+# ─────────────────────────────────────────────────────────────────────────────
+FROM nginx:alpine AS serve
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=build /app/{{OUT_DIR}} /usr/share/nginx/html
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]

package/templates/Makefile.tmpl ADDED Viewed

@@ -0,0 +1,136 @@
+{{HEADER}}
+#
+# Repo-specific targets go in Makefile.local (included at the end; a target
+# redefined there wins, with a make "overriding recipe" warning). Per-developer
+# overrides (container runner, image name, port) go in .makefile.env.
+.PHONY: help setup dev kill-port build build-examples preview-examples package publish-dry publish publish-rc clean check-version check-vars doctor sync test test-e2e test-e2e-ui test-e2e-headed test-e2e-install image-build image-run image-stop image-clean
+-include .makefile.env
+DOCKER_RUNNER  ?= {{RUNNER}}
+IMAGE_NAME     ?= {{IMAGE_NAME}}
+CONTAINER_NAME ?= {{CONTAINER_NAME}}
+IMAGE_PORT     ?= {{IMAGE_PORT}}
+DEV_PORT       := {{DEV_PORT}}
+PREVIEW_PORT   := {{PREVIEW_PORT}}
+help: ## Show this help message
+	@echo "Available targets:"
+	@grep -hE '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-18s %s\n", $$1, $$2}'
+setup: ## Install dependencies
+	npm install
+dev: ## Start the dev server (examples on http://localhost:{{DEV_PORT}})
+	@rm -rf node_modules/.vite
+	npm run dev
+# Free the dev + preview ports. Vite runs with strictPort, so a stale server is
+# the only thing that can hold them. On Windows a PowerShell one-liner covers
+# IPv4 + IPv6 listeners; `$$_` escapes make's `$` and the single quotes stop sh
+# from expanding `$_` before PowerShell sees it.
+kill-port: ## Free the dev/preview ports ({{DEV_PORT}}, {{PREVIEW_PORT}})
+ifeq ($(OS),Windows_NT)
+	-@powershell -NoProfile -Command '$(DEV_PORT),$(PREVIEW_PORT) | ForEach-Object { Get-NetTCPConnection -LocalPort $$_ -State Listen -ErrorAction SilentlyContinue } | Select-Object -ExpandProperty OwningProcess -Unique | ForEach-Object { Stop-Process -Id $$_ -Force -ErrorAction SilentlyContinue }'
+else
+	-@for p in $(DEV_PORT) $(PREVIEW_PORT); do lsof -ti tcp:$$p | xargs -r kill -9; done
+endif
+	@echo "Ports $(DEV_PORT), $(PREVIEW_PORT) are free"
+build: ## Build the library (dist/)
+	npm run build
+build-examples: ## Build the static examples site ({{OUT_DIR}}/)
+	npm run build:examples
+preview-examples: build-examples ## Serve the built examples site (http://localhost:{{PREVIEW_PORT}})
+	npm run preview:examples
+package: build ## Create an npm tarball
+	npm pack
+publish-dry: ## Publish dry run (clean build first)
+	npm run clean:dist
+	npm run build
+	npm publish --dry-run
+# Release gates (publish-command.md): the version must fit the dist-tag
+# (latest = no pre-release suffix, rc = -rcN), must not be on npm yet, and the
+# e2e suite must pass. `kmwc check-release` does the first two.
+publish: ## Publish to npm as 'latest' (release versions only)
+	npx kmwc check-release --tag latest
+	@echo "WARNING: publishing to npm under the 'latest' dist-tag. Use 'make publish-rc' for pre-releases."
+	@$(CONFIRM)
+	npm run clean:dist
+	npm run build
+ifneq ($(wildcard playwright.config.*),)
+	npm run test:e2e
+endif
+	npm publish
+publish-rc: ## Publish to npm under the 'rc' dist-tag (does NOT touch 'latest')
+	npx kmwc check-release --tag rc
+	@echo "WARNING: publishing to npm under the 'rc' dist-tag."
+	@$(CONFIRM)
+	npm run clean:dist
+	npm run build
+ifneq ($(wildcard playwright.config.*),)
+	npm run test:e2e
+endif
+	npm publish --tag rc
+clean: ## Clean build artifacts
+	npm run clean
+check-version: ## Show the current package version
+	@node -p "require('./package.json').version"
+check-vars: ## Validate component-variables.manifest.json against the CSS
+	npx kmwc check-vars
+doctor: ## Check this repo against the Keenmate component standard
+	npx kmwc doctor
+sync: ## Regenerate devkit-owned files (Dockerfile, nginx.conf, Makefile, …)
+	npx kmwc sync
+test: ## Run unit tests
+	npm test
+test-e2e: ## Run Playwright e2e tests (headless)
+	npm run test:e2e
+test-e2e-ui: ## Run Playwright e2e tests in UI mode
+	npm run test:e2e:ui
+test-e2e-headed: ## Run Playwright e2e tests headed
+	npm run test:e2e:headed
+test-e2e-install: ## Install the chromium browser binary (one-time)
+	npm run test:e2e:install
+# ── Container image (examples site) ──────────────────────────────────────────
+image-build: ## Build the examples container image
+	$(DOCKER_RUNNER) build --build-arg BUILD_TIME=$$(date -u +%Y-%m-%dT%H:%MZ) -t $(IMAGE_NAME) .
+image-run: ## Run the examples image on IMAGE_PORT (default {{IMAGE_PORT}})
+	-@$(DOCKER_RUNNER) rm -f $(CONTAINER_NAME) >/dev/null 2>&1
+	$(DOCKER_RUNNER) run -d --name $(CONTAINER_NAME) -p $(IMAGE_PORT):80 $(IMAGE_NAME)
+	@echo "Serving examples at http://localhost:$(IMAGE_PORT)"
+image-stop: ## Stop and remove the examples container
+	-@$(DOCKER_RUNNER) rm -f $(CONTAINER_NAME) >/dev/null 2>&1
+image-clean: image-stop ## Remove the examples container and image
+	-@$(DOCKER_RUNNER) rmi $(IMAGE_NAME) >/dev/null 2>&1
+ifeq ($(OS),Windows_NT)
+CONFIRM = powershell -NoProfile -Command "Write-Host 'Press Enter to continue, Ctrl+C to cancel...'; Read-Host | Out-Null"
+else
+CONFIRM = read -p "Press Enter to continue, Ctrl+C to cancel... " _
+endif
+-include Makefile.local
+.DEFAULT_GOAL := help

package/templates/claude-block.md ADDED Viewed

@@ -0,0 +1,40 @@
+## Shared infrastructure — `@keenmate/web-components-devkit` (read before touching examples/build files)
+This repo follows the Keenmate component standard: the BlissFramework rulebook
+(`C:\Git\BlissFramework\guidelines\web-components\` — structure, naming, CSS,
+theming, README, CEM, publish) plus the devkit (`../web-components`, published
+as `@keenmate/web-components-devkit`), which owns the example-site kit, the
+Vite/Playwright configs and the deploy files. Do not re-create or patch those
+locally — every local fork is how they drifted apart.
+- **Never add** `examples-chapter-nav.js`, `examples-copy-link.js`,
+  `examples-controls-store.js`, `examples-shared.css`, `plausible-snippet.html`
+  or `scripts/check-variable-manifest.mjs`. The chapter nav, copy-link buttons,
+  shared styles, theme switch, version badge and analytics are injected into
+  every root `*.html` page by the Vite plugin automatically.
+- **Generated — do not edit:** `Dockerfile`, `nginx.conf`, `Makefile`,
+  `.dockerignore` (they start with a `GENERATED by kmwc sync` header). Change
+  `package.json#kmwc` and run `npx kmwc sync`, or fix the template in the devkit.
+  Repo-specific make targets go in `Makefile.local`.
+- **Per-component settings** (title, tagline, CSS prefix, ports, accent colours,
+  analytics id, image name, canonical origin) live **only** in `package.json#kmwc`.
+- **Example page styles:** shared rules are in `@layer kmwc` and read
+  `--base-*` tokens (pages support light / dark / auto via the theme switch), so
+  any unlayered rule wins. Put component-only rules in `examples-local.css`.
+  Re-theme with `kmwc.theme.accentColor`, never by copying CSS. If a second
+  component needs a pattern, it belongs in the devkit.
+- **Example pages are fragments:** no `<html>`/`<head>`/`<header>` — start with
+  `<meta name="kmwc:title" content="…">`, the devkit layout adds the rest. Shared text
+  goes in `partials/` via `<kmwc-include>`; show code with `<kmwc-demo>` (the live
+  markup IS the snippet) — never hand-copy a demo into a `.code-block`.
+- **Controls persistence:**
+  `import { attachControlsPersistence } from '@keenmate/web-components-devkit/examples'`.
+  **Landing page:** `renderExamplesIndex({ pages })` from the same module.
+- **Found a bug in a shared helper?** Fix it in `../web-components` (so every
+  component gets it), not here. Say so in your summary if you can't.
+- **Never ship AI-assistant files:** `package.json` `files` must keep
+  `"!**/CLAUDE.md"` and `"!**/.claude"` (a `CLAUDE.md` you add under `src/` is
+  otherwise published with it).
+- Before finishing: `npx kmwc doctor` must pass — it runs the devkit checks,
+  checks the `npm pack` file list for dev-only files, and runs the rulebook's
+  `*.checks.sh` suites.

package/templates/dockerignore.tmpl ADDED Viewed

@@ -0,0 +1,10 @@
+{{HEADER}}
+node_modules
+**/node_modules
+dist
+{{OUT_DIR}}
+test-results
+playwright-report
+.git
+*.tgz
+.makefile.env

package/templates/examples-layout.html ADDED Viewed

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{DOCUMENT_TITLE}}</title>
+{{ENTRY_SCRIPT_HTML}}
+{{HEAD_HTML}}
+</head>
+<body{{BODY_ATTRIBUTES}}>
+{{BODY_HTML}}
+</body>
+</html>